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

<Note>
  The API and [Automations](/features/automations) are the supported channels for programmatic use. Do not script against the app or automate interactive CLI surfaces.
</Note>

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

## 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 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](/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.

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