Chat API
Send text chat turns with Rivya's Chat API. Learn the request fields, SSE events, session rules, and credit settlement.
Last reviewed on November 11, 2026
Use POST /api/v1/chat/completions for one complete non-streaming chat response, or POST /api/v1/chat/completions/stream for Server-Sent Events.
Omit session_id to start a new API chat session. Send the returned session_id with your next message to continue it.
Requests require an enabled Public API deployment, an active API key with the right scope, and a chat model with api_status: "available". Check API Models before choosing a model.
Text-only Gemini 4 Carbon requests
Gemini 4 Carbon accepts text without attachments, web search, tools or exposed reasoning settings in this Rivya path. It delivers one complete answer after terminal validation. The reserve covers the model’s full published context for both input and output; it does not use a default answer length as a billing cap.
The current promotional quote expires at 00:00 UTC on November 30, 2026. New requests stop then until a new quote is confirmed. Existing requests keep their creation-time quote and settle from confirmed consumption. Do not automatically continue or resend an uncertain request.
Current Scope
Chat API v1 supports:
non-streaming assistant responses
SSE streaming with
text/event-streamAPI-created chat sessions
account credit reservation, recorded token usage, and credit settlement
web search, reasoning effort, and thought mode only where the selected model supports them
Files API image attachments only where the selected model supports them
Choose a currently available chat model from the model list and check its chat_capabilities; support varies by model. Thought mode, attachments, web search, and selectable reasoning effort depend on the selected model’s capabilities. Models marked unavailable or Coming Soon cannot be called. Use the current model list to check availability and chat_capabilities; a provider's own feature list does not describe Rivya's callable features.
Chat API v1 does not support:
user-supplied raw
messageshistorycontinuing Studio-only chat sessions
arbitrary external attachment URLs
Chat webhook events
Required Scopes
Use chat:create to submit a turn and chat:read to list or read API-created sessions:
chat:create
chat:readNew keys created in Settings include both scopes. If an older key lacks them, create a replacement key. The key must also be active and unexpired, and its account must be allowed to use the API.
Create A Chat Completion
Both completion endpoints accept the same request fields:
| Field | Required | Description |
|---|---|---|
model | Yes | A currently available chat model ID, up to 160 characters. Use the session's model when continuing a session. |
message | Yes | Your next message, from 1 to 8,000 characters; whitespace-only messages are rejected. Rivya loads the saved conversation; do not send a raw messages array. |
session_id | No | An API-created session owned by this account, up to 160 characters. Omit it to start a session. |
tool_slug | No | A Rivya chat preset slug, up to 160 characters. Current presets and session rules are described under Optional Controls. |
enable_web_search | No | A boolean. Search is enabled only when the model supports it and this value is true; otherwise it is off. |
reasoning_effort | No | default, minimal, low, medium, high, or xhigh. Only values in the model's chat_capabilities.reasoning_efforts take effect; other valid choices use the default for models that allow that behavior; GPT-5.2 rejects non-default choices. |
thought_mode | No | default, on, or off. on and off take effect only when chat_capabilities.thoughts is true. default leaves the model's thought setting unspecified. |
attachments | No | Up to six objects with a file_id. The model's image limit also applies. See Image Attachments for ownership, format, and capability checks. |
client_request_id | No | An optional identifier for your own request tracking, up to 128 characters. It is recorded for auditing and does not replace Idempotency-Key. |
Replace the API key placeholder before sending this request. Use a distinct Idempotency-Key for each new turn, and make sure the account has enough available credits.
curl https://rivya.ai/api/v1/chat/completions \
-H "Authorization: Bearer rvya_sk_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: chat-turn-001" \
-d '{
"model": "claude-sonnet-5-chat",
"message": "Write a concise launch plan for a new product image campaign",
"client_request_id": "chat-001"
}'Illustrative successful response. IDs, timestamps, token counts, and credit amounts are examples, not a quote for this prompt:
{
"id": "chatcmpl_...",
"object": "chat.completion",
"session_id": "session_id",
"model": "claude-sonnet-5-chat",
"created_at": "2026-05-11T00:00:00.000Z",
"message": {
"id": "assistant_message_id",
"role": "assistant",
"content": "...",
"created_at": "2026-05-11T00:00:00.000Z"
},
"usage": {
"input_tokens": 1200,
"output_tokens": 320,
"total_tokens": 1520
},
"credits": {
"reserved": 3,
"final": 2,
"settlement_status": "SETTLED"
}
}Rivya reserves credits before requesting a reply. The reserve depends on the model, saved messages, current message, preset instructions, and any supported attachments. usage reports token counts; it is not a final credit charge.
credits.settlement_status tells you whether settlement is complete. When reported credit consumption is valid and no greater than the reserve, Rivya settles the charge and returns the unused credits. For GPT-5.2, a complete response with confirmed, consistent token counts can instead settle at the model’s credit rates when reported credit consumption is absent. An explicitly invalid consumption value cannot use this fallback. If neither settlement basis is valid, or confirmed consumption exceeds the reserve, the status is RECONCILIATION_REQUIRED and credits.final still contains the reserved amount. A saved reply can therefore have recorded usage while its credit settlement remains unresolved. See API Credits for billing details.
Stream A Chat Completion
Use POST /api/v1/chat/completions/stream to receive assistant text. GPT-5.2 delivers its answer in one text event after the complete response is ready; it does not provide progressive text updates. Other models may send multiple text events:
curl -N https://rivya.ai/api/v1/chat/completions/stream \
-H "Authorization: Bearer rvya_sk_..." \
-H "Content-Type: application/json" \
-H "Accept: text/event-stream" \
-H "Idempotency-Key: chat-stream-001" \
-d '{
"model": "claude-sonnet-5-chat",
"message": "Write a concise launch plan for a new product image campaign",
"client_request_id": "chat-stream-001"
}'Streaming responses use Content-Type: text/event-stream; charset=utf-8.
Events:
| Event | Meaning |
|---|---|
session.created | The session is ready for this turn: key, model, session, attachment, rate-limit, and credit-reservation checks passed. |
message.delta | A text fragment for display. It is not yet a saved assistant message. |
message.completed | The assistant message was committed to the API-created session. |
usage.completed | Recorded token usage and credit values, including settlement_status. This event does not guarantee that settlement is complete. |
heartbeat | A keepalive event during pauses. |
error | An error envelope after streaming started. Read its code; an error does not by itself prove that a turn was never committed. |
done | The successful stream reached its end. Check the separate credit settlement status. |
Illustrative stream for a settled turn, using the same example values as the response above:
event: session.created
data: {"request_id":"req_...","session_id":"session_id","model":"claude-sonnet-5-chat"}
event: message.delta
data: {"request_id":"req_...","session_id":"session_id","delta":"Draft ","index":0}
event: message.completed
data: {"request_id":"req_...","session_id":"session_id","message":{"id":"assistant_message_id","role":"assistant","content":"Draft ...","created_at":"2026-05-11T00:00:00.000Z"}}
event: usage.completed
data: {"request_id":"req_...","session_id":"session_id","usage":{"input_tokens":1200,"output_tokens":320,"total_tokens":1520},"credits":{"reserved":3,"final":2,"settlement_status":"SETTLED"}}
event: done
data: {"request_id":"req_...","ok":true}Before streaming starts, rejected requests return a JSON error with its HTTP status. After streaming starts, the response has HTTP 200; if an error can still be delivered, Rivya sends event: error and closes the stream without done:
event: error
data: {"error":{"code":"internal_error","message":"Rivya could not confirm the result of this request.","requestId":"req_..."}}Rivya tries to stop the upstream stream when the client disconnects. Treat message.delta as a display fragment; use message.completed or the saved session to confirm what was committed. A disconnected or truncated stream does not tell you whether the turn was committed or how credits settled. If you received a session_id, read GET /api/v1/chat/sessions/{sessionId} before sending another turn. A committed reply can be read there even if its completion events never reached your client.
Continue A Session
Use the returned session_id:
curl https://rivya.ai/api/v1/chat/completions \
-H "Authorization: Bearer rvya_sk_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: chat-turn-002" \
-d '{
"model": "claude-sonnet-5-chat",
"session_id": "session_id",
"message": "Now turn that into a 5-step execution checklist."
}'The session must belong to the same Rivya account and have been created by Public API. Chat API cannot list, read, or continue Studio-only sessions. The same account's browser chat history can also include API-created sessions.
Keep the session's model ID. If the session already has a preset, omit tool_slug to reuse it, or send that same slug; a different preset is rejected. Send your desired controls on each turn, since omitted controls resolve to their defaults rather than preserving the previous request's settings.
Image Attachments
Chat attachments use Files API records, not external URLs. The currently available Claude chat models do not accept attachments. The following format describes the attachment contract and is usable only if the model list reports an available chat model with chat_capabilities.image_attachments: true.
Upload an image with
POST /api/v1/filesusing a key withfiles:create.Use the returned
idasattachments[].file_id.
{
"model": "<image-capable-chat-model-id>",
"message": "Review this product photo and suggest a cleaner editorial direction.",
"attachments": [
{
"file_id": "file_..."
}
]
}The file must belong to this account, have kind: "image" and an available status, and use JPEG, PNG, or WebP. File IDs must be distinct. The request schema allows up to six attachments, but the model's own image limit may be lower. Replace the model placeholder only with an available model that supports images; claude-sonnet-5-chat does not qualify. Unsupported, missing, unavailable, wrong-format, or unowned images return chat_attachment_not_supported. Repeated file IDs return validation_failed when the model's capability and attachment-count checks pass.
Optional Controls
{
"model": "claude-sonnet-5-chat",
"message": "Compare three launch options.",
"enable_web_search": false,
"reasoning_effort": "default",
"thought_mode": "default"
}Read chat_capabilities in /api/v1/models before offering controls. A schema-valid choice does not enable an unsupported feature. GPT-5.2 rejects web search, non-default reasoning choices, thoughts set to on, image attachments, and unsupported request fields before reserving credits. Other models may keep unsupported web search off, resolve unsupported reasoning choices to the default, or omit unsupported thought settings. thought_mode controls the model's thought setting; Rivya does not return a separate thoughts field.
tool_slug selects preset instructions for a chat turn. The current slugs are ai-calculator and ai-solver; they do not run a separate calculator, verify answers automatically, or provide arbitrary function calling. A preset selected when creating a session is saved with it. For a session without a saved preset, sending tool_slug applies it to that turn without saving it as the session's preset.
List Sessions
Use GET /api/v1/chat/sessions with a key that includes chat:read.
curl https://rivya.ai/api/v1/chat/sessions \
-H "Authorization: Bearer rvya_sk_..."This returns this account's API-created sessions, newest activity first. The optional limit query parameter is parsed as an integer: positive results are capped at 100; otherwise the limit is 20. The endpoint does not provide a pagination cursor.
{
"object": "list",
"data": [
{
"id": "session_id",
"object": "chat.session",
"model": "claude-sonnet-5-chat",
"tool_slug": null,
"title": "Write a concise launch plan...",
"controls": {
"enable_web_search": false,
"reasoning_effort": null,
"thought_mode": null
},
"created_at": "2026-05-11T00:00:00.000Z",
"updated_at": "2026-05-11T00:00:00.000Z",
"last_message_at": "2026-05-11T00:00:00.000Z"
}
]
}Get A Session
Use GET /api/v1/chat/sessions/{sessionId} to read one API-created session and its committed messages.
curl https://rivya.ai/api/v1/chat/sessions/session_id \
-H "Authorization: Bearer rvya_sk_..."The response includes committed user and assistant messages in chronological order. Pending and failed turns are excluded. Messages contain id, role, content, and created_at; this endpoint does not return token usage, credit settlement, image attachments, or internal provider fields.
Idempotency
Send an Idempotency-Key with each new POST /api/v1/chat/completions or POST /api/v1/chat/completions/stream turn. Keep that key and the request body unchanged when checking a request after a network error.
A matching stored response is replayed without creating another turn or charging for a new turn. Stored errors are replayed too. A different body, a pending request, or a record with no response to replay returns idempotency_conflict; that error does not mean you should submit the same turn under a new key.
Successful streaming replays send session.created, message.completed, usage.completed, and done, without historical deltas. A stored failure is returned as a JSON error with its saved HTTP status, rather than replaying an error stream.
If a connection ends without a complete response, check the original session before resubmitting. When no session_id reached your client, the session list can help you look for recent API-created conversations, and the original key and body can retrieve a stored response if one is available. client_request_id is an audit label, not a duplicate-request guard. A new idempotency key can create another charged turn.
Common Errors
| Code | Meaning |
|---|---|
chat_model_not_supported | The model is missing, not a chat model, or not currently available through Chat API. |
chat_session_conflict | The requested model or preset conflicts with the session, or the preset slug is not recognized. |
chat_attachment_not_supported | The model cannot accept these attachments, or a file is missing, unavailable, unowned, not an image, or in an unsupported format. |
insufficient_credits | The account does not have enough available credits for this turn's reserve. |
idempotency_conflict | The key has different request data, the request is still pending, or no saved response is available to replay. |
not_found | The requested session is missing, belongs to another account, or was not created through Public API. |
validation_failed | Request fields do not match the schema, or attachment file IDs are repeated. |
internal_error | Rivya could not confirm the request's result. Check for a saved reply before creating another turn. |
