API access¶
Every published agent can be called programmatically through an OpenAI-compatible API, so developers can integrate it into their own apps using tools they already know.
API tokens¶
As the agent owner, you create API tokens for your agent:
- Each token has a name so you can tell them apart.
- The full secret is shown only once, at creation (it begins with
dk_). Copy and store it then — afterward only a short prefix is ever displayed. - You can list your tokens (name, prefix, last-used) and revoke any of them. A lost secret can't be recovered — revoke it and issue a new one.
A token is scoped to one agent and belongs to the person who created it: every call made with it acts as that person — with their own memory, files and profile on this agent — and the token list shows whose token each one is. The call is paid the way that person's use of the agent is paid: the agent's default, or a personal or organization wallet they chose (see Choose who pays). The owner's monthly allowance for that person applies only to use the owner pays for. Use they pay for themselves is not counted against it. A call is refused when the sponsored spend already recorded has reached that allowance, or when a chosen wallet was revoked or deleted. They have to choose a wallet again on the agent's page; the call is not moved onto the owner's balance. Work that already started is still paid for. The models the call may use follow the plan of whoever pays. As the owner, your panel always lists every key on the agent — including ones your users created for themselves — with who created it, and lets you revoke any of them.
The OpenAI-compatible endpoint¶
The API mirrors OpenAI's Chat Completions interface, per agent:
- Streaming and non-streaming responses are both supported (streaming uses the same server-sent-events format OpenAI clients expect).
- Point existing OpenAI SDKs at it by setting the base URL and API key — put the agent's handle in the "model" field, and the owner's configured model and plan decide what actually runs.
- If the agent has a structured-output (JSON) schema, the API validates the response against it and retries once automatically to get conforming output.
- A brief hiccup on the provider's side — a timeout, a dropped connection, an overloaded provider — is retried automatically, at most twice after a short wait, before the request fails with an upstream-provider error. This applies to streaming requests too; the response simply arrives a little later. A request the provider turns down (an invalid request, an authentication or quota problem, a content-filter block) is not retried.
- Errors come back in OpenAI's error format and distinguish real cases: out of credits/quota, the owner's monthly allowance for that person used up, a chosen wallet that is no longer available, a single request over its budget, invalid request, and upstream provider issues.
Scope
Only chat completions is emulated. There is no models-listing endpoint and no embeddings/images/other OpenAI routes. It's a drop-in replacement for chat, not for the whole OpenAI API.
Keys for your agent's users¶
As the owner, you can turn on Let users create their own API keys in the agent's sharing settings (see Share workflows, knowledge and API access). Once it's on, anyone with access to the agent opens API keys on the agent's page and can:
- create up to 10 keys,
- see each secret once, at creation,
- delete their own keys.
A user's key works exactly like the owner's tokens above — it acts as that person, with their own memory, files, profile, and personal connections, and it is paid the same way their other use of the agent is paid — and in the agent's database it gets user-level access, limited to whatever the agent's tables allow end users. If you turn the setting off, or the person loses access to the agent, their keys stop working immediately. This is separate from the console token panel above, which is owner-only and keeps listing every key regardless of who created it.
Keys can't be created or managed from the mobile apps — use the agent's page on the web.
Setup required before a key can call the agent¶
If a user's key belongs to a person who hasn't finished the agent's setup — connecting their personal connections or filling required parameters — a chat completions or realtime call with that key is refused before the run:
{"error": {"code": "agent_setup_required", "message": "Finish setting up this agent before using it."}}
The call fails with HTTP 409. The person finishes setup on the agent's page (see Setting up an agent shared with you) and retries.
Devices¶
Through the Donkit Desktop app you can register your own computers as devices and dispatch tasks to them from the cloud. The cloud Devices view lists your machines and sends a task (a prompt, optionally tied to a specific agent); the device runs it locally and reports progress back.
You decide up front what the agent may touch on that machine: the apps and folders you grant it are the consent, and inside them it works without stopping to ask. Anything outside a grant is refused and shown in the task activity as Denied by policy, so you can see what to allow next time, and a running session can be stopped at any moment with the on-screen kill switch or Ctrl+Alt+K. See Computer use & browser for the whole picture. Dispatching a task this way is authenticated by your own session and is separate from the public agent API.