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 tohttps://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: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: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 returns402 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
SendX-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.