Auth API

Accounts, sessions, API keys, and user profiles.

2 min read12 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/auth/signup`

Create an account and receive a session immediately. Sends a verification email in the background; email_verified starts false.

Public

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

Request body (6)

emailstringRequired: User email address.
passwordstringRequired: Password (min 8 characters, must include a number and uppercase letter).
display_namestringRequired: Name shown on the account (min 2 characters after cleanup).
usernamestringOptional: Unique handle (3-30 alphanumeric characters and underscores). Skippable at signup.
birthdaystringOptional: ISO date. When provided, accounts under 13 years old are rejected.
referral_codestringOptional: An existing user's referral code, credited on signup.

Response

Illustrative example, not a captured response

{
  "access_token": "dyva_tok_EXAMPLE",
  "refresh_token": "dyva_rtok_EXAMPLE",
  "user": {
    "id": "usr_EXAMPLE0001",
    "email": "[email protected]",
    "display_name": "Ada Lovelace",
    "username": "ada_lovelace",
    "avatar_url": null,
    "tier": "free",
    "role": "user"
  }
}

Examples (2)

curl -X POST https://api.dyva.ai/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "Str0ngP@ss!",
    "display_name": "Ada Lovelace",
    "username": "ada_lovelace"
  }'

POST `/v1/auth/login`

Authenticate and receive an access / refresh token pair. Returns requires_2fa instead when the account has TOTP enabled.

Public

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

Request body (2)

emailstringRequired: User email address.
passwordstringRequired: Password (min 8 characters, must include a number and uppercase letter).

Response

Illustrative example, not a captured response

{
  "access_token": "dyva_tok_EXAMPLE",
  "refresh_token": "dyva_rtok_EXAMPLE",
  "user": {
    "id": "usr_EXAMPLE0001",
    "email": "[email protected]",
    "display_name": "Ada Lovelace",
    "username": "ada_lovelace",
    "avatar_url": "https://cdn.dyva.ai/avatars/usr_EXAMPLE0001.webp",
    "tier": "free",
    "role": "user",
    "email_verified": true
  }
}

Examples (2)

curl -X POST https://api.dyva.ai/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "Str0ngP@ss!"
  }'

POST `/v1/auth/verify-email`

Verify email using the token from the verification email.

Public

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

Request body (1)

tokenstringRequired: One-time token sent via email. JWT-signed, 1-24h expiry depending on purpose.

Response

Illustrative example, not a captured response

{
  "message": "Email verified"
}

Examples (2)

curl -X POST https://api.dyva.ai/v1/auth/verify-email \
  -H "Content-Type: application/json" \
  -d '{ "token": "dyva_vtok_EXAMPLE" }'

POST `/v1/auth/forgot-password`

Send 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

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

Request body (1)

emailstringRequired: User email address.

Response

Illustrative example, not a captured response

{
  "message": "If an account exists, a reset link has been sent."
}

Examples (2)

curl -X POST https://api.dyva.ai/v1/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]" }'

POST `/v1/auth/reset-password`

Reset 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

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

Request body (2)

tokenstringRequired: One-time token sent via email. JWT-signed, 1-24h expiry depending on purpose.
new_passwordstringRequired: The new password (same requirements as signup).

Response

Illustrative example, not a captured response

{
  "message": "Password reset successfully"
}

Examples (2)

curl -X POST https://api.dyva.ai/v1/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "token": "dyva_rstok_EXAMPLE",
    "new_password": "N3wSecureP@ss!"
  }'

GET `/v1/auth/me`

Get the authenticated user's full profile.

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": "usr_EXAMPLE0001",
  "email": "[email protected]",
  "display_name": "Ada Lovelace",
  "username": "ada_lovelace",
  "avatar_url": "https://cdn.dyva.ai/avatars/usr_EXAMPLE0001.webp",
  "tier": "free",
  "role": "user",
  "creator_bio": null,
  "creator_slug": null,
  "email_verified": true,
  "is_verified": false,
  "follower_count": 0,
  "following_count": 0,
  "interests": [
    "scifi",
    "gaming"
  ],
  "looking_for": [
    "companion"
  ],
  "memory_opt_out": false,
  "shared_room_context_enabled": false,
  "has_password": true,
  "created_at": "2026-03-09T14:22:11.000Z"
}

Examples (2)

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

PATCH `/v1/auth/me`

Update 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.

Bearer token

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

Request body (5)

display_namestringOptional: Public display name (min 2 characters after cleanup).
usernamestringOptional: New handle (3-30 characters).
creator_biostringOptional: Creator-facing biography text.
avatar_urlstringOptional: URL to a profile image. Must already be uploaded (no blob:/data: URLs).
interestsstring[]Optional: Category slugs, filtered against a fixed allow-list server-side.

Response

Illustrative example, not a captured response

{
  "id": "usr_EXAMPLE0001",
  "email": "[email protected]",
  "display_name": "Ada L.",
  "username": "ada_lovelace",
  "avatar_url": "https://cdn.dyva.ai/avatars/usr_EXAMPLE0001.webp",
  "tier": "free",
  "role": "user",
  "creator_bio": "Building the future of AI conversations.",
  "email_verified": true,
  "interests": [
    "scifi",
    "gaming"
  ],
  "created_at": "2026-03-09T14:22:11.000Z"
}

Examples (2)

curl -X PATCH https://api.dyva.ai/v1/auth/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Ada L.",
    "creator_bio": "Building the future of AI conversations."
  }'

POST `/v1/api-keys`

Create an API key. The full key is returned once, at creation, and never again; only a short prefix is stored for display.

Bearer token

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

Request body (2)

namestringOptional: A human-readable label for this key. Defaults to "API Key" when omitted.
scopesstring[]Optional: Free-form scope labels. No fixed enum is enforced server-side today; defaults to ["read", "chat"] when omitted.

Response

Illustrative example, not a captured response

{
  "id": "key_EXAMPLE0001",
  "name": "production-backend",
  "prefix": "rk_EXAMPLE00",
  "scopes": [
    "read",
    "chat"
  ],
  "created_at": "2026-03-09T19:00:00.000Z",
  "key": "rk_EXAMPLE_full_key_shown_once_do_not_reuse_this_value"
}

Examples (2)

curl -X POST https://api.dyva.ai/v1/api-keys \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-backend",
    "scopes": ["read", "chat"]
  }'

GET `/v1/api-keys`

List your API keys. The response is a plain array; keys never include the full secret after creation, only the prefix.

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": "key_EXAMPLE0001",
    "name": "production-backend",
    "prefix": "rk_EXAMPLE00",
    "scopes": [
      "read",
      "chat"
    ],
    "last_used_at": "2026-03-09T21:34:12.000Z",
    "created_at": "2026-03-09T19:00:00.000Z"
  },
  {
    "id": "key_EXAMPLE0002",
    "name": "staging-debug",
    "prefix": "rk_EXAMPLE01",
    "scopes": [
      "read"
    ],
    "last_used_at": null,
    "created_at": "2026-03-01T10:15:00.000Z"
  }
]

Examples (2)

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

DELETE `/v1/api-keys/:id`

Revoke an API key. Requests using it fail immediately afterward. Responds with no body.

Bearer token

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

Path and query parameters (1)

idstringRequired: The API key ID (e.g. key_EXAMPLE0001).

Response

Illustrative example, not a captured response

HTTP/1.1 204 No Content

Examples (2)

curl -X DELETE https://api.dyva.ai/v1/api-keys/key_EXAMPLE0001 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

POST `/v1/auth/export-data`

Download 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.

Bearer token

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

Response

Illustrative example, not a captured response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Disposition: attachment; filename="dyva-data-export-2026-03-09.json"
Cache-Control: no-store

{ "account": { ... }, "conversations": [ ... ], ... }

Examples (2)

curl -X POST https://api.dyva.ai/v1/auth/export-data \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o dyva-export.json

DELETE `/v1/auth/me`

Permanently 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.

Bearer token

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

Response

Illustrative example, not a captured response

{
  "message": "Account deleted.",
  "already_deleted": false,
  "receipt_id": "dyva_receipt_EXAMPLE",
  "deleted_rows": 214,
  "anonymized_rows": 6,
  "retained_rows": 3,
  "kept_for_others": {
    "characters": 2,
    "rooms": 1,
    "note": "Messages you posted in shared rooms stay, with your name removed, so other members keep their conversation. Characters other people chat with stay too."
  }
}

Examples (2)

# Preview first, nothing is changed by this call
curl -X DELETE "https://api.dyva.ai/v1/auth/me?dry_run=1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Delete for real
curl -X DELETE https://api.dyva.ai/v1/auth/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Browse the complete endpoint directory

Auth API

Accounts, sessions, API keys, and user profiles.

2 min read12 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/auth/signup`

