Characters API

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

3 min read6 endpoints

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

POST `/v1/dyvas`

Create a character with a name and, optionally, a system prompt, greeting, personality, and visibility.

Bearer token

Route and method verified directly against the live ts-api source on August 13, 2026.

Request body (12)

namestringRequired: Display name of the character.
taglinestringOptional: Short public description shown in explore and cards.
system_promptstringOptional: Defines the character's personality, tone, and behavior. Returned as null to anyone who isn't the owner.
greeting_messagestringOptional: First message the character sends when a new conversation starts.
scenariostringOptional: Scene-setting context injected alongside the system prompt.
personalityobjectOptional: Free-form personality traits, stored as JSON. Merged (not replaced) on later updates.
conversation_startersstring[]Optional: Suggested opening lines shown to a new chatter.
avatar_urlstringOptional: URL to a square image used as the character's avatar.
voice_enabledbooleanOptional: Whether voice sessions are available for this character. Defaults to false.
memory_enabledbooleanOptional: Whether the character forms long-term memory of conversations. Defaults to true.
web_searchbooleanOptional: Whether the character can search the web mid-conversation. Defaults to false.
visibilitystringOptional: One of "private", "unlisted", or "public". A request for "public" at creation is always held at "unlisted" until the character clears review: there is no direct path to public on create.

Response

Illustrative example, not a captured response

{
  "id": "00000000-0000-4000-8000-EXAMPLE00001",
  "slug": "atlas-research-assistant",
  "name": "Atlas",
  "tagline": "A curious research assistant that loves diving deep into topics.",
  "system_prompt": "You are Atlas, a knowledgeable and curious research assistant...",
  "greeting_message": "Hey! I'm Atlas. What are we researching today?",
  "scenario": null,
  "personality": { "traits": ["curious", "precise"] },
  "conversation_starters": ["What are you working on?"],
  "avatar_url": "https://cdn.dyva.ai/avatars/EXAMPLE00001.webp",
  "voice_enabled": false,
  "memory_enabled": true,
  "web_search": false,
  "visibility": "unlisted",
  "total_conversations": 4832,
  "total_messages": 40211,
  "avg_rating": 4.8,
  "created_at": "2026-01-15T08:30:00.000Z",
  "updated_at": "2026-03-08T14:22:10.000Z"
}

// Abbreviated. The live row also carries fields this page doesn't
// document (moderation status, monetization flags, embed settings,
// LoRA/appearance fields): a representative subset, not the complete
// column list.

Examples (2)

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

GET `/v1/dyvas`

List every character you own. Returns a plain array; there is no pagination, sort, or filter parameter on this endpoint.

Bearer token

Route and method verified directly against the live ts-api source on August 13, 2026.

Response

Illustrative example, not a captured response

[
  {
    "id": "00000000-0000-4000-8000-EXAMPLE00001",
    "slug": "atlas-research-assistant",
    "name": "Atlas",
    "tagline": "A curious research assistant that loves diving deep into topics.",
    "avatar_url": "https://cdn.dyva.ai/avatars/EXAMPLE00001.webp",
    "visibility": "unlisted",
    "voice_enabled": false,
    "memory_enabled": true,
    "total_conversations": 4832,
    "total_messages": 40211,
    "avg_rating": 4.8,
    "created_at": "2026-01-15T08:30:00.000Z"
  }
]

// Returns every character you own in one response. There is no limit,
// offset, or sort parameter on this endpoint.

Examples (2)

curl https://api.dyva.ai/v1/dyvas \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

GET `/v1/dyvas/:id`

Get full details for a single character. Works without a token for public and unlisted characters; private characters are visible only to their owner. The system prompt is returned as null unless you're the owner.

Public

Route and method verified directly against the live ts-api source on August 13, 2026.

Path and query parameters (1)

idstringRequired: The character's UUID, or its slug (e.g. atlas-research-assistant). Both resolve the same row.

Response

Illustrative example, not a captured response

