Skip to main content

Developers · API reference

Integrator API reference

Register review work from your own systems, track each submission, and receive signed webhooks when documents move through review. Trained human reviewers do the review; this API handles the handoff.

API version
0.2.0
OpenAPI
3.1.0
Operations
9

New to the API? Start with the getting started guide or practice in the integrator sandbox.

Before you start

Base URL

Send production requests to https://review.querytek.io/api. Every path in this reference starts with /v1, so a full URL looks like https://review.querytek.io/api/v1/intake/submit.

Requests and responses use JSON (Content-Type: application/json) over HTTPS.

Authentication

Send Authorization: Bearer <access_token> on every call except the two health checks. Access tokens are issued by the QueryTek identity provider at auth.querytek.io (OpenID Connect).

Protected operations accept the client_admin, platform_admin, and integrator_sandbox roles. A missing or expired token returns 401 with code AUTH_REQUIRED; a token without one of these roles returns 403 with code INSUFFICIENT_ROLE.

To practice without production credentials, create a developer account and use the integrator sandbox.

Workspace scoping

Your workspace (tenant) comes from your access token, never from the request body. Every read and write is isolated to that workspace by PostgreSQL row-level security, and each intake call is recorded in the audit log.

The optional tenant_id query parameter on intake operations is honored only for platform_admin tokens acting on behalf of a client workspace. Ordinary integrations leave it out.

Errors

Every error response uses the same JSON envelope: an error object with a stable code, a readable message, the request_id for the call, and details when there is more to say. Branch on error.code, not on the message text, and include the request_id when you contact support.

Example error response
{
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "AUTH_REQUIRED",
    "request_id": "73f04ccf-0a8b-4fcf-9b9b-833b7436f5af"
  }
}

Safe retries (idempotency)

Both intake operations accept an optional Idempotency-Key header (1–128 characters). Retrying with the same key and the same body returns the stored 201 response without creating a second submission, audit event, or webhook.

The same key with a different body returns 409 IDEMPOTENCY_KEY_MISMATCH. A retry that arrives while the first call is still running returns 409 IDEMPOTENCY_IN_PROGRESS; wait briefly and try again. Keys are scoped to your workspace, your user, and the operation, and expire after 24 hours. Only successful 201 responses are stored, so you can reuse a key after fixing a 422.

Rate limits

Intake submissions are rate-limited per workspace and per user. Responses include X-RateLimit-* headers where limits apply. When you receive 429, wait for the number of seconds in the Retry-After header before retrying.

Versioning

The integrator contract follows semantic versioning on the OpenAPI info.version field. Breaking changes are announced at least 90 days before removal: the operation is marked deprecated in this reference with its removal date, and registered developers receive an email.

Generate your client from the OpenAPI file after each release and compare it with your integration.

Intake

Register documents for review from your own pipeline. Intake records each file's name, size, type, and your reference so the work can be tracked and invoiced. It does not carry file contents; documents are uploaded into encrypted storage through the client portal.

Submit one document

post/v1/intake/submit

Registers a single document for review and returns the new submission. Review checks the file type and size before accepting it; if either is not supported, the call returns 422 and nothing is created.

Access: Bearer token with role client_admin, platform_admin, or integrator_sandbox. About authentication

Parameters

Submit one document parameters
ParameterInTypeDetails
tenant_idOptionalQuerystring (uuid)Only for platform_admin tokens acting for a client workspace. Leave it out otherwise.
Idempotency-KeyOptionalHeaderstringOptional, 1–128 characters. Same key and body replays the stored 201; same key with a different body returns 409. Expires after 24 hours.1–128 characters

Request body IntakeSubmitRequest

Submit one document request body
FieldTypeDetails
filenameRequiredstringFile name as it should appear to your team and the reviewer.1–255 characters
file_sizeRequiredintegerFile size in bytes. Up to 50 MB.greater than 0
mime_typeRequiredstringOne of application/pdf, Word (.docx), Excel (.xlsx), text/plain, text/html, text/xml, or application/xml.1–127 characters
moduleOptionalstringor nullOptional review module key: ai_output, content_risk, plain_language, or education_accessibility. Omit to use your workspace default; other values return 422 INTAKE_INVALID_MODULE.at most 40 characters
tierOptionalstringor nullRetired — omit this field. If sent, the API returns 422 INTAKE_TIER_RETIRED.at most 20 characters
external_referenceOptionalstringor nullYour own ID for this work, such as a ticket or job number. Returned on the submission so you can match it.at most 255 characters
item_metadataOptionalobjector nullOptional JSON object you want stored with the item: up to 50 keys, 10 KB serialized, and 3 levels deep.