Create an account and receive a session immediately. Sends a verification email in the background; email_verified starts false.

Public

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

Request body (6)

emailstringRequired: User email address.
passwordstringRequired: Password (min 8 characters, must include a number and uppercase letter).
display_namestringRequired: Name shown on the account (min 2 characters after cleanup).
usernamestringOptional: Unique handle (3-30 alphanumeric characters and underscores). Skippable at signup.
birthdaystringOptional: ISO date. When provided, accounts under 13 years old are rejected.
referral_codestringOptional: An existing user's referral code, credited on signup.

Response

Illustrative example, not a captured response

{
  "access_token": "dyva_tok_EXAMPLE",
  "refresh_token": "dyva_rtok_EXAMPLE",
  "user": {
    "id": "usr_EXAMPLE0001",
    "email": "[email protected]",
    "display_name": "Ada Lovelace",
    "username": "ada_lovelace",
    "avatar_url": null,
    "tier": "free",
    "role": "user"
  }
}

Examples (2)

curl -X POST https://api.dyva.ai/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "Str0ngP@ss!",
    "display_name": "Ada Lovelace",
    "username": "ada_lovelace"
  }'

POST `/v1/auth/login`

Authenticate and receive an access / refresh token pair. Returns requires_2fa instead when the account has TOTP enabled.

