Getting started — Integrator API
Base URL
| Environment | API base |
|---|
| Local Compose | http://localhost:12020 |
| Production | https://review.querytek.io/api (path prefix as deployed) |
All routes below are relative to /v1.
Authentication
- Send
Authorization: Bearer <access_token> on every protected call (SPEC-003).
- Tokens are issued by Keycloak (ADR-003).
- Missing/invalid token →
401 with ADR-021 envelope.
Roles (typical integrator)
| Capability | Roles |
|---|
POST /v1/intake/submit | Roles accepted by the intake rate-limit dependency (includes client_admin / platform_admin; see OpenAPI) |
POST /v1/intake/batch, status GET | client_admin | platform_admin |
| Webhook subscription CRUD / deliveries | client_admin | platform_admin |
Tenant scoping
tenant_id comes from the JWT (ADR-004).platform_admin may pass optional ?tenant_id= on intake to act on a client tenant (effective-tenant resolution). Do not rely on client-supplied tenant IDs for ordinary integrators.
Contract artifacts
- OpenAPI subset:
/developer/api/raw
- Drift check:
python3 scripts/qa/validate_integrator_openapi.py
- Live drift (Compose):
python3 scripts/qa/validate_integrator_openapi.py --live http://127.0.0.1:12020/openapi.json
What this pack is not
- Not a published SDK
- Not the full portal OpenAPI
- Not WooCommerce / email / Box / Drive inbound webhooks
