Replica API - Replicas Docs

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

Organization admins can generate an API key from Settings > API Keys in the dashboard. Include it as a Bearer token in requests:

curl -X GET "https://api.tryreplicas.com/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.tryreplicas.com/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.tryreplicas.com/v1/replica" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "fix-auth-bug",
    "environment_id": "ENVIRONMENT_UUID",
    "message": "Fix the login timeout issue in src/auth.ts",
    "coding_agent": "claude",
    "model": "sonnet"
  }'

The selected environment determines which repository or repository set is checked out, and which variables, files, skills, MCPs, hooks, warm pool, and system prompt apply. 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.tryreplicas.com/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.tryreplicas.com/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.tryreplicas.com/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

Environments

Workspaces are created from environments. Each environment can be bound to a repository or repository set and carries the runtime configuration for the workspace (variables, files, skills, MCPs, warm hooks). The full environment management surface is available via the API — see Environments API below.

Chat Management

Each workspace can have multiple chat sessions with different coding agents:

# List chats
curl "https://api.tryreplicas.com/v1/replica/{id}/chats" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Create a new chat
curl -X POST "https://api.tryreplicas.com/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.tryreplicas.com/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.tryreplicas.com/v1/replica/{id}/messages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Refactor the auth module",
    "plan_mode": true
  }'

Thinking Level

Control how much reasoning the agent applies with thinking_level:

curl -X POST "https://api.tryreplicas.com/v1/replica/{id}/messages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Architect a new microservice for payments",
    "thinking_level": "max"
  }'

Level	Claude	Codex	Description
`low`	`low`	`low`	Minimal thinking, fastest responses
`medium`	`medium`	`medium`	Moderate reasoning depth
`high`	`high`	`high`	Deep reasoning
`max`	`max`	`xhigh`	Maximum effort

Provider defaults when omitted: Claude = high, Codex = medium. Also supported in POST /v1/replica when creating a replica.

Images

Attach images (screenshots, diagrams) to messages:

curl -X POST "https://api.tryreplicas.com/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.tryreplicas.com/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.tryreplicas.com/v1/replica/{id}/hooks" \
  -H "Authorization: Bearer YOUR_API_KEY"

Environments API

Environments are the primitive that ties together a repository binding plus the runtime configuration (variables, files, skills, MCPs, warm hooks) applied to every workspace created from them. See Environments for feature details. Every organization has a singleton Global environment that applies to every workspace. You can address it in any URL by passing the literal string global instead of a UUID — there’s no need to look up its ID first.

# These are equivalent once you know the UUID
curl ".../v1/environments/global"           -H "Authorization: Bearer KEY"
curl ".../v1/environments/<global-uuid>"    -H "Authorization: Bearer KEY"

List Environments

curl "https://api.tryreplicas.com/v1/environments" \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns every environment in the organization, including the Global env, with counts of attached variables / files / skills / MCPs.

Get an Environment

curl "https://api.tryreplicas.com/v1/environments/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Or address the org's Global environment directly:
curl "https://api.tryreplicas.com/v1/environments/global" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create an Environment

curl -X POST "https://api.tryreplicas.com/v1/environments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "staging",
    "description": "Staging deploys",
    "repository_id": "REPO_UUID",
    "system_prompt": "You target staging only — never push to main."
  }'

repository_id and repository_set_id are mutually exclusive; both can be omitted if you want an unbound environment.

Update an Environment

curl -X PATCH "https://api.tryreplicas.com/v1/environments/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "staging-eu",
    "system_prompt": "Region: eu-west-1."
  }'

The Global environment’s metadata cannot be edited via PATCH (only its nested resources — variables, files, etc.).

Delete an Environment

curl -X DELETE "https://api.tryreplicas.com/v1/environments/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns 409 when an automation still references the environment, or when called against the Global environment.

Variables

# List
curl "https://api.tryreplicas.com/v1/environments/{environmentId}/variables" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Create
curl -X POST "https://api.tryreplicas.com/v1/environments/{environmentId}/variables" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "key": "DATABASE_URL", "value": "postgres://..." }'