Responses

Submit one document responses
StatusMeaningBody or error code
201Successful ResponseIntakeSubmissionResponse
401Missing, expired, or invalid access tokenAPIErrorEnvelope
403Token does not carry an accepted roleAPIErrorEnvelope
409Idempotency key mismatch or in progressAPIErrorEnvelope
422Validation or intake field errorAPIValidationErrorEnvelope
429Intake rate limit exceededAPIErrorEnvelope
401Missing, expired, or invalid access token.AUTH_REQUIRED
403The token does not carry an accepted role.INSUFFICIENT_ROLE
422mime_type is not one of the supported types.FILE_TYPE_NOT_ALLOWED
422file_size is over 50 MB.FILE_TOO_LARGE
429Too many intake calls. Wait for Retry-After seconds, then retry.RATE_LIMIT_EXCEEDED
  • Send an Idempotency-Key so a network retry cannot create a duplicate submission.
  • A successful call records an intake.submitted audit event and triggers intake.submitted webhooks.
Request
curl -sS -X POST "https://review.querytek.io/api/v1/intake/submit" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "filename": "employee-handbook-2027.pdf",
    "file_size": 482113,
    "mime_type": "application/pdf",
    "external_reference": "hr-handbook-2027",
    "item_metadata": {"department": "People Operations"}
  }'

Submit a batch

post/v1/intake/batch

Registers up to 100 documents in one call under a single submission. Each item is checked on its own: supported items are accepted, and items with an unsupported type or size are recorded as failed with an error_message, without failing the whole batch. The submission status then reads completed, partial_failure, or failed.

Access: Bearer token with role client_admin, platform_admin, or integrator_sandbox. About authentication

Parameters

Submit a batch parameters
ParameterInTypeDetails
tenant_idOptionalQuerystring (uuid)Only for platform_admin tokens acting for a client workspace. Leave it out otherwise.
Idempotency-KeyOptionalHeaderstringOptional, 1–128 characters. Same key and body replays the stored 201; same key with a different body returns 409. Expires after 24 hours.1–128 characters

Request body IntakeBatchRequest

Submit a batch request body
FieldTypeDetails
moduleOptionalstringor nullOptional review module key applied to every item. See Submit one document.at most 40 characters
tierOptionalstringor nullOptional service tier key applied to every item. See Submit one document.at most 20 characters
external_referenceOptionalstringor nullYour own ID for the whole batch.at most 255 characters
itemsRequiredarray of IntakeItemRequestThe documents to register, 1 to 100 per call.1–100 items

Responses

Submit a batch responses
StatusMeaningBody or error code
201Successful ResponseIntakeSubmissionResponse
401Missing, expired, or invalid access tokenAPIErrorEnvelope
403Token does not carry an accepted roleAPIErrorEnvelope
409Idempotency key mismatch or in progressAPIErrorEnvelope
422Validation or intake field errorAPIValidationErrorEnvelope
429Intake rate limit exceededAPIErrorEnvelope
401Missing, expired, or invalid access token.AUTH_REQUIRED
403The token does not carry an accepted role.INSUFFICIENT_ROLE
422More than 100 items.INTAKE_BATCH_TOO_LARGE
429Too many intake calls. Wait for Retry-After seconds, then retry.RATE_LIMIT_EXCEEDED
  • module, tier, and external_reference apply to every item in the batch.
  • Call Get a submission afterward to see which items were accepted.
Request body
{
  "external_reference": "q3-policy-refresh",
  "items": [
    {"filename": "travel-policy.docx", "file_size": 88210,
     "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"},
    {"filename": "expense-policy.pdf", "file_size": 129554, "mime_type": "application/pdf"}
  ]
}

Get a submission

get/v1/intake/submissions/{submission_id}

