API guide

Use the Replicas API to create workspaces, send messages to coding agents, manage environments and automations, and stream workspace events.

The API and Automations are the supported channels for programmatic use. Do not script against the app or automate interactive CLI surfaces.

Prerequisites

Before using the API:

Add a repository and configure an environment.
Connect credentials for at least one coding agent.
Create an API key.

Organization admins create shared keys under Organization → Settings → API Keys. Any member can create a personal key under Personal → API Keys.

Authentication

Send the key as a bearer token. The key identifies the organization, so no separate organization header is required.

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:

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.

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:

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.

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

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

Get started

Workspaces

Coding agents

Integrations

Build and automate

Apps

Admin

Updates

Prerequisites

Authentication

Onboarding state

Repository branches

Create a workspace

Manage queued messages

Fork a chat to another harness

Workspace lifecycle

Workspace SSH transport

Environments API

Environment access

Environment plugins

Canvas

Media

Automations API

Create an automation

API versioning

API reference

​Prerequisites

​Authentication

​Onboarding state

​Repository branches

​Create a workspace

​Manage queued messages

​Fork a chat to another harness

​Workspace lifecycle

​Workspace SSH transport

​Environments API

​Environment access

​Environment plugins

​Canvas

​Media

​Automations API

​Create an automation

​API versioning

​API reference

Prerequisites

Authentication

Onboarding state

Repository branches

Create a workspace

Manage queued messages

Fork a chat to another harness

Workspace lifecycle

Workspace SSH transport

Environments API

Environment access

Environment plugins

Canvas

Media

Automations API

Create an automation

API versioning

API reference