API Reference

Characters API

Characters are AI personalities with a name, system prompt, backing model, and optional voice. Create, update, list, delete, or browse the public explore feed.

Base URL

https://api.dyva.ai/v1

POST/v1/dyvasAuth Required

Create a character with a name, system prompt, and optional model, avatar, category, greeting, and voice.

Request Body

Name	Type	Required	Description
`name`	string	Required	Display name of the character (1-80 characters).
`description`	string	Optional	Short public description shown in explore and embeds (max 300 characters).
`instructions`	string	Required	System prompt that defines the character's personality, tone, and behavior. Supports Markdown.
`model`	string	Optional	Backing LLM. Choose from our available models. See the models documentation for the full list of supported identifiers.
`avatar_url`	string	Optional	URL to a square image used as the character's avatar (recommended 256x256+).
`is_public`	boolean	Optional	Whether the character appears in the public explore feed. Defaults to false.
`category`	string	Optional	Explore category. One of assistant, tutor, character, coach, companion, creative, developer, or other.
`greeting_message`	string	Optional	First message the character sends when a new conversation starts. Omit to let the character generate one.
`voice_id`	string	Optional	Identifier for the TTS voice used in voice sessions (e.g. alloy, echo, fable).

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Atlas",
  "description": "A curious research assistant that loves diving deep into topics.",
  "instructions": "You are Atlas, a knowledgeable and curious research assistant...",
  "model": "default",
  "avatar_url": "https://cdn.dyva.ai/avatars/atlas.png",
  "is_public": true,
  "category": "assistant",
  "greeting_message": "Hey! I'm Atlas. What are we researching today?",
  "voice_id": "alloy",
  "message_count": 4832,
  "creator_id": "usr_9f8e7d6c5b4a3210",
  "created_at": "2026-01-15T08:30:00Z",
  "updated_at": "2026-03-08T14:22:10Z"
}

Examples

$_cURL

JSJavaScript

curl -X POST https://api.dyva.ai/v1/dyvas \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Atlas",
    "description": "A curious research assistant.",
    "instructions": "You are Atlas, a knowledgeable research assistant who explains complex topics clearly.",
    "model": "default",
    "is_public": true,
    "category": "assistant",
    "greeting_message": "Hey! I\u0027m Atlas. What are we researching today?"
  }'

GET/v1/dyvasAuth Required

List your characters. Supports pagination and sorting.

Path Parameters

Name	Type	Required	Description
`limit`	integer	Optional	Max items to return (1-100). Defaults to 20.
`offset`	integer	Optional	Number of items to skip for pagination. Defaults to 0.
`sort`	string	Optional	Sort order. One of "created_at", "updated_at", or "name". Defaults to "created_at".

Response

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Atlas",
      "description": "A curious research assistant that loves diving deep into topics.",
      "model": "default",
      "avatar_url": "https://cdn.dyva.ai/avatars/atlas.png",
      "is_public": true,
      "category": "assistant",
      "message_count": 4832,
      "created_at": "2026-01-15T08:30:00Z",
      "updated_at": "2026-03-08T14:22:10Z"
    },
    {
      "id": "f0e1d2c3-b4a5-6789-0fed-cba987654321",
      "name": "Luna",
      "description": "Creative writing partner with a flair for storytelling.",
      "model": "creative",
      "avatar_url": "https://cdn.dyva.ai/avatars/luna.png",
      "is_public": false,
      "category": "creative",
      "message_count": 1290,
      "created_at": "2026-02-03T19:10:00Z",
      "updated_at": "2026-03-07T11:45:30Z"
    }
  ],
  "total": 2,
  "limit": 20,
  "offset": 0
}

Examples

$_cURL

JSJavaScript

curl https://api.dyva.ai/v1/dyvas?limit=10&sort=updated_at \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/v1/dyvas/:idAuth Required

Get full details for a single character.

Path Parameters

Name	Type	Required	Description
`id`	string (UUID)	Required	Unique identifier of the character.

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Atlas",
  "description": "A curious research assistant that loves diving deep into topics.",
  "instructions": "You are Atlas, a knowledgeable and curious research assistant...",
  "model": "default",
  "avatar_url": "https://cdn.dyva.ai/avatars/atlas.png",
  "is_public": true,
  "category": "assistant",
  "greeting_message": "Hey! I'm Atlas. What are we researching today?",
  "voice_id": "alloy",
  "message_count": 4832,
  "creator_id": "usr_9f8e7d6c5b4a3210",
  "created_at": "2026-01-15T08:30:00Z",
  "updated_at": "2026-03-08T14:22:10Z"
}

