OpenAPI — pretty JSON
{
"openapi": "3.1.0",
"info": {
"title": "QueryTek Review — Integrator API (subset)",
"version": "0.2.0",
"description": "Curated OpenAPI subset for embedded evaluation intake and webhook subscriptions. Not the full portal API. Production hosts do not expose Swagger UI; use this file and the integration guides at /developers. Optional Idempotency-Key also applies to portal writes POST /v1/documents, /v1/batches, and their pay/withdraw routes (201 for uploads, 200 for pay/withdraw). Payment confirm/sync/invite are not covered."
},
"paths": {
"/v1/intake/submit": {
"post": {
"tags": [
"intake"
],
"summary": "Submit Single",
"description": "Submit a single document via API intake.",
"operationId": "submit_single_v1_intake_submit_post",
"security": [
{
"HTTPBearer": []
}
],
"parameters": [
{
"name": "tenant_id",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"title": "Tenant Id"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"description": "Optional. Same key + same body replays the stored 201 (intake and uploads) or 200 (pay/withdraw). Same key + different body returns 409 IDEMPOTENCY_KEY_MISMATCH. Scoped to tenant + caller + route. Expires after API_IDEMPOTENCY_TTL_HOURS (default 24).",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntakeSubmitRequest"
}
}
}
},
"responses": {
"201": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntakeSubmissionResponse"
}
}
}
},
"401": {
"description": "Missing, expired, or invalid access token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIErrorEnvelope"
}
}
}
},
"403": {
"description": "Token does not carry an accepted role",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIErrorEnvelope"
}
}
}
},
"409": {
"description": "Idempotency key mismatch or in progress",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIErrorEnvelope"
}
}
}
},
"422": {
"description": "Validation or intake field error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIValidationErrorEnvelope"
}
}
}
},
"429": {
"description": "Intake rate limit exceeded",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIErrorEnvelope"
}
}
}
}
}
}
},
"/v1/intake/batch": {
"post": {
"tags": [
"intake"
],
"summary": "Submit Batch",
"description": "Submit a batch of documents via API intake.",
"operationId": "submit_batch_v1_intake_batch_post",
"security": [
{
"HTTPBearer": []
}
],
"parameters": [
{
"name": "tenant_id",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"title": "Tenant Id"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"description": "Optional. Same key + same body replays the stored 201 (intake and uploads) or 200 (pay/withdraw). Same key + different body returns 409 IDEMPOTENCY_KEY_MISMATCH. Scoped to tenant + caller + route. Expires after API_IDEMPOTENCY_TTL_HOURS (default 24).",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntakeBatchRequest"
}
}
}
},
"responses": {
"201": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntakeSubmissionResponse"
}
}
}
},
"401": {
"description": "Missing, expired, or invalid access token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIErrorEnvelope"
}
}
}
},
"403": {
"description": "Token does not carry an accepted role",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIErrorEnvelope"
}
}
}
},
"409": {
"description": "Idempotency key mismatch or in progress",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIErrorEnvelope"
}
}
}
},
"422": {
"description": "Validation or intake field error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIValidationErrorEnvelope"
}
}
}
},
"429": {
"description": "Intake rate limit exceeded",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIErrorEnvelope"
}
}
}
}
}
}
},
"/v1/intake/submissions/{submission_id}": {
"get": {
"tags": [
"intake"
],
"summary": "Get Submission",
"description": "Get submission status and items.",
"operationId": "get_submission_v1_intake_submissions__submission_id__get",
"security": [
{
"HTTPBearer": []
}
],
"parameters": [
{
"name": "submission_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Submission Id"
}
},
{
"name": "tenant_id",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
],
"title": "Tenant Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntakeSubmissionDetailResponse"
}
}
}
},
"401": {
"description": "Missing, expired, or invalid access token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIErrorEnvelope"
}
}
}
},
"403": {
"description": "Token does not carry an accepted role",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIErrorEnvelope"
}
}
}
},
"404": {
"description": "Submission not found in workspace",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIErrorEnvelope"
}
}
}
},
"422": {
"description": "Validation or intake field error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIValidationErrorEnvelope"
}
}
}
}
}
}
},
"/v1/webhooks/subscriptions": {
"post": {
"tags": [
"webhook-subscriptions"
],
"summary": "Create Subscription",
"description": "Create a new webhook subscription for the tenant.",
"operationId": "create_subscription_v1_webhooks_subscriptions_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookSubscriptionCreate"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookSubscriptionResponse"
}
}
}
},
"401": {
"description": "Missing, expired, or invalid access token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIErrorEnvelope"
}
}
}
},
"403": {
"description": "Token does not carry an accepted role",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIErrorEnvelope"
}
}
}
},
"409": {
"description": "Webhook subscription limit exceeded",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIErrorEnvelope"
}
}
}
},
"422": {
"description": "Validation or intake field error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIValidationErrorEnvelope"
}
}
}
}
},
"security": [
{
"HTTPBearer": []
}
]
},
"get": {
"tags": [
"webhook-subscriptions"
],
"summary": "List Subscriptions",
"description": "List all webhook subscriptions for the tenant.",
"operationId": "list_subscriptions_v1_webhooks_subscriptions_get",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookSubscriptionListResponse"
}
}
}
},
"401": {
"description": "Missing, expired, or invalid access token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIErrorEnvelope"
}
}
}
},
"403": {
"description": "Token does not carry an accepted role",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIErrorEnvelope"
}
}
}
}
},
"security": [
{
"HTTPBearer": []
}
]
}
},
"/v1/webhooks/subscriptions/{subscription_id}": {
"delete": {
"tags": [
"webhook-subscriptions"
],
"summary": "Delete Subscription",
"description": "Deactivate a webhook subscription.",
"operationId": "delete_subscription_v1_webhooks_subscriptions__subscription_id__delete",
"security": [
{
"HTTPBearer": []
}
],
"parameters": [
{
"name": "subscription_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Subscription Id"
}
}
],
"responses": {
"204": {
"description": "Successful Response"
},
"401": {
"description": "Missing, expired, or invalid access token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIErrorEnvelope"
}
}
}
},
"403": {
"description": "Token does not carry an accepted role",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIErrorEnvelope"
}
}
}
},
"404": {
"description": "Subscription not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIErrorEnvelope"
}
}
}
},
"422": {
"description": "Validation or intake field error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIValidationErrorEnvelope"
}
}
}
}
}
}
},
"/v1/webhooks/deliveries": {
"get": {
"tags": [
"webhook-subscriptions"
],
"summary": "List Deliveries",
"description": "List recent webhook deliveries for the tenant's subscriptions.",
"operationId": "list_deliveries_v1_webhooks_deliveries_get",
"security": [
{
"HTTPBearer": []
}
],
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 200,
"minimum": 1,
"default": 50,
"title": "Limit"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookDeliveryListResponse"
}
}
}
},
"401": {
"description": "Missing, expired, or invalid access token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIErrorEnvelope"
}
}
}
},
"403": {
"description": "Token does not carry an accepted role",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIErrorEnvelope"
}
}
}
},
"422": {
"description": "Validation or intake field error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/APIValidationErrorEnvelope"
}
}
}
}
}
}
},
"/v1/health": {
"get": {
"tags": [
"system"
],
"summary": "Health Check",
"description": "Composite liveness/readiness check.\n\nReturns individual dependency statuses and an overall status.\nNo auth required. No secrets exposed.\n\nLegacy: always HTTP 200 with ``status`` in the body. External monitors MUST\ncut over to ``/v1/readyz`` for HTTP-level readiness gating.",
"operationId": "health_check_v1_health_get",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
}
}
},
"/v1/readyz": {
"get": {
"tags": [
"system"
],
"summary": "Readyz",
"description": "Readiness probe.\n\nReturns HTTP 200 only when all dependency checks pass (``status: healthy``).\nReturns HTTP 503 when degraded or unhealthy.",
"operationId": "readyz_v1_readyz_get",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
}
}
}
},
"components": {
"schemas": {
"IntakeBatchRequest": {
"properties": {
"module": {
"anyOf": [
{
"type": "string",
"maxLength": 40
},
{
"type": "null"
}
],
"title": "Module"
},
"tier": {
"anyOf": [
{
"type": "string",
"maxLength": 20
},
{
"type": "null"
}
],
"title": "Tier"
},
"external_reference": {
"anyOf": [
{
"type": "string",
"maxLength": 255
},
{
"type": "null"
}
],
"title": "External Reference"
},
"items": {
"items": {
"$ref": "#/components/schemas/IntakeItemRequest"
},
"type": "array",
"maxItems": 100,
"minItems": 1,
"title": "Items"
}
},
"type": "object",
"required": [
"items"
],
"title": "IntakeBatchRequest",
"description": "Multi-item batch intake submission."
},
"IntakeItemRequest": {
"properties": {
"filename": {
"type": "string",
"maxLength": 255,
"minLength": 1,
"title": "Filename"
},
"file_size": {
"type": "integer",
"exclusiveMinimum": 0,
"title": "File Size"
},
"mime_type": {
"type": "string",
"maxLength": 127,
"minLength": 1,
"title": "Mime Type"
},
"item_metadata": {
"anyOf": [
{
"type": "object"
},
{
"type": "null"
}
],
"title": "Item Metadata"
}
},
"type": "object",
"required": [
"filename",
"file_size",
"mime_type"
],
"title": "IntakeItemRequest"
},
"IntakeItemResponse": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"submission_id": {
"type": "string",
"title": "Submission Id"
},
"document_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Document Id"
},
"filename": {
"type": "string",
"title": "Filename"
},
"file_size": {
"type": "integer",
"title": "File Size"
},
"mime_type": {
"type": "string",
"title": "Mime Type"
},
"item_metadata": {
"anyOf": [
{
"type": "object"
},
{
"type": "null"
}
],
"title": "Item Metadata"
},
"status": {
"type": "string",
"title": "Status"
},
"error_message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error Message"
}
},
"type": "object",
"required": [
"id",
"submission_id",
"document_id",
"filename",
"file_size",
"mime_type",
"item_metadata",
"status",
"error_message"
],
"title": "IntakeItemResponse"
},
"IntakeSubmissionDetailResponse": {
"properties": {
"submission": {
"$ref": "#/components/schemas/IntakeSubmissionResponse"
},
"items": {
"items": {
"$ref": "#/components/schemas/IntakeItemResponse"
},
"type": "array",
"title": "Items"
}
},
"type": "object",
"required": [
"submission",
"items"
],
"title": "IntakeSubmissionDetailResponse"
},
"IntakeSubmissionResponse": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"tenant_id": {
"type": "string",
"title": "Tenant Id"
},
"external_reference": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "External Reference"
},
"module": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Module"
},
"tier": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Tier"
},
"item_count": {
"type": "integer",
"title": "Item Count"
},
"accepted_count": {
"type": "integer",
"title": "Accepted Count"
},
"failed_count": {
"type": "integer",
"title": "Failed Count"
},
"status": {
"type": "string",
"title": "Status"
},
"created_by": {
"type": "string",
"title": "Created By"
},
"created_at": {
"type": "string",
"title": "Created At"
}
},
"type": "object",
"required": [
"id",
"tenant_id",
"external_reference",
"module",
"tier",
"item_count",
"accepted_count",
"failed_count",
"status",
"created_by",
"created_at"
],
"title": "IntakeSubmissionResponse"
},
"IntakeSubmitRequest": {
"properties": {
"filename": {
"type": "string",
"maxLength": 255,
"minLength": 1,
"title": "Filename"
},
"file_size": {
"type": "integer",
"exclusiveMinimum": 0,
"title": "File Size"
},
"mime_type": {
"type": "string",
"maxLength": 127,
"minLength": 1,
"title": "Mime Type"
},
"module": {
"anyOf": [
{
"type": "string",
"maxLength": 40
},
{
"type": "null"
}
],
"title": "Module"
},
"tier": {
"anyOf": [
{
"type": "string",
"maxLength": 20
},
{
"type": "null"
}
],
"title": "Tier"
},
"external_reference": {
"anyOf": [
{
"type": "string",
"maxLength": 255
},
{
"type": "null"
}
],
"title": "External Reference"
},
"item_metadata": {
"anyOf": [
{
"type": "object"
},
{
"type": "null"
}
],
"title": "Item Metadata"
}
},
"type": "object",
"required": [
"filename",
"file_size",
"mime_type"
],
"title": "IntakeSubmitRequest",
"description": "Single-document intake submission."
},
"WebhookDeliveryListResponse": {
"properties": {
"deliveries": {
"items": {
"$ref": "#/components/schemas/WebhookDeliveryResponse"
},
"type": "array",
"title": "Deliveries"
},
"total": {
"type": "integer",
"title": "Total"
}
},
"type": "object",
"required": [
"deliveries",
"total"
],
"title": "WebhookDeliveryListResponse"
},
"WebhookDeliveryResponse": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"subscription_id": {
"type": "string",
"title": "Subscription Id"
},
"event_type": {
"type": "string",
"title": "Event Type"
},
"payload": {
"type": "object",
"title": "Payload"
},
"status": {
"type": "string",
"title": "Status"
},
"attempts": {
"type": "integer",
"title": "Attempts"
},
"last_attempt_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Attempt At"
},
"response_code": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Response Code"
},
"error_message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error Message"
},
"created_at": {
"type": "string",
"title": "Created At"
}
},
"type": "object",
"required": [
"id",
"subscription_id",
"event_type",
"payload",
"status",
"attempts",
"last_attempt_at",
"response_code",
"error_message",
"created_at"
],
"title": "WebhookDeliveryResponse"
},
"WebhookSubscriptionCreate": {
"properties": {
"url": {
"type": "string",
"maxLength": 2048,
"minLength": 1,
"title": "Url"
},
"events": {
"items": {
"type": "string"
},
"type": "array",
"maxItems": 20,
"minItems": 1,
"title": "Events"
}
},
"type": "object",
"required": [
"url",
"events"
],
"title": "WebhookSubscriptionCreate"
},
"WebhookSubscriptionListResponse": {
"properties": {
"subscriptions": {
"items": {
"$ref": "#/components/schemas/WebhookSubscriptionResponse"
},
"type": "array",
"title": "Subscriptions"
},
"total": {
"type": "integer",
"title": "Total"
}
},
"type": "object",
"required": [
"subscriptions",
"total"
],
"title": "WebhookSubscriptionListResponse"
},
"WebhookSubscriptionResponse": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"tenant_id": {
"type": "string",
"title": "Tenant Id"
},
"url": {
"type": "string",
"title": "Url"
},
"events": {
"items": {
"type": "string"
},
"type": "array",
"title": "Events"
},
"is_active": {
"type": "boolean",
"title": "Is Active"
},
"created_by": {
"type": "string",
"title": "Created By"
},
"created_at": {
"type": "string",
"title": "Created At"
},
"secret": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Secret"
}
},
"type": "object",
"required": [
"id",
"tenant_id",
"url",
"events",
"is_active",
"created_by",
"created_at"
],
"title": "WebhookSubscriptionResponse"
},
"APIErrorEnvelope": {
"title": "APIErrorEnvelope",
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"request_id"
],
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable code (e.g. AUTH_REQUIRED).",
"example": "AUTH_REQUIRED"
},
"message": {
"type": "string",
"description": "Safe human-facing text; no stack traces or secrets."
},
"request_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Request correlation id (matches X-Request-ID when set)."
},
"details": {
"description": "Optional structured context (validation list, field errors, etc.)."
}
}
}
},
"example": {
"error": {
"code": "TENANT_NOT_FOUND",
"message": "TENANT_NOT_FOUND",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}
},
"APIValidationErrorEnvelope": {
"title": "APIValidationErrorEnvelope",
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"request_id",
"details"
],
"properties": {
"code": {
"type": "string",
"example": "VALIDATION_ERROR"
},
"message": {
"type": "string",
"example": "Request validation failed."
},
"request_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"details": {
"type": "array",
"items": {
"type": "object"
},
"description": "Sanitized validation errors."
}
}
}
}
}
},
"securitySchemes": {
"HTTPBearer": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT",
"description": "Access token from the QueryTek identity provider (OpenID Connect). Send Authorization: Bearer <access_token> on protected calls."
}
}
}
}