Skip to main content
POST
/
v1
/
agent
/
{id}
/
messages
Send Message
curl --request POST \
  --url https://api.app.shinzo.ai/v1/agent/{id}/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "content": "<string>",
  "metadata": {},
  "channel": "<string>",
  "queue_mode": "<string>"
}
'

Documentation Index

Fetch the complete documentation index at: https://docs.shinzo.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Authentication

Requires JWT token or Platform API key via Authorization: Bearer <token> header.
​
id
string
required
Agent UUID
​
content
string
required
Message content
​
metadata
object
Arbitrary metadata to attach to the message
​
channel
string
default:"api"
Channel to send through: api or discord
​
queue_mode
string
default:"collect"
Queue behavior: collect or interrupt

​
Queue Modes

ModeDescription
collectBatches the message for processing when the agent finishes its current task. This is the default behavior.
interruptCancels the agent’s current task and processes your message immediately.

​
Example Request

curl -X POST https://api.app.shinzo.ai/v1/agent/a1b2c3d4-e5f6-7890-abcd-ef1234567890/messages \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Review the code in /workspace/src and provide feedback",
    "metadata": {
      "project": "frontend-app"
    },
    "queue_mode": "collect"
  }'

​
Example Response

{
  "id": "msg_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "role": "user",
  "content": "Review the code in /workspace/src and provide feedback",
  "status": "pending",
  "channel": "api",
  "queue_mode": "collect",
  "created_at": "2025-01-20T10:00:00Z"
}

​
Status Codes

CodeDescription
201Message sent successfully
400Invalid request (validation error)
401Unauthorized - invalid or missing authentication
404Agent not found
503Agent unavailable (stopped or error state)