Examples

$_cURL

JSJavaScript

curl https://api.dyva.ai/v1/dyvas/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer YOUR_API_KEY"

PUT/v1/dyvas/:idAuth Required

Update one or more fields. Only included fields are changed.

Path Parameters

Name	Type	Required	Description
`id`	string (UUID)	Required	Unique identifier of the character.

Request Body

Name	Type	Required	Description
`name`	string	Optional	Display name of the character (1-80 characters).
`description`	string	Optional	Short public description shown in explore and embeds (max 300 characters).
`instructions`	string	Optional	System prompt that defines the character's personality, tone, and behavior. Supports Markdown.
`model`	string	Optional	Backing LLM. Choose from our available models. See the models documentation for the full list of supported identifiers.
`avatar_url`	string	Optional	URL to a square image used as the character's avatar (recommended 256x256+).
`is_public`	boolean	Optional	Whether the character appears in the public explore feed. Defaults to false.
`category`	string	Optional	Explore category. One of assistant, tutor, character, coach, companion, creative, developer, or other.
`greeting_message`	string	Optional	First message the character sends when a new conversation starts. Omit to let the character generate one.
`voice_id`	string	Optional	Identifier for the TTS voice used in voice sessions (e.g. alloy, echo, fable).

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Atlas",
  "description": "A curious research assistant that loves diving deep into topics.",
  "instructions": "You are Atlas, a knowledgeable and curious research assistant...",
  "model": "default",
  "avatar_url": "https://cdn.dyva.ai/avatars/atlas.png",
  "is_public": true,
  "category": "assistant",
  "greeting_message": "Hey! I'm Atlas. What are we researching today?",
  "voice_id": "alloy",
  "message_count": 4832,
  "creator_id": "usr_9f8e7d6c5b4a3210",
  "created_at": "2026-01-15T08:30:00Z",
  "updated_at": "2026-03-08T14:22:10Z"
}

Examples

$_cURL

JSJavaScript

curl -X PUT https://api.dyva.ai/v1/dyvas/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description for Atlas.",
    "model": "creative"
  }'

DELETE/v1/dyvas/:idAuth Required

Delete a character and all its conversations. Cannot be undone.

Path Parameters

Name	Type	Required	Description
`id`	string (UUID)	Required	Unique identifier of the character.

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "deleted": true
}

Examples

$_cURL

JSJavaScript

curl -X DELETE https://api.dyva.ai/v1/dyvas/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/v1/dyvas/exploreAuth Required

Browse public characters. Filter by category, search by name, sort by popularity, recency, or trending.

Path Parameters

Name	Type	Required	Description
`category`	string	Optional	Filter by category (assistant, tutor, character, coach, companion, creative, developer, other).
`sort`	string	Optional	Sort order. One of "popular", "recent", or "trending". Defaults to "popular".
`limit`	integer	Optional	Max items to return (1-100). Defaults to 20.
`offset`	integer	Optional	Number of items to skip for pagination. Defaults to 0.
`q`	string	Optional	Free-text search across name and description.

Response

{
  "data": [
    {
      "id": "c3d4e5f6-a1b2-7890-fedc-ba0987654321",
      "name": "CodePilot",
      "description": "Senior engineer that reviews your code and suggests improvements.",
      "model": "default",
      "avatar_url": "https://cdn.dyva.ai/avatars/codepilot.png",
      "is_public": true,
      "category": "developer",
      "message_count": 28401,
      "creator_id": "usr_1a2b3c4d5e6f7890",
      "created_at": "2025-12-01T10:00:00Z",
      "updated_at": "2026-03-09T02:15:00Z"
    }
  ],
  "total": 148,
  "limit": 20,
  "offset": 0
}

Examples

$_cURL

JSJavaScript

curl "https://api.dyva.ai/v1/dyvas/explore?category=developer&sort=trending&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

API Reference

Characters API

Characters are AI personalities with a name, system prompt, backing model, and optional voice. Create, update, list, delete, or browse the public explore feed.

Base URL

https://api.dyva.ai/v1

POST/v1/dyvasAuth Required

Create a character with a name, system prompt, and optional model, avatar, category, greeting, and voice.

Request Body

