API Reference

AuthAccounts, sessions, API keys, and user profiles.12

POST/v1/auth/signupCreate an account and receive a session immediately. Sends a verification email in the background; email_verified starts false.Public POST/v1/auth/loginAuthenticate and receive an access / refresh token pair. Returns requires_2fa instead when the account has TOTP enabled.Public POST/v1/auth/verify-emailVerify email using the token from the verification email.Public POST/v1/auth/forgot-passwordSend a password-reset email. Always responds the same way regardless of whether the email is registered, so the endpoint cannot be used to check who has an account.Public POST/v1/auth/reset-passwordReset password using the token from the reset email. The token is single-use: a second attempt with the same token is rejected even before it expires.Public GET/v1/auth/meGet the authenticated user's full profile.Auth PATCH/v1/auth/meUpdate profile fields. Only fields present in the request body change; this is a representative subset of a larger allowed-field list, not the complete one.Auth POST/v1/api-keysCreate an API key. The full key is returned once, at creation, and never again; only a short prefix is stored for display.Auth GET/v1/api-keysList your API keys. The response is a plain array; keys never include the full secret after creation, only the prefix.Auth DELETE/v1/api-keys/:idRevoke an API key. Requests using it fail immediately afterward. Responds with no body.Auth POST/v1/auth/export-dataDownload a full data export (GDPR Art. 15/20). Streams the file directly in the response; there is no background job, export ID, or polling status to check.Auth DELETE/v1/auth/mePermanently delete your account. Deletion runs immediately, in one transaction; there is no grace period. Add ?dry_run=1 to get the same counts back without changing anything.Auth

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

POST/v1/dyvasCreate a character with a name and, optionally, a system prompt, greeting, personality, and visibility.Auth GET/v1/dyvasList every character you own. Returns a plain array; there is no pagination, sort, or filter parameter on this endpoint.Auth GET/v1/dyvas/:idGet 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 PATCH/v1/dyvas/:idUpdate 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.Auth DELETE/v1/dyvas/:idDelete a character and all its conversations. Cannot be undone.Auth GET/v1/dyvas/exploreBrowse public characters. This endpoint has no auth requirement at all; the Authorization header shown here is optional.Public

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

POST/v1/conversationsStart a conversation with a Dyva. There is no title field: a conversation is untitled until one gets set some other way. If the character has a greeting message, it's inserted immediately, so message_count may already be 1 in the response, not 0.Auth GET/v1/conversationsList your conversations, most recently active first. Returns a plain array; there is no total count or has_more flag. Pagination is page-based, not limit/offset.Auth GET/v1/conversations/:idGet one conversation's own fields: title, character, scene, takeover state. This does not include the message list; call GET /v1/conversations/:id/messages separately for that.Auth DELETE/v1/conversations/:idDelete a conversation and all messages. Cannot be undone.Auth GET/v1/conversations/:id/messagesGet message history, oldest first. Returns a plain array, capped at 200 rows per call. There is no offset parameter; page backward with before.Auth POST/v1/conversations/:id/messagesSend a message. Without stream, blocks until generation completes and returns the stored messages; see the streaming note below for real-time output.Auth POST/v1/conversations/:id/messagesSame endpoint as above, with stream: true. Response is text/event-stream instead of a blocking JSON reply.Auth GET/v1/conversations/searchSubstring search across your own message content (SQL ILIKE, not ranked full-text search). Returns a plain array of matching messages, capped at 20 rows; the limit isn't configurable. Queries under 2 characters return an empty array.Auth

VoiceText-to-speech (TTS) for character voice output and speech-to-text (STT) for transcription. Both endpoints require a Bearer token.2

POST/v1/voice/ttsSynthesize speech from text. Returns an audio/mpeg binary stream, or a JSON error body on failure (400/410/502/503).Auth POST/v1/voice/sttTranscribe an audio file to text. Response has two fields: transcript and confidence. There is no detected-language field.Auth

MarketplaceBrowse and search public Dyvas. Every endpoint on this page is read-only; rating a Dyva and adding one to your collection happen through the Dyvas API, not here.7

GET/v1/marketplaceBrowse public Dyvas. Filter, search, and sort. Responds with a plain array, not a paginated envelope: there is no total count in this response.Public GET/v1/marketplace/featuredStaff-curated Dyvas, ranked by likes and conversation count. Plain array, always up to 12 entries.Public GET/v1/marketplace/categoriesList marketplace categories with a live Dyva count in each. Use the slug for the category query parameter above.Public GET/v1/marketplace/categories/:slugPublic Dyvas within one category, ranked by the same weighted score as the browse endpoint's default sort.Public GET/v1/marketplace/:idFull listing detail. Accepts a Dyva ID or its slug. Owner-only fields (system_prompt, tool_config, and a few others) are null unless you're authenticated as the owner.Public GET/v1/marketplace/:id/reviewsWritten ratings for a listing, newest first. Plain array; there is no rating-distribution or total field in this response.Public GET/v1/marketplace/:id/similarUp to 6 other public Dyvas in the same category, ranked by conversation count.Public

