Chat - ai-cmo.dev

The chat endpoint returns a Server-Sent Events (SSE) stream, not JSON. Each response chunk contains a text-delta that the client aggregates into the full assistant message.

Endpoints

Method	Path	Scope	Description
POST	`/api/v1/chat`	`chat:write`	Stream an assistant turn (SSE)
GET	`/api/v1/threads?workspace={workspace}`	`chat:read`	List chat threads
POST	`/api/v1/threads`	`chat:write`	Create a chat thread
GET	`/api/v1/threads/{id}?workspace={workspace}`	`chat:read`	Get a thread with its messages
PATCH	`/api/v1/threads/{id}`	`chat:write`	Update thread title or pin status
DELETE	`/api/v1/threads/{id}?workspace={workspace}`	`chat:write`	Delete a thread

Stream a chat turn

curl -X POST https://ai-cmo.dev/api/v1/chat \
  -H "Authorization: Bearer gp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
"workspace": "{workspace}",
    "threadId": "{threadId}",
    "messages": [
      {
        "id": "msg_001",
        "role": "user",
        "parts": [{ "type": "text", "text": "What is my current GEO score?" }]
      }
    ]
  }'

The response is Content-Type: text/event-stream. Each event contains a text-delta that must be aggregated client-side:

event: text-delta
data: {"type":"text-delta","text":"Your","index":0}

event: text-delta
data: {"type":"text-delta","text":" GEO","index":0}

event: text-delta
data: {"type":"text-delta","text":" score","index":0}

event: finish
data: {"type":"finish","finishReason":"stop","usage":{"promptTokens":120,"completionTokens":85}}

Required fields

Idempotency

The server accepts an optional Idempotency-Key header. If absent, the server generates one automatically.

Thread CRUD

List threads

curl -H "Authorization: Bearer gp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     "https://ai-cmo.dev/api/v1/threads?workspace={workspace}"

Create a thread

curl -X POST https://ai-cmo.dev/api/v1/threads \
  -H "Authorization: Bearer gp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"workspace": "{workspace}", "title": "GEO analysis"}'

If omitted, title defaults to “New conversation”.

Get a thread

curl -H "Authorization: Bearer gp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
"https://ai-cmo.dev/api/v1/threads/{id}?workspace={workspace}"

Returns the thread metadata and all messages.

Update a thread

curl -X PATCH https://ai-cmo.dev/api/v1/threads/{id} \
  -H "Authorization: Bearer gp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"workspace": "{workspace}", "title": "Updated title", "pinned": true}'

Delete a thread

curl -X DELETE "https://ai-cmo.dev/api/v1/threads/{id}?workspace={workspace}" \
  -H "Authorization: Bearer gp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Credit reservation

Chat uses 720,000 µUSD per turn (6 steps at 120,000 µUSD per step). Each step within a turn obtains a per-step credit lease. If a lease is refused mid-turn, the stream terminates with stopped_credits.

Consuming the stream

The recommended approach (used by the MCP client at apps/mcp/src/client.ts) is to aggregate text-delta events into a full message:

Connect the stream

Connect the SSE stream to a POST to /api/v1/chat.

Aggregate the deltas

For each text-delta event, append text to the current assistant message.

Detect completion

On finish, the stream is complete.

Persist the history

After the stream, use PATCH /api/v1/threads/{id} or the internal saveChatMessages to persist the full message history.

​Endpoints

​Stream a chat turn

​Required fields

​Idempotency

​Thread CRUD

​List threads

​Create a thread

​Get a thread

​Update a thread

​Delete a thread

​Credit reservation

​Consuming the stream