> ## Documentation Index > Fetch the complete documentation index at: https://docs.tryreplicas.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Replica > Creates a new replica in your organization and sends an initial message to the coding agent. The workspace and agent are initialized asynchronously. ## OpenAPI ````yaml /openapi.json post /v1/replica openapi: 3.1.0 info: title: Replica API version: 2.0.0 description: >- The Replica API allows you to programmatically manage cloud workspaces for AI agents. Use this API to manage environments (the org-scoped primitive workspaces are created from — including variables, files, skills, MCPs, warm hooks, start hooks, and warm pools), create and manage replicas, send messages, manage chats, stream events, read connected repositories and repository sets, and configure automations. servers: - url: https://api.tryreplicas.com description: Production API security: - apiKey: [] tags: - name: Environments description: >- Manage environments — the primitive that workspaces are created from. Variables, files, skills, MCPs, warm-hooks, and warm-pools are all scoped to an environment. Every organization has a singleton Global environment whose values apply to every workspace. Personal environments are scoped to the authenticated user and can be standalone or source-backed by a team environment. - name: Repository description: >- Read repositories and repository sets connected to your organization. Repositories are the underlying GitHub-connection layer; bind them to an environment to use them in workspaces. - name: Replica description: Manage replicas (workspaces) for AI agents - name: Terminal description: Manage interactive terminal sessions in active workspaces - name: Preview description: Manage public preview URLs for workspace ports - name: Profile description: Read and update the authenticated user's profile - name: Credentials description: >- Manage coding-agent credentials for an organization or the authenticated user - name: Google Search Console description: >- Read Search Console properties, performance, sitemaps, and URL inspection results through a connected Google account - name: Slack description: Connect Slack identities and route threads to Replicas workspaces - name: Linear description: Connect Linear identities to Replicas accounts - name: Automation description: >- Create and manage automations that trigger replicas on a schedule or in response to events - name: Downloads description: Download Replicas applications - name: Analytics description: >- Read aggregated activity and usage metrics for your organization: compute minutes, workspaces created by source, and pull request throughput over a time range. - name: Presence description: >- Read and report ephemeral member presence: who is online, where they are (environment or workspace), and whether they are typing. Presence is backed by short-lived keys rather than the database and broadcast to other members over the events stream. paths: /v1/replica: post: tags: - Replica summary: Create Replica description: >- Creates a new replica in your organization and sends an initial message to the coding agent. The workspace and agent are initialized asynchronously. operationId: createReplica parameters: - name: X-Replicas-Api-Version in: header description: >- Optional dated API version. When omitted, the request blocks until the workspace reaches `active` and the response includes the populated engine details (legacy behavior). When set to `2026-05-17`, the request returns immediately with a `preparing` workspace; the initial message is still delivered to the agent in the background. See the [API Versioning](/features/api#api-versioning) section for details. required: false schema: type: string enum: - '2026-05-17' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateReplicaRequest' responses: '201': description: Replica created successfully content: application/json: schema: $ref: '#/components/schemas/CreateReplicaResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '404': description: Repository or repository set not found content: application/json: schema: $ref: '#/components/schemas/Error' '409': $ref: '#/components/responses/Conflict' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' components: schemas: CreateReplicaRequest: type: object description: Request body for creating a new replica properties: name: type: string description: Human-readable name for the replica. Must not contain whitespace. pattern: ^\S+$ message: type: string description: Initial message to send to the coding agent environment_id: type: string format: uuid description: >- ID of the environment to use. The server derives the repository or repository set from the environment binding. Required unless `repository_set_id` or `repository_ids` is provided for backwards compatibility. repository_set_id: type: string format: uuid deprecated: true description: >- Deprecated. Use `environment_id` instead. Provided for backwards compatibility: the server resolves the first environment bound to this repository set. repository_ids: type: array items: type: string format: uuid deprecated: true description: >- Deprecated. Use `environment_id` instead. Provided for backwards compatibility: the server resolves the first environment bound to one of the given repositories. coding_agent: type: string description: Coding agent to use enum: - claude - codex - cursor - opencode - pi default: claude model: type: string description: >- Model to use for the coding agent. Pi and Opencode accept z-ai/glm-5.2, minimax/minimax-m3, xiaomi/mimo-v2.5-pro, and moonshotai/kimi-k2.6 through OpenRouter. images: type: array items: $ref: '#/components/schemas/ImageContent' description: Images to attach to the initial message lifecycle_policy: type: string description: Lifecycle policy for the replica enum: - default - archive_when_done - sleep_when_done - delete_after_inactivity config: $ref: '#/components/schemas/WorkspaceConfig' plan_mode: type: boolean description: >- Whether to run the initial message in plan mode. Leading `/plan` in the message is also detected and stripped. goal_mode: type: boolean description: >- Whether to set the initial message as the active Codex goal. Leading `/goal` in the message is also detected and stripped. fast_mode: type: boolean description: >- Whether to run the initial message in fast mode. Leading `/fast` in the message is also detected and stripped. thinking_level: type: string description: >- Thinking/reasoning level. Controls how much effort the agent puts into reasoning. `ultra` is Codex-only; `ultracode` is Claude Code-only. Falls back to provider default when omitted (Claude default: high, Codex default: medium, Cursor default: medium, Opencode default: medium, Pi default: model default). enum: - low - medium - high - xhigh - max - ultra - ultracode webhook_url: description: >- Callback target for `replica.ready`, `replica.turn_completed`, `replica.deleted`, and `replica.error` events. `replica.deleted` fires only on explicit deletion; closing a linked PR or issue now archives the workspace silently, so automated cleanup no longer emits it. `replica.error` is emitted when the workspace enters `error` state and remains queryable; the payload includes the failure message. Some wake/resume errors can be retried with the wake endpoint. Pass a bare URL string or `{ url, secret }`; with a secret the platform sets `X-Replicas-Signature: sha256=` on every delivery. oneOf: - type: string format: uri - $ref: '#/components/schemas/ReplicaWebhookConfig' size: type: string description: >- Compute size for this replica. `small` (2 vCPU, 8 GB memory, 20 GB disk) bills at $0.008/min; `large` (4 vCPU, 16 GB memory, 32 GB disk) bills at $0.016/min. Defaults to `small` when omitted. enum: - small - large required: - name - message CreateReplicaResponse: type: object properties: replica: $ref: '#/components/schemas/ReplicaListItem' required: - replica Error: type: object properties: error: type: string description: Error message details: type: - string - 'null' description: Additional error details required: - error ImageContent: type: object description: An image attachment for messages properties: type: type: string const: image description: Content type, always 'image' source: type: object description: Image source data oneOf: - type: object properties: type: type: string const: base64 media_type: type: string enum: - image/png - image/jpeg - image/gif - image/webp description: MIME type of the image data: type: string description: Base64-encoded image data required: - type - media_type - data - type: object properties: type: type: string const: url url: type: string format: uri description: URL to the image required: - type - url required: - type - source WorkspaceConfig: type: object description: >- Workspace behavior configuration. Missing capabilities and preferences default to disabled. properties: capabilities: type: object description: >- Actions this workspace is allowed to perform. Automations snapshot this config onto each workspace they create; API-created replicas can set it at creation time. properties: pr_followups: type: boolean description: >- Whether matching pull requests can receive Replicas follow-up actions. Defaults to true for workspaces created from the dashboard, Slack, Linear, GitHub, or the API, and to false for workspaces created from an automation. When enabled, later CI and review-comment replies can route back to this workspace. additionalProperties: true preferences: type: object description: >- Workspace behavior preferences that do not grant new action permissions. properties: keep_open_on_pr_merge: type: boolean description: >- Whether the workspace should remain open after its last tracked PR is merged. Defaults to false. default: false keep_open_on_pr_close: type: boolean description: >- Whether the workspace should remain open after its last tracked PR is closed without merging. Defaults to false. default: false additionalProperties: true provisioning_error: type: object description: >- Setup/provisioning or wake/resume failure captured when the workspace remains queryable in `error` status. Some wake/resume failures can be retried; the `error` status can also represent an unrecoverable sandbox failure. properties: message: type: string description: >- Underlying setup failure message, such as repository clone/auth errors. additionalProperties: true additionalProperties: true ReplicaWebhookConfig: type: object properties: url: type: string format: uri description: HTTPS endpoint the platform POSTs JSON events to. secret: type: string description: >- Optional shared secret used to compute the `X-Replicas-Signature` header (`sha256=` HMAC of the raw JSON body). required: - url ReplicaListItem: type: object description: A replica item in list responses properties: id: type: string format: uuid description: Unique identifier for the replica name: type: string description: Human-readable name for the replica. Must not contain whitespace. pattern: ^\S+$ status: type: string description: Current status of the replica enum: - active - sleeping - archived - preparing - error source: type: string description: How the replica was created enum: - api - dashboard - slack - linear - github - gitlab - automation created_at: type: string format: date-time description: Timestamp when the replica was created last_activity_at: type: - string - 'null' format: date-time description: Timestamp of the last activity on the replica repositories: type: array items: $ref: '#/components/schemas/RepositoryReference' description: Repositories associated with the replica pull_requests: type: array items: $ref: '#/components/schemas/PullRequest' description: Associated pull requests required: - id - name - status - source - created_at - last_activity_at - repositories - pull_requests RepositoryReference: type: object description: A repository reference in replica list items properties: id: type: string format: uuid description: Repository ID name: type: string description: Repository name url: type: string format: uri description: Repository URL required: - id - name - url PullRequest: type: object description: A pull request associated with a replica properties: repository: type: string description: Repository name number: type: integer description: Pull request number url: type: string format: uri description: URL to the pull request required: - repository - number - url responses: BadRequest: description: Bad request - Missing or invalid parameters content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/Error' PaymentRequired: description: >- Payment Required - The organization is out of included minutes or its free trial has ended content: application/json: schema: type: object properties: error: type: string description: Error message code: type: string enum: - INSUFFICIENT_MINUTES - TRIAL_EXPIRED description: Machine-readable billing block reason required: - error - code Conflict: description: >- Conflict - Resource already exists or operation conflicts with current state content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' ServiceUnavailable: description: >- Service unavailable - The service is temporarily overloaded or under maintenance content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: apiKey: type: http scheme: bearer description: >- API key authentication. Obtain your API key from the Replicas dashboard under Organization → Settings → API Keys. ````