Skip to main content

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."
      }
    }
  }
}