Name	Type	Required	Description
`name`	string	Required	Display name of the character (1-80 characters).
`description`	string	Optional	Short public description shown in explore and embeds (max 300 characters).
`instructions`	string	Required	System prompt that defines the character's personality, tone, and behavior. Supports Markdown.
`model`	string	Optional	Backing LLM. Choose from our available models. See the models documentation for the full list of supported identifiers.
`avatar_url`	string	Optional	URL to a square image used as the character's avatar (recommended 256x256+).
`is_public`	boolean	Optional	Whether the character appears in the public explore feed. Defaults to false.
`category`	string	Optional	Explore category. One of assistant, tutor, character, coach, companion, creative, developer, or other.
`greeting_message`	string	Optional	First message the character sends when a new conversation starts. Omit to let the character generate one.
`voice_id`	string	Optional	Identifier for the TTS voice used in voice sessions (e.g. alloy, echo, fable).

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Atlas",
  "description": "A curious research assistant that loves diving deep into topics.",
  "instructions": "You are Atlas, a knowledgeable and curious research assistant...",
  "model": "default",
  "avatar_url": "https://cdn.dyva.ai/avatars/atlas.png",
  "is_public": true,
  "category": "assistant",
  "greeting_message": "Hey! I'm Atlas. What are we researching today?",
  "voice_id": "alloy",
  "message_count": 4832,
  "creator_id": "usr_9f8e7d6c5b4a3210",
  "created_at": "2026-01-15T08:30:00Z",
  "updated_at": "2026-03-08T14:22:10Z"
}

Examples

$_cURL

JSJavaScript

curl -X POST https://api.dyva.ai/v1/dyvas \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Atlas",
    "description": "A curious research assistant.",
    "instructions": "You are Atlas, a knowledgeable research assistant who explains complex topics clearly.",
    "model": "default",
    "is_public": true,
    "category": "assistant",
    "greeting_message": "Hey! I\u0027m Atlas. What are we researching today?"
  }'

GET/v1/dyvasAuth Required

List your characters. Supports pagination and sorting.

Path Parameters

Name	Type	Required	Description
`limit`	integer	Optional	Max items to return (1-100). Defaults to 20.
`offset`	integer	Optional	Number of items to skip for pagination. Defaults to 0.
`sort`	string	Optional	Sort order. One of "created_at", "updated_at", or "name". Defaults to "created_at".

Response

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Atlas",
      "description": "A curious research assistant that loves diving deep into topics.",
      "model": "default",
      "avatar_url": "https://cdn.dyva.ai/avatars/atlas.png",
      "is_public": true,
      "category": "assistant",
      "message_count": 4832,
      "created_at": "2026-01-15T08:30:00Z",
      "updated_at": "2026-03-08T14:22:10Z"
    },
    {
      "id": "f0e1d2c3-b4a5-6789-0fed-cba987654321",
      "name": "Luna",
      "description": "Creative writing partner with a flair for storytelling.",
      "model": "creative",
      "avatar_url": "https://cdn.dyva.ai/avatars/luna.png",
      "is_public": false,
      "category": "creative",
      "message_count": 1290,
      "created_at": "2026-02-03T19:10:00Z",
      "updated_at": "2026-03-07T11:45:30Z"
    }
  ],
  "total": 2,
  "limit": 20,
  "offset": 0
}

Examples

$_cURL

JSJavaScript

curl https://api.dyva.ai/v1/dyvas?limit=10&sort=updated_at \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/v1/dyvas/:idAuth Required

Get full details for a single character.

Path Parameters

Name	Type	Required	Description
`id`	string (UUID)	Required	Unique identifier of the character.

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Atlas",
  "description": "A curious research assistant that loves diving deep into topics.",
  "instructions": "You are Atlas, a knowledgeable and curious research assistant...",
  "model": "default",
  "avatar_url": "https://cdn.dyva.ai/avatars/atlas.png",
  "is_public": true,
  "category": "assistant",
  "greeting_message": "Hey! I'm Atlas. What are we researching today?",
  "voice_id": "alloy",
  "message_count": 4832,
  "creator_id": "usr_9f8e7d6c5b4a3210",
  "created_at": "2026-01-15T08:30:00Z",
  "updated_at": "2026-03-08T14:22:10Z"
}

Examples

$_cURL

JSJavaScript

curl https://api.dyva.ai/v1/dyvas/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer YOUR_API_KEY"

PUT/v1/dyvas/:idAuth Required

Update one or more fields. Only included fields are changed.

Path Parameters