{
  "id": "00000000-0000-4000-8000-EXAMPLE00001",
  "slug": "atlas-research-assistant",
  "name": "Atlas",
  "tagline": "A curious research assistant that loves diving deep into topics.",
  "system_prompt": "You are Atlas, a knowledgeable and curious research assistant...",
  "greeting_message": "Hey! I'm Atlas. What are we researching today?",
  "scenario": null,
  "personality": { "traits": ["curious", "precise"] },
  "conversation_starters": ["What are you working on?"],
  "avatar_url": "https://cdn.dyva.ai/avatars/EXAMPLE00001.webp",
  "voice_enabled": false,
  "memory_enabled": true,
  "web_search": false,
  "visibility": "unlisted",
  "total_conversations": 4832,
  "total_messages": 40211,
  "avg_rating": 4.8,
  "created_at": "2026-01-15T08:30:00.000Z",
  "updated_at": "2026-03-08T14:22:10.000Z"
}

// Abbreviated. The live row also carries fields this page doesn't
// document (moderation status, monetization flags, embed settings,
// LoRA/appearance fields): a representative subset, not the complete
// column list.

Examples (2)

curl https://api.dyva.ai/v1/dyvas/atlas-research-assistant \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

PATCH `/v1/dyvas/:id`

Update one or more fields. Only included fields change. This page previously documented this as a PUT; grepping the live route table on 2026-08-13 found only a PATCH handler. There is no PUT route for this path.

Bearer token

Route and method verified directly against the live ts-api source on August 13, 2026.

Path and query parameters (1)

idstringRequired: The character's UUID, or its slug (e.g. atlas-research-assistant). Both resolve the same row.

Request body (14)

namestringOptional: Display name of the character.
taglinestringOptional: Short public description shown in explore and cards.
system_promptstringOptional: Defines the character's personality, tone, and behavior. Returned as null to anyone who isn't the owner.
greeting_messagestringOptional: First message the character sends when a new conversation starts.
scenariostringOptional: Scene-setting context injected alongside the system prompt.
personalityobjectOptional: Free-form personality traits, stored as JSON. Merged (not replaced) on later updates.
conversation_startersstring[]Optional: Suggested opening lines shown to a new chatter.
avatar_urlstringOptional: URL to a square image used as the character's avatar.
voice_enabledbooleanOptional: Whether voice sessions are available for this character. Defaults to false.
memory_enabledbooleanOptional: Whether the character forms long-term memory of conversations. Defaults to true.
web_searchbooleanOptional: Whether the character can search the web mid-conversation. Defaults to false.
visibilitystringOptional: One of "private", "unlisted", or "public". A request for "public" at creation is always held at "unlisted" until the character clears review: there is no direct path to public on create.
voice_idstringOptional: Selects a specific TTS voice for this character. Not settable at creation, only here.
msg_credit_costintegerOptional: Sparks charged per message to this character, if the creator has monetized it.

Response

Illustrative example, not a captured response

{
  "id": "00000000-0000-4000-8000-EXAMPLE00001",
  "slug": "atlas-research-assistant",
  "name": "Atlas",
  "tagline": "A curious research assistant that loves diving deep into topics.",
  "system_prompt": "You are Atlas, a knowledgeable and curious research assistant...",
  "greeting_message": "Hey! I'm Atlas. What are we researching today?",
  "scenario": null,
  "personality": { "traits": ["curious", "precise"] },
  "conversation_starters": ["What are you working on?"],
  "avatar_url": "https://cdn.dyva.ai/avatars/EXAMPLE00001.webp",
  "voice_enabled": false,
  "memory_enabled": true,
  "web_search": false,
  "visibility": "unlisted",
  "total_conversations": 4832,
  "total_messages": 40211,
  "avg_rating": 4.8,
  "created_at": "2026-01-15T08:30:00.000Z",
  "updated_at": "2026-03-08T14:22:10.000Z"
}

// Abbreviated. The live row also carries fields this page doesn't
// document (moderation status, monetization flags, embed settings,
// LoRA/appearance fields): a representative subset, not the complete
// column list.

Examples (2)

curl -X PATCH https://api.dyva.ai/v1/dyvas/atlas-research-assistant \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tagline": "Updated tagline for Atlas.",
    "voice_enabled": true
  }'