# Update
curl -X PATCH "https://api.tryreplicas.com/v1/environments/{environmentId}/variables/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "value": "postgres://new-host/db" }'

# Delete
curl -X DELETE "https://api.tryreplicas.com/v1/environments/{environmentId}/variables/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Values are encrypted at rest. {environmentId} accepts global for the Global environment.

Files

Files are placed inside workspaces at the configured path. Max content size is 64 KB.

# Create
curl -X POST "https://api.tryreplicas.com/v1/environments/{environmentId}/files" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "AGENTS",
    "path": "~/AGENTS.md",
    "content": "# Project conventions\n..."
  }'

Same PATCH / DELETE / GET shape as variables.

Skills

Skills come from skills.sh. Search the catalog, then enable a skill on a specific environment.

# Search the catalog
curl "https://api.tryreplicas.com/v1/environment-skills/search?q=docker" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Enable a skill on an environment
curl -X POST "https://api.tryreplicas.com/v1/environments/{environmentId}/skills" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "docker",
    "slug": "docker",
    "source": "https://skills.sh/skill/docker"
  }'

# List enabled skills
curl "https://api.tryreplicas.com/v1/environments/{environmentId}/skills" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Disable a skill
curl -X DELETE "https://api.tryreplicas.com/v1/environments/{environmentId}/skills/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

MCPs

# List MCPs
curl "https://api.tryreplicas.com/v1/environments/{environmentId}/mcps" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Create a stdio MCP
curl -X POST "https://api.tryreplicas.com/v1/environments/{environmentId}/mcps" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "linear",
    "transport": "stdio",
    "config": {
      "command": "npx",
      "args": ["-y", "@linear/mcp"],
      "env": { "LINEAR_API_KEY": "..." }
    }
  }'

# Create an http MCP
curl -X POST "https://api.tryreplicas.com/v1/environments/{environmentId}/mcps" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "internal-tools",
    "transport": "http",
    "config": {
      "url": "https://mcp.example.com",
      "headers": { "Authorization": "Bearer ..." }
    }
  }'

transport may be stdio, http, or sse. PATCH and DELETE work on /v1/environments/{environmentId}/mcps/{id}.

Warm Hooks

Each environment has at most one active warm hook (a shell script that runs while pre-warming workspaces). The Global environment’s warm hook applies to every pool.

# Read the active warm hook + warm pool config for an environment
curl "https://api.tryreplicas.com/v1/environments/{environmentId}/warm-hooks" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Read the per-repo warm hooks defined in `replicas.json` / `replicas.yaml` for the env's bound repositories
curl "https://api.tryreplicas.com/v1/environments/{environmentId}/warm-hooks/repository-hooks" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Test a script without saving (useful while iterating)
curl -X POST "https://api.tryreplicas.com/v1/environments/global/warm-hooks/test" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "content": "#!/usr/bin/env bash\nset -euo pipefail\nbun install\n" }'

# Save without testing — persists and activates the hook immediately
curl -X POST "https://api.replicas.dev/v1/environments/global/warm-hooks/save" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "content": "#!/usr/bin/env bash\nset -euo pipefail\nbun install\n" }'

# Save and test — only persists the new active version when the test succeeds
curl -X POST "https://api.tryreplicas.com/v1/environments/global/warm-hooks/save-test" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "content": "#!/usr/bin/env bash\nset -euo pipefail\nbun install\n" }'

# Stream save & test with SSE (recommended — avoids gateway timeouts)
curl -N -X POST "https://api.replicas.dev/v1/environments/global/warm-hooks/save-test/stream" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{ "content": "#!/usr/bin/env bash\nset -euo pipefail\nbun install\n", "mode": "save_test" }'
# Streams SSE events: progress, output, complete (or error)

# Enable / disable the warm pool for an environment
curl -X PUT "https://api.tryreplicas.com/v1/environments/{environmentId}/warm-pools" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'