Public

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

Request body (2)

emailstringRequired: User email address.
passwordstringRequired: Password (min 8 characters, must include a number and uppercase letter).

Response

Illustrative example, not a captured response

{
  "access_token": "dyva_tok_EXAMPLE",
  "refresh_token": "dyva_rtok_EXAMPLE",
  "user": {
    "id": "usr_EXAMPLE0001",
    "email": "[email protected]",
    "display_name": "Ada Lovelace",
    "username": "ada_lovelace",
    "avatar_url": "https://cdn.dyva.ai/avatars/usr_EXAMPLE0001.webp",
    "tier": "free",
    "role": "user",
    "email_verified": true
  }
}

Examples (2)

curl -X POST https://api.dyva.ai/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "Str0ngP@ss!"
  }'

POST `/v1/auth/verify-email`

Verify email using the token from the verification email.

Public

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

Request body (1)

tokenstringRequired: One-time token sent via email. JWT-signed, 1-24h expiry depending on purpose.

Response

Illustrative example, not a captured response

{
  "message": "Email verified"
}

Examples (2)

curl -X POST https://api.dyva.ai/v1/auth/verify-email \
  -H "Content-Type: application/json" \
  -d '{ "token": "dyva_vtok_EXAMPLE" }'

POST `/v1/auth/forgot-password`

Send 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

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

Request body (1)

emailstringRequired: User email address.

Response

Illustrative example, not a captured response

{
  "message": "If an account exists, a reset link has been sent."
}

Examples (2)

curl -X POST https://api.dyva.ai/v1/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]" }'

POST `/v1/auth/reset-password`

Reset 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

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

Request body (2)

tokenstringRequired: One-time token sent via email. JWT-signed, 1-24h expiry depending on purpose.
new_passwordstringRequired: The new password (same requirements as signup).

Response

Illustrative example, not a captured response

{
  "message": "Password reset successfully"
}

Examples (2)

curl -X POST https://api.dyva.ai/v1/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "token": "dyva_rstok_EXAMPLE",
    "new_password": "N3wSecureP@ss!"
  }'

GET `/v1/auth/me`

Get the authenticated user's full profile.

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": "usr_EXAMPLE0001",
  "email": "[email protected]",
  "display_name": "Ada Lovelace",
  "username": "ada_lovelace",
  "avatar_url": "https://cdn.dyva.ai/avatars/usr_EXAMPLE0001.webp",
  "tier": "free",
  "role": "user",
  "creator_bio": null,
  "creator_slug": null,
  "email_verified": true,
  "is_verified": false,
  "follower_count": 0,
  "following_count": 0,
  "interests": [
    "scifi",
    "gaming"
  ],
  "looking_for": [
    "companion"
  ],
  "memory_opt_out": false,
  "shared_room_context_enabled": false,
  "has_password": true,
  "created_at": "2026-03-09T14:22:11.000Z"
}

Examples (2)

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

PATCH `/v1/auth/me`

Update 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.

Bearer token

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

Request body (5)

display_namestringOptional: Public display name (min 2 characters after cleanup).
usernamestringOptional: New handle (3-30 characters).
creator_biostringOptional: Creator-facing biography text.
avatar_urlstringOptional: URL to a profile image. Must already be uploaded (no blob:/data: URLs).
interestsstring[]Optional: Category slugs, filtered against a fixed allow-list server-side.

Response

Illustrative example, not a captured response

{
  "id": "usr_EXAMPLE0001",
  "email": "[email protected]",
  "display_name": "Ada L.",
  "username": "ada_lovelace",
  "avatar_url": "https://cdn.dyva.ai/avatars/usr_EXAMPLE0001.webp",
  "tier": "free",
  "role": "user",
  "creator_bio": "Building the future of AI conversations.",
  "email_verified": true,
  "interests": [
    "scifi",
    "gaming"
  ],
  "created_at": "2026-03-09T14:22:11.000Z"
}

Examples (2)

curl -X PATCH https://api.dyva.ai/v1/auth/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Ada L.",
    "creator_bio": "Building the future of AI conversations."
  }'

POST `/v1/api-keys`

Create an API key. The full key is returned once, at creation, and never again; only a short prefix is stored for display.

Bearer token

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

Request body (2)