DELETE `/v1/dyvas/:id`

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

Bearer token

Route and method verified directly against the live ts-api source on August 13, 2026.

Path and query parameters (1)

idstringRequired: The character's UUID, or its slug (e.g. atlas-research-assistant). Both resolve the same row.

Response

Illustrative example, not a captured response

HTTP/1.1 204 No Content

Examples (2)

curl -X DELETE https://api.dyva.ai/v1/dyvas/atlas-research-assistant \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

GET `/v1/dyvas/explore`

Browse public characters. This endpoint has no auth requirement at all; the Authorization header shown here is optional.

Public

Route and method verified directly against the live ts-api source on August 13, 2026.

Path and query parameters (3)

categorystringOptional: A category UUID or category slug. Unrecognized values are ignored, not rejected.
sortstringOptional: One of "popular" (default), "new", "rating", or "trending".
limitintegerOptional: Max items to return (1-100). Defaults to 50.

Response

Illustrative example, not a captured response

[
  {
    "id": "00000000-0000-4000-8000-EXAMPLE00002",
    "slug": "codepilot",
    "name": "CodePilot",
    "tagline": "Senior engineer that reviews your code and suggests improvements.",
    "avatar_url": "https://cdn.dyva.ai/avatars/EXAMPLE00002.webp",
    "category_id": "00000000-0000-4000-8000-EXAMPLE00099",
    "category_name": "Developer",
    "total_conversations": 28401,
    "total_messages": 190442,
    "avg_rating": 4.9,
    "like_count": 3120,
    "voice_enabled": true,
    "owner_id": "00000000-0000-4000-8000-EXAMPLE00003",
    "created_at": "2025-12-01T10:00:00.000Z"
  }
]

Examples (2)

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

Browse the complete endpoint directory

Characters API

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

3 min read6 endpoints

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

POST `/v1/dyvas`

Create a character with a name and, optionally, a system prompt, greeting, personality, and visibility.

Bearer token

Route and method verified directly against the live ts-api source on August 13, 2026.

Request body (12)

namestringRequired: Display name of the character.
taglinestringOptional: Short public description shown in explore and cards.
system_promptstringOptional: Defines the character's personality, tone, and behavior. Returned as null to anyone who isn't the owner.
greeting_messagestringOptional: First message the character sends when a new conversation starts.
scenariostringOptional: Scene-setting context injected alongside the system prompt.
personalityobjectOptional: Free-form personality traits, stored as JSON. Merged (not replaced) on later updates.
conversation_startersstring[]Optional: Suggested opening lines shown to a new chatter.
avatar_urlstringOptional: URL to a square image used as the character's avatar.
voice_enabledbooleanOptional: Whether voice sessions are available for this character. Defaults to false.
memory_enabledbooleanOptional: Whether the character forms long-term memory of conversations. Defaults to true.
web_searchbooleanOptional: Whether the character can search the web mid-conversation. Defaults to false.
visibilitystringOptional: One of "private", "unlisted", or "public". A request for "public" at creation is always held at "unlisted" until the character clears review: there is no direct path to public on create.

Response

Illustrative example, not a captured response

{
  "id": "00000000-0000-4000-8000-EXAMPLE00001",
  "slug": "atlas-research-assistant",
  "name": "Atlas",
  "tagline": "A curious research assistant that loves diving deep into topics.",
  "system_prompt": "You are Atlas, a knowledgeable and curious research assistant...",
  "greeting_message": "Hey! I'm Atlas. What are we researching today?",
  "scenario": null,
  "personality": { "traits": ["curious", "precise"] },
  "conversation_starters": ["What are you working on?"],
  "avatar_url": "https://cdn.dyva.ai/avatars/EXAMPLE00001.webp",
  "voice_enabled": false,
  "memory_enabled": true,
  "web_search": false,
  "visibility": "unlisted",
  "total_conversations": 4832,
  "total_messages": 40211,
  "avg_rating": 4.8,
  "created_at": "2026-01-15T08:30:00.000Z",
  "updated_at": "2026-03-08T14:22:10.000Z"
}

