Skip to main content

Developer API

The Digitorn API lets your own software use the agents you build in the Studio: put them in your site with your users already signed in, talk to them from your server, manage your users and their plans.

text
https://api.digitorn.ai/v1

Every call runs through the same rules as the Digitorn app: your plans and limits, your billing, and the isolation between your users all apply, with nothing to rebuild on your side.

Keys​

KeyWhere it comes fromWhat it can do
sk_… secret keyStudio → your agent → Project → AccessEverything about your project: its agents, its users, their conversations and plans. Server only.
pk_… publishable keysame placeUsed by your published app in the browser. Not accepted by the API.

Access to your own Digitorn space (your agents and conversations, for scripts and AI tools you use yourself) is coming with account keys and the Digitorn MCP server.

Send the key in the Authorization header:

bash
curl https://api.digitorn.ai/v1/me \
  -H "Authorization: Bearer sk_..."
json
{ "kind": "project", "project": { "id": "6828…", "name": "My shop", "mode": "test" } }
Keep sk_ on your server

A request carrying a secret key and an Origin header (a browser) is refused with server_only. Never put sk_ in a web page, a mobile app or a repository.

Acting for one of your users​

Add the Digitorn-User header with your own id for that user (from your database: user_482, an e-mail, a UUID…). The call then runs as that user, with exactly their rights: their conversations, their plan, their connected accounts.

bash
curl https://api.digitorn.ai/v1/conversations \
  -H "Authorization: Bearer sk_..." \
  -H "Digitorn-User: user_482"
  • The user is created the first time a write names them; a read never creates anyone (it answers user_not_found).
  • Ids are 1 to 128 characters among letters, digits and . _ : @ + -.
  • The same id is the same person everywhere: on every device, in your site and through the API.

Errors​

Every error has the same shape and says whether to retry:

json
{
  "error": {
    "code": "quota_reached",
    "message": "you reached your limit; it resets later",
    "retryable": true,
    "retry_after_seconds": 50361,
    "trace_id": "tr_d14536a9511aec79e09e"
  }
}
HTTPMeaning
401Missing, invalid or revoked key
403Not allowed for this key (server_only, user_disabled, project_key_required…)
404Unknown agent, conversation, user or plan (also what you get for something that is not yours)
409Conflict (user_conflict, agent_ambiguous, idempotency_key_in_use)
422Invalid request; fields lists what is wrong. Unknown fields are refused.
429Too many requests, or the user's plan / the project's ceiling is reached (quota). Retry-After is set.
503Unavailable for a moment; retry.

Tracing, retries and limits​

  • X-Trace-Id: send your own (up to 64 characters A-Z a-z 0-9 . _ : -) or get one back on every answer. Quote it when you contact us.
  • Idempotency-Key on any POST, PUT or DELETE: retrying with the same key returns the first answer (Idempotent-Replayed: true) instead of acting twice. The same key with a different request is refused (idempotency_key_reused). Keys are kept 24 hours.
  • Rate limit per key, announced in RateLimit-Limit and RateLimit-Remaining; over it you get 429 with Retry-After.
  • Bodies are JSON, at most 1 MB. Dates are ISO 8601 in UTC.

Next​