Cosmic Logo

Agent messages

Send messages to an agent you already created, and read its conversations. This is the HTTP channel shown on the agent detail page under API tools.

To provision a new project for an agent that does not yet have a Cosmic account, see Agent signup. To configure channels, capabilities, and Slack, see Agents.

Base URL

https://dapi.cosmicjs.com

These endpoints live on the dashboard API, not the bucket API. Authenticate POST /messages and the conversation reads with a Personal Access Token (cos_ prefix) or a session JWT. The inbound webhook uses a per-agent secret instead of a Bearer token.

POST/v3/ai/agents/:agentId/messages

Send a message

After you create an agent, the endpoint URL is shown on the agent detail page. Create a token at Account Settings > API Tokens.

Required body

  • Name
    message
    Type
    string
    Description

    The message text.

Optional body

  • Name
    conversation_id
    Type
    string
    Description

    Continue an existing conversation. Omit to start a new one.

  • Name
    channel_metadata
    Type
    object
    Description

    Additional context passed to the agent.

  • Name
    model
    Type
    string
    Description

    Override the agent's default AI model.

  • Name
    context
    Type
    object
    Description

    Extra context for this message.

  • Name
    stream
    Type
    boolean
    Description

    Set to true to receive a streaming SSE response instead of JSON. See Streaming.

Request

POST
/v3/ai/agents/:agentId/messages
curl -X POST https://dapi.cosmicjs.com/v3/ai/agents/AGENT_ID/messages \
  -H "Authorization: Bearer cos_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Summarize our latest blog posts"}'

If the agent is still working on the previous message in that conversation, the request returns 202 with status: "queued" and the new message is processed next.

Streaming

Pass stream: true in the request body to receive a streaming response via Server-Sent Events (Content-Type: text/event-stream). Each event is a data: line containing JSON.

Event types

Event typeDescription
infoSent immediately with conversation_id and model
text_deltaIncremental text chunk with text and accumulated fullText
tool_progressStatus label while the agent executes a tool
doneFinal event with conversation_id, complete message, tokens_used, and model
awaiting_approvalAgent is waiting for approval, includes pending_approval details
errorAn error occurred, includes message

Request

POST
/v3/ai/agents/:agentId/messages
curl -N -X POST https://dapi.cosmicjs.com/v3/ai/agents/AGENT_ID/messages \
  -H "Authorization: Bearer cos_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Summarize our latest blog posts", "stream": true}'

data: {"type":"info","conversation_id":"abc123","model":"claude-opus-5"}

data: {"type":"text_delta","text":"Here","fullText":"Here"}

data: {"type":"tool_progress","label":"Fetching content..."}

data: {"type":"done","conversation_id":"abc123","message":"The latest posts cover...","tokens_used":1234,"model":"claude-opus-5"}
POST/v3/ai/agents/:agentId/webhook

Inbound webhook

Receive messages from external systems without a Personal Access Token. Enable the webhook channel on the agent. A webhook endpoint and secret are shown on the agent detail page. Use Reveal to view the secret and Copy to copy it.

If a webhook secret is compromised, click Regenerate on the agent detail page. The old secret stops working immediately.

Authenticate with one of these methods:

MethodHow to use
Query parameter?secret=YOUR_WEBHOOK_SECRET
HeaderX-Webhook-Secret: YOUR_WEBHOOK_SECRET
Header (alternate)X-Cosmic-Webhook-Secret: YOUR_WEBHOOK_SECRET
HMAC signatureX-Webhook-Signature: sha256=HMAC_HEX (HMAC-SHA256 of the raw request body using the secret as the key)

Required body

  • Name
    message
    Type
    string
    Description

    The message text.

Optional body

  • Name
    conversation_id
    Type
    string
    Description

    Continue an existing conversation.

  • Name
    metadata
    Type
    object
    Description

    Additional context passed to the agent.

Request

POST
/v3/ai/agents/:agentId/webhook
curl -X POST https://dapi.cosmicjs.com/v3/ai/agents/AGENT_ID/webhook?secret=YOUR_WEBHOOK_SECRET \
  -H "Content-Type: application/json" \
  -d '{"message": "New deployment completed successfully"}'

Use this for Zapier, GitHub Actions, or any automation that should not hold a Personal Access Token.

GET/v3/ai/agents/:agentId/conversations

List conversations

Authentication: Personal Access Token or session JWT.

Returns the agent's conversations. Conversations are scoped to the agent, not to a bucket.

GET/v3/ai/agents/:agentId/conversations/:conversationId

Get conversation history

Authentication: Personal Access Token or session JWT.

Returns one conversation and its messages. Optional query: messagesLimit, messagesOffset.

Related

  • Agents - channels, capabilities, Slack, /reset, and plan limits.
  • Personal Access Tokens - cos_ auth for /messages and conversation reads.
  • Agent signup - provision a project for an agent that does not yet have a Cosmic account.