Quick Start

Four steps. Account, API key, character, first message. Done.

Base URL

https://api.dyva.ai/v1

Prerequisites

curl, Node.js, or Python 3.8+
A terminal or API client

Create An Account

POST/v1/auth/register

Request Body

Name	Type	Required	Description
`email`	string	Required	Your email.
`password`	string	Required	8+ characters.
`username`	string	Required	3-32 chars, alphanumeric and underscores.

Response

{
  "id": "usr_a1b2c3d4e5f6",
  "email": "you@example.com",
  "username": "your_username",
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "created_at": "2026-03-09T12:00:00Z"
}

Examples

$_curl

JSJavaScript

TSTypeScript

PyPython

curl -X POST https://api.dyva.ai/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "s3cure_passw0rd!",
    "username": "your_username"
  }'

WarningSave your access token. You need it for Step 2. Use a long-lived API key for production.

Generate An API Key

Long-lived credentials. Create from Settings or hit the API with your Step 1 token.

POST/v1/auth/api-keysAuth Required

Generate a new API key.

Request Body

Name	Type	Required	Description
`name`	string	Required	Label for the key.
`scopes`	string[]	Optional	Permission scopes. Defaults to all.
`expires_in`	number	Optional	Seconds until expiry. Omit for permanent.

Response

{
  "id": "key_m9n8o7p6q5r4",
  "name": "Development",
  "key": "rp_live_abc123def456ghi789jkl012mno345",
  "scopes": ["*"],
  "created_at": "2026-03-09T12:01:00Z",
  "expires_at": null
}

Examples

$_curl

JSJavaScript

TSTypeScript

PyPython

curl -X POST https://api.dyva.ai/v1/auth/api-keys \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Development"
  }'

ImportantShown once. Copy it now. Lost keys get revoked and regenerated.

Create Your First Dyva

A Dyva is an AI persona. Name, instructions, model. That is the whole thing.

POST/v1/dyvasAuth Required

Create a character with personality and model.

Request Body

Name	Type	Required	Description
`name`	string	Required	Display name.
`description`	string	Optional	Public one-liner.
`instructions`	string	Required	System prompt. Defines personality and behavior.
`model`	string	Required	Model ID. See models docs for options.
`visibility`	string	Optional	"private" (default) or "public". Public ones hit the marketplace.

Response

{
  "id": "rpl_x4y5z6a7b8c9",
  "name": "Code Mentor",
  "description": "A patient programming tutor that explains concepts with real-world analogies.",
  "instructions": "You are Code Mentor, a senior software engineer...",
  "model": "grok-3",
  "visibility": "private",
  "owner_id": "usr_a1b2c3d4e5f6",
  "created_at": "2026-03-09T12:02:00Z",
  "updated_at": "2026-03-09T12:02:00Z"
}

Examples

$_curl

JSJavaScript

TSTypeScript

PyPython

curl -X POST https://api.dyva.ai/v1/dyvas \
  -H "Authorization: Bearer rp_live_abc123def456ghi789jkl012mno345" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Code Mentor",
    "description": "A patient programming tutor that explains concepts with real-world analogies.",
    "instructions": "You are Code Mentor, a senior software engineer who teaches programming. Break down complex topics into simple explanations. Use real-world analogies. Always provide working code examples.",
    "model": "grok-3"
  }'

Start A Conversation

Threaded message histories. Create one, send messages.

4a. Create a conversation

POST/v1/conversationsAuth Required

Open a new conversation with a Dyva.

Request Body

Name	Type	Required	Description
`dyva_id`	string	Required	Dyva to talk to.
`title`	string	Optional	Optional title.

Response

{
  "id": "conv_j1k2l3m4n5o6",
  "dyva_id": "rpl_x4y5z6a7b8c9",
  "title": null,
  "message_count": 0,
  "created_at": "2026-03-09T12:03:00Z",
  "updated_at": "2026-03-09T12:03:00Z"
}

Examples

$_curl

JSJavaScript

TSTypeScript

PyPython

curl -X POST https://api.dyva.ai/v1/conversations \
  -H "Authorization: Bearer rp_live_abc123def456ghi789jkl012mno345" \
  -H "Content-Type: application/json" \
  -d '{
    "dyva_id": "rpl_x4y5z6a7b8c9"
  }'

4b. Send a message

POST/v1/conversations/:id/messagesAuth Required

Send a message. Get a response.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	Conversation ID.

Request Body

Name	Type	Required	Description
`content`	string	Required	Message text.

Response

