API reference

Conventions shared by every endpoint, followed by an index of routes grouped by system. Each system's guide covers request and response bodies in detail.

Base URL and versioning

Text

https://api.dianthan.com/v1

The version is part of the path. Within v1, changes are additive: new fields, new endpoints and new optional parameters. Write clients that ignore fields they don't recognise. Anything that would break existing clients ships as v2, and v1 keeps working for at least twelve months after that.

Authentication

Header	When
`Authorization: Bearer <jwt>`	Acting as a signed-in person, or as yourself
`X-API-Key: dn_live_…`	Acting as your server, for one app
`X-App-Id: app_…`	Selects the app. Required with a server key; when sent with a token, it takes precedence over the app in the token
`X-Client-IP: <ip>`	Your visitor's IP when your server calls on their behalf. Only honoured with server keys

Requests and responses

Bodies are JSON with Content-Type: application/json. Field names are snake_case. Timestamps are ISO 8601 in UTC. Money is an integer number of the currency's smallest unit, with a separate currency field.

IDs carry a prefix for their type:

Prefix	Type	Prefix	Type
`usr_`	User	`sub_`	Subscription
`app_`	App	`fil_`	File
`org_`	Organization	`job_`	Job
`key_`	API key	`whk_`	Webhook

Errors

Every error has the same shape:

JSON

{
  "error": "quota_exceeded",
  "message": "This app has used its 1,000,000 usage events for November."
}

error is a stable machine-readable code you can branch on. message is written for a developer reading logs and may be reworded at any time.

Status	Meaning
`400`	The request is invalid. `message` names the field and the rule it broke.
`401`	No valid credential
`403`	The credential is valid but can't do this, for example a key for another app or a disabled system
`404`	Not found, or not visible to this credential
`409`	Conflicts with existing state, such as a duplicate key
`410`	The endpoint has been removed. `message` says what replaces it.
`429`	Rate limited. Wait for the number of seconds in `Retry-After`.
`501`	The feature needs configuration first, such as connecting a merchant account before checkout

Rate limits

Each app has a per-minute quota, and sign-in endpoints have stricter per-IP limits. Responses include RateLimit-Limit and RateLimit-Remaining, and a 429 includes Retry-After. If you send X-Client-IP from your server, per-IP limits apply to your visitors individually, not to your server as a whole.

Route index

Identity

Text

POST   /v1/auth/magic-link            GET    /v1/auth/oauth/:provider
POST   /v1/auth/grants/exchange       GET    /v1/auth/sso/:connection_id/start
POST   /v1/auth/refresh               POST   /v1/auth/logout
GET    /v1/auth/sessions              DELETE /v1/auth/sessions[/:id]
POST   /v1/auth/register              POST   /v1/auth/step-up
GET    /v1/me                         PATCH  /v1/me
GET    /v1/me/mfa                     POST   /v1/me/mfa/totp/setup
POST   /v1/me/mfa/totp/verify         POST   /v1/me/mfa/recovery
GET    /v1/users                      GET    /v1/users/:id
POST   /v1/organizations              GET    /v1/organizations/:id/members
POST   /v1/organizations/:id/invitations
POST   /v1/invitations/:id/accept     POST   /v1/organizations/:id/roles
POST   /v1/organizations/:id/sso      GET    /v1/permissions

Billing

Text

GET    /v1/billing/plans              GET    /v1/billing/plans/:id
POST   /v1/billing/checkout           POST   /v1/billing/portal
GET    /v1/billing/subscriptions      POST   /v1/billing/subscriptions/:id/cancel
POST   /v1/billing/subscriptions/:id/resume
GET    /v1/billing/invoices           GET    /v1/me/entitlements[/:key]
GET    /v1/organizations/:id/entitlements

Metering

Text

POST   /v1/usage/events               GET    /v1/usage[/:metric]
GET    /v1/organizations/:id/usage    GET    /v1/apps/:id/usage

Data

Text

POST   /v1/records                    GET    /v1/records[/:id]
PATCH  /v1/records/:id                DELETE /v1/records/:id
POST   /v1/query                      POST   /v1/search
POST   /v1/resources                  GET    /v1/resources
POST   /v1/files/upload-url           PUT    /v1/files/:id/content
POST   /v1/files/:id/complete         GET    /v1/files/:id/download-url

Messaging

Text

POST   /v1/messages/email             GET    /v1/messages
GET    /v1/push/vapid-public-key      POST   /v1/push/subscriptions
POST   /v1/push/send                  GET    /v1/notifications
POST   /v1/notifications/:id/read     POST   /v1/notifications/read-all
POST   /v1/channels/publish           GET    /v1/channels/:channel/subscribe

Automation

Text

POST   /v1/jobs                       GET    /v1/jobs[/:id]
POST   /v1/jobs/:id/cancel            POST   /v1/jobs/:id/retry
POST   /v1/schedules                  PATCH  /v1/schedules/:id
POST   /v1/webhooks                   GET    /v1/webhooks/:id/deliveries
POST   /v1/webhooks/:id/test          POST   /v1/webhooks/:id/deliveries/:delivery_id/retry
GET    /v1/events                     GET    /v1/audit-log

Observe

Text

POST   /v1/logs                       GET    /v1/logs[/:id]
GET    /v1/logs/counts                POST   /v1/telemetry/errors
GET    /v1/telemetry/traces           POST   /v1/alerts
GET    /v1/audit-log                  POST   /v1/audit-log/revert

Flags

Text

POST   /v1/flags                      GET    /v1/flags[/:key]
PATCH  /v1/flags/:key                 DELETE /v1/flags/:key
POST   /v1/flags/evaluate

Models

Text

POST   /v1/ai/chat/completions        GET    /v1/ai/models
GET    /v1/ai/usage                   GET    /v1/ai/margin
POST   /v1/ai/credits                 GET    /v1/ai/credits

System

Text

GET    /health                        GET    /v1/system/status
GET    /v1/system/capabilities