API Reference

Conversations API

Chat sessions between a user and a Dyva. Each conversation holds an ordered message sequence with its own context window.

Base URL

https://api.dyva.ai/v1

POST/v1/conversationsAuth Required

Start a conversation with a Dyva. Title is auto-generated from the first exchange if omitted.

Request Body

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.

Response

{
  "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
}

Examples

$_cURL

JSJavaScript

PyPython

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"
  }'

GET/v1/conversationsAuth Required

List conversations. Filter by Dyva and paginate.

Path Parameters

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.

Response

{
  "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
}

Examples

curl "https://api.dyva.ai/v1/conversations?dyva_id=dyva_9x8y7z6w5v4u&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/v1/conversations/:idAuth Required

Get a conversation with its most recent messages.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The conversation ID.

Response

{
  "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"
    }
  ]
}

Examples

curl "https://api.dyva.ai/v1/conversations/conv_a1b2c3d4e5f6" \
  -H "Authorization: Bearer YOUR_API_KEY"

DELETE/v1/conversations/:idAuth Required

Delete a conversation and all messages. Cannot be undone.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The conversation ID to delete.

Response

{
  "id": "conv_a1b2c3d4e5f6",
  "deleted": true
}

Examples

curl -X DELETE "https://api.dyva.ai/v1/conversations/conv_a1b2c3d4e5f6" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/v1/conversations/:id/messagesAuth Required

Get message history. Supports cursor-based pagination for scrollback.

Path Parameters

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.

Response

{
  "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
}

Examples

$_cURL

JSJavaScript

curl "https://api.dyva.ai/v1/conversations/conv_a1b2c3d4e5f6/messages?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/v1/conversations/:id/messagesAuth Required

Send a message and receive the Dyva's response. Blocks until generation completes.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The conversation ID.

Request Body

Name	Type	Required	Description
`content`	string	Required	The message text to send.
`role`	string	Optional	Sender role. Must be "user". Default: "user".

Response

{
  "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"
  }
}

Examples

$_cURL

JSJavaScript

PyPython

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?"}'

POST/v1/conversations/:id/messages/streamAuth Required

Send a message and stream the response via SSE. Ideal for real-time UIs.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The conversation ID.

Request Body

Name	Type	Required	Description
`content`	string	Required	The message text to send.

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_g7h8i9j0k1l2"}

Examples

$_cURL

JSJavaScript

PyPython

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?"}'

GET/v1/conversations/searchAuth Required

Full-text search across all conversations. Returns matching messages with conversation context.

Path Parameters

Name	Type	Required	Description
`q`	string	Required	Search query string.
`limit`	integer	Optional	Maximum number of matching messages to return (1-100). Default: 20.

Response

{
  "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
}

Examples

curl "https://api.dyva.ai/v1/conversations/search?q=webhooks&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

SSE Streaming Format

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`).

TipListen for the 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.

API Reference

Conversations API

Chat sessions between a user and a Dyva. Each conversation holds an ordered message sequence with its own context window.

Base URL

https://api.dyva.ai/v1

POST/v1/conversationsAuth Required

Start a conversation with a Dyva. Title is auto-generated from the first exchange if omitted.

Request Body

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.

Response

{
  "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
}

Examples

$_cURL

JSJavaScript

PyPython

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"
  }'

GET/v1/conversationsAuth Required

List conversations. Filter by Dyva and paginate.

Path Parameters

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.

Response

{
  "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
}

Examples

curl "https://api.dyva.ai/v1/conversations?dyva_id=dyva_9x8y7z6w5v4u&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/v1/conversations/:idAuth Required

Get a conversation with its most recent messages.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The conversation ID.

Response

{
  "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"
    }
  ]
}

Examples

curl "https://api.dyva.ai/v1/conversations/conv_a1b2c3d4e5f6" \
  -H "Authorization: Bearer YOUR_API_KEY"

DELETE/v1/conversations/:idAuth Required

Delete a conversation and all messages. Cannot be undone.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The conversation ID to delete.

Response

{
  "id": "conv_a1b2c3d4e5f6",
  "deleted": true
}

Examples

curl -X DELETE "https://api.dyva.ai/v1/conversations/conv_a1b2c3d4e5f6" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/v1/conversations/:id/messagesAuth Required

Get message history. Supports cursor-based pagination for scrollback.

Path Parameters

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.

Response

{
  "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
}

Examples

$_cURL

JSJavaScript

curl "https://api.dyva.ai/v1/conversations/conv_a1b2c3d4e5f6/messages?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST/v1/conversations/:id/messagesAuth Required

Send a message and receive the Dyva's response. Blocks until generation completes.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The conversation ID.

Request Body

Name	Type	Required	Description
`content`	string	Required	The message text to send.
`role`	string	Optional	Sender role. Must be "user". Default: "user".

Response

{
  "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"
  }
}

Examples

$_cURL

JSJavaScript

PyPython

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?"}'

POST/v1/conversations/:id/messages/streamAuth Required

Send a message and stream the response via SSE. Ideal for real-time UIs.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	The conversation ID.

Request Body

Name	Type	Required	Description
`content`	string	Required	The message text to send.

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_g7h8i9j0k1l2"}

Examples

$_cURL

JSJavaScript

PyPython

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?"}'

GET/v1/conversations/searchAuth Required

Full-text search across all conversations. Returns matching messages with conversation context.

Path Parameters

Name	Type	Required	Description
`q`	string	Required	Search query string.
`limit`	integer	Optional	Maximum number of matching messages to return (1-100). Default: 20.

Response

{
  "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
}

Examples

curl "https://api.dyva.ai/v1/conversations/search?q=webhooks&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

SSE Streaming Format

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`).

TipListen for the 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.

Conversations API

POST /v1/conversations

Request Body

Response

Examples

GET /v1/conversations

Path Parameters

Response

Examples

GET /v1/conversations/:id

Path Parameters

Response

Examples

DELETE /v1/conversations/:id

Path Parameters

Response

Examples

GET /v1/conversations/:id/messages

Path Parameters

Response

Examples

POST /v1/conversations/:id/messages

Path Parameters

Request Body

Response

Examples

POST /v1/conversations/:id/messages/stream

Path Parameters

Request Body

Response

Examples

GET /v1/conversations/search

Path Parameters

Response

Examples

SSE Streaming Format

Conversations API

POST /v1/conversations

Request Body

Response

Examples

GET /v1/conversations

Path Parameters

Response

Examples

GET /v1/conversations/:id

Path Parameters

Response

Examples

DELETE /v1/conversations/:id

Path Parameters

Response

Examples

GET /v1/conversations/:id/messages

Path Parameters

Response

Examples

POST /v1/conversations/:id/messages

Path Parameters

Request Body

Response

Examples

POST /v1/conversations/:id/messages/stream

Path Parameters

Request Body

Response

Examples

GET /v1/conversations/search

Path Parameters

Response

Examples

SSE Streaming Format