Workspaces API

Workspaces are isolated sandboxes where agents (or humans) can write files, commit, and submit stacks — all remote, no local checkout needed. Each workspace is based on a commit and maintains an overlay of changed files.

Create a workspace

POST /api/repos/{owner}/{name}/workspaces

{
  "name": "feature-auth",
  "agent_name": "claude",
  "base_commit": "optional-commit-id"
}

If base_commit is omitted, the workspace is based on the latest main ref.

Response:

{
  "workspace": {
    "id": "ws_abc123",
    "name": "feature-auth",
    "base_commit": "a1b2c3...",
    "current_commit": "a1b2c3...",
    "agent_name": "claude",
    "status": "active"
  }
}

List workspaces

GET /api/repos/{owner}/{name}/workspaces

Write a file

PUT /api/repos/{owner}/{name}/workspaces/{wsId}/files/{path}

Send raw file content as the request body. The file is stored in the workspace overlay.

curl -X PUT "https://dojo.ninja/api/repos/owner/name/workspaces/ws_abc123/files/src/auth.ts" \
  -H "Authorization: Bearer $TOKEN" \
  --data-binary @auth.ts

Read a file

GET /api/repos/{owner}/{name}/workspaces/{wsId}/files/{path}

Returns content from the overlay if the file was modified, otherwise from the base commit.

{
  "path": "src/auth.ts",
  "content": "base64-encoded...",
  "source": "overlay"
}

Delete a file

DELETE /api/repos/{owner}/{name}/workspaces/{wsId}/files/{path}

Marks the file as deleted in the overlay.

Check status

GET /api/repos/{owner}/{name}/workspaces/{wsId}/status

{
  "added": ["src/auth.ts", "src/middleware.ts"],
  "modified": ["package.json"],
  "deleted": ["src/old-auth.ts"]
}

Commit

POST /api/repos/{owner}/{name}/workspaces/{wsId}/commit

{
  "message": "Implement OAuth flow",
  "author_name": "claude",
  "author_email": "claude@agent.dev",
  "intent": {
    "goal": "Add GitHub OAuth authentication",
    "plan": "Create OAuth handler, session middleware, user model",
    "confidence": "high",
    "agent": "claude-code"
  }
}

Creates a commit from the workspace overlay, clears the overlay, and advances the workspace head. Intent metadata is stored on the commit for traceability.

Submit as stack

POST /api/repos/{owner}/{name}/workspaces/{wsId}/submit

{
  "title": "Add authentication system"
}

Creates a bookmark and submits the workspace’s commit chain as a stack for review.

Check conflicts

GET /api/repos/{owner}/{name}/workspaces/{wsId}/check-conflicts

Checks if any other workspace has locked paths that overlap with this workspace’s changes.

Browse workspace tree

GET /api/repos/{owner}/{name}/workspaces/{wsId}/tree

See Tree Browsing API for details. Returns base commit files merged with workspace overlay.

Search workspace files

GET /api/repos/{owner}/{name}/workspaces/{wsId}/search?q=query

See Search API for details. Searches both base commit and overlay files.

Lock paths

POST /api/repos/{owner}/{name}/workspaces/{wsId}/lock

{
  "patterns": ["src/auth/*", "package.json"]
}

Path locking prevents other workspaces from modifying the same files, avoiding merge conflicts.

Delete workspace

DELETE /api/repos/{owner}/{name}/workspaces/{wsId}

Removes the workspace and its overlay. Committed changes are preserved in the commit graph.