Skip to main content

Users and plans

Your users are named by your own ids. These calls take the user in the path and never the Digitorn-User header.

Users​

Call
PUT /v1/users/{id}Creates the user if needed (201, "created": true) and updates email, name, disabled.
GET /v1/users/{id}One user: e-mail, name, plan, when created and last seen.
GET /v1/usersAll your users, oldest first (limit up to 100, cursor = next_cursor).
POST /v1/users/{id}/sign-outEnds at once every access the user holds, on every device.
POST /v1/users/{id}/launchA link that opens your app already signed in as the user: see Put your agent in your site.
bash
curl -X PUT https://api.digitorn.ai/v1/users/user_482 \
  -H "Authorization: Bearer sk_..." -H "Content-Type: application/json" \
  -d '{"email":"aicha@example.com","name":"Aïcha Koné"}'

A disabled user ("disabled": true) can no longer talk to your agents.

Labels you vouch for (claims)​

Facts only your server may state about a user: their tier, their role, their company. Neither the user nor a web page can change them; the agent is told they are verified and trusts them over anything the conversation or the page claims, and your app's functions read them in ctx.user.claims.

bash
curl -X PUT https://api.digitorn.ai/v1/users/user_482 \
  -H "Authorization: Bearer sk_..." -H "Content-Type: application/json" \
  -d '{"claims":{"tier":"gold","company":"Acme"}}'

A JSON object of at most 1000 bytes; it replaces the previous one ({} clears it). The launch link takes claims too.

Your app's functions also get ctx.user.external_id, your own id for the user: use it to look them up in your systems (with a key kept in the app's secrets), which is the safest way to get data that matters, like a balance or orders.

Plans​

You create your plans in the Studio (Project → Plans): for example Free, 5 messages a day, and Premium, unlimited with the pdf feature. The first one is the plan every new user gets. Digitorn counts the messages and stops a user at their limit before the agent runs; the chat tells them when it resets.

Move a user to a plan, for a time if you want, when they pay on your side:

bash
curl -X PUT https://api.digitorn.ai/v1/users/user_482/plan \
  -H "Authorization: Bearer sk_..." -H "Content-Type: application/json" \
  -d '{"plan":"premium","until":"2026-12-31T00:00:00Z"}'

{"plan": null} puts them back on the default plan. When until passes, they go back to it by themselves.

Usage​

bash
curl https://api.digitorn.ai/v1/users/user_482/usage -H "Authorization: Bearer sk_..."
json
{
  "user": "user_482",
  "plan": "free",
  "plan_name": "Free",
  "features": {},
  "usage": [
    { "counter": "messages", "period": "day", "used": 3, "limit": 5, "resets_at": "2026-10-12T00:00:00Z" },
    { "counter": "messages", "period": "month", "used": 41, "limit": null, "resets_at": "2026-11-01T00:00:00Z" }
  ]
}

limit: null means unlimited. Days and months follow the project's time zone (Project → Plans).

Connected accounts​

In Project → Connectors you choose whose accounts the agent uses: yours, for everyone, or each user's own. With each user's own, a user connects their Gmail, calendar… once, inside your app, and the agent only ever reaches theirs. Because it is tied to your id for them, it follows them on every device.