There are three mutation endpoints: test-only (runs without persisting), save-only (persists and activates immediately without testing), and save-and-test (persists only if the test passes). The test and save-test endpoints spin up a real isolated sandbox and run your script there. The streaming endpoint (POST .../warm-hooks/save-test/stream) returns Server-Sent Events so the connection stays alive during long-running hooks — use it instead of the synchronous save-test endpoint to avoid gateway timeouts. Events include progress (status messages), output (captured stdout/stderr), and complete (final exit_code, timed_out, and the saved warm_hook record on success). The mode field can be "save_test" (default, persists on success) or "test_only".

Automations API

Automations let you trigger replicas on a schedule or in response to GitHub events. The full CRUD is available via the API. See Automations for feature details.

List Automations

curl "https://api.tryreplicas.com/v1/automations?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create an Automation

Create a cron-triggered automation that runs every weekday at 9am:

curl -X POST "https://api.tryreplicas.com/v1/automations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "daily-code-review",
    "prompt": "Review open PRs and leave comments on code quality issues",
    "environment_id": "ENVIRONMENT_UUID",
    "triggers": [
      {
        "type": "cron",
        "config": {
          "schedule": "0 9 * * 1-5",
          "timezone": "America/New_York"
        }
      }
    ]
  }'

Create a GitHub-triggered automation that fires when a PR is opened:

curl -X POST "https://api.tryreplicas.com/v1/automations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "pr-review",
    "prompt": "Review this PR for bugs and suggest improvements",
    "environment_id": "ENVIRONMENT_UUID",
    "triggers": [
      {
        "type": "github",
        "config": {
          "event": "pull_request.opened"
        }
      }
    ],
    "workspace_lifecycle_policy": "delete_when_done"
  }'

The automation runs against the repository (or repository set) bound to the chosen environment. See [Environments](/features/environments) for how to obtain an `environment_id`.

Get an Automation

curl "https://api.tryreplicas.com/v1/automations/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Update an Automation

curl -X PATCH "https://api.tryreplicas.com/v1/automations/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'

Delete an Automation

curl -X DELETE "https://api.tryreplicas.com/v1/automations/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Manually Trigger an Automation

Only works for automations with a cron trigger:

curl -X POST "https://api.tryreplicas.com/v1/automations/{id}/trigger" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

List Execution History

curl "https://api.tryreplicas.com/v1/automations/{id}/executions?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Workspace Lifecycle

Status	Description
`preparing`	Workspace is being created and initialized
`active`	Workspace is running and ready for messages
`sleeping`	Workspace is paused (auto-wakes on interaction)

When you interact with a sleeping workspace, it wakes automatically. The response will include waking: true. When a warm pool is configured for the target repository or repository set, expect setup times under 10 seconds. Otherwise, expect 10-60 seconds depending on repository size.

Prerequisites

Before using the API:

Add your repository in the dashboard
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.

Getting Started

Features

Admin

Updates

Documentation Index

​Authentication

​Quick Start

​1. List Available Repositories

​2. Create a Replica

​3. Send a Follow-up Message

​4. Check Status

​5. Stream Events (SSE)

​Key Concepts

​Environments

​Chat Management

​Plan Mode

​Thinking Level

​Images

​Chat History

​Hooks

​Environments API

​List Environments

​Get an Environment

​Create an Environment

​Update an Environment

​Delete an Environment

​Variables

​Files

​Skills

​MCPs

​Warm Hooks

​Automations API

​List Automations

​Create an Automation

​Get an Automation

​Update an Automation

​Delete an Automation

​Manually Trigger an Automation

​List Execution History

​Workspace Lifecycle

​Prerequisites

​Use Cases

​Billing

​API Reference

Authentication

Quick Start

1. List Available Repositories

2. Create a Replica

3. Send a Follow-up Message

4. Check Status

5. Stream Events (SSE)

Key Concepts

Environments

Chat Management

Plan Mode

Thinking Level

Images

Chat History

Hooks

Environments API

List Environments

Get an Environment

Create an Environment

Update an Environment

Delete an Environment

Variables

Files

Skills

MCPs

Warm Hooks

Automations API

List Automations

Create an Automation

Get an Automation

Update an Automation

Delete an Automation

Manually Trigger an Automation

List Execution History

Workspace Lifecycle

Prerequisites

Use Cases

Billing

API Reference