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>"
}
'

POST

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>"
}
'

Authentication

Requires JWT token or Platform API key via Authorization: Bearer <token> header.

string

required

Agent UUID

string

required

Message content

object

Arbitrary metadata to attach to the message

string

default:"api"

Channel to send through: api or discord

string

default:"collect"

Queue behavior: collect or interrupt

Queue Modes

Mode	Description
`collect`	Batches the message for processing when the agent finishes its current task. This is the default behavior.
`interrupt`	Cancels 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

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

Overview

Authentication

AI Agents

Agent Messaging

Agent Schedules & Triggers

Agent Channels

Agent Filesystem

MCP Servers

Spotlight

Tokens

Provider Keys

Telemetry

Send Message

Authentication

Queue Modes

Example Request

Example Response

Status Codes

​Authentication

​Queue Modes

​Example Request

​Example Response

​Status Codes

Authentication

Queue Modes

Example Request

Example Response

Status Codes