This article is auto-synced from its in-app version in Tai.

The Agent REST API lets a server-side integration call one of your agents over HTTP — send typed input parameters, get back a schema-validated JSON answer — with no chat session to manage and no conversation state carried between calls. A call that finishes quickly answers inline; one that takes longer hands you back a run to poll, so a slow agent doesn't cost you the answer just because your connection didn't wait for it (see Long-running runs below).

Use the REST API when your own backend, a scheduled job, or another system needs a single, structured answer from an agent — for example, running a risk check against a booking and getting a typed verdict back, rather than driving a conversational chat session.

Each agent that exposes this channel publishes one or more versioned contracts — a contract pins the exact input parameters and output shape for that version, so your integration can keep working even as the agent evolves.

A Company Admin sets the agent up in the Workbench: switches on its REST API channel, chooses the Accepted authentication, publishes a contract version, and runs a test call on the agent's Test API tab. Setting up an agent's REST API walks through each step. The agent must be a Company agent: a call with an API key to a Personal agent gets 404 AGENT_NOT_FOUND, even though the Test API tab works for anyone who can edit it.

Your integration then needs the agent's ID, the contract version to pin, and an API key — or a short-lived token minted from an OAuth client's secret — described under Authenticate below.

A small agent that takes a destination and answers with the best times of year to travel there. It shows the whole loop: the contract you declare, the call an integration sends, and the answer it gets back.

