Creates a new repository for the authenticated organization. Repository names cannot include path separators.

curl -X POST "https://api.driftstone.ai/v1/repos" \
  -H "Authorization: Bearer dk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "hello-world"
  }'

Returns repositories for the authenticated organization. Supports page and pageSize query parameters.

Returns one repository resolved under the authenticated organization.

Marks a repository as deleting and starts background deletion for repository files, uploads, branches, and the repository record.

Returns signed upload URLs for files under the target branch storage directory. Upload each file to its URL with Content-Type: application/octet-stream. Pass message to record a commit message when the upload is completed.

curl -X POST "https://api.driftstone.ai/v1/repos/hello-world/uploads" \
  -H "Authorization: Bearer dk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "branch": "main",
    "storageDir": "ver-1234abcd",
    "message": "Update README copy",
    "files": [
      {
        "name": "README.md",
        "hash": "64-character-sha256-or-client-hash"
      }
    ]
  }'

Returns signed download URLs for specific files under the selected main or branch namespace. File paths are relative to that namespace.

curl -X POST "https://api.driftstone.ai/v1/repos/hello-world/downloads" \
  -H "Authorization: Bearer dk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "main",
    "files": [
      {
        "path": "ver-1234abcd/README.md"
      }
    ]
  }'

Returns signed download URLs for every file under a live directory. Response paths are relative to the requested directory.

curl -X POST "https://api.driftstone.ai/v1/repos/hello-world/downloads/directory" \
  -H "Authorization: Bearer dk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "branch",
    "directory": "profile-123/state-456"
  }'

Marks a pending upload as complete. Main uploads can create a main diff record. Custom branch uploads update the branch immediately unless matching pre_promote_upload validators require an async validation run first.

Polls an upload. This is useful when completion returns validating because branch promotion is waiting on validators.

curl -X GET "https://api.driftstone.ai/v1/repos/hello-world/uploads/upload-..." \
  -H "Authorization: Bearer dk-..."

Returns branches available in a repository. Supports page and pageSize query parameters.

Returns metadata for a single branch.

Creates a branch. By default, Driftstone copies the repository main head and optional transforms can patch files after the copy. Set deriveFromMain to false to create only the branch record before uploading its first directory.

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",
    "storageDir": "state-123",
    "deriveFromMain": true,
    "transforms": {
      "README.md": "# Branch-specific README\n"
    }
  }'

curl -X POST "https://api.driftstone.ai/v1/repos/hello-world/branches" \
  -H "Authorization: Bearer dk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "profile-123",
    "deriveFromMain": false
  }'

Marks a branch as deleting and starts background deletion for the stored branch files and branch record.

Returns commit history for a branch with headIdentifier, headCommitId, and per-commit isCurrent. Use storageDir to inspect the files for a commit and message for the human-readable commit message.

curl -X GET "https://api.driftstone.ai/v1/repos/hello-world/commits?branch=feature-readme" \
  -H "Authorization: Bearer dk-..."

Moves a branch head to an existing commit or storage snapshot and records a new rollback commit. The files served by the branch change only when the selected commit points to a different storageDir than the current headIdentifier. Use expectedHead to guard against stale UI or concurrent updates.

curl -X POST "https://api.driftstone.ai/v1/repos/hello-world/branches/feature-readme/rollback" \
  -H "Authorization: Bearer dk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "commitId": "commit-...",
    "expectedHead": "state-456",
    "message": "Rollback feature-readme to stable README"
  }'

Starts a background copy from sourceDir to destDir. Source and destination branches default to main.

curl -X POST "https://api.driftstone.ai/v1/repos/hello-world/copies" \
  -H "Authorization: Bearer dk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "sourceDir": "ver-1234abcd",
    "destDir": "state-456",
    "sourceBranch": "main",
    "destBranch": "profile-123",
    "archive": true
  }'

Returns running, completed, or failed for a directory copy run.

Starts a background sync from incomingStorageDir into each target branch. The strategy field is typed as manual, current, incoming, or smart.

curl -X POST "https://api.driftstone.ai/v1/repos/hello-world/sync" \
  -H "Authorization: Bearer dk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "incomingStorageDir": "ver-456",
    "strategy": "smart",
    "targets": [
      {
        "branch": "profile-123",
        "baseStorageDir": "ver-123",
        "currentStorageDir": "state-123",
        "outputStorageDir": "state-456"
      }
    ]
  }'

Starts the new main-diff sync flow. Driftstone resolves missing main diffs, creates a workspace with main/, custom/, work/, MAIN_DIFF.json, MAIN_DIFF.patch, and SYNC_TASK.md, then promotes work/ only after validators pass.

curl -X POST "https://api.driftstone.ai/v1/repos/hello-world/sync" \
  -H "Authorization: Bearer dk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "agent-diff",
    "branch": "profile-123"
  }'

Returns running, completed, or failed for a repository sync run.

Lists recorded main diffs in creation order. Each record includes the source main storage dir, target main storage dir, changed paths, stats, summary, and artifact paths.

curl -X GET "https://api.driftstone.ai/v1/repos/hello-world/main-diffs" \
  -H "Authorization: Bearer dk-..."

Combines the linear diff chain between two main storage dirs. If both storage dirs are the same, the response is up_to_date.

curl -X POST "https://api.driftstone.ai/v1/repos/hello-world/main-diffs/range" \
  -H "Authorization: Bearer dk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "fromStorageDir": "ver-123",
    "toStorageDir": "ver-456"
  }'

Extension validators run a Driftstone extension against /workspace/repo/work. The extension must write VALIDATION_RESULT.json with status set to passed or failed.

curl -X POST "https://api.driftstone.ai/v1/repos/hello-world/validators" \
  -H "Authorization: Bearer dk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "semantic validation",
    "type": "extension",
    "branchPattern": "*",
    "events": ["pre_promote_sync", "pre_promote_upload"],
    "required": true,
    "config": {
      "extensionId": "ext-..."
    }
  }'

Command validators run shell commands against a temporary copy of candidate work/. Any non-zero exit code or timeout fails the validator.

curl -X POST "https://api.driftstone.ai/v1/repos/hello-world/validators" \
  -H "Authorization: Bearer dk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "test check",
    "type": "command",
    "branchPattern": "*",
    "events": ["pre_promote_sync", "pre_promote_upload"],
    "required": true,
    "config": {
      "commands": ["npm test"],
      "workingDirectory": ".",
      "timeoutSeconds": 600,
      "env": {
        "CI": "true"
      }
    }
  }'

Returns active validator definitions for the repo.

curl -X GET "https://api.driftstone.ai/v1/repos/hello-world/validators" \
  -H "Authorization: Bearer dk-..."

Updates validator name, branch pattern, events, required flag, status, or config.

curl -X PATCH "https://api.driftstone.ai/v1/repos/hello-world/validators/validator-..." \
  -H "Authorization: Bearer dk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "disabled"
  }'

Soft-deletes a validator definition.

curl -X DELETE "https://api.driftstone.ai/v1/repos/hello-world/validators/validator-..." \
  -H "Authorization: Bearer dk-..."

Returns the checks, summary, candidate storage dir, previous storage dir, and sync or upload id for one validation run.

curl -X GET "https://api.driftstone.ai/v1/repos/hello-world/validations/valrun-..." \
  -H "Authorization: Bearer dk-..."