API Reference
Interactive documentation for the AskRAI Public API — query execution, session management, audit inspection, and more.
The AskRAI Public API provides programmable access to the AskRAI platform. Use it to execute governed queries, retrieve conversation history, inspect audit records, and discover tenant capabilities.
Authentication
All Public API endpoints require an API key in the Authorization header:
Authorization: Bearer {api_key}API keys are created and managed on the console's Admin → Programmable Access page: click Create Credential.
A refused key counts against the address that sent it. Once around ten keys from one address have been refused within a minute, every key sent from that address is answered 429 with the code RATE_LIMITED and a Retry-After header, a working one included, until the minute is up.
Request bodies
The query endpoints, POST /v1/query and POST /v1/query/stream, take a body of up to 121,024 bytes, sent with a Content-Length header or chunked, as .NET's PostAsJsonAsync and JsonContent send it. An agent's A2A endpoint takes one of up to 8,192 bytes, either way. A chunked body that grows past its endpoint's bound is answered 413 with the code CONTENT_TOO_LARGE as soon as that much of it has arrived. A body whose Content-Length declares more is refused before it reaches the API, with 403 and an HTML page.
A request carrying a Transfer-Encoding header, as a chunked one does, to any other endpoint is refused before it reaches the API: it is answered 403 with an HTML page, not a JSON error with a code.
Rate limits
Queries — POST /v1/query and POST /v1/query/stream — are held to request budgets per minute and per day, set for your tenant and for each credential on the Admin Console's Programmable Access page. A credential is held to both its own budgets and its tenant's. Budgets are counted in fixed UTC windows: each whole minute, and each day from 00:00 UTC. A query counts once, when it is admitted; a query refused by any check counts against nothing. An outside agent's SendMessage to a project's agent over A2A counts too, once its key, its address and its message pass their checks, and is refused with the same 429. Other endpoints are neither counted nor refused by a budget.
A query sent once a budget is spent is answered 429 with the code RATE_LIMITED and a Retry-After header: the whole seconds until the window renews. The detail names the budget and when it renews, for example This credential's budget of 60 requests per minute is spent. It renews in 23 seconds. On POST /v1/query/stream this 429 arrives before the stream starts. A budget of 0 is answered the same 429 with no Retry-After, since no window renews it. A query refused because a concurrency limit is full is also answered 429 with the code RATE_LIMITED.
A prompt longer than the credential's limit is answered 400 with the code INVALID_REQUEST, for example The prompt is 812 characters, over this credential's limit of 500. A prompt longer than 10,000 characters is answered 422 whatever the credential allows.
Base URLs
| Environment | Public API | MCP server |
|---|---|---|
| Production | https://public.askrai.ai | https://mcp.askrai.ai/mcp |
The MCP server admits only a credential created with Channel MCP: see Connect an AI agent (MCP).
Project events and dashboards
A project's events and its Dashboard are written through the console's API, https://api.be.askrai.ai, rather than the Public API, so they are not in the endpoint list below. Its routes take a person's console sign-in as the bearer token, not an API key, and act with that person's access to the project.
| Route | |
|---|---|
GET /api/v1/projects/{project_id}/event-types | The event types a project declares |
PUT /api/v1/projects/{project_id}/event-types/{name} | Declares an event type, or edits it |
POST /api/v1/projects/{project_id}/events | Records up to 100 events at once |
GET /api/v1/projects/{project_id}/events | The project's events, newest first |
GET /api/v1/projects/{project_id}/dashboard | The project's Dashboard and its widgets |
PUT /api/v1/projects/{project_id}/dashboard | Replaces the Dashboard's widgets, those carrying your own figures among them |
POST /api/v1/projects/{project_id}/dashboard/query-preview | Computes a figure over the project's events now, saving nothing |
PUT /api/v1/projects/{project_id}/assistant-dashboards/{dashboard_id}/dashboard-pin | Pins an assistant dashboard's pieces to the Dashboard |
DELETE /api/v1/projects/{project_id}/assistant-dashboards/{dashboard_id}/dashboard-pin | Removes them |
Endpoints
Browse the API reference in the sidebar to see detailed documentation for each endpoint, including request/response schemas and an interactive playground.