// Abbreviated. The live row also carries fields this page doesn't
// document (moderation status, monetization flags, embed settings,
// LoRA/appearance fields): a representative subset, not the complete
// column list.

Examples (2)

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

GET `/v1/dyvas`

List every character you own. Returns a plain array; there is no pagination, sort, or filter parameter on this endpoint.

Bearer token

Route and method verified directly against the live ts-api source on August 13, 2026.

Response

Illustrative example, not a captured response

[
  {
    "id": "00000000-0000-4000-8000-EXAMPLE00001",
    "slug": "atlas-research-assistant",
    "name": "Atlas",
    "tagline": "A curious research assistant that loves diving deep into topics.",
    "avatar_url": "https://cdn.dyva.ai/avatars/EXAMPLE00001.webp",
    "visibility": "unlisted",
    "voice_enabled": false,
    "memory_enabled": true,
    "total_conversations": 4832,
    "total_messages": 40211,
    "avg_rating": 4.8,
    "created_at": "2026-01-15T08:30:00.000Z"
  }
]

// Returns every character you own in one response. There is no limit,
// offset, or sort parameter on this endpoint.

Examples (2)

curl https://api.dyva.ai/v1/dyvas \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

GET `/v1/dyvas/:id`

Public

Route and method verified directly against the live ts-api source on August 13, 2026.

Path and query parameters (1)

idstringRequired: The character's UUID, or its slug (e.g. atlas-research-assistant). Both resolve the same row.

Response

Illustrative example, not a captured response

{
  "id": "00000000-0000-4000-8000-EXAMPLE00001",
  "slug": "atlas-research-assistant",
  "name": "Atlas",
  "tagline": "A curious research assistant that loves diving deep into topics.",
  "system_prompt": "You are Atlas, a knowledgeable and curious research assistant...",
  "greeting_message": "Hey! I'm Atlas. What are we researching today?",
  "scenario": null,
  "personality": { "traits": ["curious", "precise"] },
  "conversation_starters": ["What are you working on?"],
  "avatar_url": "https://cdn.dyva.ai/avatars/EXAMPLE00001.webp",
  "voice_enabled": false,
  "memory_enabled": true,
  "web_search": false,
  "visibility": "unlisted",
  "total_conversations": 4832,
  "total_messages": 40211,
  "avg_rating": 4.8,
  "created_at": "2026-01-15T08:30:00.000Z",
  "updated_at": "2026-03-08T14:22:10.000Z"
}

// Abbreviated. The live row also carries fields this page doesn't
// document (moderation status, monetization flags, embed settings,
// LoRA/appearance fields): a representative subset, not the complete
// column list.

Examples (2)

curl https://api.dyva.ai/v1/dyvas/atlas-research-assistant \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

PATCH `/v1/dyvas/:id`

Bearer token

Route and method verified directly against the live ts-api source on August 13, 2026.

Path and query parameters (1)

idstringRequired: The character's UUID, or its slug (e.g. atlas-research-assistant). Both resolve the same row.

Request body (14)

namestringOptional: Display name of the character.
taglinestringOptional: Short public description shown in explore and cards.
system_promptstringOptional: Defines the character's personality, tone, and behavior. Returned as null to anyone who isn't the owner.
greeting_messagestringOptional: First message the character sends when a new conversation starts.
scenariostringOptional: Scene-setting context injected alongside the system prompt.
personalityobjectOptional: Free-form personality traits, stored as JSON. Merged (not replaced) on later updates.
conversation_startersstring[]Optional: Suggested opening lines shown to a new chatter.
avatar_urlstringOptional: URL to a square image used as the character's avatar.
voice_enabledbooleanOptional: Whether voice sessions are available for this character. Defaults to false.
memory_enabledbooleanOptional: Whether the character forms long-term memory of conversations. Defaults to true.
web_searchbooleanOptional: Whether the character can search the web mid-conversation. Defaults to false.
visibilitystringOptional: One of "private", "unlisted", or "public". A request for "public" at creation is always held at "unlisted" until the character clears review: there is no direct path to public on create.
voice_idstringOptional: Selects a specific TTS voice for this character. Not settable at creation, only here.
msg_credit_costintegerOptional: Sparks charged per message to this character, if the creator has monetized it.