1. Declare the input. In a draft contract version, add one input parameter (Setting up an agent's REST API shows where):

2. Declare the output. Replace the default {"type": "object"} under Output JSON Schema with:

3. Publish the version and call it:

The envelope in the answer (see The response envelope below) then looks like:

Do you need to explain the inputs and outputs in the system prompt? No. On every call, TAI hands the agent your inputs as labelled lines — here Destination (destination): PT — together with the version's output JSON Schema and an instruction to answer with JSON only. It then checks the answer against the schema and, if it doesn't match, asks the agent once to correct it. The contract alone is enough for a valid answer. Use the system prompt for what the contract can't say:

A system prompt for this agent can be as short as:

Every call carries an API key in an X-API-Key header — not Authorization: Bearer — or, instead, a short-lived token (see below):

The key must be scoped to the agent you're calling, allow the REST API channel, and carry the Invoke agents permission. A key that's valid but outside its scope gets the same response as a request naming an agent that doesn't exist — see Errors below.

By default, a new agent accepts an API key and an OAuth client (a short-lived token minted with an OAuth client's secret, described next). Some agents set up earlier accept an API key only; if a token call gets AUTH_METHOD_NOT_ACCEPTED, tick OAuth client on the agent. Anyone who can edit the agent can change this, under Configuration → Channels → Accepted authentication: untick API key to force integrations onto short-lived tokens, or tick either of these to also accept:

For a server-to-server integration, keep the default — an API key or an OAuth client is what this guide describes. Widening the setting matters only if you also want a Workbench user or a TripBuilder session to call the same endpoint directly. A call using a method the agent doesn't accept gets 403 AUTH_METHOD_NOT_ACCEPTED — see Errors below.

On a Personal agent, Accepted authentication is fixed to Workbench user: only the agent's owner or a Company Admin, signed in to the Workbench, can call it. API keys, OAuth clients, and TripBuilder sessions never reach a personal agent. When a Company Admin releases it with Release to company, the confirmation offers to also accept API keys and OAuth clients — ticked by default. Return to owner sets it back to Workbench user only.

Instead of sending a long-lived key on every call, your integration can use an OAuth client: it trades a client secret for an access token that expires after 15 minutes. The token carries the client's agent and channel scope, so a leaked token is useful for minutes, not until someone notices. The client secret stays on the machine that requests tokens, and it goes only to the token endpoint.

Create an OAuth client. A Company Admin clicks New API key or OAuth client under Settings → API Keys and chooses the OAuth client type. It is set up like an API key — agents, channels, permissions, IP restrictions, expiry — but has no key value. On creation the page shows its Client ID (the client_id) and its first client secret (the client_secret); copy the secret immediately, as it is shown once. An API key's value is never accepted as a client secret.

Rotate the client secret. An OAuth client can have up to two active client secrets, so you can rotate without downtime: open the client, click Generate client secret in the OAuth client secrets card, switch your integration to the new secret, then revoke the old one.

Send the token as Authorization: Bearer <access_token> — on the same endpoints, instead of X-API-Key:

You can also send client_id and client_secret as form fields rather than HTTP Basic credentials, but not both in one request.

For how this compares with the other ways to connect, see Agent authentication.

Token errors follow the standard OAuth 2.0 shape rather than the TAI error envelope:

Look up an agent's contract — the input parameters it accepts and the output shape it returns — when you build or deploy your integration, not on every call. A pinned integration already knows the shape it sends and receives; re-reading the contract per invoke doubles your request count and adds a round-trip to every answer.

ref takes the agent's UUID — it's the last segment of the agent's URL in the Workbench — or, for a built-in Nezasa agent, its nezasa/… slug, and returns at most one agent. The key needs the Read agents permission. The response's channel_configs entry for the REST API channel carries the full list of contract versions:

Each input_schema entry declares a type — one of TEXT, STRING, NUMBER, DATE, DATE_RANGE, REFERENCE or JSON — and whether it's required. The same channel_configs entry also carries timeout_seconds, the agent's wall-time budget for a call.

Pin the contract version you integrate against. If you never pin one, TAI picks the newest usable version for you on every call, which means your integration's inputs and outputs can change out from under it the moment a new version ships.

The contract list may include versions with status: "DRAFT" — a version still being prepared. A DRAFT can never be invoked, whether or not you pin it; wait for it to become ACTIVE before building against it.

POST /api/v1/agents/invoke, with a body of:

A successful call returns:

agent_id is the agent's canonical id — its UUID, or a built-in's nezasa/… slug. That's the agent's one published identifier, so it may differ from what you sent as agent: address a built-in by its UUID and you get its slug back. envelope is your agent's answer, already validated against the contract's output_schema. If the agent's first answer fails that validation it gets one corrective turn. It's still one request, and what it costs you covers both turns.

invocation_meta.duration_ms is how long the run took, and contract_version the version that answered. invocation_meta.consumption is the run's credit figure; it is filled in for Workbench users (for example in the agent's Test API tab) and is always null on API-key and OAuth-client calls, so do not rely on it in an integration. invocation_meta.internal is reserved and always null for you. Your company admins see the credits your calls consumed in the Billing Center.

If the resolved contract is DEPRECATED, invocation_meta.deprecation is populated instead of null, and the response also carries two headers, both HTTP-date formatted: Deprecation, the date the version was deprecated, and Sunset, the date it stops working. deprecation.latest_active_version names the version to move to — enough for your integration to log, alert, or migrate on its own before the sunset date. Your company's admins also get an email within about a week of one of your API keys calling a deprecated version, and again as its sunset date approaches.

Every call to /agents/invoke is a durable, resumable run under the hood — a 200 response is just the case where it finished before you stopped waiting. A run that takes longer keeps going without you: you get back 202 Accepted with a Location header pointing at the run, and a Retry-After: 5. The run then has up to its own budget — 10 minutes, or less if your agent's REST API channel sets a shorter one — to finish, and its result waits for you however many polls that takes. Past that budget it ends as a FAILED run with an AGENT_TIMEOUT. Treat a 202 as a normal, expected outcome — not an error — for any agent whose answer can take more than a few seconds.

Poll the run with GET /api/v1/agents/runs/{id}. It long-polls by default — it holds the connection for up to 25 seconds waiting for the run to finish, so your loop doesn't spin. ?wait=N sets your own window (seconds, capped at 55); ?wait=0 returns the run's current state immediately. Unlike the invoke call itself, GET never raises an error for a run that finished badly — a FAILED run comes back as an ordinary 200 with status: "FAILED" and an error: {code, message} object in place of result, and a CANCELLED one likewise, so your poll loop only ever needs to branch on data.status.

Cancel a run you no longer need with POST /api/v1/agents/runs/{id}/cancel. A run already in progress isn't interrupted mid-turn — it finishes its current turn (and is billed for it) before the cancellation takes effect — but no further work happens after that. Cancelling a run that has already finished returns 409.

agent_id on a run is the agent's canonical id, exactly as on the inline answer above, and expires_at is when the finished run is deleted — after that its Idempotency-Key starts a fresh run rather than re-attaching.

Skip the wait entirely by sending Prefer: respond-async on the original POST /agents/invoke — you get a 202 immediately, every time, regardless of how fast the agent would have answered. Use this when your integration always polls anyway and would rather not hold the connection open at all.

Retry safely with an Idempotency-Key header on POST /agents/invoke. The same key (scoped to your API key and the agent you're calling) re-attaches to the run your first attempt already created instead of starting a second one — so a dropped connection or a client-side retry never double-runs, and never double-bills, the same call. That re-attach happens even while you're over your per-key, per-agent or per-company rate limit, or over your credit budget — it isn't new work, so it isn't refused as if it were. The invoke-admission limit still applies, because it counts attempts rather than work, so keep backing off on a 429 that names that scope. Reusing a key with a different body is treated as a mistake, not a retry, and returns 422 IDEMPOTENCY_KEY_MISMATCH. A key is honoured only until its run's TTL expires (currently 24 hours after the run finished); after that the same key starts a fresh run. Max 255 characters.

If your infrastructure tolerates Server-Sent Events, GET /api/v1/agents/runs/{id}/stream attaches to a run and pushes its outcome instead of making you poll for it. The stream sends :keepalive comment lines while the run is still going, then exactly one terminal result event carrying the same run object GET /agents/runs/{id} returns — a FAILED or CANCELLED run arrives the same way, so you branch on data.status here exactly as you would when polling — and finally a done event that closes the stream. It never sends the agent's answer incrementally; you still get the full result in one frame, just pushed instead of polled.

Polling stays the primary, recommended way to check on a run — it works everywhere. Reach for SSE only if your client and everything between it and TAI (proxies, gateways, load balancers) passes event-stream responses through untouched; if you're not sure, poll.

Handle the error event too. It means the stream could not deliver a run — never that the run failed, which is a result event with status: "FAILED". You get one if the run was deleted while you were attached, if it outlived the stream's 15-minute cap (STREAM_WAIT_EXPIRED), or on an unexpected fault (INTERNAL_ERROR). The run is unaffected either way: fall back to GET /api/v1/agents/runs/{id} for its outcome. Note the event carries code and error directly — it is a stream frame, not the HTTP error body described under Errors below.

Close the connection when done arrives. The stream is one attach, not a subscription — a client that reconnects automatically (a browser EventSource does, by default) will re-attach in a loop and spend its rate-limit allowance on it.

Every error shares one JSON shape:

details is null for most errors and carries structured context for a few: RATE_LIMIT_EXCEEDED names which limit fired (see Rate limits below), and CREDIT_BUDGET_EXCEEDED carries [{"reason": "budget_exceeded", "period": "MONTHLY", "reset_at": "..."}] — the instant your budget frees up.

The table below lists what an integration mistake produces. Any other failure uses this same envelope, so branch on error.code rather than assuming this list is closed — and when you meet a code you don't recognise, let the HTTP status decide: retry a 5xx, alert on a 4xx.

A malformed request body is the one exception. If the body itself doesn't parse as valid JSON matching the request shape (for example, agent is missing entirely), the response is still HTTP 422 but comes back in a different shape — {"detail": [...]} — not the {"error": {...}} envelope above. Handle both shapes at 422, or validate your request body against the contract before sending it so you only ever see the TAI shape.

A request must clear every limit that applies to it; the tightest one wins. Each returns RATE_LIMIT_EXCEEDED with a Retry-After header — sleep for that many seconds before retrying. Retrying sooner just spends the next window's allowance on rejected requests.

A company admin sees and manages the per-key and per-company numbers above, and any per-agent overrides, from Settings → Rate limits. Nezasa sets your company's overall allocation; contact your Nezasa representative to raise it.

Each one names itself in the response body: error.details carries [{"scope": "principal"}] for the per-key limit, "company", "agent", "api-key-auth" for verification, "oauth-token" for token requests, or "invoke-admission" for invoke attempts — so your backoff can tell "this key is going too fast" apart from "your whole company is", and "you are calling an agent that doesn't exist" apart from either.

Read the contract once (see Discover the agent's contract above), pin the version it gave you, then call the agent as often as you need:

Branch your retry logic on error.code, not on the HTTP status alone — the two 429s want opposite handling, and only some 5xx codes are worth a second attempt.