StudioCreator dashboard for your Dyvas: analytics, instruction versioning, A/B testing, and marketplace publishing. Every endpoint requires ownership of the Dyva.10

GET/v1/studio/:id/analyticsConversation and message counts for the period, plus a day-by-day conversation breakdown. There is no unique_users or retention_rate field.Auth GET/v1/studio/:id/versionsList saved snapshots, newest first. Plain array, capped at 20.Auth POST/v1/studio/:id/versionsSnapshot the Dyva's current system_prompt and personality as a new version. The body cannot set instruction text directly; it only labels the snapshot.Auth POST/v1/studio/:id/versions/:version_id/restoreCopy a saved snapshot's system_prompt and personality back onto the live Dyva. Not the PUT .../activate endpoint some older client code may expect: restoring is a POST, and the response is the full updated Dyva, not a version object.Auth POST/v1/studio/:id/test-chatSend a single test turn against an optional system prompt override, without creating a real conversation. The body param is content, not message, and there is no version_id targeting; pass system_prompt directly if you want to test something other than the Dyva's current live prompt.Auth GET/v1/studio/:id/variantsList A/B variants for a Dyva. Plain array; metrics aren't included in this response (see /variants/analytics for that).Auth POST/v1/studio/:id/variantsCreate a variant. name is required; traffic_pct defaults to 50 and must not push the active total over 100.Auth PATCH/v1/studio/:id/variants/:variant_idUpdate a variant. All fields optional. Not a PUT: a PUT to this path returns 404, since only PATCH is registered.Auth POST/v1/studio/:id/publishPublish to the marketplace. Only category_slug is accepted in the body. There is no tags or pricing field on this endpoint. Fails with 422 and a readiness object when the Dyva isn't publish-ready (missing avatar, no category, etc.), not with a generic 400.Auth POST/v1/studio/:id/unpublishTake a Dyva off the marketplace. Sets visibility back to private; the Dyva itself is untouched.Auth

IntegrationsAttach an external platform connection to your account.3

GET/v1/integrationsList every integration on your account.Auth POST/v1/integrationsCreate an integration. This is a generic record, not a platform-specific setup flow: there is no dedicated Discord, Telegram, or Slack connect endpoint (see the note below). platform_config is stored as-is; this API does not validate its shape against a platform.Auth DELETE/v1/integrations/:idRemove an integration by id.Auth

RoomsGroup chat spaces with multiple Dyvas. Members join and leave themselves; there is no separate endpoint for adding another user to a room.16

POST/v1/roomsCreate a room. At least one Dyva is required; you can't create an empty room and add characters later through this endpoint alone. You become the owner.Auth GET/v1/roomsPublic room directory, ranked by message count. Plain array, capped at 50 rooms, no pagination parameters. Use GET /v1/rooms/my for the rooms you actually belong to.Public GET/v1/rooms/discoverSearchable, filterable room directory with pagination and a message preview per room. This is the endpoint the in-app Rooms discovery page actually uses, not GET /v1/rooms.Public GET/v1/rooms/myRooms you own or are a member of, most recently active first. Capped at 50, no pagination parameters.Auth GET/v1/rooms/:idFull room detail: settings, members, and Dyvas. Accepts a room ID or slug.Public PATCH/v1/rooms/:idUpdate room settings. Owner only. Every field is optional; omitted fields keep their current value.Auth DELETE/v1/rooms/:idDelete a room and its messages. Owner only.Auth POST/v1/rooms/:id/joinJoin a room as a member. Private rooms only allow the owner to join; everyone else gets a 403. Fails with a 400 once the room hits max_members.Auth POST/v1/rooms/:id/leaveLeave a room. Always succeeds, even if you weren't a member.Auth GET/v1/rooms/:id/membersList a room's members. Plain array, no pagination.Public GET/v1/rooms/:id/messagesMessage history in chronological order (oldest first, despite the underlying query fetching newest-first and reversing). Supports limit and a before cursor; there is no offset parameter.Public POST/v1/rooms/:id/messagesSend a message. Room Dyvas may reply based on the room's ai_interaction and max_ai_responses settings. Set stream: true to receive Server-Sent Events instead of the JSON body below.Auth DELETE/v1/rooms/:id/messages/:msg_idDelete a message.Auth POST/v1/rooms/:id/dyvasAdd a Dyva to the room. Owner only.Auth GET/v1/rooms/:id/dyvasList a room's Dyvas.Public DELETE/v1/rooms/:id/dyvas/:dyva_idRemove a Dyva from the room. Owner only.Auth

SocialFollow creators, like Dyvas, and read public profiles and feeds. Every endpoint here requires a Bearer token except public profile lookups and reads.14