Chat sessions between a user and a Dyva. Each conversation holds an ordered message sequence with its own context window.
https://api.dyva.ai/v1/v1/conversationsAuth RequiredStart a conversation with a Dyva. Title is auto-generated from the first exchange if omitted.
| Name | Type | Required | Description |
|---|---|---|---|
dyva_id | string | Required | ID of the Dyva to start a conversation with. |
title | string | Optional | Optional display title. Auto-generated from the first message if not provided. |
{
"id": "conv_a1b2c3d4e5f6",
"dyva_id": "dyva_9x8y7z6w5v4u",
"title": null,
"created_at": "2026-03-09T14:22:00Z",
"updated_at": "2026-03-09T14:22:00Z",
"message_count": 0
}curl -X POST https://api.dyva.ai/v1/conversations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"dyva_id": "dyva_9x8y7z6w5v4u",
"title": "Onboarding chat"
}'/v1/conversationsAuth RequiredList conversations. Filter by Dyva and paginate.
| Name | Type | Required | Description |
|---|---|---|---|
dyva_id | string | Optional | Filter conversations to a specific Dyva. |
limit | integer | Optional | Maximum number of results to return (1-100). Default: 20. |
offset | integer | Optional | Number of results to skip for pagination. Default: 0. |
{
"data": [
{
"id": "conv_a1b2c3d4e5f6",
"dyva_id": "dyva_9x8y7z6w5v4u",
"title": "Onboarding chat",
"created_at": "2026-03-09T14:22:00Z",
"updated_at": "2026-03-09T14:35:12Z",
"message_count": 8
},
{
"id": "conv_f6e5d4c3b2a1",
"dyva_id": "dyva_9x8y7z6w5v4u",
"title": "Product questions",
"created_at": "2026-03-08T09:10:00Z",
"updated_at": "2026-03-08T09:48:33Z",
"message_count": 14
}
],
"has_more": true,
"total": 37
}curl "https://api.dyva.ai/v1/conversations?dyva_id=dyva_9x8y7z6w5v4u&limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"/v1/conversations/:idAuth RequiredGet a conversation with its most recent messages.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The conversation ID. |
{
"id": "conv_a1b2c3d4e5f6",
"dyva_id": "dyva_9x8y7z6w5v4u",
"title": "Onboarding chat",
"created_at": "2026-03-09T14:22:00Z",
"updated_at": "2026-03-09T14:35:12Z",
"message_count": 8,
"messages": [
{
"id": "msg_t1u2v3w4x5y6",
"conversation_id": "conv_a1b2c3d4e5f6",
"role": "user",
"content": "Hey, how do I get started?",
"created_at": "2026-03-09T14:22:05Z"
},
{
"id": "msg_z6y5x4w3v2u1",
"conversation_id": "conv_a1b2c3d4e5f6",
"role": "assistant",
"content": "Welcome! I can walk you through the basics. What are you looking to build?",
"created_at": "2026-03-09T14:22:07Z"
}
]
}curl "https://api.dyva.ai/v1/conversations/conv_a1b2c3d4e5f6" \
-H "Authorization: Bearer YOUR_API_KEY"/v1/conversations/:idAuth RequiredDelete a conversation and all messages. Cannot be undone.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The conversation ID to delete. |
{
"id": "conv_a1b2c3d4e5f6",
"deleted": true
}curl -X DELETE "https://api.dyva.ai/v1/conversations/conv_a1b2c3d4e5f6" \
-H "Authorization: Bearer YOUR_API_KEY"/v1/conversations/:id/messagesAuth RequiredGet message history. Supports cursor-based pagination for scrollback.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The conversation ID. |
limit | integer | Optional | Maximum number of results to return (1-100). Default: 20. |
offset | integer | Optional | Number of results to skip for pagination. Default: 0. |
before | string | Optional | Message ID cursor. Returns messages created before this message, newest first. |
{
"data": [
{
"id": "msg_t1u2v3w4x5y6",
"conversation_id": "conv_a1b2c3d4e5f6",
"role": "user",
"content": "Hey, how do I get started?",
"created_at": "2026-03-09T14:22:05Z"
},
{
"id": "msg_z6y5x4w3v2u1",
"conversation_id": "conv_a1b2c3d4e5f6",
"role": "assistant",
"content": "Welcome! I can walk you through the basics. What are you looking to build?",
"created_at": "2026-03-09T14:22:07Z"
}
],
"has_more": true
}curl "https://api.dyva.ai/v1/conversations/conv_a1b2c3d4e5f6/messages?limit=50" \
-H "Authorization: Bearer YOUR_API_KEY"/v1/conversations/:id/messagesAuth RequiredSend a message and receive the Dyva's response. Blocks until generation completes.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The conversation ID. |
| Name | Type | Required | Description |
|---|---|---|---|
content | string | Required | The message text to send. |
role | string | Optional | Sender role. Must be "user". Default: "user". |
{
"user_message": {
"id": "msg_a1b2c3d4e5f6",
"conversation_id": "conv_a1b2c3d4e5f6",
"role": "user",
"content": "What can you help me with?",
"created_at": "2026-03-09T14:30:00Z"
},
"assistant_message": {
"id": "msg_g7h8i9j0k1l2",
"conversation_id": "conv_a1b2c3d4e5f6",
"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"
}
}curl -X POST "https://api.dyva.ai/v1/conversations/conv_a1b2c3d4e5f6/messages" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"content": "What can you help me with?"}'/v1/conversations/:id/messages/streamAuth RequiredSend a message and stream the response via SSE. Ideal for real-time UIs.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The conversation ID. |
| Name | Type | Required | Description |
|---|---|---|---|
content | string | Required | The message text to send. |
// 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_g7h8i9j0k1l2"}curl -N -X POST "https://api.dyva.ai/v1/conversations/conv_a1b2c3d4e5f6/messages/stream" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"content": "What can you help me with?"}'/v1/conversations/searchAuth RequiredFull-text search across all conversations. Returns matching messages with conversation context.
| Name | Type | Required | Description |
|---|---|---|---|
q | string | Required | Search query string. |
limit | integer | Optional | Maximum number of matching messages to return (1-100). Default: 20. |
{
"data": [
{
"message": {
"id": "msg_t1u2v3w4x5y6",
"conversation_id": "conv_a1b2c3d4e5f6",
"role": "user",
"content": "How do I configure webhooks?",
"created_at": "2026-03-09T14:22:05Z"
},
"conversation": {
"id": "conv_a1b2c3d4e5f6",
"title": "Onboarding chat"
},
"highlight": "How do I configure <mark>webhooks</mark>?"
}
],
"has_more": false,
"total": 1
}curl "https://api.dyva.ai/v1/conversations/search?q=webhooks&limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"Returns a text/event-stream response. Each event has a named type and JSON payload on the data: line.
| Event Type | Payload | Description |
|---|---|---|
delta | { "content": "..." } | Response chunk. Concatenate all deltas to build the full message. |
done | { "message_id": "..." } | Response complete. Contains the stored message ID. |
error | { "code": "...", "message": "..." } | Error during generation. Stream closes after this event. Check code for the error type (e.g. rate_limited, context_length_exceeded). |
done event to confirm the stream has completed. If the connection drops before a done or error event, treat it as a network failure and retry with the same message.