Chat API

The chat API is the same chat as manova.ir/app, under your own account: replies use your plan's models and credits, and conversations you start through the API appear in your workspace.

Authenticate with an API token:

Authorization: Bearer manova_4c1f...e07b

Full schemas and a request playground are in the API reference.

Send a messageCopy Anchor Link

curl -N https://manova.ir/api/v1/external/chat/messages \
  -H "Authorization: Bearer $MANOVA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1d2c9e-6b8a-4f0e-9a51-0c2a7d1f4b33" \
  -d '{
    "clientRequestId": "6f1d2c9e-6b8a-4f0e-9a51-0c2a7d1f4b33",
    "mode": "auto",
    "content": [{ "type": "text", "text": "یک متن کوتاه برای معرفی فروشگاه کفش بنویس" }]
  }'

The reply arrives as server-sent events while the model writes it.

Retries are safeCopy Anchor Link

Every send carries an id, twice: clientRequestId in the body and the same value in the Idempotency-Key header. Generate a fresh UUID per message and reuse it only to retry that message.

• Retrying a send that already ended (completed, aborted or failed) does not charge again: you get its final events once more.
• Retrying one that is still running gets 409 CONFLICT.
• Reusing an id with a different body gets 409 CONFLICT.

CreditsCopy Anchor Link

Each reply costs credits according to the model, reserved when the send starts and settled when it ends. With too few credits left the send is refused with 402 INSUFFICIENT_CREDITS; a plan's daily message limit gives 429 RATE_LIMITED. Check your balance with GET /usage; the stream also reports it after every reply.

ConversationsCopy Anchor Link

curl "https://manova.ir/api/v1/external/conversations?limit=20" \
  -H "Authorization: Bearer $MANOVA_TOKEN"

{
  "items": [
    {
      "id": "9b2e4c1a-7d3f-4e8b-a0c2-5f6d7e8a9b0c",
      "title": "معرفی فروشگاه کفش",
      "createdAt": "2026-10-30T08:10:00.000000Z",
      "updatedAt": "2026-10-30T08:10:21.000000Z",
      "lastMessagePreview": "فروشگاه ما با بیش از ده سال تجربه…",
      "projectId": null,
      "agentId": null,
      "isPinned": false,
      "createdByUserId": "42"
    }
  ],
  "nextCursor": "eyJpZCI6Ij..."
}

• limit is 1 to 40 (default 40). Pass nextCursor back as cursor for the next page; it is null on the last.
• projectId filters to one project; projectId=none to conversations outside any project.
• Pinned conversations come first.

GET /conversations/{id} returns the same fields plus messages, oldest first. A message's content is a list of parts; its text is in the part with "type": "text".