Returns a submission with its counts and every item, including each item's status, any error_message, and the document_id once the item is linked to a document in the portal.

Access: Bearer token with role client_admin, platform_admin, or integrator_sandbox. About authentication

Parameters

Get a submission parameters
ParameterInTypeDetails
submission_idRequiredPathstringThe id returned when the submission was created.
tenant_idOptionalQuerystring (uuid)Only for platform_admin tokens acting for a client workspace. Leave it out otherwise.

Responses

Get a submission responses
StatusMeaningBody or error code
200Successful ResponseIntakeSubmissionDetailResponse
401Missing, expired, or invalid access tokenAPIErrorEnvelope
403Token does not carry an accepted roleAPIErrorEnvelope
404Submission not found in workspaceAPIErrorEnvelope
422Validation or intake field errorAPIValidationErrorEnvelope
401Missing, expired, or invalid access token.AUTH_REQUIRED
403The token does not carry an accepted role.INSUFFICIENT_ROLE
404No submission with this ID exists in your workspace.INTAKE_SUBMISSION_NOT_FOUND
  • Prefer webhooks for status changes; poll this operation when you need the full item list.

Webhook subscriptions

Ask Review to call your HTTPS endpoint when something changes, such as a document being uploaded, its status changing, or a scorecard being created. Each delivery is signed with HMAC-SHA256 so you can confirm it came from Review. Payloads carry IDs and status, never document text.

List webhook subscriptions

get/v1/webhooks/subscriptions

Returns your workspace's active subscriptions with their URLs and events. Signing secrets are not included.

Access: Bearer token with role client_admin, platform_admin, or integrator_sandbox. About authentication

Responses

List webhook subscriptions responses
StatusMeaningBody or error code
200Successful ResponseWebhookSubscriptionListResponse
401Missing, expired, or invalid access tokenAPIErrorEnvelope
403Token does not carry an accepted roleAPIErrorEnvelope
401Missing, expired, or invalid access token.AUTH_REQUIRED
403The token does not carry an accepted role.INSUFFICIENT_ROLE

Create a webhook subscription

post/v1/webhooks/subscriptions

Registers an HTTPS endpoint and the events it should receive. The response includes the signing secret exactly once. Store it right away; list calls never return it.

Access: Bearer token with role client_admin, platform_admin, or integrator_sandbox. About authentication

Request body WebhookSubscriptionCreate

Create a webhook subscription request body
FieldTypeDetails
urlRequiredstringYour HTTPS endpoint. Fully qualified host; no private or reserved IP addresses.1–2048 characters
eventsRequiredarray of string1 to 20 event names, or * for all events.1–20 items

Responses

Create a webhook subscription responses
StatusMeaningBody or error code
201Successful ResponseWebhookSubscriptionResponse
401Missing, expired, or invalid access tokenAPIErrorEnvelope
403Token does not carry an accepted roleAPIErrorEnvelope
409Webhook subscription limit exceededAPIErrorEnvelope
422Validation or intake field errorAPIValidationErrorEnvelope
401Missing, expired, or invalid access token.AUTH_REQUIRED
403The token does not carry an accepted role.INSUFFICIENT_ROLE
409The workspace already has 10 active subscriptions.WEBHOOK_SUBSCRIPTION_LIMIT_EXCEEDED
422One or more events values are not subscribable.INVALID_WEBHOOK_EVENTS
  • The URL must use https, name a fully qualified host, and must not point at a private or reserved IP address.
  • Subscribable events: document.uploaded, document.status_changed, document.completed, scorecard.created, adjudication.case_created, adjudication.case_resolved, intake.submitted, intake.batch_submitted. Use * to receive all of them.
  • Each workspace can have up to 10 active subscriptions.
Request body
{
  "url": "https://hooks.example.com/querytek-review",
  "events": ["document.status_changed", "scorecard.created"]
}

Deactivate a webhook subscription

delete/v1/webhooks/subscriptions/{subscription_id}

Stops deliveries to a subscription. The subscription is deactivated rather than erased, so its delivery history stays available for review.

Access: Bearer token with role client_admin, platform_admin, or integrator_sandbox. About authentication

Parameters

