Chat with an agent

POST https://www.chatmount.co/api/v2/agents/{agentId}/chat

Replace {agentId}with the UUID of the agent you’re chatting with. You can find this in your dashboard URL — chatmount.co/dashboard/…/chatbot/{agentId}.

Bearer token in the Authorization header. Generate keys from your workspace API keys settings (Plus tier or above). Keys are scoped to your entire workspace — one key works for every agent the workspace owns. The agent id in the URL is what tells us which agent to send the message to.

Authorization: Bearer YOUR_API_KEY

{
  "message": "Hello! How can you help me?",
  "stream": false,
  "conversationId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "userId": "user-123"
}

Fields:

• message (string, required)— the user’s message. Must be 1–2000 characters.
• stream (boolean, optional, default false) — when true, the response is sent as Server-Sent Events.
• conversationId (string, optional) — pass the same id across multiple requests to give the agent multi-turn memory. Omit it to start a fresh conversation; the response then returns a freshly-issued id you can reuse.
• userId (string, optional) — your own end-user identifier. Surfaces in analytics + chat logs so you can map conversations back to your own users.

{
  "data": {
    "id": "msg_abc123",
    "role": "assistant",
    "parts": [
      { "type": "text", "text": "Hello! I'm here to help. What can I assist you with today?" }
    ],
    "metadata": {
      "userMessageId": "msg_xyz789",
      "conversationId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "userId": null,
      "finishReason": "stop",
      "usage": { "credits": 2 }
    }
  }
}

• data.id — id of the assistant message.
• data.role — always "assistant" in this response; the field exists for parity with multi-turn message arrays.
• data.parts — array of message segments. The base case is a single { type: "text", text: "..." } entry; future part types (tool calls, source citations) extend this shape additively.
• data.metadata.userMessageId — id of the inbound user message that triggered this reply. Useful for joining client logs to server logs.
• data.metadata.conversationId — the conversation id the message was added to. Reuse this in the next request to keep context.
• data.metadata.userId — the userId you sent on the request, or nullif you didn’t pass one.
• data.metadata.finishReason — "stop" on a normal completion; other values mirror the underlying provider ("length", "content_filter", etc.).
• data.metadata.usage.credits— credits consumed by this request, deducted from your workspace’s monthly pool.

Set stream: trueto receive Server-Sent Events. Tokens stream as they’re generated; the final event mirrors the full response body.

data: {"type":"token","content":"Hello"}

data: {"type":"token","content":"!"}

data: {"type":"token","content":" I'm"}

data: {"type":"done","data":{"id":"msg_abc123","role":"assistant","parts":[{"type":"text","text":"Hello! I'm here to help."}],"metadata":{"conversationId":"a1b2c3d4-…","finishReason":"stop","usage":{"credits":2}}}}

Event types:

• token — { content: string }. A chunk of the assistant’s reply. Concatenate every token content for the full text.
• done — { data: {...} }. Final event mirroring the non-streaming response body. Close the connection here.
• error — { message: string }. Sent in lieu of done when something goes wrong mid-stream.

curl -X POST 'https://www.chatmount.co/api/v2/agents/YOUR_AGENT_ID/chat' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --no-buffer \
  -d '{
    "message": "Hello! How can you help me?",
    "stream": true
  }'

Pass the same conversationIdacross multiple requests so the agent remembers earlier turns. The first request can omit the field — the response’s data.metadata.conversationId is the freshly-issued id you should reuse on follow-ups.

# Turn 1 — no conversationId yet
curl -X POST 'https://www.chatmount.co/api/v2/agents/YOUR_AGENT_ID/chat' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "message": "What services do you offer?" }'

# Response includes data.metadata.conversationId — reuse it:

# Turn 2 — agent remembers turn 1
curl -X POST 'https://www.chatmount.co/api/v2/agents/YOUR_AGENT_ID/chat' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "Tell me more about the first one",
    "conversationId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
  }'

Per API key, with a monthly credit pool shared with widget chat usage at the workspace level.

• Plus — 60 req/min, 1,500 credits/month, 10,000/agent daily cap, 15 keys max.
• Enterprise — 200 req/min, unlimited credits/month, 50,000/agent daily cap, 50 keys max.

Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.

Errors return a JSON body:

{
  "error": {
    "code": "invalid_message",
    "message": "Message must be between 1 and 2000 characters"
  }
}

• 400 — malformed request (invalid message length, bad JSON).
• 401 — invalid or missing API key.
• 403— key doesn’t belong to a workspace that owns the agent in the URL, or your IP isn’t in the key’s allowlist.
• 404 — agent id in the URL does not exist.
• 429 — rate limit exceeded; back off and retry.
• 5xx — our problem; retry with exponential backoff.