> ## Documentation Index > Fetch the complete documentation index at: https://docs.replicas.dev/llms.txt > Use this file to discover all available pages before exploring further. # API guide > Authenticate, create workspaces, and build on the Replicas API. Use the Replicas API to create workspaces, send messages to coding agents, manage environments and automations, and stream workspace events. The API and [Automations](/features/automations) are the supported channels for programmatic use. Do not script against the app or automate interactive CLI surfaces. ## Prerequisites Before using the API: 1. Add a repository and configure an [environment](/features/environments). 2. Connect credentials for at least one [coding agent](/admin/credentials). 3. Create an API key. Organization admins create shared keys under [Organization → Settings → API Keys](https://replicas.dev/dashboard/settings?tab=api-keys). Any member can create a personal key under [Personal → API Keys](https://replicas.dev/dashboard/account/api-keys). ## Authentication Send the key as a bearer token. The key identifies the organization, so no separate organization header is required. ```bash theme={null} curl "https://api.replicas.dev/v1/replica/repositories" \ -H "Authorization: Bearer $REPLICAS_API_KEY" ``` | Key | Attribution | Access | | ------------ | ------------ | ------------------------------------------------------------- | | Organization | Replicas bot | Organization resources and automations | | Personal | Key owner | Organization automations and the owner's personal automations | Keep API keys in a secret manager. Do not place them in repositories, client-side code, or workspace prompts. ## Onboarding state First-party clients read onboarding progress with `GET /v1/organization/onboarding`. Authenticate with a logged-in user JWT and send the organization UUID in `Replicas-Org-Id`. The response contains `onboarding.completed` and these boolean values under `onboarding.steps`: `added_repository`, `skipped_repository`, `connected_code_editor`, `created_workspace`, `connected_integration`, `configured_github_triggers`, and `invited_member`. Call `POST /v1/organization/onboarding/steps/configured_github_triggers` to persist trigger setup. Call `POST /v1/organization/onboarding/complete` after connecting a coding agent, connecting GitHub or GitLab, and adding a repository. Both return `{ "success": true }`; invalid steps or incomplete mandatory setup return `400`. The legacy `skipped_repository` field no longer bypasses required setup. During repository setup, call `GET /v1/organization/onboarding/organizations?provider=github|gitlab` to list Replicas organizations connected to the same account or repository owners. GitHub users can call `POST /v1/organization/onboarding/organizations/{id}/join` when the response sets `canJoin` to `true`. Members can call `POST /v1/organization/onboarding/organizations/{id}/open` to dismiss the current organization's setup and open the existing organization. ## Repository branches List a connected repository's branches before choosing a task's starting point: ```bash theme={null} curl "https://api.replicas.dev/v1/repositories/REPOSITORY_UUID/branches" \ -H "Authorization: Bearer $REPLICAS_API_KEY" ``` The response contains up to 100 branches. Pass `?q=feature` to search branch prefixes without loading every branch in large repositories. Repository IDs come from `GET /v1/replica/repositories`. ## Create a workspace First, list environments and choose the environment that contains the repositories and configuration for the task. ```bash theme={null} curl "https://api.replicas.dev/v1/environments" \ -H "Authorization: Bearer $REPLICAS_API_KEY" ``` Create a workspace with a short machine-readable name, the environment ID, and the initial instruction: ```bash theme={null} curl -X POST "https://api.replicas.dev/v1/replica" \ -H "Authorization: Bearer $REPLICAS_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Replicas-Api-Version: 2026-05-17" \ -d '{ "name": "fix-login-timeout", "environment_id": "ENVIRONMENT_UUID", "message": "Fix the login timeout and open a pull request", "coding_agent": "claude" }' ``` The dated API version returns a `preparing` workspace immediately. Poll `GET /v1/replica/{id}` or stream `GET /v1/replica/{id}/events` until the workspace becomes active and the agent finishes. Send follow-up instructions with `POST /v1/replica/{id}/messages`. Sleeping workspaces wake automatically when you interact with them. Archived workspaces stay paused; message requests return `409 Conflict` until you explicitly restore the workspace with `POST /v1/workspaces/{id}/wake?restore=true`. A message accepted before a concurrent archive remains queued and runs after the workspace is restored. `GET /v1/replica` returns newest `created_at` first. With `status=archived`, results are ordered by most recent interaction instead: messages sent and agent turns completed. Waking a workspace does not change its position. ## Manage queued messages Read a chat's pending messages with `GET /v1/replica/{id}/chats/{chatId}/queue`. Delete one with `DELETE /v1/replica/{id}/chats/{chatId}/queue/{messageId}`, or clear the queue with `DELETE /v1/replica/{id}/chats/{chatId}/queue`. Successful removal responses include `removedMessageIds`. When caching chat history, retain these IDs and omit matching queued-message events from `GET /v1/replica/{id}/chats/{chatId}/history`; this prevents a stale or earlier history page from restoring a canceled message. ## Fork a chat to another harness Continue an existing chat on a different coding agent harness with `POST /v1/workspaces/{workspaceId}/chats/{chatId}/fork`. The source chat is left unchanged. ```bash theme={null} curl -X POST "https://api.replicas.dev/v1/workspaces/WORKSPACE_UUID/chats/CHAT_UUID/fork" \ -H "Authorization: Bearer $REPLICAS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "provider": "codex", "message": "Review the current changes and finish the implementation." }' ``` `message` is optional. When provided, it becomes the new harness's first instruction alongside the inherited context. Omit it or send an empty string to continue the source chat without new guidance. The response returns the new chat with `fork.state` set to `preparing`. Replicas sanitizes the source transcript, writes it into the workspace, and starts the new harness with the recent turns plus a reference to the full transcript; `fork.state` then becomes `ready` or `failed`. Poll `GET /v1/workspaces/{workspaceId}/chats` or stream workspace events to observe the change. The target harness must have credentials connected in the workspace, and the workspace must be active. A non-empty `message` returns `409 Conflict` when the workspace engine does not support fork messages; create a new workspace to use the field. See [Chat forking](/features/workspaces/chat-forking) for the user-facing behavior and automatic fallback. ## Workspace lifecycle | Status | Meaning | | ----------- | ---------------------------------------------------------- | | `preparing` | The workspace is starting or waking. | | `active` | The workspace can process messages. | | `sleeping` | Compute is paused and resumes on interaction. | | `archived` | The workspace is paused for retention and can be restored. | | `error` | Setup or wake failed and can be retried. | Engine-backed endpoints return `409 Conflict` while a workspace is sleeping, archived, or in error. Read the current workspace status before calling history, canvas, terminal, preview, or event endpoints. Pull request actions use the code host directly instead: `POST /v1/workspaces/{workspaceId}/pull-requests/merge` can merge an eligible GitHub pull request while its workspace is sleeping without waking it. Approval uses the requesting user's connected GitHub account and does not require the pull request's stored workspace link to match; close and draft-state actions still require that link. Preview URLs return `409 Conflict` while a workspace is preparing, sleeping, archived, or in error. Wait until it becomes active, or wake a suspended workspace before loading its previews. ## Workspace SSH transport First-party clients can request short-lived credentials for an active workspace with `POST /v1/workspaces/{workspaceId}/ssh-token`. Authenticate with a logged-in user JWT and send the workspace organization in `Replicas-Org-Id`. The response includes the SSH `token` and `host`. CLI clients can use `proxyCommand`; native clients can connect through `transport.url`, sending any `transport.headers` only during the secure WebSocket upgrade. Treat every returned value as a secret and do not persist it. See [Local tunnels](/features/desktop-app#local-tunnels) for the desktop workflow. ## Environments API Environments define the repositories, variables, files, skills, MCP servers, plugin connections, hooks, warm pools, and system prompt used to create workspaces. Use the `/v1/environments` endpoints to list, create, and update environments. Nested endpoints manage variables, files, skills, MCP servers, plugin connections, warm hooks, and start hooks. Personal environments use `scope: "user"`; organization environments use `scope: "org"`. The **Global** environment applies organization defaults to every workspace. Its metadata cannot be edited, but its nested resources can be managed through the same endpoints. ### Environment access Environment endpoints require `environments:read` to list, view, select, or use an environment and `environments:write` to change it or its nested configuration. Automation endpoints require `automations:read` and `automations:write` the same way, and creating a shared automation needs organization-wide `automations:write`. `analytics:read` opens the analytics overview. Write includes Read. See [Access](/admin/team#access) for the user-facing model. Organization admins manage custom roles with `/v1/organization/roles`, assign them with `PUT /v1/organization/members/{userId}/roles`, and read or replace grants with `/v1/organization/access` and `PUT /v1/organization/access/{subject}`, where `subject` is `everyone` or a role ID. A grant with a null `resource_id` covers every resource of that type. See the API Reference for request and response schemas. ### Environment plugins Use `/v1/environments/{environmentId}/plugins/connections` to read an environment's [plugin](/features/plugins) connections, and the nested `plugins/{pluginId}` endpoints to install or uninstall one. `environmentId` accepts a UUID or the literal `global`. ## Canvas Use `GET /v1/replica/{workspaceId}/canvas` to list files the agent writes to `~/.replicas/canvas/`. The response identifies Markdown plans, Mermaid diagrams, HTML pages, text, images, PDFs, video, and audio so clients can choose an appropriate viewer. Upload a chat attachment with `POST /v1/workspaces/{workspaceId}/canvas` as multipart form data containing `file` and an optional Canvas-relative `filename`. Active workspaces return `200`; preparing, sleeping, and archived workspaces return `202` and preserve the upload until startup completes. A queued upload response includes `uploadId`; pass those IDs as `canvasUploadIds` when sending the related chat message. The message wakes a sleeping workspace, then its files are written immediately before the message is delivered. Archived workspaces must be restored before sending a message. Save an editable Canvas file with `PUT /v1/workspaces/{workspaceId}/canvas/{filename}`. Save a repository file with `PUT /v1/workspaces/{workspaceId}/repo-files/content?repoName={repoName}&path={path}`. Both requests include `content` and the `expectedRevision` returned when the file was read. If the file changed meanwhile, the response returns `saved: false` with its current content and revision instead of overwriting it. Inspect a repository symbol with `GET /v1/workspaces/{workspaceId}/repo-files/symbol`, passing `repoName`, `path`, one-based `line`, zero-based `character`, and `action=hover|definition|references`. The response includes hover details or repository-relative locations from the language server, with workspace search as a fallback. See [Canvas](/features/workspaces/canvas) for the user-facing behavior. ## Media Use the workspace media endpoints for screenshots, recordings, generated images, audio, and other shareable assets. Request a short-lived download URL for files or a preview URL when a browser should render the object inline. Media access is organization-scoped. Public access uses revocable bearer URLs and is limited to supported image, video, and audio assets. ## Automations API The `/v1/automations` endpoints create and manage scheduled, GitHub, GitLab, Slack, Sentry, and webhook-triggered agent runs. ### Create an automation Create an automation with a name, prompt, trigger, and environment. Optional settings choose the coding agent, model, thinking level, workspace size, lifecycle policy, debounce window, and GitHub checks. ```bash theme={null} curl -X POST "https://api.replicas.dev/v1/automations" \ -H "Authorization: Bearer $REPLICAS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "daily-dependency-review", "prompt": "Review dependency updates and open a pull request when needed", "environment_id": "ENVIRONMENT_UUID", "triggers": [ { "type": "cron", "config": { "schedule": "0 9 * * 1-5", "timezone": "UTC" } } ] }' ``` See [Automations](/features/automations) for trigger behavior, lifecycle policies, GitHub checks, and billing. ## API versioning `POST /v1/replica` accepts `X-Replicas-Api-Version`. | Header | Behavior | | ------------ | -------------------------------------------------------- | | Omitted | Legacy request waits for the workspace to become active. | | `2026-05-17` | Request returns a preparing workspace immediately. | Pin a dated version so future API changes do not alter an integration unexpectedly. ## API reference Open the **API Reference** tab for endpoint schemas, parameters, responses, and interactive request examples generated from `openapi.json`.