Driftstone Docs
Back to landing

Reference

API Overview

POST/v1/repos/createCreate a repository from initial files or an archive.GET/v1/repos/{repo}Return repository metadata for the authenticated organization.POST/v1/repos/{repo}/diffReturn a unified diff between two commits or refs.GET/v1/repos/{repo}/branchesList repository branches.GET/v1/repos/{repo}/branches/{branch}Return metadata for one branch.POST/v1/repos/{repo}/branchesCreate a branch, or replace branch contents from an archive.GET/v1/repos/{repo}/contents/{path}Read a file from a repository branch.PUT/v1/repos/{repo}/contents/{path}Write a file and commit the change.PUT/v1/repos/{repo}/mergesMerge one branch or commit into another branch.POST/v1/repos/{repo}/syncPublish a branch or commit into target branches.

API Reference

Repositories

Repository endpoints create and retrieve Driftstone repositories within the authenticated organization.

POST/v1/repos/create

Create a repository

Creates a new repository from either an archive payload or an initialFiles object. Send exactly one of base64 or initialFiles.

FieldLocationRequiredDescription
namebodyyesRepository name.
base64bodyconditionalBase64-encoded repository archive. Send exactly one of base64 or initialFiles.
initialFilesbodyconditionalObject keyed by repository file path. Send exactly one of initialFiles or base64.
pathbodynoOptional repository path override.
defaultBranchbodynoInitial default branch. Defaults to main.
replaceIfExistsbodynoReplace an existing repository with the same resolved path.
messagebodynoInitial commit message.
curl -X POST "https://api.driftstone.ai/v1/repos/create" \
  -H "Authorization: Bearer dk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "hello-world",
    "defaultBranch": "main",
    "initialFiles": {
      "README.md": "# Example Repo\n"
    }
  }'
GET/v1/repos/{repo}

Get a repository

Returns one repository resolved under the authenticated organization.

POST/v1/repos/{repo}/diff

Diff repository commits

Returns a unified diff between two commits, branches, or refs in the repository. Use path to limit the diff to a file or directory.

FieldLocationRequiredDescription
repopathyesRepository identifier.
baseCommitbodyyesBase commit hash or ref. Aliases: baseCommitHash, fromCommit, fromRef, base.
headCommitbodyyesHead commit hash or ref. Aliases: headCommitHash, toCommit, toRef, head.
pathbodynoOptional path within the repository to diff.
contextLinesbodynoUnified diff context line count. Defaults to 3.
curl -X POST "https://api.driftstone.ai/v1/repos/hello-world/diff" \
  -H "Authorization: Bearer dk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "baseCommit": "main~1",
    "headCommit": "main",
    "contextLines": 3
  }'

API Reference

Branches

Branch endpoints keep agent work isolated and reviewable before it is merged or synced into target branches.

GET/v1/repos/{repo}/branches

List branches

Returns the branches available in a repository.

GET/v1/repos/{repo}/branches/{branch}

Get a branch

Returns metadata for a single branch.

POST/v1/repos/{repo}/branches

Create a branch

Creates a branch from another branch or commit hash. The same endpoint can replace the branch contents when an archive is provided through base64 or storageUrl.

FieldLocationRequiredDescription
repopathyesRepository identifier.
namebodyyesNew branch name.
fromRefbodyyesSource branch name or commit hash.
base64bodynoArchive payload used to replace the new branch contents.
storageUrlbodynoStorage URL for an archive used to replace branch contents.
messagebodynoCommit message for branch replacement.
curl -X POST "https://api.driftstone.ai/v1/repos/hello-world/branches" \
  -H "Authorization: Bearer dk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "feature/readme",
    "fromRef": "main"
  }'

API Reference

Contents

Content endpoints read and write individual files in a repository. Writes become Git commits with the supplied message.

GET/v1/repos/{repo}/contents/{path}

Read a file

Reads a file from a repository. Use the branch query parameter to read from a branch other than main.

FieldLocationRequiredDescription
repopathyesRepository identifier.
pathpathyesFile path inside the repository.
branchquery/bodyyes for writesBranch to read from or write to. Reads default to main.
messagebodyyes for writesCommit message for the file update.
contentbodyyes for writesFile content.
base64bodynoSet true when content is base64-encoded.
PUT/v1/repos/{repo}/contents/{path}

Write a file

Writes content to a path on a branch and commits the update. Set base64 to true when sending base64-encoded content.

curl -X PUT "https://api.driftstone.ai/v1/repos/hello-world/contents/README.md" \
  -H "Authorization: Bearer dk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "branch": "main",
    "message": "Update README",
    "content": "# Example Repo\nUpdated content.\n"
  }'

API Reference

Merges

Merge endpoints move reviewed work from a head branch or commit into a base branch and return commit metadata.

PUT/v1/repos/{repo}/merges

Merge head into base

Merges head into base using the supplied commit message.

FieldLocationRequiredDescription
repopathyesRepository identifier.
headbodyyesSource branch or commit to merge from.
basebodyyesTarget branch to merge into.
messagebodyyesCommit message for the merge.
curl -X PUT "https://api.driftstone.ai/v1/repos/hello-world/merges" \
  -H "Authorization: Bearer dk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "head": "feature/readme",
    "base": "main",
    "message": "Merge feature/readme"
  }'

API Reference

Sync

Sync publishes a branch or commit into one or more target branches and can record archive storage paths for published outputs.

POST/v1/repos/{repo}/sync

Sync a branch

Sends a source branch or commit into the configured target branches. Use this when generated work needs to be published to release branches or downstream environments.

FieldLocationRequiredDescription
repopathyesRepository identifier.
branchbodyyesSource branch or commit to publish.
targetBranchesbodynoTarget branches that should receive the source changes.
pathbodynoOptional repository path override.
messagebodynoSync commit message.
archiveStoragePathsbodynoStorage paths keyed by target branch for archived sync output.