Chat sessions between a user and a Dyva. Each conversation holds an ordered message sequence with its own context window.
Every route and HTTP method below was checked directly against the live ts-api source on August 13, 2026. Response bodies are illustrative examples, never captured responses.
Base URL
https://api.dyva.ai/v1/v1/conversationsStart a conversation with a Dyva. There is no title field: a conversation is untitled until one gets set some other way. If the character has a greeting message, it's inserted immediately, so message_count may already be 1 in the response, not 0.
Route and method verified directly against the live ts-api source on August 13, 2026.
Request body (2)
dyva_idstringRequiredscene_idstringOptionalResponse
Illustrative example, not a captured response{
"id": "conv_EXAMPLE00001",
"dyva_id": "00000000-0000-4000-8000-EXAMPLE00001",
"dyva_name": "Atlas",
"title": null,
"is_active": true,
"pinned": false,
"created_at": "2026-03-09T14:22:00.000Z",
"message_count": 1
}Examples (3)
curl -X POST https://api.dyva.ai/v1/conversations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"dyva_id": "00000000-0000-4000-8000-EXAMPLE00001",
"title": "Onboarding chat"
}'/v1/conversationsList your conversations, most recently active first. Returns a plain array; there is no total count or has_more flag. Pagination is page-based, not limit/offset.
Route and method verified directly against the live ts-api source on August 13, 2026.
Path and query parameters (4)
dyva_idstringOptionalpageintegerOptionalper_pageintegerOptionalinclude_archivedbooleanOptionalResponse
Illustrative example, not a captured response[
{
"id": "conv_EXAMPLE00001",
"dyva_id": "00000000-0000-4000-8000-EXAMPLE00001",
"dyva_name": "Atlas",
"title": null,
"pinned": false,
"is_active": true,
"message_count": 8,
"last_message_at": "2026-03-09T14:35:12.000Z",
"last_message_preview": "Welcome! I can walk you through the basics.",
"created_at": "2026-03-09T14:22:00.000Z"
}
]Examples (1)
curl "https://api.dyva.ai/v1/conversations?dyva_id=00000000-0000-4000-8000-EXAMPLE00001&per_page=10" \
-H "Authorization: Bearer YOUR_API_KEY"/v1/conversations/:idGet one conversation's own fields: title, character, scene, takeover state. This does not include the message list; call GET /v1/conversations/:id/messages separately for that.
Route and method verified directly against the live ts-api source on August 13, 2026.
Path and query parameters (1)
idstringRequiredResponse
Illustrative example, not a captured response{
"id": "conv_EXAMPLE00001",
"dyva_id": "00000000-0000-4000-8000-EXAMPLE00001",
"dyva_name": "Atlas",
"dyva_avatar_url": "https://cdn.dyva.ai/avatars/EXAMPLE00001.webp",
"title": null,
"is_active": true,
"pinned": false,
"message_count": 8,
"created_at": "2026-03-09T14:22:00.000Z"
}Examples (1)
curl "https://api.dyva.ai/v1/conversations/conv_EXAMPLE00001" \
-H "Authorization: Bearer YOUR_API_KEY"/v1/conversations/:idDelete a conversation and all messages. Cannot be undone.
Route and method verified directly against the live ts-api source on August 13, 2026.
Path and query parameters (1)
idstringRequiredResponse
Illustrative example, not a captured responseHTTP/1.1 204 No ContentExamples (1)
curl -X DELETE "https://api.dyva.ai/v1/conversations/conv_EXAMPLE00001" \
-H "Authorization: Bearer YOUR_API_KEY"/v1/conversations/:id/messagesGet message history, oldest first. Returns a plain array, capped at 200 rows per call. There is no offset parameter; page backward with before.
Route and method verified directly against the live ts-api source on August 13, 2026.
Path and query parameters (3)
idstringRequiredlimitintegerOptionalbeforestringOptionalResponse
Illustrative example, not a captured response[
{
"id": "msg_EXAMPLE00001",
"conversation_id": "conv_EXAMPLE00001",
"role": "user",
"content": "Hey, how do I get started?",
"author_type": "user",
"created_at": "2026-03-09T14:22:05.000Z"
},
{
"id": "msg_EXAMPLE00002",
"conversation_id": "conv_EXAMPLE00001",
"role": "assistant",
"content": "Welcome! I can walk you through the basics. What are you looking to build?",
"latency_ms": 1840,
"created_at": "2026-03-09T14:22:07.000Z"
}
]Examples (2)
curl "https://api.dyva.ai/v1/conversations/conv_EXAMPLE00001/messages?limit=50" \
-H "Authorization: Bearer YOUR_API_KEY"/v1/conversations/:id/messagesSend a message. Without stream, blocks until generation completes and returns the stored messages; see the streaming note below for real-time output.
Route and method verified directly against the live ts-api source on August 13, 2026.
Path and query parameters (1)
idstringRequiredRequest body (2)
contentstringRequiredstreambooleanOptionalResponse
Illustrative example, not a captured response{
"user_message": {
"id": "msg_EXAMPLE00003",
"conversation_id": "conv_EXAMPLE00001",
"role": "user",
"content": "What can you help me with?",
"created_at": "2026-03-09T14:30:00Z"
},
"assistant_message": {
"id": "msg_EXAMPLE00004",
"conversation_id": "conv_EXAMPLE00001",
"role": "assistant",
"content": "I can help you with onboarding, product questions, troubleshooting, and more. What would you like to dive into?",
"created_at": "2026-03-09T14:30:02Z"
}
}Examples (3)
curl -X POST "https://api.dyva.ai/v1/conversations/conv_EXAMPLE00001/messages" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"content": "What can you help me with?"}'/v1/conversations/:id/messagesSame endpoint as above, with stream: true. Response is text/event-stream instead of a blocking JSON reply.
Route and method verified directly against the live ts-api source on August 13, 2026.
Path and query parameters (1)
idstringRequiredRequest body (2)
contentstringRequiredstreambooleanRequiredResponse
Illustrative example, not a captured response// Content-Type: text/event-stream
event: delta
data: {"content": "I can "}
event: delta
data: {"content": "help you "}
event: delta
data: {"content": "with onboarding, "}
event: delta
data: {"content": "product questions, and more."}
event: done
data: {"message_id": "msg_EXAMPLE00004"}Examples (3)
curl -N -X POST "https://api.dyva.ai/v1/conversations/conv_EXAMPLE00001/messages" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"content": "What can you help me with?", "stream": true}'/v1/conversations/searchSubstring search across your own message content (SQL ILIKE, not ranked full-text search). Returns a plain array of matching messages, capped at 20 rows; the limit isn't configurable. Queries under 2 characters return an empty array.
Route and method verified directly against the live ts-api source on August 13, 2026.
Path and query parameters (1)
qstringRequiredResponse
Illustrative example, not a captured response[
{
"id": "msg_EXAMPLE00001",
"conversation_id": "conv_EXAMPLE00001",
"role": "user",
"content": "How do I configure webhooks?",
"created_at": "2026-03-09T14:22:05.000Z"
}
]Examples (1)
curl "https://api.dyva.ai/v1/conversations/search?q=webhooks" \
-H "Authorization: Bearer YOUR_API_KEY"