namestringOptional: A human-readable label for this key. Defaults to "API Key" when omitted.
scopesstring[]Optional: Free-form scope labels. No fixed enum is enforced server-side today; defaults to ["read", "chat"] when omitted.

Response

Illustrative example, not a captured response

{
  "id": "key_EXAMPLE0001",
  "name": "production-backend",
  "prefix": "rk_EXAMPLE00",
  "scopes": [
    "read",
    "chat"
  ],
  "created_at": "2026-03-09T19:00:00.000Z",
  "key": "rk_EXAMPLE_full_key_shown_once_do_not_reuse_this_value"
}

Examples (2)

curl -X POST https://api.dyva.ai/v1/api-keys \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-backend",
    "scopes": ["read", "chat"]
  }'

GET `/v1/api-keys`

List your API keys. The response is a plain array; keys never include the full secret after creation, only the prefix.

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": "key_EXAMPLE0001",
    "name": "production-backend",
    "prefix": "rk_EXAMPLE00",
    "scopes": [
      "read",
      "chat"
    ],
    "last_used_at": "2026-03-09T21:34:12.000Z",
    "created_at": "2026-03-09T19:00:00.000Z"
  },
  {
    "id": "key_EXAMPLE0002",
    "name": "staging-debug",
    "prefix": "rk_EXAMPLE01",
    "scopes": [
      "read"
    ],
    "last_used_at": null,
    "created_at": "2026-03-01T10:15:00.000Z"
  }
]

Examples (2)

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

DELETE `/v1/api-keys/:id`

Revoke an API key. Requests using it fail immediately afterward. Responds with no body.

Bearer token

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

Path and query parameters (1)

idstringRequired: The API key ID (e.g. key_EXAMPLE0001).

Response

Illustrative example, not a captured response

HTTP/1.1 204 No Content

Examples (2)

curl -X DELETE https://api.dyva.ai/v1/api-keys/key_EXAMPLE0001 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

POST `/v1/auth/export-data`

Download 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.

Bearer token

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

Response

Illustrative example, not a captured response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Disposition: attachment; filename="dyva-data-export-2026-03-09.json"
Cache-Control: no-store

{ "account": { ... }, "conversations": [ ... ], ... }

Examples (2)

curl -X POST https://api.dyva.ai/v1/auth/export-data \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o dyva-export.json

DELETE `/v1/auth/me`

Permanently 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.

Bearer token

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

Response

Illustrative example, not a captured response

{
  "message": "Account deleted.",
  "already_deleted": false,
  "receipt_id": "dyva_receipt_EXAMPLE",
  "deleted_rows": 214,
  "anonymized_rows": 6,
  "retained_rows": 3,
  "kept_for_others": {
    "characters": 2,
    "rooms": 1,
    "note": "Messages you posted in shared rooms stay, with your name removed, so other members keep their conversation. Characters other people chat with stay too."
  }
}

Examples (2)

# Preview first, nothing is changed by this call
curl -X DELETE "https://api.dyva.ai/v1/auth/me?dry_run=1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Delete for real
curl -X DELETE https://api.dyva.ai/v1/auth/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Browse the complete endpoint directory

POST /v1/auth/signup

POST /v1/auth/login

POST /v1/auth/verify-email

POST /v1/auth/forgot-password

POST /v1/auth/reset-password

GET /v1/auth/me

PATCH /v1/auth/me

POST /v1/api-keys

GET /v1/api-keys

DELETE /v1/api-keys/:id

POST /v1/auth/export-data

DELETE /v1/auth/me

POST /v1/auth/signup

POST /v1/auth/login

POST /v1/auth/verify-email

POST /v1/auth/forgot-password

POST /v1/auth/reset-password

GET /v1/auth/me

PATCH /v1/auth/me

POST /v1/api-keys

GET /v1/api-keys

DELETE /v1/api-keys/:id

POST /v1/auth/export-data

DELETE /v1/auth/me

POST `/v1/auth/signup`

POST `/v1/auth/login`

POST `/v1/auth/verify-email`

POST `/v1/auth/forgot-password`

POST `/v1/auth/reset-password`

GET `/v1/auth/me`

PATCH `/v1/auth/me`

POST `/v1/api-keys`

GET `/v1/api-keys`

DELETE `/v1/api-keys/:id`

POST `/v1/auth/export-data`

DELETE `/v1/auth/me`

POST `/v1/auth/signup`

POST `/v1/auth/login`

POST `/v1/auth/verify-email`

POST `/v1/auth/forgot-password`

POST `/v1/auth/reset-password`

GET `/v1/auth/me`

PATCH `/v1/auth/me`

POST `/v1/api-keys`

GET `/v1/api-keys`

DELETE `/v1/api-keys/:id`

POST `/v1/auth/export-data`

DELETE `/v1/auth/me`