Deactivate a webhook subscription parameters
ParameterInTypeDetails
subscription_idRequiredPathstringThe id returned when the subscription was created.

Responses

Deactivate a webhook subscription responses
StatusMeaningBody or error code
204Successful Response—
401Missing, expired, or invalid access tokenAPIErrorEnvelope
403Token does not carry an accepted roleAPIErrorEnvelope
404Subscription not foundAPIErrorEnvelope
422Validation or intake field errorAPIValidationErrorEnvelope
401Missing, expired, or invalid access token.AUTH_REQUIRED
403The token does not carry an accepted role.INSUFFICIENT_ROLE
404No active subscription with this ID exists in your workspace.SUBSCRIPTION_NOT_FOUND

List webhook deliveries

get/v1/webhooks/deliveries

Returns recent delivery attempts across your subscriptions, newest first. Use it to confirm your endpoint is receiving events and to diagnose failures.

Access: Bearer token with role client_admin, platform_admin, or integrator_sandbox. About authentication

Parameters

List webhook deliveries parameters
ParameterInTypeDetails
limitOptionalQueryintegerHow many recent deliveries to return.1–200 · default 50

Responses

List webhook deliveries responses
StatusMeaningBody or error code
200Successful ResponseWebhookDeliveryListResponse
401Missing, expired, or invalid access tokenAPIErrorEnvelope
403Token does not carry an accepted roleAPIErrorEnvelope
422Validation or intake field errorAPIValidationErrorEnvelope
401Missing, expired, or invalid access token.AUTH_REQUIRED
403The token does not carry an accepted role.INSUFFICIENT_ROLE
  • Each event is sent as a signed HTTPS POST with up to 3 attempts and an increasing delay between them. A delivery's status is pending, delivered, or failed.
  • To verify a delivery, compute the HMAC-SHA256 hex digest of the raw request body with your subscription secret and compare it with the X-QueryTek-Review-Signature header using a constant-time comparison.
Verify a signature (Python)
import hashlib
import hmac


def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = hmac.new(secret.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header)

System health

Public checks for monitors and go-live scripts. No token is required and no workspace data or secrets are returned.

Health check

get/v1/health

Reports the status of each dependency and an overall status. It always returns HTTP 200, so read the body; use Readiness check for monitors that gate on the HTTP status code.

Access: Public. No token required.

Responses

Health check responses
StatusMeaningBody or error code
200Successful Response—

Readiness check

get/v1/readyz

Returns HTTP 200 only when every dependency check passes (status: healthy), and HTTP 503 when the service is degraded or unhealthy. Point uptime monitors here.

Access: Public. No token required.

Responses

Readiness check responses
StatusMeaningBody or error code
200Successful Response—
503One or more dependencies are degraded or unhealthy.—

Schemas

Every request and response object in the OpenAPI file. Type names in the tables above link here.

IntakeBatchRequest

Body for Submit a batch.

IntakeBatchRequest fields
FieldTypeDetails
moduleOptionalstringor nullOptional review module key applied to every item. See Submit one document.at most 40 characters
tierOptionalstringor nullOptional service tier key applied to every item. See Submit one document.at most 20 characters
external_referenceOptionalstringor nullYour own ID for the whole batch.at most 255 characters
itemsRequiredarray of IntakeItemRequestThe documents to register, 1 to 100 per call.1–100 items

IntakeItemRequest

One document in a batch.

IntakeItemRequest fields
FieldTypeDetails
filenameRequiredstringFile name as it should appear to your team and the reviewer.1–255 characters
file_sizeRequiredintegerFile size in bytes. Items over 50 MB are recorded as failed.greater than 0
mime_typeRequiredstringSame supported types as single intake. Unsupported types are recorded as failed.1–127 characters
item_metadataOptionalobjector nullOptional JSON object stored with the item, with the same limits as single intake.

IntakeItemResponse

One registered document and its intake result.

IntakeItemResponse fields
FieldTypeDetails
idRequiredstring
submission_idRequiredstring
document_idRequiredstringor nullThe portal document this item is linked to, once linked.
filenameRequiredstring
file_sizeRequiredinteger
mime_typeRequiredstring
item_metadataRequiredobjector null
statusRequiredstringaccepted or failed.
error_messageRequiredstringor nullWhy the item failed, when it did.

