API Reference

API Reference

All HTTP endpoints live under /api/v1 (health is at root). Every route declares an explicit rate-limit tier (see Security). Authentication is JWT Bearer unless marked public.

Conventions

• Auth header: Authorization: Bearer <access_token>.
• Transparent refresh: the frontend client retries once on 401 by rotating the refresh token (see Frontend-Reference).
• Error shape (FastAPI): {"detail": "..."} for simple errors, or a 422 validation array. ApiError on the client carries status.
• Auth tiers (core/deps.py):
  • CurrentUser — any valid token.
  • ActiveUser — token + account not deletion-locked (returns 403 while locked; most product endpoints).
  • VerifiedUser — ActiveUser + email verified (only POST /tasks and POST /api-keys; gated by EMAIL_VERIFICATION_REQUIRED).
• Rate-limit tiers (name / requests-per-60s): PUBLIC 30, AUTH 20, READ 60, WRITE 20, PAYMENT 10, EXPENSIVE 30, UPLOAD 10, WEBSOCKET 30.

Health (root)

Method	Path	Purpose
GET	/health	Liveness probe.
GET	/health/ready	Readiness; 503 if any datastore is degraded.

Auth — /api/v1/auth (tier AUTH)

Method	Path	Purpose
POST	/auth/register	Create account (201). Sends verification email; does not create a subscription.
POST	/auth/login	Password login → token pair, or an MFA challenge if 2FA is on.
POST	/auth/login/totp	Complete 2FA (TOTP or recovery code) → token pair.
POST	/auth/refresh	Rotate the refresh token (reuse-detection revokes the family).
POST	/auth/logout	Revoke the current session family (204).
POST	/auth/verify-email	Redeem an emailed verification token (public, single-use).
POST	/auth/resend-verification	Re-send verification (202; auth required; 202 even if already verified).
POST	/auth/forgot-password	Start reset (always 202, enumeration-safe).
POST	/auth/reset-password	Redeem reset token; on success revokes all sessions.

Users & GDPR — /api/v1/users

Method	Path	Purpose
GET	/users/me	Current profile (works while account is deletion-locked).
PATCH	/users/me	Update profile / default provider / reviewer default / model preferences.
POST	/users/me/password	Change password (204).
GET	/users/me/sessions	List active sessions.
DELETE	/users/me/sessions/{family_id}	Revoke one session (204).
POST	/users/me/sessions/revoke-others	Sign out all other sessions (204).
POST	/users/me/2fa/setup	Begin TOTP enrollment (returns QR SVG).
POST	/users/me/2fa/enable	Confirm TOTP; returns recovery codes.
POST	/users/me/2fa/disable	Turn off 2FA.
DELETE	/users/me	Request account deletion (30-day grace).
POST	/users/me/deletion/cancel	Restore a deletion-locked account.
GET	/users/me/export	GDPR data export (JSON download).

API keys (BYOK) — /api/v1/api-keys

Method	Path	Purpose
GET	/api-keys	List keys — metadata only (provider, label, key_hint). Never returns the key.
POST	/api-keys	Store an AES-256-GCM-encrypted key (201; VerifiedUser; SSRF check for custom endpoints).
DELETE	/api-keys/{key_id}	Delete a key (204).

Tasks — /api/v1/tasks

Method	Path	Purpose
POST	/tasks	Start a task (202; VerifiedUser; quota enforced; tier EXPENSIVE). Returns task_id.
GET	/tasks	List tasks (paginated, newest first).
GET	/tasks/{task_id}	Current task state.
GET	/tasks/{task_id}/trace	Span tree (waterfall).
GET	/tasks/{task_id}/trace/summary	Per-node token/cost rollup.
POST	/tasks/{task_id}/cancel	Cancel a running task.
DELETE	/tasks/{task_id}	Delete task + logs (204).
POST	/tasks/{task_id}/answer	Answer a human-in-the-loop question (HTTP fallback to the WS path).

POST /tasks returns HTTP 402 when the user has no active subscription. See Billing-and-Quota.

Billing — /api/v1/billing

Method	Path	Purpose	Tier
GET	/billing/plans	The 3 paid plans (authed).	READ
GET	/billing/plans/public	Plans for anonymous visitors.	PUBLIC
GET	/billing/subscription	Current subscription + live quota usage.	READ
GET	/billing/payment-method	Stored card metadata (brand + last4 + expiry).	READ
POST	/billing/subscribe	Charge + activate a plan (full price).	PAYMENT
POST	/billing/cancel	Cancel at period end.	WRITE

Dashboard — /api/v1/dashboard (tier READ)

Method	Path	Purpose
GET	/dashboard/metrics	Task counts, success rate, tokens.
GET	/dashboard/token-usage	Token usage by provider.
GET	/dashboard/cost-summary	Estimated cost by provider.
GET	/dashboard/costs?days&group_by=day|model|domain	Trace-derived costs.

Marketplace — /api/v1/marketplace

Method	Path	Purpose
GET	/marketplace	List published agent teams.
GET	/marketplace/showcase	Anonymous listing (featured first).
POST	/marketplace	Publish a team (201; mandatory prompt-injection security scan).
GET	/marketplace/{item_id}	Item detail.
POST	/marketplace/{item_id}/install	Install into the caller's agents (201).
GET	/marketplace/{item_id}/reviews	Paged reviews + the caller's own.
POST	/marketplace/{item_id}/reviews	Upsert a review (200).

Agents — /api/v1/agents

Method	Path	Purpose
GET	/agents	Built-in + custom agents ({builtin, custom}).
GET	/agents/tools	Tool catalog (web_search, data_fetch, code_execution).
POST	/agents	Create a custom agent (201; prompt scanned).
GET	/agents/{agent_id}	Get a custom agent.
PUT	/agents/{agent_id}	Update a custom agent.
PATCH	/agents/{agent_id}/system-prompt	Update only the system prompt.
DELETE	/agents/{agent_id}	Delete a custom agent (204).

Documents (RAG) — /api/v1/documents

Method	Path	Purpose
GET	/documents	List uploaded documents.
POST	/documents	Upload txt/md (201; tier UPLOAD; 2 MB cap). Chunked + embedded to Qdrant.
DELETE	/documents/{document_id}	Delete document + its vector chunks (204).

WebSocket — /api/v1

Both authenticate via ?token=<access> query param, are owner-only, and rate-limit the handshake (check_websocket before accept()).

Path	Purpose
WS /api/v1/tasks/{task_id}/stream	Snapshot + live events; ?after_seq=N resume; inbound answer messages for HITL.
WS /api/v1/architect/live?task_id=	Architect communication stream (live agent graph).

See Realtime-and-WebSockets for the event envelope and message types.