{ "openapi": "3.1.0", "info": { "title": "QueryTek Review \u2014 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.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.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" } } } } } }