{
  "id": "msg_p7q8r9s0t1u2",
  "conversation_id": "conv_j1k2l3m4n5o6",
  "role": "assistant",
  "content": "Hey! Great question. Think of recursion like Russian nesting dolls...",
  "model": "grok-3",
  "tokens": { "prompt": 142, "completion": 87, "total": 229 },
  "created_at": "2026-03-09T12:03:05Z"
}

Examples

$_curl

JSJavaScript

TSTypeScript

PyPython

curl -X POST https://api.dyva.ai/v1/conversations/conv_j1k2l3m4n5o6/messages \
  -H "Authorization: Bearer rp_live_abc123def456ghi789jkl012mno345" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Explain recursion like I am a beginner."
  }'

Complete Example

All four steps in one script. Swap in your credentials.

$_curl

JSJavaScript

TSTypeScript

PyPython

# 1. Register
TOKEN=$(curl -s -X POST https://api.dyva.ai/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "s3cure_passw0rd!",
    "username": "your_username"
  }' | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")

# 2. Create API key
API_KEY=$(curl -s -X POST https://api.dyva.ai/v1/auth/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Quickstart"}' | python3 -c "import sys,json; print(json.load(sys.stdin)['key'])")

# 3. Create a Dyva
DYVA_ID=$(curl -s -X POST https://api.dyva.ai/v1/dyvas \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Code Mentor",
    "instructions": "You are a patient programming tutor.",
    "model": "grok-3"
  }' | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")

# 4a. Start a conversation
CONV_ID=$(curl -s -X POST https://api.dyva.ai/v1/conversations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{"dyva_id": "$DYVA_ID"}" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")

# 4b. Send a message
curl -X POST "https://api.dyva.ai/v1/conversations/$CONV_ID/messages" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Explain recursion like I am a beginner."}'

Documentation

Authentication

Quick Start

Four steps. Account, API key, character, first message. Done.

Base URL

https://api.dyva.ai/v1

Prerequisites

curl, Node.js, or Python 3.8+
A terminal or API client

Create An Account

POST/v1/auth/register

Request Body

Name	Type	Required	Description
`email`	string	Required	Your email.
`password`	string	Required	8+ characters.
`username`	string	Required	3-32 chars, alphanumeric and underscores.

Response

{
  "id": "usr_a1b2c3d4e5f6",
  "email": "you@example.com",
  "username": "your_username",
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "created_at": "2026-03-09T12:00:00Z"
}

Examples

$_curl

JSJavaScript

TSTypeScript

PyPython

curl -X POST https://api.dyva.ai/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "s3cure_passw0rd!",
    "username": "your_username"
  }'

WarningSave your access token. You need it for Step 2. Use a long-lived API key for production.

Generate An API Key

Long-lived credentials. Create from Settings or hit the API with your Step 1 token.

POST/v1/auth/api-keysAuth Required

Generate a new API key.

Request Body

Name	Type	Required	Description
`name`	string	Required	Label for the key.
`scopes`	string[]	Optional	Permission scopes. Defaults to all.
`expires_in`	number	Optional	Seconds until expiry. Omit for permanent.

Response

{
  "id": "key_m9n8o7p6q5r4",
  "name": "Development",
  "key": "rp_live_abc123def456ghi789jkl012mno345",
  "scopes": ["*"],
  "created_at": "2026-03-09T12:01:00Z",
  "expires_at": null
}

Examples

$_curl

JSJavaScript

TSTypeScript

PyPython

curl -X POST https://api.dyva.ai/v1/auth/api-keys \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Development"
  }'

ImportantShown once. Copy it now. Lost keys get revoked and regenerated.

Create Your First Dyva

A Dyva is an AI persona. Name, instructions, model. That is the whole thing.

POST/v1/dyvasAuth Required

Create a character with personality and model.

Request Body

Name	Type	Required	Description
`name`	string	Required	Display name.
`description`	string	Optional	Public one-liner.
`instructions`	string	Required	System prompt. Defines personality and behavior.
`model`	string	Required	Model ID. See models docs for options.
`visibility`	string	Optional	"private" (default) or "public". Public ones hit the marketplace.

Response

{
  "id": "rpl_x4y5z6a7b8c9",
  "name": "Code Mentor",
  "description": "A patient programming tutor that explains concepts with real-world analogies.",
  "instructions": "You are Code Mentor, a senior software engineer...",
  "model": "grok-3",
  "visibility": "private",
  "owner_id": "usr_a1b2c3d4e5f6",
  "created_at": "2026-03-09T12:02:00Z",
  "updated_at": "2026-03-09T12:02:00Z"
}

Examples

$_curl