Name	Type	Required	Description
`id`	string (UUID)	Required	Unique identifier of the character.

Request Body

Name	Type	Required	Description
`name`	string	Optional	Display name of the character (1-80 characters).
`description`	string	Optional	Short public description shown in explore and embeds (max 300 characters).
`instructions`	string	Optional	System prompt that defines the character's personality, tone, and behavior. Supports Markdown.
`model`	string	Optional	Backing LLM. Choose from our available models. See the models documentation for the full list of supported identifiers.
`avatar_url`	string	Optional	URL to a square image used as the character's avatar (recommended 256x256+).
`is_public`	boolean	Optional	Whether the character appears in the public explore feed. Defaults to false.
`category`	string	Optional	Explore category. One of assistant, tutor, character, coach, companion, creative, developer, or other.
`greeting_message`	string	Optional	First message the character sends when a new conversation starts. Omit to let the character generate one.
`voice_id`	string	Optional	Identifier for the TTS voice used in voice sessions (e.g. alloy, echo, fable).

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Atlas",
  "description": "A curious research assistant that loves diving deep into topics.",
  "instructions": "You are Atlas, a knowledgeable and curious research assistant...",
  "model": "default",
  "avatar_url": "https://cdn.dyva.ai/avatars/atlas.png",
  "is_public": true,
  "category": "assistant",
  "greeting_message": "Hey! I'm Atlas. What are we researching today?",
  "voice_id": "alloy",
  "message_count": 4832,
  "creator_id": "usr_9f8e7d6c5b4a3210",
  "created_at": "2026-01-15T08:30:00Z",
  "updated_at": "2026-03-08T14:22:10Z"
}

Examples

$_cURL

JSJavaScript

curl -X PUT https://api.dyva.ai/v1/dyvas/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description for Atlas.",
    "model": "creative"
  }'

DELETE/v1/dyvas/:idAuth Required

Delete a character and all its conversations. Cannot be undone.

Path Parameters

Name	Type	Required	Description
`id`	string (UUID)	Required	Unique identifier of the character.

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "deleted": true
}

Examples

$_cURL

JSJavaScript

curl -X DELETE https://api.dyva.ai/v1/dyvas/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/v1/dyvas/exploreAuth Required

Browse public characters. Filter by category, search by name, sort by popularity, recency, or trending.

Path Parameters

Name	Type	Required	Description
`category`	string	Optional	Filter by category (assistant, tutor, character, coach, companion, creative, developer, other).
`sort`	string	Optional	Sort order. One of "popular", "recent", or "trending". Defaults to "popular".
`limit`	integer	Optional	Max items to return (1-100). Defaults to 20.
`offset`	integer	Optional	Number of items to skip for pagination. Defaults to 0.
`q`	string	Optional	Free-text search across name and description.

Response

{
  "data": [
    {
      "id": "c3d4e5f6-a1b2-7890-fedc-ba0987654321",
      "name": "CodePilot",
      "description": "Senior engineer that reviews your code and suggests improvements.",
      "model": "default",
      "avatar_url": "https://cdn.dyva.ai/avatars/codepilot.png",
      "is_public": true,
      "category": "developer",
      "message_count": 28401,
      "creator_id": "usr_1a2b3c4d5e6f7890",
      "created_at": "2025-12-01T10:00:00Z",
      "updated_at": "2026-03-09T02:15:00Z"
    }
  ],
  "total": 148,
  "limit": 20,
  "offset": 0
}

Examples

$_cURL

JSJavaScript

curl "https://api.dyva.ai/v1/dyvas/explore?category=developer&sort=trending&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Characters API

POST /v1/dyvas

Request Body

Response

Examples

GET /v1/dyvas

Path Parameters

Response

Examples

GET /v1/dyvas/:id

Path Parameters

Response

Examples

PUT /v1/dyvas/:id

Path Parameters

Request Body

Response

Examples

DELETE /v1/dyvas/:id

Path Parameters

Response

Examples

GET /v1/dyvas/explore

Path Parameters

Response

Examples

Characters API

POST /v1/dyvas

Request Body

Response

Examples

GET /v1/dyvas

Path Parameters

Response

Examples

GET /v1/dyvas/:id

Path Parameters

Response

Examples

PUT /v1/dyvas/:id

Path Parameters

Request Body

Response

Examples

DELETE /v1/dyvas/:id

Path Parameters

Response

Examples

GET /v1/dyvas/explore

Path Parameters

Response

Examples