Four steps. Account, API key, character, first message. Done.
Base URL https://api.dyva.ai/v1
Prerequisites
Sign up in the dashboard or hit the API. Only unauthenticated endpoint.
/v1/auth/registerRegister. Returns an access token.
Request body (3)
emailstringRequiredpasswordstringRequiredusernamestringRequiredResponse
Illustrative example, not a captured response{
"id": "usr_a1b2c3d4e5f6",
"email": "[email protected]",
"username": "your_username",
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "bearer",
"created_at": "2026-03-09T12:00:00Z"
}Examples (4)
curl -X POST https://api.dyva.ai/v1/auth/register \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"password": "s3cure_passw0rd!",
"username": "your_username"
}'Getting a validation error instead? Registration returns field-level messages, listed in Error Handling.
Long-lived credentials. Create from Settings or hit the API with your Step 1 token.
/v1/auth/api-keysGenerate a new API key.
Request body (3)
namestringRequiredscopesstring[]Optionalexpires_innumberOptionalResponse
Illustrative example, not a captured response{
"id": "key_m9n8o7p6q5r4",
"name": "Development",
"key": "rp_live_abc123def456ghi789jkl012mno345",
"scopes": ["*"],
"created_at": "2026-03-09T12:01:00Z",
"expires_at": null
}Examples (4)
curl -X POST https://api.dyva.ai/v1/auth/api-keys \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
-H "Content-Type: application/json" \
-d '{
"name": "Development"
}'Getting unauthorized here or on any step after this one? See the fixes in Error Handling.
A Dyva is an AI persona. Name, instructions, model. That is the whole thing.
/v1/dyvasCreate a character with personality and model.
Request body (5)
namestringRequireddescriptionstringOptionalinstructionsstringRequiredmodelstringRequiredvisibilitystringOptionalResponse
Illustrative example, not a captured 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 (4)
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"
}'Threaded message histories. Create one, send messages.
/v1/conversationsOpen a new conversation with a Dyva.
Request body (2)
dyva_idstringRequiredtitlestringOptionalResponse
Illustrative example, not a captured 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 (4)
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"
}'/v1/conversations/:id/messagesSend a message. Get a response.
Path and query parameters (1)
idstringRequiredRequest body (1)
contentstringRequiredResponse
Illustrative example, not a captured 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 (4)
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."
}'All four steps in one script. Swap in your credentials.
# 1. Register
TOKEN=$(curl -s -X POST https://api.dyva.ai/v1/auth/register \
-H "Content-Type: application/json" \
-d '{
"email": "[email protected]",
"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."}'