Skip to content

Agents

The routes an agent's app uses. The SDKs call them for you; this page is for reading traces, or for writing a client in another language.

Server version

These routes need a Fadenstack server 0.4.2 or later. Pairing, the tools list and the reasoning cap need core 0.7.1; each is marked below.

Signing in

Two ways: a login token (below), or pairing, which needs no password in the app.

Route Does
POST /api/auth/jwt/login The user's login, with a form body username (email) and password. Returns a login token. Single sign-on gives the same token.
POST /api/agent-tokens Exchanges the login token for an agent sign-in on this device. Body: {"agent": "<address>", "device_label": "My laptop"}. Returns an access token, a refresh token and their lifetimes, and the device id.
GET /api/agent-tokens/mine The user's agent sign-ins, per device
DELETE /api/agent-tokens/{device_id} Ends a sign-in

Sign in by pairing

Core 0.7.1 and later. The shape is RFC 8628, the OAuth device grant: the app starts, the person approves in the console, the app collects its tokens. Every answer carries Cache-Control: no-store. The codes travel in request bodies, never in an address.

Route Who calls it Does
POST /api/agent-tokens/pairings The app, with no sign-in Starts a pairing. Body: {"agent": "<address>", "agents": [...], "device_label": "My laptop", "client": {"name": ..., "version": ..., "os": ...}}. agents is optional: up to 8 in all, the first being agent, none twice. Returns pairing_code (the app's secret, for polling), user_code (XXXX-XXXX, to show), verification_uri, verification_uri_complete (the console's /pair page with the code in the fragment, which browsers never send), expires_in, interval and agents. Limited per address: beyond it, 429 with Retry-After.
POST /api/agent-tokens/pairings/token The app Polls. Body: {"pairing_code": "...", "agent": "<address>"}; agent is optional and defaults to the first. Until the person approves, 400 with an RFC 8628 error: authorization_pending, slow_down (with the new interval), access_denied, expired_token or invalid_grant. Then it returns the agent tokens once, as POST /api/agent-tokens does, with who signed in. With several agents, call it once per agent.

The console, not the app, uses three more routes, and they need a console sign-in: POST /api/agent-tokens/pairings/lookup (what the code asks for, which agents the person may use, the device label, where the request came from), .../pairings/approve and .../pairings/deny. An app does not call them. A pairing is valid for ten minutes. An approval covers the agents the person may use; if there is none, the console is refused.

The SDKs do all this for you: .NET, TypeScript. A server older than 0.7.1 answers the start with 404 or 405: the SDKs then report that pairing is not supported, and the app signs in with a login token.

Renewing with a refresh token returns a new refresh token; the old one stops working. Using an old one again ends the sign-in on every device, with refresh_token_reused. These routes report errors as {"detail": {"code": ..., "message": ...}}.

Working as an agent

All take the agent's access token as Authorization: Bearer.

Route Does
GET /v1/agents/{agent}/profile The agent's profile. See Agents on the server.
GET /v1/agents/{agent}/tools The server's MCP tools for this agent: name, server, description, allowed and enabled for each, sorted by server and name; never how a server is reached. Core 0.7.1 and later. See Agents on the server.
POST /v1/agents/{agent}/tools/check The server's current policy for one host tool call, before it runs. No tool runs. The SDKs use it for commands the person starts, and, from core 0.7.1, around the model's host tool calls. See Host commands in the SDK pages: .NET, TypeScript.
PUT /v1/agents/{agent}/manifest Reports the app: its name and version, the SDK, its tools (name, description, parameters as JSON Schema, class) and its greeting. Returns whether the server has seen this report before.
POST /v1/agents/{agent}/chat/completions Chat, as on /v1/chat/completions. The agent's model is used, whatever model says.
POST /v1/agents/{agent}/approvals/{id} Answers an approval the server asked for
POST /v1/agents/{agent}/events Reports what the agent did: up to 100 events per call

Headers on agent chat

Header Means
X-Faden-Tool-Mode The session's tool mode: off, read_only, ask or auto
X-Faden-Conversation-Id, X-Faden-Turn-Id Ties requests to a conversation and a turn on the device (1 to 128 characters of letters, digits and ., _, :, -)
X-Faden-PII-Mode redact or tokenize_reversible, if the agent lets the user choose
X-Faden-Events: ag-ui Switches on the extra events

When the agent's tool contract is not empty, tools the app offered that the contract does not list are held back until an administrator accepts them, and the response's X-Faden-Held-Tools header lists them. Nothing is held back while local MCP servers are allowed on the device.

Limits

A manifest is at most 512 kB, with up to 200 tools and up to 100 context entries. A tool's description is at most 4,000 characters and its parameters at most 32 kB.