> ## Documentation Index
> Fetch the complete documentation index at: https://docs.re-factor.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspaces API

This page documents the Workspace endpoints exposed by the deploy server (`libs/deploy-server/src/server/routes/workspaces.ts`). All endpoints require Bearer authentication and are namespaced under your gateway base URL (e.g., `https://gateway.re-factor.ai/v2/api`). Replace `{workspaceId}` and other path params with real values.

### 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

Example: create workspace

```bash theme={null}
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)

Stores `.rfctr/workspace-config.rfctr.yaml` in the workspace directory.

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

Example update payload

```json theme={null}
{
  "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

Streaming

* 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

Thread example payload (save/update)

```json theme={null}
{
  "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:
    ```json theme={null}
    { "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)

Notes

* 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`).