IntakeSubmissionResponse

A submission and its counts.

IntakeSubmissionResponse fields
FieldTypeDetails
idRequiredstringSubmission ID. Use it with Get a submission.
tenant_idRequiredstringThe workspace that owns the submission.
external_referenceRequiredstringor null
moduleRequiredstringor null
tierRequiredstringor null
item_countRequiredintegerNumber of items received.
accepted_countRequiredintegerItems that passed intake checks.
failed_countRequiredintegerItems rejected for type or size.
statusRequiredstringcompleted, partial_failure, or failed.
created_byRequiredstringSubject ID of the token that made the call.
created_atRequiredstringISO 8601 timestamp.

IntakeSubmitRequest

Body for Submit one document.

IntakeSubmitRequest fields
FieldTypeDetails
filenameRequiredstringFile name as it should appear to your team and the reviewer.1–255 characters
file_sizeRequiredintegerFile size in bytes. Up to 50 MB.greater than 0
mime_typeRequiredstringOne of application/pdf, Word (.docx), Excel (.xlsx), text/plain, text/html, text/xml, or application/xml.1–127 characters
moduleOptionalstringor nullOptional review module key: ai_output, content_risk, plain_language, or education_accessibility. Omit to use your workspace default; other values return 422 INTAKE_INVALID_MODULE.at most 40 characters
tierOptionalstringor nullRetired — omit this field. If sent, the API returns 422 INTAKE_TIER_RETIRED.at most 20 characters
external_referenceOptionalstringor nullYour own ID for this work, such as a ticket or job number. Returned on the submission so you can match it.at most 255 characters
item_metadataOptionalobjector nullOptional JSON object you want stored with the item: up to 50 keys, 10 KB serialized, and 3 levels deep.

WebhookDeliveryListResponse

Recent delivery attempts.

WebhookDeliveryListResponse fields
FieldTypeDetails
deliveriesRequiredarray of WebhookDeliveryResponse
totalRequiredinteger

WebhookDeliveryResponse

One delivery attempt record.

WebhookDeliveryResponse fields
FieldTypeDetails
idRequiredstring
subscription_idRequiredstring
event_typeRequiredstringThe event that triggered this delivery.
payloadRequiredobjectThe JSON body that was sent: event, tenant_id, timestamp, and a data object with IDs and status.
statusRequiredstringpending, delivered, or failed.
attemptsRequiredintegerAttempts made so far, up to 3.
last_attempt_atRequiredstringor null
response_codeRequiredintegeror nullHTTP status your endpoint returned on the last attempt.
error_messageRequiredstringor null
created_atRequiredstring

WebhookSubscriptionCreate

Body for Create a webhook subscription.

WebhookSubscriptionCreate fields
FieldTypeDetails
urlRequiredstringYour HTTPS endpoint. Fully qualified host; no private or reserved IP addresses.1–2048 characters
eventsRequiredarray of string1 to 20 event names, or * for all events.1–20 items

WebhookSubscriptionListResponse

Active subscriptions for your workspace.

WebhookSubscriptionListResponse fields
FieldTypeDetails
subscriptionsRequiredarray of WebhookSubscriptionResponse
totalRequiredinteger

WebhookSubscriptionResponse

A webhook subscription.

WebhookSubscriptionResponse fields
FieldTypeDetails
idRequiredstring
tenant_idRequiredstring
urlRequiredstring
eventsRequiredarray of string
is_activeRequiredbooleanfalse after the subscription is deactivated.
created_byRequiredstring
created_atRequiredstring
secretOptionalstringor nullSigning secret. Returned only in the create response; store it securely.

APIErrorEnvelope

Error body returned by every failed call. See Errors above.

APIErrorEnvelope fields
FieldTypeDetails
errorRequiredobjectcode, message, request_id, and optional details. Branch on code; include request_id when contacting support.

APIValidationErrorEnvelope

Validation and intake field errors use the same envelope with a details array when applicable.

APIValidationErrorEnvelope fields
FieldTypeDetails
errorRequiredobjectSame envelope shape with code VALIDATION_ERROR or an intake-specific code; field issues appear in details.