OpenAPI — pretty JSON
{
"openapi": "3.1.0",
"info": {
"title": "QueryTek Review — Integrator API (subset)",
"version": "0.1.0",
"description": "Curated OpenAPI subset for embedded evaluation intake and webhook subscriptions (P3-004 / P6-017). Not the full portal API. Production hosts do not expose Swagger UI; use this file + Integrator guides."
},
"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": [
{
"OAuth2PasswordBearer": []
}
],
"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. 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"
}
}
}
},
"409": {
"description": "Idempotency key mismatch or in progress",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReviewApiErrorEnvelope"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/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": [
{
"OAuth2PasswordBearer": []
}
],
"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. 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"
}
}
}
},
"409": {
"description": "Idempotency key mismatch or in progress",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReviewApiErrorEnvelope"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/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": [
{
"OAuth2PasswordBearer": []
}
],
"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"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/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"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
},
"security": [
{
"OAuth2PasswordBearer": []
}
]
},
"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"
}
}
}
}
},
"security": [
{
"OAuth2PasswordBearer": []
}
]
}
},
"/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": [
{
"OAuth2PasswordBearer": []
}
],
"parameters": [
{
"name": "subscription_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Subscription Id"
}
}
],
"responses": {
"204": {
"description": "Successful Response"
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/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": [
{
"OAuth2PasswordBearer": []
}
],
"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"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/health": {
"get": {
"tags": [
"system"
],
"summary": "Health Check",
"description": "Composite liveness/readiness check (SPEC-013).\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 (SPEC-037 / P5-001).\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": {
"ReviewApiErrorEnvelope": {
"type": "object",
"title": "ReviewApiErrorEnvelope",
"required": [
"error",
"request_id"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "Stable code such as IDEMPOTENCY_KEY_MISMATCH"
},
"message": {
"type": "string"
},
"details": {
"type": "object"
}
}
},
"request_id": {
"type": "string"
}
}
},
"HTTPValidationError": {
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
},
"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."
},
"ValidationError": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"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"
}
},
"securitySchemes": {
"OAuth2PasswordBearer": {
"type": "oauth2",
"flows": {
"password": {
"scopes": {},
"tokenUrl": "token"
}
}
}
}
}
}