Response

Illustrative example, not a captured response

{
  "id": "00000000-0000-4000-8000-EXAMPLE00001",
  "slug": "atlas-research-assistant",
  "name": "Atlas",
  "tagline": "A curious research assistant that loves diving deep into topics.",
  "system_prompt": "You are Atlas, a knowledgeable and curious research assistant...",
  "greeting_message": "Hey! I'm Atlas. What are we researching today?",
  "scenario": null,
  "personality": { "traits": ["curious", "precise"] },
  "conversation_starters": ["What are you working on?"],
  "avatar_url": "https://cdn.dyva.ai/avatars/EXAMPLE00001.webp",
  "voice_enabled": false,
  "memory_enabled": true,
  "web_search": false,
  "visibility": "unlisted",
  "total_conversations": 4832,
  "total_messages": 40211,
  "avg_rating": 4.8,
  "created_at": "2026-01-15T08:30:00.000Z",
  "updated_at": "2026-03-08T14:22:10.000Z"
}

// Abbreviated. The live row also carries fields this page doesn't
// document (moderation status, monetization flags, embed settings,
// LoRA/appearance fields): a representative subset, not the complete
// column list.

Examples (2)

curl -X PATCH https://api.dyva.ai/v1/dyvas/atlas-research-assistant \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tagline": "Updated tagline for Atlas.",
    "voice_enabled": true
  }'

DELETE `/v1/dyvas/:id`

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

Bearer token

Route and method verified directly against the live ts-api source on August 13, 2026.

Path and query parameters (1)

idstringRequired: The character's UUID, or its slug (e.g. atlas-research-assistant). Both resolve the same row.

Response

Illustrative example, not a captured response

HTTP/1.1 204 No Content

Examples (2)

curl -X DELETE https://api.dyva.ai/v1/dyvas/atlas-research-assistant \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

GET `/v1/dyvas/explore`

Browse public characters. This endpoint has no auth requirement at all; the Authorization header shown here is optional.

Public

Route and method verified directly against the live ts-api source on August 13, 2026.

Path and query parameters (3)

categorystringOptional: A category UUID or category slug. Unrecognized values are ignored, not rejected.
sortstringOptional: One of "popular" (default), "new", "rating", or "trending".
limitintegerOptional: Max items to return (1-100). Defaults to 50.

Response

Illustrative example, not a captured response

[
  {
    "id": "00000000-0000-4000-8000-EXAMPLE00002",
    "slug": "codepilot",
    "name": "CodePilot",
    "tagline": "Senior engineer that reviews your code and suggests improvements.",
    "avatar_url": "https://cdn.dyva.ai/avatars/EXAMPLE00002.webp",
    "category_id": "00000000-0000-4000-8000-EXAMPLE00099",
    "category_name": "Developer",
    "total_conversations": 28401,
    "total_messages": 190442,
    "avg_rating": 4.9,
    "like_count": 3120,
    "voice_enabled": true,
    "owner_id": "00000000-0000-4000-8000-EXAMPLE00003",
    "created_at": "2025-12-01T10:00:00.000Z"
  }
]

Examples (2)

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

Browse the complete endpoint directory

POST /v1/dyvas

GET /v1/dyvas

GET /v1/dyvas/:id

PATCH /v1/dyvas/:id

DELETE /v1/dyvas/:id

GET /v1/dyvas/explore

POST /v1/dyvas

GET /v1/dyvas

GET /v1/dyvas/:id

PATCH /v1/dyvas/:id

DELETE /v1/dyvas/:id

GET /v1/dyvas/explore

POST `/v1/dyvas`

GET `/v1/dyvas`

GET `/v1/dyvas/:id`

PATCH `/v1/dyvas/:id`

DELETE `/v1/dyvas/:id`

GET `/v1/dyvas/explore`

POST `/v1/dyvas`

GET `/v1/dyvas`

GET `/v1/dyvas/:id`

PATCH `/v1/dyvas/:id`

DELETE `/v1/dyvas/:id`

GET `/v1/dyvas/explore`