canonical: https://jentic.com/apis/replicas.dev/replicas

# Replicas API

The Replicas API creates and controls replicas: cloud workspaces where a coding agent such as claude, codex, or cursor works on your repositories. You start a replica from an environment with a first message, then send follow-up messages, manage chats and their queues, run shell commands, open terminal sessions, expose preview URLs for a port, and read or merge the GitHub pull requests the agent opens. Environments carry the variables, files, skills, tool-server connections, and start and warm hooks a workspace boots with, while automations launch replicas from triggers and learnings are loaded into every new workspace.

## For AI agents

Start cloud coding-agent workspaces on Replicas, message them, run commands, open previews, merge their pull requests, and manage the environments and automations they run with. Bearer API key auth.

## Scope

Does not handle source code hosting, CI test execution, or production application deployment. Use for creating and driving Replicas coding-agent workspaces and their environments and automations only.

## Capabilities

- Start a replica workspace from an environment with a first message and a chosen coding_agent
- Send follow-up messages to a replica chat and wait for the agent to finish its turn
- Run a shell command inside a replica and read its output and exit code
- Expose a public preview URL for a port running inside a replica
- Read and merge the GitHub pull requests a replica has opened
- Configure environment variables, files, skills, and start hooks that new workspaces boot with
- Create automations that launch replicas from triggers and retry failed executions

## Use cases

### Delegate coding tasks from your own agent

Your orchestrating agent hands a coding task to a Replicas workspace instead of doing it locally. It creates a replica with a name and message, optionally choosing coding_agent, model, and size (small, large, or ultra), waits for the agent's turn to finish, and reads the chats to see what was done.

Example prompt: Call POST `/v1/replica` with name set to 'fix-login-test' and message describing the bug, then GET `/v1/replica/{id}/wait` until it returns done: true

### Review and ship the agent's pull request

Once a replica has opened a pull request, the agent reads its details and, if checks pass, merges it by pr_url. Replicas returns 403 when the organization's security policy blocks agent merges, so a human gate can stay in place.

Example prompt: Call POST `/v1/replica/{id}/pull-requests/details` to read the open pull requests, then POST `/v1/replica/{id}/pull-requests/merge` with pr_url set to the approved one

### Hands-on checks inside a workspace

To verify a change, the agent runs commands in the replica with a timeout_seconds limit, opens a terminal session for longer work, and creates a preview URL for the port the app listens on so a person can click through it.

Example prompt: Call POST `/v1/replica/{id}/exec` with command set to 'npm test' and timeout_seconds set to 300, then POST `/v1/replica/{id}/previews` with port set to 3000

### Standardise workspaces with environments and automations

Environments define what every workspace starts with: variables, files, enabled skills, tool-server connections, and start and warm hooks. Automations then launch replicas from triggers with a prompt and an environment_id, and failed executions can be retried.

Example prompt: Call POST `/v1/environments/{environment_id}/variables` to add the variable, then POST `/v1/automations` with name, triggers, prompt, and environment_id

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/replica` | Create replica |
| POST | `/v1/replica/{id}/messages` | Send message |
| GET | `/v1/replica/{id}/wait` | Wait for replica |
| POST | `/v1/replica/{id}/exec` | Run command |
| POST | `/v1/replica/{id}/previews` | Create preview |
| POST | `/v1/replica/{id}/pull-requests/merge` | Merge pull request |
| POST | `/v1/environments` | Create environment |
| POST | `/v1/automations/{id}/trigger` | Trigger automation |

## Key resources

- **Replicas** — Cloud workspaces: create, list, read, rename, delete, wake, sleep, archive, wait, stream events, read history
- **Chats** — Conversations with the workspace agent: create, rename, delete, restore, interrupt, fork, set goals, manage queued messages
- **Exec and terminals** — Run shell commands and open, resize, stream, and close terminal sessions
- **Pull requests and previews** — Read, update, and merge GitHub pull requests; create and delete preview URLs for ports
- **Environments** — Variables, files, skills, skill registries, tool-server connections, start and warm hooks, warm pools, plugins
- **Automations** — Trigger-driven replica runs: create, update, trigger, list executions, retry
- **Repositories and learnings** — Connected repositories and repository sets; learnings loaded into every new workspace

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 60 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 47 / 100
  - Developer Experience & Jentic Compatibility: 68 / 100
  - AI-Readiness & Agent Experience: 53 / 100
  - Agent Usability: 73 / 100
  - Security: 60 / 100
  - AI Discoverability: 69 / 100
- **View full report:** https://jentic.com/apis/replicas.dev/replicas/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Replicas by hand means handling its bearer API key, polling the wait operation until a preparing replica is ready, and threading replica, chat, and environment ids through a large nested surface. Through Jentic you install once, import Replicas from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Replicas puts the replica id in the URL path (`/v1/replica/{id}/...`), so a rule can pin your agent to one workspace, and environment ids sit in the path the same way. You choose the operations it may call, so high-impact ones like shell exec, pull request merge, or replica deletion are not included unless you add them.
- **Credential handling:** Your Replicas API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'start a cloud coding agent workspace' or 'merge the replica's pull request', and Jentic returns the matching Replicas operation with its input schema so the agent calls the right endpoint.

## Related APIs

- **E2B** — Cloud sandboxes for running AI-generated code
- **GitHub** — Repositories and pull requests replicas work on
- **CircleCI** — CI pipelines that test replica pull requests

## FAQ

### What authentication does the Replicas API use?

Per its OpenAPI spec, the Replicas API uses a bearer token: an organization or personal API key created under Settings, API Keys, sent in the Authorization header. The two workspace identity discovery documents under /.well-known need no API key. Through Jentic, your key is stored encrypted by your own Jentic One instance and injected at execution time.

### How many replicas can run at once?

The spec states that an organization can have 100 API and automation replicas active or preparing at once. A new replica returns status preparing straight away, and GET `/v1/replica/{id}/wait` blocks until it has started and its agents finish their turns.

### Which coding agents can a Replicas workspace use?

The create replica operation takes a coding_agent value such as claude, codex, cursor, or opencode, with claude as the default, plus an optional model and a size of small, large, or ultra.

### What are the rate limits for the Replicas API?

The OpenAPI spec does not specify request rate limits beyond the concurrent replica cap. Check https://docs.replicas.dev for current limits.

### How do I start a Replicas workspace through Jentic?

Search Jentic for 'start a cloud coding agent workspace'. It returns POST `/v1/replica`, which requires a name and a first message; your agent fills those in and Jentic sends the call with your stored key. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Is there a Replicas MCP server?

You don't need an MCP server to give your agent Replicas. Jentic connects it directly from the API Directory: import it, store your API key once, and your agent calls it, finding the right operation by intent instead of loading a tool list for the whole surface into its context.

### Can I limit what my agent is allowed to do with the Replicas API?

Yes. For instance, allow POST `/v1/replica/42/messages`, GET `/v1/replica/42/wait`, and GET `/v1/replica/42/history` only, so the agent can talk to that one workspace and read its progress but cannot run shell commands, merge pull requests, or change environments or credentials. Every call it makes is logged.