Skip to main content

Integration guide

Getting started — Integrator API

Authentication, tenant scoping, base URLs, and roles for the QueryTek Review integrator API.

Field-level detail for every endpoint is in the API reference.

Base URL

EnvironmentAPI base
Local Composehttp://localhost:12020
Productionhttps://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.
  • Tokens are issued by the QueryTek identity provider (Keycloak, OpenID Connect).
  • Missing/invalid token → 401 AUTH_REQUIRED; a token without an accepted role → 403 INSUFFICIENT_ROLE. Both use the standard error envelope.

Roles (typical integrator)

CapabilityRoles
POST /v1/intake/submit, POST /v1/intake/batch, status GETclient_admin | platform_admin | integrator_sandbox
Webhook subscription CRUD / deliveriesclient_admin | platform_admin | integrator_sandbox

Tenant scoping

  • tenant_id comes from the JWT, never from the request body. Every query is isolated to that tenant.
  • 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

  1. OpenAPI subset: /developer/api/raw
  2. Versioning: the integrator contract follows semver 0.1.x; breaking changes are announced at least 90 days before removal: the operation is marked deprecated in the API reference with its removal date, and registered developers receive an email.
  3. Regenerate your client from the subset after each release and diff it against your integration.

What this pack is not

  • Not a published SDK
  • Not the full portal OpenAPI
  • Not WooCommerce / email / Box / Drive inbound webhooks