Workspaces API

​

Workspaces

• GET /workspaces — List workspaces for the account
• POST /workspaces — Create a workspace
• GET /workspace/{workspaceId} — Get a workspace
• PATCH /workspace/{workspaceId} — Update a workspace
• GET /workspace/{workspaceId}/metadata — Get summarized metadata for UI display

POST /workspaces
Content-Type: application/json

{
  "tags": [{ "scope": "env", "value": "dev" }],
  "template_id": "<uuid>",
  "template_commit_hash": "<hash>",
  "config": {},
  "display": "My Workspace",
  "mode": "freestyle",
  "slug": "my-workspace",
  "description": "optional",
  "machine_id": "<machine-id>"
}

​

Templates & Repository Integrations

• GET /workspaces/templates — List workspace templates
• POST /workspaces/templates — Create a template
• GET /workspaces/templates/{templateId} — Get a template
• GET /workspaces/repository-integrations — List GitHub App repository integrations

​

Workspace Configuration (YAML)

• GET /workspace/{workspaceId}/config — Get integrations config
• PATCH /workspace/{workspaceId}/config — Update integrations config (partial deep-merge)

{
  "integrations": {
    "slack": { "enabled": true },
    "data_warehouse": { "snowflake": { "enabled": false } }
  }
}

​

Threads (Chat)

• GET /workspace/{workspaceId}/threads — List threads (metadata)
• GET /workspace/{workspaceId}/thread/{threadId} — Get a thread
• PATCH /workspace/{workspaceId}/thread/{threadId} — Update a thread (messages, summary, metadata)
• PATCH /workspace/{workspaceId}/thread/{threadId}/metadata — Update metadata only
• POST /workspace/{workspaceId}/thread/{threadId}/save — Create or overwrite a thread
• DELETE /workspace/{workspaceId}/thread/{threadId} — Delete a thread
• POST /workspace/{workspaceId}/threads/rebuild-metadata — Rebuild thread metadata index

• POST /workspace/{workspaceId}/threads/stream — Start streaming AI response (SSE v2)
• GET /workspace/{workspaceId}/threads/stream — Reconnect to an active stream (SSE v2)
• DELETE /workspace/{workspaceId}/threads/{threadId}/stream — Cancel active streams for a thread

{
  "messages": [
    { "role": "user", "content": "Hello" },
    { "role": "assistant", "content": "Hi there!" }
  ],
  "workspace_id": "{workspaceId}",
  "account_id": "<accountId>",
  "created_by": "<userId>",
  "display": "Thread 1234",
  "summary": "Short summary",
  "metadata": {}
}

​

Workspace Events (SSE)

• GET /workspace/{workspaceId}/events — Subscribe to file/directory/task events via Server-Sent Events. Event name: workspace-event. Data is a JSON-encoded typed event.

​

Files

• POST /workspace/{workspaceId}/files?path={path} — Create/Upload a file
  • Body for upload via signed URL:
    Copy

    Ask AI

    { "url": "<signed-url>", "size": 123, "mimeType": "text/plain", "storageBucket": "...", "storageKey": "..." }
    

  • If size: 0, creates an empty file.
• GET /workspace/{workspaceId}/file?path={path} — Download a file (binary)
• GET /workspace/{workspaceId}/file/pdf?path={path} — Convert DOC/DOCX to PDF or return PDF (binary)
• PATCH /workspace/{workspaceId}/file/path?path={old}&newPath={new} — Rename/move file
• DELETE /workspace/{workspaceId}/file?path={path} — Delete file

​

Directories & Search

• POST /workspace/{workspaceId}/directory?path={path} — Create directory (recursive)
• PATCH /workspace/{workspaceId}/directory/path?path={old}&newPath={new} — Rename/move directory
• DELETE /workspace/{workspaceId}/directory?path={path} — Delete directory (recursive)
• GET /workspace/{workspaceId}/directory/download?path={path} — Zip and download directory (binary zip)
• POST /workspace/{workspaceId}/search/paths — Glob search
  • Body: { "globPattern": "src/**/*", "maxDepth": 20, "stats": true }

​

Lifecycle Events

• POST /workspace/{workspaceId}/lifecycle-events — Create a lifecycle event for the workspace
  • Body: { "event": "created|archived|...", "notes": "optional" }

​

Commands

• GET /workspace/{workspaceId}/commands — List commands (filters: type, search, offset, limit)
• POST /workspace/{workspaceId}/commands — Create a command
• GET /workspace/{workspaceId}/commands/suggestions?query=... — Suggest commands
• GET /workspace/{workspaceId}/command/{trigger} — Get a command
• PATCH /workspace/{workspaceId}/command/{trigger} — Update a command
• DELETE /workspace/{workspaceId}/command/{trigger} — Delete a command
• POST /workspace/{workspaceId}/command/{trigger}/execute — Execute a command
  • Body: { "args": ["..."], "threadId": "optional", "toolCallId": "optional" }
• GET /workspace/{workspaceId}/command/{trigger}/executions/{runId} — Execution status
• GET /workspace/{workspaceId}/command/{trigger}/executions/{runId}/output — Stream command output (ReadableStream)
• GET /workspace/{workspaceId}/command/{trigger}/executions/{runId}/events — Stream command events (SSE)
• DELETE /workspace/{workspaceId}/command/{trigger}/executions/{runId} — Cancel execution
• GET /workspace/{workspaceId}/commands/search?query=... — Full-text command search
• GET /workspace/{workspaceId}/commands/categories — List categories
• GET /workspace/{workspaceId}/commands/categories/{category} — Commands by category
• GET /workspace/{workspaceId}/commands/recent?limit=5 — Recently used
• GET /workspace/{workspaceId}/commands/popular?limit=5 — Popular commands

​

Processes

• POST /workspace/{workspaceId}/processes/{processId}/runs — Create a process run
  • Body: { "spec": <processSpec>, "inputs": { ... }, "metadata": { ... }, "instructions": "..." }
• GET /workspace/{workspaceId}/processes/{processId}/runs — List runs for a process
• POST /workspace/{workspaceId}/processes/runs/{runId}/start — Start a run
• GET /workspace/{workspaceId}/processes/runs/{runId} — Get run
• GET /workspace/{workspaceId}/processes/runs/{runId}/logs — Get run logs
• GET /workspace/{workspaceId}/processes/runs/{runId}/events — Stream run events (SSE)
• POST /workspace/{workspaceId}/processes/runs/{runId}/pause — Pause
• POST /workspace/{workspaceId}/processes/runs/{runId}/resume — Resume
• POST /workspace/{workspaceId}/processes/runs/{runId}/cancel — Cancel
• POST /workspace/{workspaceId}/processes/runs/{runId}/approve — Approve (human-in-the-loop)
• POST /workspace/{workspaceId}/processes/runs/{runId}/tasks/{phaseId}/{taskId}/retry — Retry task
• POST /workspace/{workspaceId}/processes/runs/{runId}/tasks/{phaseId}/{taskId}/skip — Skip task

​

Streams Debug

• GET /workspace/{workspaceId}/streams/debug — Inspect active SSE/data streams and subscribers (debug only)

• SSE responses use text/event-stream and Vercel AI v2 data stream markers where applicable.
• Most GET/POST JSON responses follow { data: ... } or { message: ... } for mutation acknowledgement.
• File and directory download endpoints return binary data (set appropriate Accept headers or fetch as blob).