JSJavaScript

TSTypeScript

PyPython

curl -X POST https://api.dyva.ai/v1/dyvas \
  -H "Authorization: Bearer rp_live_abc123def456ghi789jkl012mno345" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Code Mentor",
    "description": "A patient programming tutor that explains concepts with real-world analogies.",
    "instructions": "You are Code Mentor, a senior software engineer who teaches programming. Break down complex topics into simple explanations. Use real-world analogies. Always provide working code examples.",
    "model": "grok-3"
  }'

Start A Conversation

Threaded message histories. Create one, send messages.

4a. Create a conversation

POST/v1/conversationsAuth Required

Open a new conversation with a Dyva.

Request Body

Name	Type	Required	Description
`dyva_id`	string	Required	Dyva to talk to.
`title`	string	Optional	Optional title.

Response

{
  "id": "conv_j1k2l3m4n5o6",
  "dyva_id": "rpl_x4y5z6a7b8c9",
  "title": null,
  "message_count": 0,
  "created_at": "2026-03-09T12:03:00Z",
  "updated_at": "2026-03-09T12:03:00Z"
}

Examples

$_curl

JSJavaScript

TSTypeScript

PyPython

curl -X POST https://api.dyva.ai/v1/conversations \
  -H "Authorization: Bearer rp_live_abc123def456ghi789jkl012mno345" \
  -H "Content-Type: application/json" \
  -d '{
    "dyva_id": "rpl_x4y5z6a7b8c9"
  }'

4b. Send a message

POST/v1/conversations/:id/messagesAuth Required

Send a message. Get a response.

Path Parameters

Name	Type	Required	Description
`id`	string	Required	Conversation ID.

Request Body

Name	Type	Required	Description
`content`	string	Required	Message text.

Response

{
  "id": "msg_p7q8r9s0t1u2",
  "conversation_id": "conv_j1k2l3m4n5o6",
  "role": "assistant",
  "content": "Hey! Great question. Think of recursion like Russian nesting dolls...",
  "model": "grok-3",
  "tokens": { "prompt": 142, "completion": 87, "total": 229 },
  "created_at": "2026-03-09T12:03:05Z"
}

Examples

$_curl

JSJavaScript

TSTypeScript

PyPython

curl -X POST https://api.dyva.ai/v1/conversations/conv_j1k2l3m4n5o6/messages \
  -H "Authorization: Bearer rp_live_abc123def456ghi789jkl012mno345" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Explain recursion like I am a beginner."
  }'

Complete Example

All four steps in one script. Swap in your credentials.

$_curl

JSJavaScript

TSTypeScript

PyPython

# 1. Register
TOKEN=$(curl -s -X POST https://api.dyva.ai/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "s3cure_passw0rd!",
    "username": "your_username"
  }' | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")

# 2. Create API key
API_KEY=$(curl -s -X POST https://api.dyva.ai/v1/auth/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Quickstart"}' | python3 -c "import sys,json; print(json.load(sys.stdin)['key'])")

# 3. Create a Dyva
DYVA_ID=$(curl -s -X POST https://api.dyva.ai/v1/dyvas \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Code Mentor",
    "instructions": "You are a patient programming tutor.",
    "model": "grok-3"
  }' | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")

# 4a. Start a conversation
CONV_ID=$(curl -s -X POST https://api.dyva.ai/v1/conversations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{"dyva_id": "$DYVA_ID"}" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")

# 4b. Send a message
curl -X POST "https://api.dyva.ai/v1/conversations/$CONV_ID/messages" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Explain recursion like I am a beginner."}'

Documentation

Authentication

Quick Start

Prerequisites

Create An Account

POST /v1/auth/register

Request Body

Response

Examples

Generate An API Key

POST /v1/auth/api-keys

Request Body

Response

Examples

Create Your First Dyva

POST /v1/dyvas

Request Body

Response

Examples

Start A Conversation

4a. Create a conversation

POST /v1/conversations

Request Body

Response

Examples

4b. Send a message

POST /v1/conversations/:id/messages

Path Parameters

Request Body

Response

Examples

Complete Example

Quick Start

Prerequisites

Create An Account

POST /v1/auth/register

Request Body

Response

Examples

Generate An API Key

POST /v1/auth/api-keys

Request Body

Response

Examples

Create Your First Dyva

POST /v1/dyvas

Request Body

Response

Examples

Start A Conversation

4a. Create a conversation

POST /v1/conversations

Request Body

Response

Examples

4b. Send a message

POST /v1/conversations/:id/messages

Path Parameters

Request Body

Response

Examples

Complete Example