Skip to main content
The Replica API lets you programmatically create workspaces, send messages to coding agents, manage chats, and monitor workspace state.
The Replica API and Automations are the only sanctioned channels for programmatic use of Replicas. Scripting against the dashboard, automating the CLI, or driving interactive surfaces from headless browsers is prohibited under our Terms of Service.

​
Authentication

API keys are available on the Developer plan and above. See Billing for plan details. Generate an API key from Settings > API Keys in the dashboard. Include it as a Bearer token in requests: 
curl -X GET "https://api.replicas.dev/v1/replica" \
  -H "Authorization: Bearer YOUR_API_KEY"
The API key identifies your organization automatically - no additional headers are needed. The CLI interacts with this API through JWT authentication, meaning usage through the CLI does not incur API usage costs.

​
Quick Start

​
1. List Available Repositories

Before creating a replica, list the repositories available in your organization: 
curl "https://api.replicas.dev/v1/replica/repositories" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
2. Create a Replica

The name field must not contain whitespace (e.g. fix-auth-bug, not fix auth bug). 
curl -X POST "https://api.replicas.dev/v1/replica" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "fix-auth-bug",
    "repository_ids": ["REPO_UUID"],
    "message": "Fix the login timeout issue in src/auth.ts",
    "coding_agent": "claude",
    "model": "sonnet"
  }'
You can also use a repository_set_id instead of repository_ids to target a group of repositories. Optional lifecycle_policy controls what happens when work is done:
  • default - workspace sleeps after inactivity (default)
  • delete_when_done - workspace is deleted when the agent finishes (useful for CI/CD)
  • delete_after_inactivity - workspace is deleted after a period of inactivity
The replica boots asynchronously and the message is delivered once ready.

​
3. Send a Follow-up Message

curl -X POST "https://api.replicas.dev/v1/replica/{id}/messages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Also add tests for the fix"
  }'
If the replica is sleeping, it wakes automatically. Messages queue if the agent is busy.

​
4. Check Status

curl "https://api.replicas.dev/v1/replica/{id}?include=environment" \
  -H "Authorization: Bearer YOUR_API_KEY"
Use include=environment to get detailed environment info, or include=diffs for full git diffs.

​
5. Stream Events (SSE)

curl -N "https://api.replicas.dev/v1/replica/{id}/events" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: text/event-stream"
Receive real-time updates including chat turns, repository changes, and hook progress.

​
Key Concepts

​
Repositories and Repository Sets

Workspaces are created from repositories that have been added to your organization. You can target:
  • repository_ids - One or more specific repository UUIDs
  • repository_set_id - A named collection of repositories
Use GET /v1/replica/repositories and GET /v1/replica/repository-sets to discover available targets.

​
Chat Management

Each workspace can have multiple chat sessions with different coding agents: 
# List chats
curl "https://api.replicas.dev/v1/replica/{id}/chats" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Create a new chat
curl -X POST "https://api.replicas.dev/v1/replica/{id}/chats" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "claude", "title": "Refactoring" }'

# Send to a specific chat
curl -X POST "https://api.replicas.dev/v1/replica/{id}/messages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Continue the refactoring", "chat_id": "CHAT_ID" }'

​
Plan Mode

Send a message in plan mode to get a plan before execution: 
curl -X POST "https://api.replicas.dev/v1/replica/{id}/messages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Refactor the auth module",
    "plan_mode": true
  }'

​
Images

Attach images (screenshots, diagrams) to messages: 
curl -X POST "https://api.replicas.dev/v1/replica/{id}/messages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Fix the layout issue shown in this screenshot",
    "images": [{
      "type": "image",
      "source": {
        "type": "base64",
        "media_type": "image/png",
        "data": "BASE64_DATA"
      }
    }]
  }'

​
Chat History

Read the message history for a chat (replaces the deprecated /read endpoint): 
curl "https://api.replicas.dev/v1/replica/{id}/history?chat_id={chatId}&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Hooks

View warm and start hook execution logs: 
curl "https://api.replicas.dev/v1/replica/{id}/hooks" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Workspace Lifecycle

StatusDescription
preparingWorkspace is being created and initialized
activeWorkspace is running and ready for messages
sleepingWorkspace is paused (auto-wakes on interaction)
When you interact with a sleeping workspace, it wakes automatically. The response will include waking: true. Organizations on the Team plan or higher with warm pools enabled can expect setup times under 10 seconds. Otherwise, expect 10-60 seconds depending on repository size.

​
Prerequisites

Before using the API:
  1. Add your repository in the dashboard
  2. Configure credentials for your coding agent (Claude or Codex)

​
Use Cases

  • CI/CD Integration - Trigger replicas from GitHub Actions or other pipelines
  • Batch Operations - Create multiple replicas for parallel task execution
  • Custom Workflows - Build internal tools that leverage AI coding agents
  • Monitoring - Stream events and poll workspace state for dashboards

​
Billing

API workspaces are metered separately from your seat subscription. See Billing for rates, rounding, and plan details.

​
API Reference

See the API Reference tab for complete endpoint documentation with request/response schemas.