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. Every endpoint in the API Reference supports API key authentication.

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 workspaces wake automatically when you interact with them. Message requests automatically restore archived workspaces. API reads leave them archived. 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.

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.

Event streaming requires an active workspace. Send a message to wake a suspended workspace before opening its event stream.

Environments API

Environments define the repositories, variables, files, skills, MCP servers, 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, 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. Write includes Read. Manage roles and grants in the dashboard. See Access.

Media

Use the media URL endpoints to retrieve 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: images uploaded from workspaces always get one, video and audio can opt in, and HTML never does.

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",
    "agent_provider": "codex",
    "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.

Workspace identity

GET /v1/environments/{environmentId}/workload-identity returns the workspace identity issuer, discovery, and JWKS URLs. Tokens are minted inside the workspace, not through this API. HTTP MCPs can use auth: { "type": "workspace_identity", "audience": "YOUR_AUDIENCE" } instead of saved headers.

Get started

Workspaces

Coding agents

Integrations

Build and automate

Apps

Admin

Updates

Prerequisites

Authentication

Repository branches

Create a workspace

Workspace lifecycle

Environments API

Environment access

Media

Automations API

Create an automation

API versioning

API reference

Workspace identity

​Prerequisites

​Authentication

​Repository branches

​Create a workspace

​Workspace lifecycle

​Environments API

​Environment access

​Media

​Automations API

​Create an automation

​API versioning

​API reference

​Workspace identity

Prerequisites

Authentication

Repository branches

Create a workspace

Workspace lifecycle

Environments API

Environment access

Media

Automations API

Create an automation

API versioning

API reference

Workspace identity