---
title: "Send Message"
method: POST
path: "/v1/replica/{id}/messages"
tags: ["Replica"]
---

# Send Message

`POST /v1/replica/{id}/messages`

Sends a message to an existing replica. Supports targeting a specific chat, choosing a coding agent and model, attaching images, and enabling plan mode.

## Path parameters

- `id` string, uuid, required

## Request body

- SendReplicaMessageRequest — Request body for sending a message to a replica
  - `message` string, required — Message to send to the coding agent
  - `coding_agent` 'claude' | 'codex' | 'cursor' | 'opencode' | 'pi' — Coding agent to use
  - `chat_id` string — Target a specific chat session
  - `model` string — Model to use for this message. 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` ImageContent[] — Images to attach to the message
    - `type` 'image', required — Content type, always 'image'
    - `source` union, required — Image source data
      - object
        - `type` 'base64', required
        - `media_type` 'image/png' | 'image/jpeg' | 'image/gif' | 'image/webp', required — MIME type of the image
        - `data` string, required — Base64-encoded image data
      - object
        - `type` 'url', required
        - `url` string, uri, required — URL to the image
  - `plan_mode` boolean — Whether to run in plan mode. Leading `/plan` in the message is also detected and stripped.
  - `goal_mode` boolean — Whether to set the message as the active Codex goal. Leading `/goal` in the message is also detected and stripped.
  - `fast_mode` boolean — Whether to run in fast mode. Leading `/fast` in the message is also detected and stripped.
  - `thinking_level` 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'ultra' | 'ultracode' — 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).
  - `senderUserId` string — Identifier of the user sending this message. When the request is authenticated via dashboard auth, the server overrides this with the authenticated user's id so team workspaces can attribute messages to the actual sender.
  - `senderEmail` string — Email of the user sending this message. When the request is authenticated via dashboard auth, the server overrides this with the authenticated user's email.

## Response `200`

Message accepted

- SendReplicaMessageResponse — Response after sending a message to a replica
  - `status` 'sent' | 'queued' | 'waking', required — Status of the message delivery
  - `message_id` string, nullable, required — Unique identifier for the sent message
  - `position` integer, nullable, required — Queue position if status is 'queued'
  - `chat_id` string, nullable, required — ID of the chat the message was sent to

## Other responses

- `400` — Bad request - Missing or invalid parameters
- `401` — Unauthorized - Invalid or missing API key
- `404` — Resource not found
- `409` — Conflict - Resource already exists or operation conflicts with current state
- `500` — Internal server error
- `502` — Bad gateway - The workspace is unreachable or returned an invalid response
- `503` — Service unavailable - The service is temporarily overloaded or under maintenance

---

[API](https://skmtc.net/tryreplicas/apis/replica-api.md) · [All operations](https://skmtc.net/tryreplicas/apis/replica-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tryreplicas/replica-api/versions/aa3b4c932f7a/schema)