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

# Send message

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

## Request

- Base URL: `https://api.replicas.dev`
- URL: `https://api.replicas.dev/v1/replica/{id}/messages`
- Auth: HTTP bearer

Sends a message to a chat. Sleeping replicas wake and archived replicas restore first. Messages sent while the agent is working are queued.

## Path parameters

- `id` string, uuid, required

## Headers

- `X-Replicas-Api-Version` '2026-10-07'

## Request body

- SendReplicaMessageRequest: Request body for sending a message to a workspace
  - `message` string, required: Message to send to the coding agent
  - `coding_agent` 'claude' | 'codex' | 'cursor' | 'muse' | 'opencode' | 'pi': Coding agent to use. With `chat_id`, naming another agent than the chat's continues that chat on it, with the conversation handed over.
  - `chat_id` string: Target a specific chat session
  - `model` string: Model ID. Defaults to the organization default for the coding agent.
  - `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 goal (Claude Code and Codex). 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': Reasoning effort. `ultra` is for Codex and Muse Code; `ultracode` is for Claude Code. Defaults to the agent's default.
  - `sender_email` 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 workspace
  - `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.dev/replicas/apis/replicas-api.md) - [All operations](https://skmtc.dev/replicas/apis/replicas-api/llms.txt) - [OpenAPI document](https://skmtc.dev/replicas/apis/replicas-api/revisions/2703ac1c9cb7?raw)