API Reference

Xagent exposes three API surfaces. This page is the canonical reference for how to authenticate against each one and how errors are shaped — the other API pages link back here rather than repeat it.

API Surfaces

Surface	Prefix	Authentication	Error shape
Application API	`/api`	JWT access token from sign-in.	`{ "detail": "..." }`
Workspace SDK	`/v1`	API key — workspace `xag_personal_<prefix>_<secret>` or runtime `xag_<prefix>_<secret>`.	`{ "error": { "code", "message" } }`
Billing & Teams	`/api/billing`, `/api/teams`	JWT access token + team context.	`{ "detail": "..." }`

Base URL

All endpoints are served from your Xagent deployment. For a local install the backend listens on port 8000:

Self-hosted:  http://localhost:8000
Production:   https://your-domain.com

Authentication

Every request carries a bearer token; which token depends on the surface (see the table above):

Authorization: Bearer <token>

Application API (/api) — a JWT access token from POST /api/auth/login. See Authentication.
Workspace SDK (/v1) — an API key. Use a personal key (xag_personal_…) to manage agents and templates, and a runtime key (xag_…) to run tasks.

Keys are shown once

Both API key types are returned in full only at creation. The <prefix> is a public-safe 6-character handle; the secret half is never retrievable again — rotate the key to replace it. Using the wrong key type on a /v1 endpoint returns 401 invalid_api_key.

Error Handling

There are two error envelopes. Parse the one that matches the surface you are calling.

Application API and Billing/Teams (/api/*) use FastAPI's default shape — string-match or display the detail:

{ "detail": "Agent not found" }

Workspace SDK (/v1/*) uses a stable, machine-readable envelope — switch on error.code:

{
  "error": {
    "code": "invalid_input",
    "message": "Request body failed validation."
  }
}

The /v1 surface returns these codes:

Core codes

Code	HTTP	Meaning
`invalid_api_key`	401	Any authentication failure — missing, malformed, wrong-type, expired, paused, or revoked key. One opaque code by design; the message is always `Invalid or revoked API key.`
`invalid_input`	422, also 400 / 413	Body or parameter validation failed. 400 for client-side rejections (e.g. inaccessible file ids); 413 when an upload exceeds the size cap.
`agent_not_found`	404	Agent does not exist or is not bound to this key. Also returned when a workforce key sends `agent_id`.
`workforce_not_found`	404	Workforce does not exist or is not bound to this key. Also returned when an agent key sends `workforce_id`.
`template_not_found`	404	Template id is unknown or unavailable.
`task_not_found`	404	Task does not exist, does not belong to this key, or was not created through the SDK.
`file_not_found`	404	A file id in `message.files` is inaccessible. Returned on workforce-run creation; the task endpoints report this as `invalid_input` (400) instead.
`task_busy`	409	Task is still running and cannot accept new input yet. Retryable — poll status, then retry.
`internal_error`	500, also 503	Server-side failure; the detail is sanitized. 503 signals a temporarily unavailable dependency (e.g. file storage).

Workforce run conflicts — all 409, and unlike task_busy these are permanent: retrying the same request will not succeed.

Code	Meaning
`workforce_archived`	The workforce is archived. Restore it or target another workforce.
`workforce_not_active`	The workforce is not in `active` status (for example, still a draft). Publish it first.
`workforce_config_changed`	The run's pinned configuration no longer matches the workforce. Start a new run.
`idempotency_conflict`	The `idempotency_key` was already used by a run whose task no longer exists. Use a new key.

Connector runtime — returned when a request carries connector_runtime_context.

Code	HTTP	Meaning
`connector_not_found`	404	The referenced connector was not found or is not accessible.
`invalid_runtime_context`	400	Malformed runtime context (duplicate reference, bad shape, unsupported selector).
`missing_runtime_context`	400	A required runtime context value was not supplied.
`runtime_context_immutable`	409	Runtime context cannot be changed after the task is created.
`runtime_secret_not_allowed`	400	A runtime secret is not permitted for this entry point.
`runtime_secret_unavailable`	400	A required runtime secret is unavailable.
`connector_runtime_unavailable`	503	Runtime context is temporarily unavailable. Retry later.

Reserved codes

Handle these defensively — they are part of the contract but are not emitted by the /v1 endpoints in this deployment: rate_limited (429), quota_exceeded and client_quota_exceeded (402, emitted by hosted deployments), scheduled_secret_unavailable, mcp_oauth_authorization_failed, delegated_authorization_failed.

Pin against the code, not the status

The code is the stable contract; message is human-readable and may change. The HTTP status is chosen per endpoint, so a single code can appear with more than one status (invalid_input and internal_error both do).

Validation & quotas

Body validation fails as 422 invalid_input on /v1; the untyped Billing/Teams bodies return 400 with a detail message. Exceeding a plan quota returns 402 Payment Required — see Usage & Quotas. There is no per-second rate limiting.

Interactive & Machine-Readable Spec

Every deployment ships live API explorers generated from the server's OpenAPI schema:

Tool	Path	Best for
Swagger UI	`/docs`	Trying requests interactively.
ReDoc	`/redoc`	Readable reference for the whole API.
OpenAPI JSON	`/openapi.json`	The raw spec — import into Postman or codegen.

API Groups

Group	Prefix	Purpose
Authentication	`/api/auth`	Login, SSO, refresh, password management.
Agents	`/api/agents`	Create, configure, publish, and key agents.
Workforces	`/api/workforces`	Multi-agent teams and runs.
Knowledge Bases	`/api/kb`	Ingest and search documents.
Tools / Skills	`/api/tools`, `/api/skills`	Tooling and packaged capabilities.
MCP / Custom APIs	`/api/mcp`, `/api/custom-apis`	External tool integrations.
Chat / Tasks	`/api/chat`	Create and track task runs.
Teams	`/api/teams`, `/api/invitations`	Workspaces, members, invitations.
Billing	`/api/billing`, `/api/webhooks`	Subscriptions, usage, and Stripe webhooks.
Workspace SDK	`/v1`	Versioned agent & task SDK.