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.

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 and archived workspaces wake automatically when you interact with them.

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.

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

Repository branches

Create a workspace

Workspace lifecycle

Environments API

Environment plugins

Canvas

Media

Automations API

Create an automation

API versioning

API reference

​Prerequisites

​Authentication

​Repository branches

​Create a workspace

​Workspace lifecycle

​Environments API

​Environment plugins

​Canvas

​Media

​Automations API

​Create an automation

​API versioning

​API reference

Prerequisites

Authentication

Repository branches

Create a workspace

Workspace lifecycle

Environments API

Environment plugins

Canvas

Media

Automations API

Create an automation

API versioning

API reference