API overview
How Grounded's API is organised, its conventions, and where to start.
Everything the web app does goes through Grounded's HTTP API, and the same routes serve programs. There are two surfaces:
- The OpenAI-compatible API:
POST /v1/chat/completionsandGET /v1/models, where each agent is a model namedagent:<team>/<agent>. Any OpenAI client library works. This surface is meant to stay stable through 0.x. See OpenAI-compatible chat. - The native REST API under
/v1: teams, sources, documents, knowledge bases, agents, chat, evaluations, and the admin API. It's described by an OpenAPI 3.0 document that covers every route (a test in the Grounded repository enforces it), and it may change between minor releases before 1.0. See the reference, generated from that document.
Authentication
API keys, scopes and browser sessions.
OpenAI-compatible chat
Chat completions with citations and claims.
Native chat API
Streamed answers with conversations, retrieval events and verdicts.
Conventions
- Base URL: your install's
APP_URL, for examplehttps://grounded.example.org. All API routes are under/v1, except/healthz,/readyzand/metrics. - Responses are
{"data": ...}on success and{"error": {"code": "...", "message": "..."}}on failure. The OpenAI-compatible endpoints use OpenAI's shapes instead. - Credentials decide what's allowed. Browser sessions and API keys share the same routes; an API key can only do what its team, scopes and restrictions allow.
- Admin writes need a revision precondition (
If-Match): a missing one returns 428, a stale one 412. - Limits return 429 with
Retry-Afterfor rate limits (rate_limited), daily quotas (quota_exceeded) and used-up budgets (budget_exhausted), withdetails: {limit, max, current}or the budget figures. Resource caps return 409limit_reached. - Maintenance mode returns 503
maintenance_modefor new uploads, syncs and crawls. - Streaming uses Server-Sent Events, with a
: pingcomment every 15 seconds.
Common tasks
| Task | Route |
|---|---|
| Ask an agent (OpenAI-compatible) | POST /v1/chat/completions |
| List the agents a key can use | GET /v1/models |
| Ask an agent (native, with conversations) | POST /v1/agents/{team}/{agent}/chat |
| Search a knowledge base | POST /v1/teams/{team}/kbs/{kbId}/retrieve |
| Upload documents | POST /v1/teams/{team}/sources/{sourceId}/documents (multipart, ingest scope) |
| List your conversations, export one | GET /v1/conversations, GET /v1/conversations/{id}/export |
Keeping the spec
The reference is generated from openapi/grounded.yaml in this documentation's repository, a copy of api/openapi.yaml from the Grounded release these docs describe (v0.2.1). The Grounded repository's copy is the source of truth.