API overview
The bAInquet REST API is a Koa modular monolith that serves the dashboard, the admin plane, the knowledge reads, and the connector ingestion surface from one versioned base URL.
Base URL
https://api.bainquet.online/v1Locally the API serves on http://localhost:8080. Every route path is written with its full /v1/... prefix; there is no router-level base path. The current contractVersion is 0.4.0 (the ingestion item contract is pinned at 0.3.0).
Three ways to read the surface
- The interactive reference renders every endpoint, schema, and example from the authoritative OpenAPI 3.1 spec, so it never drifts from these prose pages.
- Download
openapi.yamlto generate clients or load the spec into Postman, Insomnia, or your editor. - The prose pages (REST, Ingestion and signing, Envelope and errors) explain the behavior and the gotchas the raw spec cannot.
The response envelope
Every JSON response uses one wrapper:
{ "ok": true, "data": { "...": "typed payload" }, "meta": { "requestId": "req_01J..." } }{ "ok": false, "error": { "code": "website.not_verified", "message": "...", "status": 409, "retryable": false } }Branch on the boolean ok, never on the HTTP status alone. A 200 can carry a partial-batch ingest result where some items failed, and an error body still carries the ok field so a single code path handles both branches. The full envelope, the error object shape, pagination, and the error-code catalogue live on Envelope and errors.
Authentication
Three principal types authenticate against the API. Pick the one that matches the caller.
| Principal | Credential | Used for |
|---|---|---|
| User | Authorization: Bearer <access JWT> (EdDSA, ~15 min) plus a rotating refresh token in the httpOnly bnq_refresh cookie | dashboard and admin traffic; carries an RBAC role |
| Connector | Authorization: Bearer <connectorId>.<secret> plus per-request HMAC headers | ingestion only; scope-limited, cannot publish or read the dashboard |
| API key | bnq_live_... (X-Api-Key or Authorization: Bearer) | programmatic access; created under /v1/organizations/{id}/api-keys, hashed at rest, shown once |
The RBAC role ladder, low to high, is viewer < editor < organization_admin < organization_owner < admin < super_admin. The User flow (register, verify, login, refresh, roles) is covered in Authentication. The Connector flow (token issue, HMAC signing, scopes) is covered in Ingestion and signing and Connector tokens.
Rate limiting
Two limiters run in the middleware chain:
- Pre-auth, keyed by client IP, runs before authentication. It protects the public surface (register, login, password reset, waitlist) from abuse.
- Post-auth, keyed per tenant, runs after the principal resolves. It enforces per-organization throughput.
A limited request returns 429 with quota.rate_limited (global or per-IP abuse) or quota.exceeded (a plan limit), both with a Retry-After header. Both codes are retryable: true.
Endpoint groups
| Group | Base path | What it covers |
|---|---|---|
| Auth | /v1/auth/* | register, verify email, login, Google sign-in, refresh, logout, profile, password |
| Organizations | /v1/organizations/* | org CRUD, membership, GDPR erasure |
| Websites | /v1/websites/*, /v1/organizations/:orgId/websites | website CRUD under an org |
| Verification | /v1/websites/:id/verification/* | ownership challenge and check (drives the trust tier) |
| Connectors | /v1/websites/:id/connectors, /v1/connectors/:cid/* | issue, list, rotate, revoke connector tokens |
| Ingestion | /v1/ingest/* | connector + HMAC content push (batch, item, delete, heartbeat, schema) |
| Knowledge | /v1/websites/:id/knowledge/*, /v1/websites/:id/entities/* | search, entity facts, related entities |
| Publishing | /v1/websites/:id/publish, /node/preview, /node | run the exporter pipeline, preview, take down |
| Billing | /v1/organizations/:id/entitlements, /usage | plan entitlements and usage reads |
| Admin | /v1/admin/* | audited org and audit-log reads, impersonation |
| Analytics | /v1/websites/:id/analytics | read-only per-website rollups |
| Waitlist | /v1/waitlist | public marketing capture (always 202) |
| System | /healthz, /readyz, /metrics, / | unauthenticated liveness, readiness, Prometheus metrics, banner |
Each group is documented with method, path, required role, and examples on REST API. The ingestion group has its own page because it uses a different principal and a request-signing scheme: Ingestion and signing.
How to read the spec
The OpenAPI document tags every operation with one of the groups above, declares the three security schemes (userJwt, connectorToken, apiKey), and carries a worked example on every response. When the prose and the spec describe the same endpoint, treat the spec as the machine contract and the prose as the explanation of behavior the schema cannot express (idempotency, replay guards, partial-batch semantics, and the divergences noted on each page).