Skip to main content
The Replicas API covers what you can do in the app: create and message workspaces, control their agents, and manage the environments, automations, and learnings they run with. The API Reference tab documents every endpoint.
The API, MCP server, CLI, and Automations are the supported ways to use Replicas programmatically. Do not script the app.

Authenticate

Send an API key as a bearer token to https://api.replicas.dev:
Trial organizations can create keys once onboarding is finished. Store keys in a secret manager. Never commit them or put them in prompts.

Create a replica

The API calls workspaces replicas. A replica starts from an environment, which supplies its repositories and configuration. Find the environment’s ID:
Then create the replica with its first message:
The response returns at once with status: "preparing". To follow progress, stream events once the replica is active, wait for its agents to finish, or set webhook_url to receive replica.ready and replica.turn_completed callbacks. Replicas created through the API default to lifecycle_policy: "delete_when_done": the replica is deleted as soon as its agents finish, and its history can no longer be read. Pass "lifecycle_policy": "default" to keep it for follow-up messages or reading history, or "sleep_when_done" to pause it until the next message. See workspace lifecycle for when to use each.

Work with a replica

Replicas move through these states: You can also wake, sleep, archive, and delete replicas directly. Reading a replica, its chats, history, or Canvas never wakes it.

Automations

Automations run a prompt in a new replica on a schedule or event:
See Automations for every trigger type.

Access

GET /v1/whoami shows which organization and identity a key acts as. A personal key acts as you, so it reaches the replicas you can see in the app: your own, ones shared with you, ones started by the API, automations, and integrations, and teammates’ when an admin turns on Workspace Visibility. An organization key acts for the organization: it reaches organization-owned replicas, like ones it created or ones from organization automations, and every replica when Workspace Visibility is on. Only a replica’s owner can share it; anyone with access can share an organization-owned replica. Environments and automations use access roles. Reading or using one requires environments:read or automations:read. Changing one requires environments:write or automations:write, which also covers an environment’s plugins. Write includes read. Creating a shared automation requires organization-wide automations:write. Any key can read the balance. Usage needs an admin’s personal key. Managing repositories and organization agent credentials requires an admin’s personal key. Personal agent credentials need a personal key. Starting a plugin’s OAuth flow and approving pull requests act on a person’s accounts, so they need a personal key.

Billing

Creating or waking a replica returns 402 when the organization is out of credit or reached its usage limit. The body has a code, a message, and the same balance as GET /v1/organization/billing/balance. To stop a loop before that happens, check limit.remaining_cents and blocked:

Versioning

Send X-Replicas-Api-Version: 2026-10-07 on every request: Request field names are the same in every version: send the snake_case names shown in the API reference. Fields that were added in camelCase still accept it. Without the header, responses use the earlier field names during the migration period.