Conventions
Base URL and versions
Section titled “Base URL and versions”https://api.dev.loupestack.com/v1/TODO: confirm the production host; only a development environment exists so far.
The version is in the path. Within v1, changes are additive: new endpoints, new optional request fields, new
response fields and new enum values. Treat unknown response fields and enum values as possible, and ignore what
you don’t know. A change that breaks this gets a new path version.
TODO: decide how long an old version stays available after a new one ships, and how deprecations are announced.
Requests
Section titled “Requests”- Bodies are JSON (
Content-Type: application/json), at most 256 KB. - A body is checked against its schema in the reference. A field of the wrong type, a missing
required field or a value out of range gets
422 invalid_request, withdetailsnaming each problem. - Unknown fields are dropped, except in connector bodies, where they are refused: a connector accepts only the fields of its own kind.
- In a
PATCH, fields you leave out stay as they are.
Identifiers and timestamps
Section titled “Identifiers and timestamps”- Resources you create (connectors, saved queries, descriptions, conversations, UIs, sync jobs and runs) have UUIDs. Users and workspaces have opaque string ids.
- Timestamps are ISO 8601 in UTC with milliseconds, for example
2026-11-20T09:30:00.000Z. - In query results,
DECIMALvalues are strings (so no precision is lost) and dates are ISO strings.
Paging
Section titled “Paging”Every list endpoint returns one page:
{ "items": [ ... ], "nextCursor": "WyIyMDI2LTExLTIwIDA5OjMwOjAwLjAwMDAwMCswMCIsIjZmMWMuLi4iXQ" }limit: items per page, 1 to 100, default 50.cursor: thenextCursorof the previous page.nextCursorisnullon the last page.- Items come in creation order, oldest first. A cursor is opaque: pass it back as it is.
The messages of GET /v1/conversations/{id} page the same way, with the conversation itself on every page.
Rate limits
Section titled “Rate limits”| Limit | Default | Over the limit |
|---|---|---|
| Requests per client IP address | 300 per minute | 429 rate_limited |
| Questions, UI generations and chat messages per workspace | 30 per minute, together | 429 rate_limited |
| Questions and UI generations in progress at once, per workspace | 4 | 429 llm_busy |
| Queries running at once, per workspace | 4 | 429 too_many_queries |
Responses carry x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset (seconds) for the
per-IP limit, and a 429 from it carries retry-after.
TODO: confirm the production values. The counters are kept per server process, so with several servers the effective limit is higher; a shared limit per user is planned.
Retries and idempotency
Section titled “Retries and idempotency”There are no idempotency keys. What is safe to repeat:
| Request | Safe to repeat? |
|---|---|
GET |
Yes |
PATCH |
Yes, with the same body |
DELETE |
Yes; a repeat answers 404 not_found |
POST that creates something |
No: a repeat may create a second one, or fail with a 409 such as alias_in_use |
POST .../run, POST /v1/ask, POST /v1/chat |
Reads only, but each one counts against the limits above |
Retry after 429, 503 (engine_busy, shutting_down, llm_unavailable) and 504, with a growing delay.
Do not retry other 4xx errors unchanged.
Caching
Section titled “Caching”Every response carries Cache-Control: no-store: responses are per user and per workspace. The API caches
results itself: a saved query’s results are reused for cacheTtlSeconds (cached: true in the result).
Query limits
Section titled “Query limits”A query runs for at most 15 seconds (504 query_timeout) and returns at most maxRows rows (default 1000, at
most 10,000); truncated: true says more rows existed. A question gets 60 seconds in all; a UI generation
10 minutes.
TODO: confirm the production values of these limits.