Skip to main content
POST
/
v1
/
replica
/
{id}
/
messages
Send Message
curl --request POST \
  --url https://api.tryreplicas.com/v1/replica/{id}/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": "<string>",
  "chat_id": "<string>",
  "model": "<string>",
  "images": [
    {
      "type": "<string>",
      "source": {
        "type": "<string>",
        "data": "<string>"
      }
    }
  ],
  "plan_mode": true,
  "goal_mode": true,
  "fast_mode": true,
  "senderUserId": "<string>",
  "senderEmail": "<string>"
}
'
{
  "message_id": "<string>",
  "position": 123,
  "chat_id": "<string>"
}

Authorizations

​
Authorization
string
header
required

API key authentication. Obtain your API key from the Replicas dashboard under Settings > API Keys.

Path Parameters

​
id
string<uuid>
required

The unique identifier of the replica

Body

application/json

Request body for sending a message to a replica

​
message
string
required

Message to send to the coding agent

​
coding_agent
enum<string>

Coding agent to use

Available options:
claude,
codex,
cursor,
opencode
​
chat_id
string

Target a specific chat session

​
model
string

Model to use for this message

​
images
object[]

Images to attach to the message

​
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
enum<string>

Thinking/reasoning level. Controls how much effort the agent puts into reasoning. Falls back to provider default when omitted (Claude default: high, Codex default: medium, Cursor default: medium, Opencode default: medium).

Available options:
low,
medium,
high,
max
​
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

Message accepted

Response after sending a message to a replica

​
status
enum<string>
required

Status of the message delivery

Available options:
sent,
queued,
waking
​
message_id
string | null
required

Unique identifier for the sent message

​
position
integer | null
required

Queue position if status is 'queued'

​
chat_id
string | null
required

ID of the chat the message was sent to