openapi.json

{
  "components": {
    "schemas": {
      "ABAnalysisResult": {
        "description": "Outcome of comparing two experiment variants on one metric — Step 5.7.\n\nProduced by ``rag_config.eval.analyze_ab_experiment``.  ``lift`` is the\n*relative* change of B over A (``(mean_b - mean_a) / mean_a``); ``diff`` is\nthe absolute difference, and ``ci_lower`` / ``ci_upper`` bound that difference\nat ``confidence`` (a normal-approximation Welch interval).  ``significant`` is\n``True`` when the interval excludes 0 (equivalently ``p_value < 1 - confidence``).\n``status`` is ``analyzed`` or ``insufficient_data`` (either side below\n``min_samples``), in which case the statistics are ``0`` / not meaningful.\n\nAttributes:\n    experiment: The experiment id this verdict is for.\n    metric: The compared metric (e.g. ``\"satisfaction\"`` / ``\"latency_ms\"``).\n    variant_a: Control variant name.\n    variant_b: Candidate variant name.\n    status: ``analyzed`` or ``insufficient_data``.\n    n_a / n_b: Sample counts per variant.\n    mean_a / mean_b: Per-variant means.\n    diff: ``mean_b - mean_a`` (absolute).\n    lift: ``diff / mean_a`` (relative; ``0`` when ``mean_a == 0``).\n    ci_lower / ci_upper: Confidence interval on ``diff``.\n    p_value: Two-sided p-value (normal approximation).\n    confidence: The interval's confidence level (e.g. ``0.95``).\n    significant: Whether the CI excludes 0 at ``confidence``.",
        "properties": {
          "ci_lower": {
            "default": 0.0,
            "title": "Ci Lower",
            "type": "number"
          },
          "ci_upper": {
            "default": 0.0,
            "title": "Ci Upper",
            "type": "number"
          },
          "confidence": {
            "default": 0.95,
            "title": "Confidence",
            "type": "number"
          },
          "diff": {
            "default": 0.0,
            "title": "Diff",
            "type": "number"
          },
          "experiment": {
            "default": "",
            "title": "Experiment",
            "type": "string"
          },
          "lift": {
            "default": 0.0,
            "title": "Lift",
            "type": "number"
          },
          "mean_a": {
            "default": 0.0,
            "title": "Mean A",
            "type": "number"
          },
          "mean_b": {
            "default": 0.0,
            "title": "Mean B",
            "type": "number"
          },
          "metric": {
            "default": "",
            "title": "Metric",
            "type": "string"
          },
          "n_a": {
            "default": 0,
            "title": "N A",
            "type": "integer"
          },
          "n_b": {
            "default": 0,
            "title": "N B",
            "type": "integer"
          },
          "p_value": {
            "default": 1.0,
            "title": "P Value",
            "type": "number"
          },
          "significant": {
            "default": false,
            "title": "Significant",
            "type": "boolean"
          },
          "status": {
            "default": "insufficient_data",
            "title": "Status",
            "type": "string"
          },
          "variant_a": {
            "default": "control",
            "title": "Variant A",
            "type": "string"
          },
          "variant_b": {
            "default": "candidate",
            "title": "Variant B",
            "type": "string"
          }
        },
        "title": "ABAnalysisResult",
        "type": "object"
      },
      "AgentRequest": {
        "description": "``POST /v1/agent`` body / gRPC ``ConverseRequest`` payload.\n\nThe budget fields map one-for-one onto :class:`~rag_core.types.Budget`\ncaps; ``None`` means uncapped on that dimension.  ``max_steps`` is the\nconfig-level ceiling (defence-in-depth, distinct from ``budget_iter``\nwhich is operator-set per request).",
        "properties": {
          "budget_dollars": {
            "anyOf": [
              {
                "exclusiveMinimum": 0.0,
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Budget Dollars"
          },
          "budget_iter": {
            "anyOf": [
              {
                "minimum": 1.0,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Budget Iter"
          },
          "budget_tokens": {
            "anyOf": [
              {
                "minimum": 1.0,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Budget Tokens"
          },
          "budget_wall_ms": {
            "anyOf": [
              {
                "minimum": 1.0,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Budget Wall Ms"
          },
          "corpus_ids": {
            "items": {
              "type": "string"
            },
            "title": "Corpus Ids",
            "type": "array"
          },
          "goal": {
            "description": "The task / question for the agent.",
            "minLength": 1,
            "title": "Goal",
            "type": "string"
          },
          "max_steps": {
            "default": 6,
            "maximum": 50.0,
            "minimum": 1.0,
            "title": "Max Steps",
            "type": "integer"
          },
          "principal_id": {
            "title": "Principal Id",
            "type": "string"
          },
          "request_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Request Id"
          },
          "resume_run_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Resume a previously checkpointed run instead of starting fresh.",
            "title": "Resume Run Id"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          },
          "top_k": {
            "default": 8,
            "maximum": 100.0,
            "minimum": 1.0,
            "title": "Top K",
            "type": "integer"
          }
        },
        "required": [
          "tenant_id",
          "principal_id",
          "goal"
        ],
        "title": "AgentRequest",
        "type": "object"
      },
      "Answer": {
        "description": "LLM-generated natural-language response (Step 3.1, ``generate=True``).\n\nEmbedded inside :class:`QueryResponse.answer` when the caller\nrequested generation.  ``citations`` link the generated text to\nspecific chunks in the packed context — built by string-matching\ncitation markers in the LLM output, with the packer's chunk\norder as the index.\n\nSee [reference/gateway.md](../../../../docs/reference/gateway.md#answer-generation)\nfor the citation format the prompt asks the LLM to emit.",
        "properties": {
          "citations": {
            "items": {
              "$ref": "#/components/schemas/Citation"
            },
            "title": "Citations",
            "type": "array"
          },
          "finish_reason": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Finish Reason"
          },
          "guard": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/GuardResult"
              },
              {
                "type": "null"
              }
            ]
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "input_tokens": {
            "default": 0,
            "title": "Input Tokens",
            "type": "integer"
          },
          "metadata": {
            "additionalProperties": true,
            "title": "Metadata",
            "type": "object"
          },
          "model": {
            "title": "Model",
            "type": "string"
          },
          "output_tokens": {
            "default": 0,
            "title": "Output Tokens",
            "type": "integer"
          },
          "text": {
            "title": "Text",
            "type": "string"
          }
        },
        "required": [
          "text",
          "model"
        ],
        "title": "Answer",
        "type": "object"
      },
      "AuditEvent": {
        "description": "Immutable record of a security-relevant or compliance-relevant action.\n\nWritten by every pipeline stage that touches tenant data.  The hash-chain\nverification (Step 0.7c) links consecutive events to detect tampering.",
        "properties": {
          "action": {
            "title": "Action",
            "type": "string"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "metadata": {
            "additionalProperties": true,
            "title": "Metadata",
            "type": "object"
          },
          "outcome": {
            "$ref": "#/components/schemas/AuditOutcome"
          },
          "principal_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Principal Id"
          },
          "resource": {
            "title": "Resource",
            "type": "string"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          },
          "timestamp": {
            "format": "date-time",
            "title": "Timestamp",
            "type": "string"
          },
          "trace_context": {
            "$ref": "#/components/schemas/TraceContext"
          }
        },
        "required": [
          "tenant_id",
          "action",
          "resource",
          "outcome",
          "trace_context"
        ],
        "title": "AuditEvent",
        "type": "object"
      },
      "AuditExport": {
        "description": "A signed, point-in-time WORM export of the audit log (Step 6.6b).\n\nA self-verifying bundle: ``content_hash`` is the SHA-256 over the canonical\nserialisation of ``events`` (pins the exact set + order), and ``signature``\nis the HMAC over that hash (authenticity).  An offline verifier recomputes\n``content_hash`` from ``events`` and re-checks the HMAC, so any add / remove /\nedit is detected.  ``chain_verified`` attests the *source* store's whole-log\nhash chain was intact at export time.  ``tenant_id`` is set for a\ntenant-scoped export (the HTTP path) and ``None`` for a whole-log export.\nThe bundle is the artifact an operator writes to immutable storage\n(e.g. S3 Object Lock).",
        "properties": {
          "chain_verified": {
            "default": true,
            "title": "Chain Verified",
            "type": "boolean"
          },
          "content_hash": {
            "default": "",
            "title": "Content Hash",
            "type": "string"
          },
          "count": {
            "default": 0,
            "title": "Count",
            "type": "integer"
          },
          "events": {
            "items": {
              "$ref": "#/components/schemas/AuditEvent"
            },
            "title": "Events",
            "type": "array"
          },
          "exported_at": {
            "format": "date-time",
            "title": "Exported At",
            "type": "string"
          },
          "schema_version": {
            "default": "audit-export-v1",
            "title": "Schema Version",
            "type": "string"
          },
          "signature": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/AuditExportSignature"
              },
              {
                "type": "null"
              }
            ]
          },
          "tenant_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Tenant Id"
          }
        },
        "title": "AuditExport",
        "type": "object"
      },
      "AuditExportSignature": {
        "description": "Detached HMAC signature over an :class:`AuditExport` (Step 6.6b).\n\nMirrors :class:`ProvenanceSignature` — HMAC-SHA256 over\n``f\"{timestamp}.{content_hash}\"`` — so the WORM export reuses one signing\nmodel across the platform.  ``timestamp`` (unix seconds) is bound into the\ndigest; ``key_id`` is an opaque label for key-rotation bookkeeping.",
        "properties": {
          "algorithm": {
            "default": "HMAC-SHA256",
            "title": "Algorithm",
            "type": "string"
          },
          "key_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Key Id"
          },
          "timestamp": {
            "default": 0,
            "title": "Timestamp",
            "type": "integer"
          },
          "value": {
            "default": "",
            "title": "Value",
            "type": "string"
          }
        },
        "title": "AuditExportSignature",
        "type": "object"
      },
      "AuditListResponse": {
        "description": "``GET /v1/audit`` response — the tenant's audit events (Step 6.6).\n\nReturns the calling tenant's :class:`AuditEvent` records **newest-first**\n(only its own — never another tenant's), bounded by the ``limit`` query\nparam.  ``chain_verified`` reports whether the **whole-log** SHA-256 hash\nchain still validates at read time, so a consumer sees in one call both the\nevents and that the underlying log is tamper-free.  ``returned`` is the page\nsize; ``total`` is how many events the tenant has before the limit.",
        "properties": {
          "chain_verified": {
            "default": true,
            "title": "Chain Verified",
            "type": "boolean"
          },
          "events": {
            "items": {
              "$ref": "#/components/schemas/AuditEvent"
            },
            "title": "Events",
            "type": "array"
          },
          "returned": {
            "default": 0,
            "title": "Returned",
            "type": "integer"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          },
          "total": {
            "default": 0,
            "title": "Total",
            "type": "integer"
          }
        },
        "required": [
          "tenant_id"
        ],
        "title": "AuditListResponse",
        "type": "object"
      },
      "AuditOutcome": {
        "enum": [
          "allowed",
          "denied",
          "error"
        ],
        "title": "AuditOutcome",
        "type": "string"
      },
      "AuditVerifyResponse": {
        "description": "``GET /v1/audit/verify`` response — whole-log hash-chain integrity (Step 6.6).\n\nThe hash chain links **all** events (across tenants) into one tamper-evident\nsequence, so verification is inherently whole-log: ``ok`` is True when every\nlink matches its expected SHA-256, False if any event or stored hash was\naltered.  ``event_count`` is the total number of events verified.",
        "properties": {
          "event_count": {
            "default": 0,
            "title": "Event Count",
            "type": "integer"
          },
          "ok": {
            "title": "Ok",
            "type": "boolean"
          }
        },
        "required": [
          "ok"
        ],
        "title": "AuditVerifyResponse",
        "type": "object"
      },
      "BillingUsageResponse": {
        "description": "One tenant's accrued metered usage for the current billing period (Step 7.9).\n\nMirrors :class:`~rag_observability.billing.UsageSnapshot`.  Per-tenant — the\ntenant comes from the ``tenant_id`` query param or the ``X-Tenant-Id`` header.\n``usage`` maps each billing dimension (queries / docs_ingested / storage_gb /\nreranker_calls / llm_tokens) to its accrued quantity; empty when no usage meter\nis wired.  Read-only — metering never mutates a request.",
        "properties": {
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          },
          "usage": {
            "additionalProperties": {
              "type": "number"
            },
            "title": "Usage",
            "type": "object"
          }
        },
        "required": [
          "tenant_id"
        ],
        "title": "BillingUsageResponse",
        "type": "object"
      },
      "BlobRef": {
        "description": "Reference to a blob stored in the ``Storage`` SPI rather than inline.\n\nUsed by chunks whose text exceeds the inline-storage threshold (see\nADR-0007 tiered storage).  Callers must hydrate via ``Storage.get(uri)``\nonly when the text is actually needed.",
        "properties": {
          "content_type": {
            "default": "text/plain; charset=utf-8",
            "title": "Content Type",
            "type": "string"
          },
          "sha256": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Sha256"
          },
          "size_bytes": {
            "title": "Size Bytes",
            "type": "integer"
          },
          "uri": {
            "title": "Uri",
            "type": "string"
          }
        },
        "required": [
          "uri",
          "size_bytes"
        ],
        "title": "BlobRef",
        "type": "object"
      },
      "Body_ingest_document_v1_ingest_document_post": {
        "properties": {
          "corpus_id": {
            "title": "Corpus Id",
            "type": "string"
          },
          "file": {
            "contentMediaType": "application/octet-stream",
            "title": "File",
            "type": "string"
          },
          "principal_id": {
            "default": "gateway-anon",
            "title": "Principal Id",
            "type": "string"
          },
          "source_uri": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Source Uri"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          }
        },
        "required": [
          "tenant_id",
          "corpus_id",
          "file"
        ],
        "title": "Body_ingest_document_v1_ingest_document_post",
        "type": "object"
      },
      "BreakerActionResponse": {
        "description": "Result of an operator breaker action (force-close).",
        "properties": {
          "breaker": {
            "$ref": "#/components/schemas/BreakerSnapshot"
          },
          "forced_closed": {
            "title": "Forced Closed",
            "type": "boolean"
          }
        },
        "required": [
          "breaker",
          "forced_closed"
        ],
        "title": "BreakerActionResponse",
        "type": "object"
      },
      "BreakerSnapshot": {
        "description": "Frozen point-in-time view of one circuit breaker (Step 4.4).\n\nProduced by :meth:`~rag_breaker.breaker.CircuitBreaker.snapshot`; surfaced by\nthe gateway status API (``GET /v1/status/breakers``) and the operator\nconsole.  Carries only operational counters — no tenant data or query text —\nso it is safe to expose on the unauthenticated status surface.\n\n``failure_count`` is the current consecutive-failure streak (meaningful only\nwhile CLOSED).  ``opened_total`` is the lifetime trip count (how many times\nthis backend has gone OPEN).  ``seconds_until_retry`` is how long until the\nOPEN breaker admits its next trial call (``None`` unless OPEN).",
        "properties": {
          "failure_count": {
            "default": 0,
            "title": "Failure Count",
            "type": "integer"
          },
          "failure_threshold": {
            "default": 0,
            "title": "Failure Threshold",
            "type": "integer"
          },
          "name": {
            "title": "Name",
            "type": "string"
          },
          "opened_total": {
            "default": 0,
            "title": "Opened Total",
            "type": "integer"
          },
          "reset_timeout_s": {
            "default": 0.0,
            "title": "Reset Timeout S",
            "type": "number"
          },
          "seconds_until_retry": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Seconds Until Retry"
          },
          "state": {
            "$ref": "#/components/schemas/CircuitState"
          }
        },
        "required": [
          "name",
          "state"
        ],
        "title": "BreakerSnapshot",
        "type": "object"
      },
      "BreakersStatusResponse": {
        "description": "Snapshot of every per-backend circuit breaker (Step 4.4).\n\n``breakers`` reuses the domain :class:`~rag_core.types.BreakerSnapshot` (the\nsnapshot *is* the data — operational counters only, no tenant rows), ordered\nby backend name.  Empty when no breaker registry is wired (the plain\n``build_app`` default).",
        "properties": {
          "breakers": {
            "items": {
              "$ref": "#/components/schemas/BreakerSnapshot"
            },
            "title": "Breakers",
            "type": "array"
          },
          "total": {
            "title": "Total",
            "type": "integer"
          }
        },
        "required": [
          "breakers",
          "total"
        ],
        "title": "BreakersStatusResponse",
        "type": "object"
      },
      "ChatCompletionChoice": {
        "description": "One choice in a non-streaming completion.",
        "properties": {
          "finish_reason": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": "stop",
            "title": "Finish Reason"
          },
          "index": {
            "default": 0,
            "title": "Index",
            "type": "integer"
          },
          "message": {
            "$ref": "#/components/schemas/ChatCompletionResponseMessage"
          }
        },
        "required": [
          "message"
        ],
        "title": "ChatCompletionChoice",
        "type": "object"
      },
      "ChatCompletionRequest": {
        "description": "``POST /v1/chat/completions`` body (OpenAI-compatible + ``rag`` ext).\n\nStandard OpenAI fields are honoured where they map onto the LLM SPI\n(``messages`` / ``temperature`` / ``max_tokens`` / ``stop`` /\n``stream``).  ``n > 1`` is rejected (the gateway returns a single\nchoice).  Unsupported sampling knobs (``top_p`` etc.) are accepted and\nignored so clients that always send them don't break.",
        "properties": {
          "max_tokens": {
            "default": 1024,
            "maximum": 32000.0,
            "minimum": 1.0,
            "title": "Max Tokens",
            "type": "integer"
          },
          "messages": {
            "description": "Conversation so far.  Retrieval runs over the last user turn.",
            "items": {
              "$ref": "#/components/schemas/ChatMessage"
            },
            "minItems": 1,
            "title": "Messages",
            "type": "array"
          },
          "model": {
            "default": "rag-gateway",
            "description": "Informational — the wired LLM's model id is reported in the response.",
            "title": "Model",
            "type": "string"
          },
          "n": {
            "default": 1,
            "description": "Only a single choice is supported.",
            "maximum": 1.0,
            "minimum": 1.0,
            "title": "N",
            "type": "integer"
          },
          "rag": {
            "$ref": "#/components/schemas/RagOptions",
            "description": "Retrieval pre-fetch controls (non-standard extension)."
          },
          "stop": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "description": "Up to 4 stop sequences forwarded to the LLM.",
            "title": "Stop"
          },
          "stream": {
            "default": false,
            "description": "When true, responses are streamed as SSE chat.completion.chunk events.",
            "title": "Stream",
            "type": "boolean"
          },
          "temperature": {
            "default": 0.0,
            "maximum": 2.0,
            "minimum": 0.0,
            "title": "Temperature",
            "type": "number"
          },
          "top_p": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Accepted for compatibility; ignored.",
            "title": "Top P"
          },
          "user": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Opaque end-user id for abuse monitoring (not used for auth).",
            "title": "User"
          }
        },
        "required": [
          "messages"
        ],
        "title": "ChatCompletionRequest",
        "type": "object"
      },
      "ChatCompletionResponse": {
        "description": "``POST /v1/chat/completions`` response (OpenAI-compatible + ``rag``).",
        "properties": {
          "choices": {
            "items": {
              "$ref": "#/components/schemas/ChatCompletionChoice"
            },
            "title": "Choices",
            "type": "array"
          },
          "created": {
            "title": "Created",
            "type": "integer"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "model": {
            "title": "Model",
            "type": "string"
          },
          "object": {
            "const": "chat.completion",
            "default": "chat.completion",
            "title": "Object",
            "type": "string"
          },
          "rag": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/RagAnnotations"
              },
              {
                "type": "null"
              }
            ]
          },
          "usage": {
            "$ref": "#/components/schemas/ChatCompletionUsage"
          }
        },
        "required": [
          "model"
        ],
        "title": "ChatCompletionResponse",
        "type": "object"
      },
      "ChatCompletionResponseMessage": {
        "description": "The assistant message inside a completion choice.",
        "properties": {
          "content": {
            "title": "Content",
            "type": "string"
          },
          "role": {
            "const": "assistant",
            "default": "assistant",
            "title": "Role",
            "type": "string"
          }
        },
        "required": [
          "content"
        ],
        "title": "ChatCompletionResponseMessage",
        "type": "object"
      },
      "ChatCompletionUsage": {
        "description": "Prompt / completion / total token accounting.",
        "properties": {
          "completion_tokens": {
            "default": 0,
            "title": "Completion Tokens",
            "type": "integer"
          },
          "prompt_tokens": {
            "default": 0,
            "title": "Prompt Tokens",
            "type": "integer"
          },
          "total_tokens": {
            "default": 0,
            "title": "Total Tokens",
            "type": "integer"
          }
        },
        "title": "ChatCompletionUsage",
        "type": "object"
      },
      "ChatMessage": {
        "description": "A single chat turn.\n\nOnly the string ``content`` form is supported (not OpenAI's\nmulti-part content arrays).  ``role`` is one of ``system`` / ``user``\n/ ``assistant`` / ``tool``; the gateway treats unknown roles as\nopaque and forwards them to the LLM.",
        "properties": {
          "content": {
            "default": "",
            "title": "Content",
            "type": "string"
          },
          "name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Name"
          },
          "role": {
            "title": "Role",
            "type": "string"
          }
        },
        "required": [
          "role"
        ],
        "title": "ChatMessage",
        "type": "object"
      },
      "Chunk": {
        "description": "A contiguous piece of a Document produced by the chunking pipeline.\n\nStep 1.1a promoted three governance-relevant fields out of the\n``metadata`` dict into typed required fields:\n\n- ``acl_labels``  — set of ACL labels the PolicyEngine compares against\n  the requesting principal's ``acl_labels``.\n- ``trust_level`` — provenance, used by the prompt-injection defense.\n- ``content_ref`` — optional ``BlobRef`` for tiered text storage; when set,\n  ``content`` may be ``None`` and callers must hydrate via Storage.",
        "properties": {
          "acl_labels": {
            "items": {
              "type": "string"
            },
            "title": "Acl Labels",
            "type": "array",
            "uniqueItems": true
          },
          "content": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Content"
          },
          "content_ref": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/BlobRef"
              },
              {
                "type": "null"
              }
            ]
          },
          "corpus_id": {
            "title": "Corpus Id",
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "document_id": {
            "title": "Document Id",
            "type": "string"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "metadata": {
            "additionalProperties": true,
            "title": "Metadata",
            "type": "object"
          },
          "parent_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Parent Id"
          },
          "position": {
            "title": "Position",
            "type": "integer"
          },
          "score": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Score"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          },
          "token_count": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Token Count"
          },
          "trust_level": {
            "$ref": "#/components/schemas/TrustLevel",
            "default": "ingested"
          }
        },
        "required": [
          "document_id",
          "tenant_id",
          "corpus_id",
          "position"
        ],
        "title": "Chunk",
        "type": "object"
      },
      "ChunkRef": {
        "description": "Lightweight reference to a chunk returned by ID-only retrieval paths.\n\nUsed by `RetrievalBackend.retrieve_ids` (Step 1.1b) to avoid hydrating\nfull chunk content for results that may be rejected by the reranker or\nPolicyEngine.  Carries only what downstream stages need to fuse, rerank,\nand policy-check before hydration.",
        "properties": {
          "acl_labels": {
            "items": {
              "type": "string"
            },
            "title": "Acl Labels",
            "type": "array",
            "uniqueItems": true
          },
          "chunk_id": {
            "title": "Chunk Id",
            "type": "string"
          },
          "corpus_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Corpus Id"
          },
          "metadata": {
            "additionalProperties": true,
            "title": "Metadata",
            "type": "object"
          },
          "score": {
            "title": "Score",
            "type": "number"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          }
        },
        "required": [
          "chunk_id",
          "tenant_id",
          "score"
        ],
        "title": "ChunkRef",
        "type": "object"
      },
      "CircuitState": {
        "description": "State of a per-backend circuit breaker (Step 4.4).\n\nThe breaker is a three-state machine that isolates a failing backend so a\nsick dependency fails *fast* instead of stalling every request behind a\ntimeout:\n\nCLOSED\n    Normal operation — calls pass through and failures are counted.  A run\n    of ``failure_threshold`` consecutive failures trips the breaker OPEN.\nOPEN\n    The backend is presumed down — calls are rejected immediately\n    (:class:`~rag_core.errors.CircuitOpenError`) without touching it.  After\n    ``reset_timeout_s`` the breaker admits a single trial call by moving to\n    HALF_OPEN.\nHALF_OPEN\n    Probing recovery — a limited number of trial calls are allowed.  Enough\n    successes close the breaker; any failure re-opens it.",
        "enum": [
          "closed",
          "open",
          "half_open"
        ],
        "title": "CircuitState",
        "type": "string"
      },
      "Citation": {
        "description": "A single chunk surfaced as evidence supporting an answer.",
        "properties": {
          "chunk_id": {
            "title": "Chunk Id",
            "type": "string"
          },
          "document_id": {
            "title": "Document Id",
            "type": "string"
          },
          "excerpt": {
            "title": "Excerpt",
            "type": "string"
          },
          "position_in_context": {
            "title": "Position In Context",
            "type": "integer"
          },
          "score": {
            "title": "Score",
            "type": "number"
          },
          "source_uri": {
            "title": "Source Uri",
            "type": "string"
          }
        },
        "required": [
          "chunk_id",
          "document_id",
          "source_uri",
          "excerpt",
          "score",
          "position_in_context"
        ],
        "title": "Citation",
        "type": "object"
      },
      "ClaimVerdict": {
        "description": "Per-claim faithfulness verdict (Step 4.3).\n\nOne entry per claim extracted from the generated answer.  ``supported`` is\n``True`` iff ``entailment >= threshold`` for the resolved per-tenant\nthreshold.  ``claim`` carries the claim text so a guard-aware caller can\nshow the user exactly which sentences were unsupported — this is a\nresponse-side value object, never logged (the ``guard.claim_blocked``\nevent carries only counts + scores, never claim text).",
        "properties": {
          "claim": {
            "title": "Claim",
            "type": "string"
          },
          "entailment": {
            "title": "Entailment",
            "type": "number"
          },
          "label": {
            "$ref": "#/components/schemas/NLILabel"
          },
          "supported": {
            "title": "Supported",
            "type": "boolean"
          }
        },
        "required": [
          "claim",
          "label",
          "entailment",
          "supported"
        ],
        "title": "ClaimVerdict",
        "type": "object"
      },
      "ComplianceEraseRequest": {
        "description": "``POST /v1/compliance/erase`` body — GDPR right-to-erasure (Step 6.10).\n\nErases the **calling tenant's** data across the retention-enforcer's wired\nstores (tenant scope comes from the authenticated principal, never the body).\n``dry_run`` defaults to ``True`` (a safe preview that *counts* without\ndeleting); set it ``false`` **and** ``confirm`` ``true`` to actually delete —\nboth are required so an erasure is never a one-flag accident.",
        "properties": {
          "confirm": {
            "default": false,
            "title": "Confirm",
            "type": "boolean"
          },
          "dry_run": {
            "default": true,
            "title": "Dry Run",
            "type": "boolean"
          }
        },
        "title": "ComplianceEraseRequest",
        "type": "object"
      },
      "CompliancePosture": {
        "description": "The platform's live compliance posture (Step 6.10).\n\nA point-in-time view of which governance controls are enabled, the deployment's\ndata region (GDPR residency), and the retention windows — computed from ``cfg``\nby ``rag_compliance.compliance_posture`` and served by\n``GET /v1/status/compliance`` + ``ragctl compliance report``.  It is the\nmachine-readable backing for the SOC 2 / GDPR control-mapping docs: each control\nmaps to a Trust Service Criterion, and this reports whether it is on in *this*\ndeployment.  Carries no tenant data — only configuration booleans — so it is\nsafe on the status surface.",
        "properties": {
          "controls": {
            "additionalProperties": {
              "type": "boolean"
            },
            "title": "Controls",
            "type": "object"
          },
          "enabled_controls": {
            "items": {
              "type": "string"
            },
            "title": "Enabled Controls",
            "type": "array"
          },
          "generated_at": {
            "format": "date-time",
            "title": "Generated At",
            "type": "string"
          },
          "region": {
            "default": "",
            "title": "Region",
            "type": "string"
          },
          "retention": {
            "$ref": "#/components/schemas/RetentionPolicy"
          }
        },
        "title": "CompliancePosture",
        "type": "object"
      },
      "ComponentHealth": {
        "description": "Liveness of one gateway component.",
        "properties": {
          "detail": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Detail"
          },
          "kind": {
            "title": "Kind",
            "type": "string"
          },
          "name": {
            "title": "Name",
            "type": "string"
          },
          "status": {
            "title": "Status",
            "type": "string"
          }
        },
        "required": [
          "name",
          "kind",
          "status"
        ],
        "title": "ComponentHealth",
        "type": "object"
      },
      "ConflictAnnotation": {
        "description": "Advisory annotation flagging a likely conflict between packed chunks.\n\nConflicts are surfaced as metadata only — chunks are NOT dropped in\nV1.  The downstream prompt template / gateway decides whether to\nsurface conflicts to the LLM (e.g. as a \"note: sources disagree\"\npreamble) or fail closed.",
        "properties": {
          "chunk_ids": {
            "items": {
              "type": "string"
            },
            "title": "Chunk Ids",
            "type": "array"
          },
          "detail": {
            "title": "Detail",
            "type": "string"
          },
          "kind": {
            "enum": [
              "trust_mismatch",
              "numeric_disagreement"
            ],
            "title": "Kind",
            "type": "string"
          }
        },
        "required": [
          "kind",
          "chunk_ids",
          "detail"
        ],
        "title": "ConflictAnnotation",
        "type": "object"
      },
      "ConnectorStatusView": {
        "description": "Runtime status of one registered connector.",
        "properties": {
          "detail": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Detail"
          },
          "documents_ingested": {
            "default": 0,
            "title": "Documents Ingested",
            "type": "integer"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "last_run": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Last Run"
          },
          "name": {
            "title": "Name",
            "type": "string"
          },
          "status": {
            "title": "Status",
            "type": "string"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          },
          "type": {
            "title": "Type",
            "type": "string"
          },
          "watermark": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Watermark"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "name",
          "type",
          "status"
        ],
        "title": "ConnectorStatusView",
        "type": "object"
      },
      "ConnectorsStatusResponse": {
        "properties": {
          "connectors": {
            "items": {
              "$ref": "#/components/schemas/ConnectorStatusView"
            },
            "title": "Connectors",
            "type": "array"
          },
          "total": {
            "title": "Total",
            "type": "integer"
          }
        },
        "required": [
          "connectors",
          "total"
        ],
        "title": "ConnectorsStatusResponse",
        "type": "object"
      },
      "Corpus": {
        "description": "Tenant-owned document collection.\n\nStep 3.1.  Production corpora carry richer metadata (embedding\nmodel, chunking config, retention policy) that lands with the\nfull corpus router in Step 3.5.  v0 keeps the model tight: just\nthe identifying triple + display fields callers need to populate\na UI.\n\nThe ``embedding_model`` field is informational — it documents\nwhich model the corpus was embedded with so cross-corpus queries\ncan detect dimension mismatches.  Enforcement is the router's\njob (Step 3.5).",
        "properties": {
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "description": {
            "default": "",
            "title": "Description",
            "type": "string"
          },
          "display_name": {
            "title": "Display Name",
            "type": "string"
          },
          "document_count": {
            "default": 0,
            "title": "Document Count",
            "type": "integer"
          },
          "embedding_dimension": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Embedding Dimension"
          },
          "embedding_model": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Embedding Model"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "metadata": {
            "additionalProperties": true,
            "title": "Metadata",
            "type": "object"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "display_name"
        ],
        "title": "Corpus",
        "type": "object"
      },
      "CorpusList": {
        "description": "``GET /v1/corpora`` response envelope.\n\nA wrapper rather than a raw list lets us add paging fields in\nPhase 3.x without breaking the wire shape.",
        "properties": {
          "corpora": {
            "items": {
              "$ref": "#/components/schemas/Corpus"
            },
            "title": "Corpora",
            "type": "array"
          },
          "total": {
            "default": 0,
            "title": "Total",
            "type": "integer"
          }
        },
        "title": "CorpusList",
        "type": "object"
      },
      "CorpusRoutingDecision": {
        "description": "Frozen output of the corpus router's selection step (Step 3.5).\n\nProduced by\n:meth:`~rag_retrieval.corpus_router.CorpusRouter.decide` and surfaced\non the gateway query / retrieve responses + the ``corpus.route`` OTel\nspan + the ``corpus.route`` audit event.\n\n``fan_out`` distinguishes *federated* execution (one retrieval per\nselected corpus, results fused) from a *single-pass* execution (one\nretrieval scoped to all selected corpora).  ``candidate_n`` is the\nnumber of visible corpora considered before selection.",
        "properties": {
          "candidate_n": {
            "default": 0,
            "title": "Candidate N",
            "type": "integer"
          },
          "fan_out": {
            "default": false,
            "title": "Fan Out",
            "type": "boolean"
          },
          "reason": {
            "default": "",
            "title": "Reason",
            "type": "string"
          },
          "scores": {
            "items": {
              "$ref": "#/components/schemas/CorpusScore"
            },
            "title": "Scores",
            "type": "array"
          },
          "selected_corpora": {
            "items": {
              "type": "string"
            },
            "title": "Selected Corpora",
            "type": "array"
          },
          "strategy": {
            "$ref": "#/components/schemas/CorpusRoutingStrategy"
          }
        },
        "required": [
          "strategy"
        ],
        "title": "CorpusRoutingDecision",
        "type": "object"
      },
      "CorpusRoutingStrategy": {
        "description": "How the corpus router chose the corpus set for a query.\n\nStep 3.5.  Sits *above* :class:`QueryShape` / :class:`RoutingDecision`\n(which pick the *backends* for one corpus) and answers the prior\nquestion: **which corpora should this query touch at all?**\n\nValues\n------\nEXPLICIT\n    The caller named ``corpus_ids`` directly; the router only\n    intersected that set with tenant visibility (no scoring).\nSTATIC_RULES\n    Config-driven keyword / regex rules selected the corpora\n    (deterministic, auditable, no model).\nLEARNED\n    The learned classifier ranked corpora by a per-corpus term\n    profile and the selection strategy kept the top scorers.\nALL\n    No rule fired and no learned signal applied (or the tenant has\n    ≤ ``min_corpora`` corpora) — every visible corpus is queried.\nUNCONSTRAINED\n    No corpora are visible / registered for the tenant — the router\n    falls through to a single unconstrained retrieval (``corpus_ids``\n    is ``None``), preserving pre-3.5 behaviour.",
        "enum": [
          "explicit",
          "static_rules",
          "learned",
          "all",
          "unconstrained"
        ],
        "title": "CorpusRoutingStrategy",
        "type": "string"
      },
      "CorpusScore": {
        "description": "Per-corpus relevance score produced during corpus selection.\n\nStep 3.5.  ``score`` is a unitless relevance in ``[0.0, +inf)`` whose\nonly contract is *monotonic* — higher means more relevant for this\nquery.  ``selected`` records whether the selection strategy kept the\ncorpus.  ``reason`` is advisory (rule name, \"learned\", \"explicit\",\n\"below_threshold\") — never parse it in production.",
        "properties": {
          "corpus_id": {
            "title": "Corpus Id",
            "type": "string"
          },
          "reason": {
            "default": "",
            "title": "Reason",
            "type": "string"
          },
          "score": {
            "title": "Score",
            "type": "number"
          },
          "selected": {
            "title": "Selected",
            "type": "boolean"
          }
        },
        "required": [
          "corpus_id",
          "score",
          "selected"
        ],
        "title": "CorpusScore",
        "type": "object"
      },
      "CostStatusResponse": {
        "description": "One tenant's recent-spend anomaly verdict (Step 5.6c).\n\nMirrors :class:`~rag_observability.cost.CostSnapshot`.  Per-tenant (like\nquotas / feedback): the tenant comes from the ``tenant_id`` query param or the\n``X-Tenant-Id`` header.  ``status`` is ``ok`` / ``elevated`` /\n``insufficient_data`` (the last when fewer than ``min_samples`` requests have\nbeen seen, or no cost tracker is wired).",
        "properties": {
          "baseline_cost_micros": {
            "default": 0.0,
            "title": "Baseline Cost Micros",
            "type": "number"
          },
          "baseline_mean_tokens": {
            "default": 0.0,
            "title": "Baseline Mean Tokens",
            "type": "number"
          },
          "baseline_std_tokens": {
            "default": 0.0,
            "title": "Baseline Std Tokens",
            "type": "number"
          },
          "ratio": {
            "default": 0.0,
            "title": "Ratio",
            "type": "number"
          },
          "recent_cost_micros": {
            "default": 0.0,
            "title": "Recent Cost Micros",
            "type": "number"
          },
          "recent_mean_tokens": {
            "default": 0.0,
            "title": "Recent Mean Tokens",
            "type": "number"
          },
          "recent_n": {
            "default": 0,
            "title": "Recent N",
            "type": "integer"
          },
          "samples_n": {
            "default": 0,
            "title": "Samples N",
            "type": "integer"
          },
          "status": {
            "default": "insufficient_data",
            "title": "Status",
            "type": "string"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          },
          "z_score": {
            "default": 0.0,
            "title": "Z Score",
            "type": "number"
          }
        },
        "required": [
          "tenant_id"
        ],
        "title": "CostStatusResponse",
        "type": "object"
      },
      "CounterView": {
        "properties": {
          "labels": {
            "additionalProperties": {
              "type": "string"
            },
            "title": "Labels",
            "type": "object"
          },
          "name": {
            "title": "Name",
            "type": "string"
          },
          "value": {
            "title": "Value",
            "type": "number"
          }
        },
        "required": [
          "name",
          "labels",
          "value"
        ],
        "title": "CounterView",
        "type": "object"
      },
      "CreateCorpusRequest": {
        "description": "``POST /v1/corpora`` body (admin write surface — Step 3.10).\n\n``id`` and ``tenant_id`` are assigned server-side — the id is minted\nas a unique ``corpus_…`` token and the tenant is taken from the\nauthenticated request — so a caller can neither choose a corpus id nor\ncreate into another tenant.  ``document_count`` starts at 0; it is\nmaintained by the ingest path, never set on create.",
        "properties": {
          "description": {
            "default": "",
            "title": "Description",
            "type": "string"
          },
          "display_name": {
            "description": "Human-readable corpus name shown in the console.",
            "minLength": 1,
            "title": "Display Name",
            "type": "string"
          },
          "embedding_dimension": {
            "anyOf": [
              {
                "minimum": 1.0,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "Embedding vector dimension.",
            "title": "Embedding Dimension"
          },
          "embedding_model": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Model the corpus is embedded with (informational — documents dimension).",
            "title": "Embedding Model"
          },
          "metadata": {
            "additionalProperties": true,
            "title": "Metadata",
            "type": "object"
          }
        },
        "required": [
          "display_name"
        ],
        "title": "CreateCorpusRequest",
        "type": "object"
      },
      "CreateSubscriptionRequest": {
        "description": "``POST /v1/webhooks/subscriptions`` body.",
        "properties": {
          "description": {
            "default": "",
            "title": "Description",
            "type": "string"
          },
          "event_types": {
            "description": "Events to deliver.  Empty = all event types.",
            "items": {
              "$ref": "#/components/schemas/WebhookEventType"
            },
            "title": "Event Types",
            "type": "array"
          },
          "secret": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "HMAC signing secret.  Generated if omitted (returned once on create).",
            "title": "Secret"
          },
          "url": {
            "description": "HTTPS endpoint to deliver events to.",
            "minLength": 1,
            "title": "Url",
            "type": "string"
          }
        },
        "required": [
          "url"
        ],
        "title": "CreateSubscriptionRequest",
        "type": "object"
      },
      "DeliveryStatus": {
        "description": "Terminal state of a delivery to one subscription.",
        "enum": [
          "delivered",
          "failed"
        ],
        "title": "DeliveryStatus",
        "type": "string"
      },
      "DriftMethod": {
        "description": "How a drift monitor turns its windows into a drift statistic.",
        "enum": [
          "psi",
          "mean_drop"
        ],
        "title": "DriftMethod",
        "type": "string"
      },
      "DriftMetric": {
        "description": "The five signals the platform monitors for drift (Step 5.5).",
        "enum": [
          "query_distribution",
          "embedding_psi",
          "retrieval_score",
          "citation_clickthrough",
          "faithfulness"
        ],
        "title": "DriftMetric",
        "type": "string"
      },
      "DriftReport": {
        "description": "Aggregate drift verdict across every monitor (Step 5.5).\n\nServed by ``GET /v1/status/drift``.  Drift is infra-scoped (one set of\nmonitors per deployment, like circuit breakers), so the report carries no\ntenant rows — just the per-monitor snapshots and the count that are drifting.",
        "properties": {
          "drifted_n": {
            "default": 0,
            "title": "Drifted N",
            "type": "integer"
          },
          "generated_at": {
            "format": "date-time",
            "title": "Generated At",
            "type": "string"
          },
          "monitors": {
            "items": {
              "$ref": "#/components/schemas/DriftSnapshot"
            },
            "title": "Monitors",
            "type": "array"
          }
        },
        "title": "DriftReport",
        "type": "object"
      },
      "DriftSnapshot": {
        "description": "One monitor's current verdict (Step 5.5).\n\n``statistic`` is the PSI value for a ``psi`` monitor, or the **drop**\n(``reference_value - current_value``) for a ``mean_drop`` monitor.  For\n``mean_drop`` the ``reference_value`` / ``current_value`` means are reported;\nfor ``psi`` they are ``None`` (PSI is not a mean).  ``drifted`` is\n``status is DriftStatus.drifted``.",
        "properties": {
          "current_n": {
            "default": 0,
            "title": "Current N",
            "type": "integer"
          },
          "current_value": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Current Value"
          },
          "method": {
            "$ref": "#/components/schemas/DriftMethod"
          },
          "metric": {
            "$ref": "#/components/schemas/DriftMetric"
          },
          "reference_n": {
            "default": 0,
            "title": "Reference N",
            "type": "integer"
          },
          "reference_value": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Reference Value"
          },
          "statistic": {
            "default": 0.0,
            "title": "Statistic",
            "type": "number"
          },
          "status": {
            "$ref": "#/components/schemas/DriftStatus"
          },
          "threshold": {
            "default": 0.0,
            "title": "Threshold",
            "type": "number"
          }
        },
        "required": [
          "metric",
          "method",
          "status"
        ],
        "title": "DriftSnapshot",
        "type": "object"
      },
      "DriftStatus": {
        "description": "Verdict for one monitor.",
        "enum": [
          "ok",
          "drifted",
          "insufficient_data"
        ],
        "title": "DriftStatus",
        "type": "string"
      },
      "EmbeddingObject": {
        "description": "One embedding in an :class:`EmbeddingsResponse`.\n\n``embedding`` is a ``list[float]`` when ``encoding_format=float`` (the\ndefault) and a base64 string when ``encoding_format=base64`` — exactly\nmatching OpenAI's union return type.",
        "properties": {
          "embedding": {
            "anyOf": [
              {
                "items": {
                  "type": "number"
                },
                "type": "array"
              },
              {
                "type": "string"
              }
            ],
            "title": "Embedding"
          },
          "index": {
            "title": "Index",
            "type": "integer"
          },
          "object": {
            "const": "embedding",
            "default": "embedding",
            "title": "Object",
            "type": "string"
          }
        },
        "required": [
          "embedding",
          "index"
        ],
        "title": "EmbeddingObject",
        "type": "object"
      },
      "EmbeddingsRequest": {
        "description": "``POST /v1/embeddings`` body (OpenAI-compatible).\n\n``input`` accepts a single string or a list of strings.  OpenAI's\ntoken-array input forms (``list[int]`` / ``list[list[int]]``) are\n**not** supported — the gateway embeds text, not pre-tokenised ids,\nand rejects array-of-int input with HTTP 400.\n\n``model`` is accepted for client compatibility but is informational:\nthe gateway embeds with its wired ``Embedder`` and reports that\nbackend's canonical model id in the response.  ``dimensions`` is\nlikewise accepted for compatibility; the wired embedder controls the\noutput dimension (a real Matryoshka-capable embedder honours it via\nits own config).",
        "properties": {
          "dimensions": {
            "anyOf": [
              {
                "minimum": 1.0,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "Accepted for compatibility; the wired embedder controls dimension.",
            "title": "Dimensions"
          },
          "encoding_format": {
            "default": "float",
            "description": "`float` returns a JSON number array; `base64` returns a base64 string.",
            "enum": [
              "float",
              "base64"
            ],
            "title": "Encoding Format",
            "type": "string"
          },
          "input": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              }
            ],
            "description": "Text (or list of texts) to embed.  Token-id arrays are not supported.",
            "title": "Input"
          },
          "model": {
            "default": "text-embedding-3-small",
            "description": "Informational — the wired Embedder's model is used + reported.",
            "title": "Model",
            "type": "string"
          },
          "user": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Opaque end-user id for abuse monitoring (passed through, not used for auth).",
            "title": "User"
          }
        },
        "required": [
          "input"
        ],
        "title": "EmbeddingsRequest",
        "type": "object"
      },
      "EmbeddingsResponse": {
        "description": "``POST /v1/embeddings`` response (OpenAI-compatible).",
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/EmbeddingObject"
            },
            "title": "Data",
            "type": "array"
          },
          "model": {
            "title": "Model",
            "type": "string"
          },
          "object": {
            "const": "list",
            "default": "list",
            "title": "Object",
            "type": "string"
          },
          "usage": {
            "$ref": "#/components/schemas/EmbeddingsUsage"
          }
        },
        "required": [
          "model"
        ],
        "title": "EmbeddingsResponse",
        "type": "object"
      },
      "EmbeddingsUsage": {
        "description": "Token accounting for an embeddings call.\n\n``prompt_tokens == total_tokens`` for embeddings (there are no\ncompletion tokens).  Counts are computed with the same tokenizer the\ncontext packer uses; they are best-effort and may differ slightly from\na specific provider's accounting.",
        "properties": {
          "prompt_tokens": {
            "default": 0,
            "title": "Prompt Tokens",
            "type": "integer"
          },
          "total_tokens": {
            "default": 0,
            "title": "Total Tokens",
            "type": "integer"
          }
        },
        "title": "EmbeddingsUsage",
        "type": "object"
      },
      "ErasureResult": {
        "description": "Outcome of a retention purge or a GDPR right-to-erasure run (Step 6.10).\n\n``purged`` maps each :class:`DataClass` (by value) to the number of records\nremoved; ``total`` is their sum.  ``dry_run`` is ``True`` when the run only\n*counted* what would be purged without deleting (the default for a preview).",
        "properties": {
          "dry_run": {
            "default": false,
            "title": "Dry Run",
            "type": "boolean"
          },
          "generated_at": {
            "format": "date-time",
            "title": "Generated At",
            "type": "string"
          },
          "purged": {
            "additionalProperties": {
              "type": "integer"
            },
            "title": "Purged",
            "type": "object"
          },
          "scope": {
            "default": "retention",
            "title": "Scope",
            "type": "string"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          },
          "total": {
            "default": 0,
            "title": "Total",
            "type": "integer"
          }
        },
        "required": [
          "tenant_id"
        ],
        "title": "ErasureResult",
        "type": "object"
      },
      "ExperimentAssignment": {
        "description": "Which A/B variant served this response (Step 5.7c).\n\nPresent on a :class:`QueryResponse` / :class:`RetrieveResponse` only when\nA/B *routing* is active and assigned the request to an experiment — the\ndeterministic, ``request_id``-hashed slice that can actually change which\nretrieval config a user gets (shadow mode, Step 5.7b, never tags a response).\n``None`` otherwise (routing off, or the request was not in the experiment).\n\nCarries no query or answer text — only the experiment id and the assigned\nvariant label, so the tag is safe to log and surface.  ``is_candidate``\nflags whether the *candidate* (alternative) config served the response, so a\nconsumer can split traffic without re-deriving it from the variant name.",
        "properties": {
          "experiment": {
            "title": "Experiment",
            "type": "string"
          },
          "is_candidate": {
            "default": false,
            "title": "Is Candidate",
            "type": "boolean"
          },
          "variant": {
            "title": "Variant",
            "type": "string"
          }
        },
        "required": [
          "experiment",
          "variant"
        ],
        "title": "ExperimentAssignment",
        "type": "object"
      },
      "ExperimentsStatusResponse": {
        "description": "A/B experiment comparisons (Step 5.7).\n\nOne :class:`~rag_core.eval.ABAnalysisResult` per running experiment, each\ncomparing the control variant against the candidate on the collected metric.\nEmpty when experiments are disabled or none have been observed.",
        "properties": {
          "experiments": {
            "items": {
              "$ref": "#/components/schemas/ABAnalysisResult"
            },
            "title": "Experiments",
            "type": "array"
          },
          "total": {
            "title": "Total",
            "type": "integer"
          }
        },
        "required": [
          "experiments",
          "total"
        ],
        "title": "ExperimentsStatusResponse",
        "type": "object"
      },
      "FeedbackAck": {
        "description": "``POST /v1/feedback`` response (Step 5.4).\n\nEchoes the resolved ``kind`` / ``signal`` / normalised ``score`` and reports\nwhether the record was persisted.  ``stored`` is ``False`` (with\n``feedback_id=None``) when feedback is disabled on the gateway or recording\ndegraded — the submission is acknowledged either way (recording is\ndegrade-open and never errors the client).",
        "properties": {
          "comment_redacted": {
            "default": false,
            "title": "Comment Redacted",
            "type": "boolean"
          },
          "feedback_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Feedback Id"
          },
          "kind": {
            "$ref": "#/components/schemas/FeedbackKind"
          },
          "request_id": {
            "title": "Request Id",
            "type": "string"
          },
          "score": {
            "default": 0.0,
            "title": "Score",
            "type": "number"
          },
          "signal": {
            "$ref": "#/components/schemas/FeedbackSignal"
          },
          "stored": {
            "default": false,
            "title": "Stored",
            "type": "boolean"
          }
        },
        "required": [
          "request_id",
          "kind",
          "signal"
        ],
        "title": "FeedbackAck",
        "type": "object"
      },
      "FeedbackKind": {
        "description": "Whether feedback was given deliberately by a user or inferred from behaviour.",
        "enum": [
          "explicit",
          "implicit"
        ],
        "title": "FeedbackKind",
        "type": "string"
      },
      "FeedbackRequest": {
        "description": "``POST /v1/feedback`` body (Step 5.4).\n\nSubmits explicit feedback (``thumb_up`` / ``thumb_down`` / ``rating`` /\n``comment``) or an implicit signal (``citation_click`` / ``answer_copied`` /\n``regenerated`` / ``accepted`` / ``dwell``) about a previously-executed query.\nIdentity is body-carried (``tenant_id`` / ``principal_id``) like\n:class:`QueryRequest`; ``request_id`` ties the feedback back to the query (the\nsame id returned in :class:`QueryResponse` and used by\n``GET /v1/query/{id}/trace``).  ``kind`` is inferred from ``signal`` when\nomitted.  A free-text ``comment`` is **PII-redacted** before it is stored.",
        "properties": {
          "comment": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Free-text comment — PII-redacted before storage.",
            "title": "Comment"
          },
          "kind": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FeedbackKind"
              },
              {
                "type": "null"
              }
            ],
            "description": "Explicit vs implicit; inferred from signal when omitted."
          },
          "metadata": {
            "additionalProperties": true,
            "title": "Metadata",
            "type": "object"
          },
          "principal_id": {
            "title": "Principal Id",
            "type": "string"
          },
          "rating": {
            "anyOf": [
              {
                "maximum": 5.0,
                "minimum": 1.0,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "1–5 star rating; used to derive the score when signal=rating.",
            "title": "Rating"
          },
          "request_id": {
            "description": "The query this feedback is about.",
            "title": "Request Id",
            "type": "string"
          },
          "signal": {
            "$ref": "#/components/schemas/FeedbackSignal"
          },
          "target_chunk_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "The citation a click / copy referenced, if any.",
            "title": "Target Chunk Id"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          },
          "value": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Raw signal value (e.g. dwell milliseconds), if any.",
            "title": "Value"
          }
        },
        "required": [
          "tenant_id",
          "principal_id",
          "request_id",
          "signal"
        ],
        "title": "FeedbackRequest",
        "type": "object"
      },
      "FeedbackSignal": {
        "description": "The specific feedback signal attached to a query (Step 5.4).\n\nEach signal carries a default *polarity* used to normalise a ``[-1, 1]``\nsatisfaction score when no explicit rating is supplied:\n\n* positive (+1): ``thumb_up``, ``citation_click``, ``answer_copied``, ``accepted``\n* negative (-1): ``thumb_down``, ``regenerated``\n* neutral (0): ``rating`` (score derives from the 1–5 value), ``comment``, ``dwell``",
        "enum": [
          "thumb_up",
          "thumb_down",
          "rating",
          "comment",
          "citation_click",
          "answer_copied",
          "regenerated",
          "accepted",
          "dwell"
        ],
        "title": "FeedbackSignal",
        "type": "string"
      },
      "FeedbackStats": {
        "description": "Per-tenant aggregate feedback for the dashboard (Step 5.4).\n\nMacro counts + a mean satisfaction score over a tenant's\n:class:`FeedbackRecord` set, with sentiment buckets and the headline implicit\nsignals broken out.  ``mean_score`` is ``None`` when the tenant has no\nfeedback yet.  Computed by :func:`rag_feedback.aggregate.aggregate_feedback`\nand returned by ``GET /v1/status/feedback``.",
        "properties": {
          "by_signal": {
            "additionalProperties": {
              "type": "integer"
            },
            "title": "By Signal",
            "type": "object"
          },
          "citation_click_n": {
            "default": 0,
            "title": "Citation Click N",
            "type": "integer"
          },
          "comment_n": {
            "default": 0,
            "title": "Comment N",
            "type": "integer"
          },
          "explicit_n": {
            "default": 0,
            "title": "Explicit N",
            "type": "integer"
          },
          "implicit_n": {
            "default": 0,
            "title": "Implicit N",
            "type": "integer"
          },
          "mean_score": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Mean Score"
          },
          "negative_n": {
            "default": 0,
            "title": "Negative N",
            "type": "integer"
          },
          "neutral_n": {
            "default": 0,
            "title": "Neutral N",
            "type": "integer"
          },
          "positive_n": {
            "default": 0,
            "title": "Positive N",
            "type": "integer"
          },
          "regenerated_n": {
            "default": 0,
            "title": "Regenerated N",
            "type": "integer"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          },
          "total": {
            "default": 0,
            "title": "Total",
            "type": "integer"
          }
        },
        "required": [
          "tenant_id"
        ],
        "title": "FeedbackStats",
        "type": "object"
      },
      "GatewayError": {
        "description": "JSON error body returned for 4xx / 5xx responses.\n\nMirrors the pattern in :class:`rag_core.errors.RagError` so\ndownstream consumers can use one shape.  The HTTP status is\nNOT included in the body — it's the response status.\n``code`` is the machine-readable ``RagError.code`` value;\n``message`` is the human-readable description.\n\nAlways emitted as ``{\"error\": GatewayError}`` so the body\ndiscriminates from successful responses by key.",
        "properties": {
          "code": {
            "title": "Code",
            "type": "string"
          },
          "context": {
            "additionalProperties": true,
            "title": "Context",
            "type": "object"
          },
          "message": {
            "title": "Message",
            "type": "string"
          },
          "request_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Request Id"
          },
          "trace_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Trace Id"
          }
        },
        "required": [
          "code",
          "message"
        ],
        "title": "GatewayError",
        "type": "object"
      },
      "GaugeView": {
        "properties": {
          "labels": {
            "additionalProperties": {
              "type": "string"
            },
            "title": "Labels",
            "type": "object"
          },
          "name": {
            "title": "Name",
            "type": "string"
          },
          "value": {
            "title": "Value",
            "type": "number"
          }
        },
        "required": [
          "name",
          "labels",
          "value"
        ],
        "title": "GaugeView",
        "type": "object"
      },
      "GuardAction": {
        "description": "What the hallucination guard does with an unfaithful answer (Step 4.3).\n\nANNOTATE\n    Observe only: attach per-claim verdicts to the response and emit the\n    ``guard.claim_blocked`` event, but return the answer text unchanged.\n    The behaviour-neutral default — safe to enable in production for\n    monitoring before any enforcement.\nREDACT\n    Drop the unsupported claims from the answer, returning the grounded\n    remainder.\nBLOCK\n    Withhold the whole answer when any claim is unsupported, replacing it\n    with a refusal notice.",
        "enum": [
          "annotate",
          "redact",
          "block"
        ],
        "title": "GuardAction",
        "type": "string"
      },
      "GuardResult": {
        "description": "Frozen record of a hallucination-guard check (Step 4.3).\n\nProduced by :meth:`~rag_guard.guard.HallucinationGuard.check` (which\nreturns it alongside the possibly-modified answer text, mirroring\n:meth:`~rag_retrieval.fallback.FallbackChain.run`'s\n``(FallbackResult, refs)`` shape).  Surfaced on the ``guard.check`` OTel\nspan, the ``guard.claim_blocked`` event (when ``blocked_n > 0``), and the\ngateway response (``Answer.guard`` / ``RagAnnotations.guard``).\n\nCarries the per-claim verdicts but *not* the final answer text — that is\nreturned separately so this stays a lightweight decision object (mirrors\n:class:`FallbackResult` / :class:`RoutingDecision`).  ``threshold`` is the\nresolved per-tenant entailment floor that produced these verdicts.\n``reason`` is advisory free-text — never parse it in production code.",
        "properties": {
          "action": {
            "$ref": "#/components/schemas/GuardAction"
          },
          "blocked_n": {
            "default": 0,
            "title": "Blocked N",
            "type": "integer"
          },
          "claims": {
            "items": {
              "$ref": "#/components/schemas/ClaimVerdict"
            },
            "title": "Claims",
            "type": "array"
          },
          "claims_n": {
            "default": 0,
            "title": "Claims N",
            "type": "integer"
          },
          "reason": {
            "default": "",
            "title": "Reason",
            "type": "string"
          },
          "threshold": {
            "title": "Threshold",
            "type": "number"
          },
          "verdict": {
            "$ref": "#/components/schemas/GuardVerdict"
          }
        },
        "required": [
          "verdict",
          "action",
          "threshold"
        ],
        "title": "GuardResult",
        "type": "object"
      },
      "GuardVerdict": {
        "description": "Overall faithfulness assessment of a generated answer (Step 4.3).\n\nPASS\n    Every extracted claim cleared the faithfulness threshold.\nFLAGGED\n    One or more claims were unsupported, but the configured\n    :class:`GuardAction` left the answer text intact (``ANNOTATE``).\nBLOCKED\n    One or more claims were unsupported and the answer was modified or\n    withheld (``REDACT`` / ``BLOCK``).",
        "enum": [
          "pass",
          "flagged",
          "blocked"
        ],
        "title": "GuardVerdict",
        "type": "string"
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "title": "Detail",
            "type": "array"
          }
        },
        "title": "HTTPValidationError",
        "type": "object"
      },
      "HealthResponse": {
        "description": "Overall gateway health plus the per-component breakdown.",
        "properties": {
          "checked_at": {
            "title": "Checked At",
            "type": "string"
          },
          "components": {
            "items": {
              "$ref": "#/components/schemas/ComponentHealth"
            },
            "title": "Components",
            "type": "array"
          },
          "service": {
            "title": "Service",
            "type": "string"
          },
          "started_at": {
            "title": "Started At",
            "type": "string"
          },
          "status": {
            "title": "Status",
            "type": "string"
          },
          "uptime_s": {
            "title": "Uptime S",
            "type": "number"
          },
          "version": {
            "title": "Version",
            "type": "string"
          }
        },
        "required": [
          "status",
          "service",
          "version",
          "uptime_s",
          "started_at",
          "checked_at",
          "components"
        ],
        "title": "HealthResponse",
        "type": "object"
      },
      "HistogramView": {
        "properties": {
          "count": {
            "title": "Count",
            "type": "integer"
          },
          "labels": {
            "additionalProperties": {
              "type": "string"
            },
            "title": "Labels",
            "type": "object"
          },
          "max": {
            "title": "Max",
            "type": "number"
          },
          "mean": {
            "title": "Mean",
            "type": "number"
          },
          "min": {
            "title": "Min",
            "type": "number"
          },
          "name": {
            "title": "Name",
            "type": "string"
          },
          "p50": {
            "title": "P50",
            "type": "number"
          },
          "p95": {
            "title": "P95",
            "type": "number"
          },
          "p99": {
            "title": "P99",
            "type": "number"
          },
          "sum": {
            "title": "Sum",
            "type": "number"
          }
        },
        "required": [
          "name",
          "labels",
          "count",
          "sum",
          "min",
          "max",
          "mean",
          "p50",
          "p95",
          "p99"
        ],
        "title": "HistogramView",
        "type": "object"
      },
      "IngestResult": {
        "description": "Per-document outcome of a single ingest-pipeline run.\n\nThe shape doubles as the gateway response body (``POST /v1/ingest/document``)\nand as the unit aggregated by ``IngestRunSummary`` when the pipeline is\ndriven from a ``Connector`` instead of a single upload.",
        "properties": {
          "blocked_chunk_count": {
            "default": 0,
            "title": "Blocked Chunk Count",
            "type": "integer"
          },
          "bytes_in": {
            "default": 0,
            "title": "Bytes In",
            "type": "integer"
          },
          "chunk_count": {
            "default": 0,
            "title": "Chunk Count",
            "type": "integer"
          },
          "document_id": {
            "title": "Document Id",
            "type": "string"
          },
          "embedding_count": {
            "default": 0,
            "title": "Embedding Count",
            "type": "integer"
          },
          "error": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Error"
          },
          "metadata": {
            "additionalProperties": true,
            "title": "Metadata",
            "type": "object"
          },
          "status": {
            "$ref": "#/components/schemas/IngestStatus"
          }
        },
        "required": [
          "document_id",
          "status"
        ],
        "title": "IngestResult",
        "type": "object"
      },
      "IngestStatus": {
        "description": "Outcome of running the ingest pipeline against a single document (Step 1.10).\n\nThe set is deliberately small — the gateway response, the CLI summary,\nand the audit log all key off these values.",
        "enum": [
          "ingested",
          "blocked_by_policy",
          "skipped_empty",
          "failed"
        ],
        "title": "IngestStatus",
        "type": "string"
      },
      "LogRecordView": {
        "description": "One structured log record as served to the console.",
        "properties": {
          "event": {
            "title": "Event",
            "type": "string"
          },
          "fields": {
            "additionalProperties": true,
            "title": "Fields",
            "type": "object"
          },
          "level": {
            "title": "Level",
            "type": "string"
          },
          "module": {
            "title": "Module",
            "type": "string"
          },
          "msg": {
            "title": "Msg",
            "type": "string"
          },
          "seq": {
            "title": "Seq",
            "type": "integer"
          },
          "span_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Span Id"
          },
          "tenant_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Tenant Id"
          },
          "trace_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Trace Id"
          },
          "ts": {
            "title": "Ts",
            "type": "string"
          }
        },
        "required": [
          "seq",
          "ts",
          "level",
          "module",
          "msg",
          "event"
        ],
        "title": "LogRecordView",
        "type": "object"
      },
      "LogsResponse": {
        "properties": {
          "capacity": {
            "title": "Capacity",
            "type": "integer"
          },
          "max_seq": {
            "title": "Max Seq",
            "type": "integer"
          },
          "records": {
            "items": {
              "$ref": "#/components/schemas/LogRecordView"
            },
            "title": "Records",
            "type": "array"
          },
          "returned": {
            "title": "Returned",
            "type": "integer"
          }
        },
        "required": [
          "records",
          "returned",
          "max_seq",
          "capacity"
        ],
        "title": "LogsResponse",
        "type": "object"
      },
      "MetricsResponse": {
        "description": "A point-in-time snapshot of every metric series + process info.",
        "properties": {
          "captured_at": {
            "title": "Captured At",
            "type": "string"
          },
          "counters": {
            "items": {
              "$ref": "#/components/schemas/CounterView"
            },
            "title": "Counters",
            "type": "array"
          },
          "gauges": {
            "items": {
              "$ref": "#/components/schemas/GaugeView"
            },
            "title": "Gauges",
            "type": "array"
          },
          "histograms": {
            "items": {
              "$ref": "#/components/schemas/HistogramView"
            },
            "title": "Histograms",
            "type": "array"
          },
          "process": {
            "$ref": "#/components/schemas/ProcessInfo"
          }
        },
        "required": [
          "captured_at",
          "process",
          "counters",
          "gauges",
          "histograms"
        ],
        "title": "MetricsResponse",
        "type": "object"
      },
      "ModelList": {
        "description": "``GET /v1/models`` response (OpenAI-compatible).",
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/ModelObject"
            },
            "title": "Data",
            "type": "array"
          },
          "object": {
            "const": "list",
            "default": "list",
            "title": "Object",
            "type": "string"
          }
        },
        "title": "ModelList",
        "type": "object"
      },
      "ModelObject": {
        "description": "One model in the ``GET /v1/models`` listing.",
        "properties": {
          "created": {
            "title": "Created",
            "type": "integer"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "object": {
            "const": "model",
            "default": "model",
            "title": "Object",
            "type": "string"
          },
          "owned_by": {
            "default": "agent-context-os",
            "title": "Owned By",
            "type": "string"
          }
        },
        "required": [
          "id"
        ],
        "title": "ModelObject",
        "type": "object"
      },
      "NLILabel": {
        "description": "Natural-language-inference relation between a premise and a hypothesis.\n\nStep 4.3.  The hallucination guard treats the *retrieved context* as the\npremise and each *claim extracted from the generated answer* as the\nhypothesis:\n\nENTAILMENT\n    The context supports the claim — the claim is grounded.\nNEUTRAL\n    The context neither supports nor refutes the claim — the claim is\n    unsupported (a potential hallucination: nothing in the evidence backs\n    it).\nCONTRADICTION\n    The context refutes the claim — the claim conflicts with the evidence\n    (the most serious failure).",
        "enum": [
          "entailment",
          "neutral",
          "contradiction"
        ],
        "title": "NLILabel",
        "type": "string"
      },
      "OpenAIError": {
        "description": "OpenAI-style error envelope: ``{\"error\": {...}}``.\n\nOpenAI clients parse this shape, so 4xx / 5xx responses on the\n``/v1/embeddings`` + ``/v1/chat/completions`` routes use it instead of\nthe platform's :class:`~rag_core.gateway_types.GatewayError` envelope.",
        "properties": {
          "error": {
            "$ref": "#/components/schemas/OpenAIErrorDetail"
          }
        },
        "required": [
          "error"
        ],
        "title": "OpenAIError",
        "type": "object"
      },
      "OpenAIErrorDetail": {
        "description": "The ``error`` object inside an OpenAI-style error body.",
        "properties": {
          "code": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Code"
          },
          "message": {
            "title": "Message",
            "type": "string"
          },
          "param": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Param"
          },
          "type": {
            "default": "invalid_request_error",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "message"
        ],
        "title": "OpenAIErrorDetail",
        "type": "object"
      },
      "PackedContext": {
        "description": "Output of :class:`ContextPacker` (Step 2.8).\n\nThe packer takes the reranker's ``list[Chunk]``, drops duplicates,\nfits the survivors into a token budget, orders them for LLM\nattention, and annotates any detected conflicts.  Citations are\ndeliberately NOT computed here — they're a gateway concern that\nruns after the LLM answer is shaped (so position_in_context can\nreference final prompt offsets).",
        "properties": {
          "chunks": {
            "items": {
              "$ref": "#/components/schemas/Chunk"
            },
            "title": "Chunks",
            "type": "array"
          },
          "chunks_in": {
            "title": "Chunks In",
            "type": "integer"
          },
          "conflicts": {
            "items": {
              "$ref": "#/components/schemas/ConflictAnnotation"
            },
            "title": "Conflicts",
            "type": "array"
          },
          "dropped_budget": {
            "title": "Dropped Budget",
            "type": "integer"
          },
          "dropped_dedup": {
            "title": "Dropped Dedup",
            "type": "integer"
          },
          "elapsed_ms": {
            "title": "Elapsed Ms",
            "type": "number"
          },
          "tokenizer": {
            "title": "Tokenizer",
            "type": "string"
          },
          "tokens_budget": {
            "title": "Tokens Budget",
            "type": "integer"
          },
          "tokens_used": {
            "title": "Tokens Used",
            "type": "integer"
          }
        },
        "required": [
          "chunks",
          "tokens_used",
          "tokens_budget",
          "chunks_in",
          "dropped_dedup",
          "dropped_budget",
          "tokenizer",
          "elapsed_ms"
        ],
        "title": "PackedContext",
        "type": "object"
      },
      "ProcessInfo": {
        "properties": {
          "pid": {
            "title": "Pid",
            "type": "integer"
          },
          "platform": {
            "title": "Platform",
            "type": "string"
          },
          "python": {
            "title": "Python",
            "type": "string"
          },
          "started_at": {
            "title": "Started At",
            "type": "string"
          },
          "uptime_s": {
            "title": "Uptime S",
            "type": "number"
          }
        },
        "required": [
          "pid",
          "python",
          "platform",
          "uptime_s",
          "started_at"
        ],
        "title": "ProcessInfo",
        "type": "object"
      },
      "ProvenanceCitation": {
        "description": "One evidence pointer captured in a provenance record (Step 5.1).\n\nA locator, not content: which chunk of which document, from where, and at\nwhat retrieval score — enough to re-fetch and re-verify the evidence behind\nan answer without persisting the excerpt text.",
        "properties": {
          "chunk_id": {
            "title": "Chunk Id",
            "type": "string"
          },
          "document_id": {
            "title": "Document Id",
            "type": "string"
          },
          "score": {
            "default": 0.0,
            "title": "Score",
            "type": "number"
          },
          "source_uri": {
            "default": "",
            "title": "Source Uri",
            "type": "string"
          }
        },
        "required": [
          "chunk_id",
          "document_id"
        ],
        "title": "ProvenanceCitation",
        "type": "object"
      },
      "ProvenanceRecord": {
        "description": "Tamper-evident record of what produced one answer (Step 5.1).\n\nCaptured at the gateway after a ``/v1/query`` (or ``/v1/retrieve``) and signed\n(HMAC-SHA256) by :class:`~rag_provenance.signer.ProvenanceSigner` so the chain\n``query → routing → evidence → answer`` can be audited and independently\nre-verified later.  Privacy by default: the query and answer are persisted as\nSHA-256 hashes; raw text is captured only when the operator opts in\n(``provenance.capture_query_text`` / ``capture_answer_text``).",
        "properties": {
          "answer_hash": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Answer Hash"
          },
          "answer_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Answer Id"
          },
          "backends_used": {
            "items": {
              "type": "string"
            },
            "title": "Backends Used",
            "type": "array"
          },
          "citations": {
            "items": {
              "$ref": "#/components/schemas/ProvenanceCitation"
            },
            "title": "Citations",
            "type": "array"
          },
          "corpus_ids": {
            "items": {
              "type": "string"
            },
            "title": "Corpus Ids",
            "type": "array"
          },
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "model": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Model"
          },
          "principal_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Principal Id"
          },
          "query_hash": {
            "default": "",
            "title": "Query Hash",
            "type": "string"
          },
          "query_text": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Query Text"
          },
          "request_id": {
            "title": "Request Id",
            "type": "string"
          },
          "routing_reason": {
            "default": "",
            "title": "Routing Reason",
            "type": "string"
          },
          "routing_shape": {
            "default": "",
            "title": "Routing Shape",
            "type": "string"
          },
          "schema_version": {
            "default": "1.0",
            "title": "Schema Version",
            "type": "string"
          },
          "surface": {
            "default": "",
            "title": "Surface",
            "type": "string"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          },
          "timings_ms": {
            "additionalProperties": {
              "type": "number"
            },
            "title": "Timings Ms",
            "type": "object"
          },
          "trace_id": {
            "title": "Trace Id",
            "type": "string"
          }
        },
        "required": [
          "request_id",
          "trace_id",
          "tenant_id"
        ],
        "title": "ProvenanceRecord",
        "type": "object"
      },
      "ProvenanceSignature": {
        "description": "Detached HMAC signature over a :class:`ProvenanceRecord` (Step 5.1).\n\n``timestamp`` (unix seconds) is bound into the signed string — the same\nscheme as webhook signing — so a verifier can also reason about record age.",
        "properties": {
          "algorithm": {
            "default": "HMAC-SHA256",
            "title": "Algorithm",
            "type": "string"
          },
          "key_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Key Id"
          },
          "timestamp": {
            "default": 0,
            "title": "Timestamp",
            "type": "integer"
          },
          "value": {
            "default": "",
            "title": "Value",
            "type": "string"
          }
        },
        "title": "ProvenanceSignature",
        "type": "object"
      },
      "ProvenanceVerification": {
        "description": "Result of verifying a :class:`SignedProvenanceRecord` (Step 5.1).",
        "properties": {
          "reason": {
            "default": "",
            "title": "Reason",
            "type": "string"
          },
          "signed": {
            "default": false,
            "title": "Signed",
            "type": "boolean"
          },
          "verified": {
            "default": false,
            "title": "Verified",
            "type": "boolean"
          }
        },
        "title": "ProvenanceVerification",
        "type": "object"
      },
      "QueryRequest": {
        "description": "Full ``POST /v1/query`` body.\n\nThe request flags fan out across the pipeline: ``rerank=False``\nskips the cross-encoder pass; ``pack=False`` returns raw\nreranked chunks without budget-fit packing; ``generate=True``\nadditionally calls the wired ``LLM.complete`` and returns an\n:class:`Answer` envelope.\n\nDefaults are tuned for the \"🥈 curl-able RAG\" demo: rerank +\npack on, generate off (no LLM credentials required).",
        "properties": {
          "corpus_ids": {
            "description": "Restrict retrieval to these corpora.  Empty list = search every corpus the principal has read access to.",
            "items": {
              "type": "string"
            },
            "title": "Corpus Ids",
            "type": "array"
          },
          "filters": {
            "additionalProperties": true,
            "description": "Free-form FilterExpr-equivalent dict for backends that translate JSON filters into their native form.  The gateway validates it against the active FilterExpr translator.",
            "title": "Filters",
            "type": "object"
          },
          "generate": {
            "default": false,
            "description": "Call the wired LLM to produce a natural-language answer from the packed context.  Requires LLM credentials in the deployment.  Default off so the demo runs creds-free.",
            "title": "Generate",
            "type": "boolean"
          },
          "generate_max_tokens": {
            "default": 1024,
            "description": "Cap on output tokens for the LLM call.",
            "maximum": 32000.0,
            "minimum": 1.0,
            "title": "Generate Max Tokens",
            "type": "integer"
          },
          "generate_temperature": {
            "default": 0.0,
            "description": "LLM sampling temperature for the answer call.",
            "maximum": 2.0,
            "minimum": 0.0,
            "title": "Generate Temperature",
            "type": "number"
          },
          "pack": {
            "default": true,
            "description": "Apply ContextPacker budget-fit + lost-in-middle reorder.",
            "title": "Pack",
            "type": "boolean"
          },
          "pack_budget": {
            "default": 2048,
            "description": "Token budget passed to ContextPacker.  Ignored when pack=False.",
            "maximum": 128000.0,
            "minimum": 64.0,
            "title": "Pack Budget",
            "type": "integer"
          },
          "principal_id": {
            "title": "Principal Id",
            "type": "string"
          },
          "query": {
            "description": "The user's question or search input.",
            "minLength": 1,
            "title": "Query",
            "type": "string"
          },
          "request_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Optional caller-supplied request id.  When absent the gateway generates one and returns it in the response.",
            "title": "Request Id"
          },
          "rerank": {
            "default": true,
            "description": "Run the cross-encoder reranker over retrieval output.",
            "title": "Rerank",
            "type": "boolean"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          },
          "top_k": {
            "default": 10,
            "description": "Maximum number of chunks returned from retrieval (pre-rerank).",
            "maximum": 100.0,
            "minimum": 1.0,
            "title": "Top K",
            "type": "integer"
          }
        },
        "required": [
          "tenant_id",
          "principal_id",
          "query"
        ],
        "title": "QueryRequest",
        "type": "object"
      },
      "QueryResponse": {
        "description": "``POST /v1/query`` response envelope.\n\nCarries TWO chunk views so callers can pick the right one for\ntheir use case:\n\n* ``chunks`` is the hydrated, reranked output — populated when\n  ``rerank=True``.  Each entry is a full :class:`Chunk` with\n  content + metadata + ``score`` (the stage-2 relevance).\n* ``chunk_refs`` is the lightweight router output — always\n  populated when retrieval ran, even with ``rerank=False``.\n  Each entry is a :class:`ChunkRef` (id + tenant + score).\n\nWire-level separation matters: callers that skipped rerank\n(e.g. they're piping refs into their own custom reranker) get\na clean :class:`ChunkRef` shape rather than a half-populated\n:class:`Chunk`.  Both fields are always present in the\nresponse shape so downstream consumers don't have to branch\non optionality.\n\n``packed`` is present iff ``pack=True``.  ``answer`` is\npresent iff ``generate=True`` and the LLM call succeeded —\ntransient LLM failure with ``generate=True`` degrades to\n``answer=None`` with the structured-log event\n``gateway.answer.failed`` (chunks + packed context still\nreturned).",
        "properties": {
          "answer": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Answer"
              },
              {
                "type": "null"
              }
            ]
          },
          "chunk_refs": {
            "items": {
              "$ref": "#/components/schemas/ChunkRef"
            },
            "title": "Chunk Refs",
            "type": "array"
          },
          "chunks": {
            "items": {
              "$ref": "#/components/schemas/Chunk"
            },
            "title": "Chunks",
            "type": "array"
          },
          "citations": {
            "items": {
              "$ref": "#/components/schemas/Citation"
            },
            "title": "Citations",
            "type": "array"
          },
          "corpus_decision": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/CorpusRoutingDecision"
              },
              {
                "type": "null"
              }
            ]
          },
          "decision": {
            "$ref": "#/components/schemas/RoutingDecision"
          },
          "experiment": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ExperimentAssignment"
              },
              {
                "type": "null"
              }
            ]
          },
          "packed": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/PackedContext"
              },
              {
                "type": "null"
              }
            ]
          },
          "query": {
            "title": "Query",
            "type": "string"
          },
          "request_id": {
            "title": "Request Id",
            "type": "string"
          },
          "timings": {
            "$ref": "#/components/schemas/StageTimings"
          },
          "trace": {
            "$ref": "#/components/schemas/TraceContext"
          }
        },
        "required": [
          "request_id",
          "query",
          "decision"
        ],
        "title": "QueryResponse",
        "type": "object"
      },
      "QueryShape": {
        "description": "Coarse classification of an incoming query, used by the router.\n\nStep 2.10.  The router maps an :class:`~rag_query.types.UnderstoodQuery`\nonto a shape and uses it to bias backend selection + per-backend\ntop-k.  Shape detection is deliberately heuristic — the cost of a\nwrong call is small (an unused backend's results are simply ignored\nafter RRF fusion) and a richer classifier (LLM-based, learned) can\nbe slotted behind the same enum later.\n\nValues\n------\nKEYWORD_HEAVY\n    Short, term-like query (no question form, ≤ 3 tokens, no HyDE\n    signal).  Keyword path is primary; vector path is optional.\nSEMANTIC\n    Natural-language question or HyDE-augmented query.  All three\n    backends are useful; vector + keyword in fusion is the typical\n    sweet spot.\nENTITY_RICH\n    Query whose glossary expansion / decomposition surfaces multiple\n    named entities — graph + keyword get a boost; vector still runs.\nMIXED\n    Default fall-through when no specific shape rule fires.  All\n    wired backends run with equal weight.",
        "enum": [
          "keyword_heavy",
          "semantic",
          "entity_rich",
          "mixed"
        ],
        "title": "QueryShape",
        "type": "string"
      },
      "QueryTraceResponse": {
        "description": "``GET /v1/query/{id}/trace`` response envelope (Step 5.1).\n\nReturns the *signed provenance record* for a previously-executed query\n(what produced the answer — query hash, routing, evidence locators, model)\ntogether with a fresh :class:`ProvenanceVerification` (did the HMAC still\nmatch?) and the captured per-query :class:`SpanRecord` tree (the pipeline\nstages, ordered root-first).  A miss is a 404 ``GatewayError``, not an empty\n``found=False`` body — this field is always ``True`` on a 200.",
        "properties": {
          "found": {
            "default": true,
            "title": "Found",
            "type": "boolean"
          },
          "provenance": {
            "$ref": "#/components/schemas/SignedProvenanceRecord"
          },
          "request_id": {
            "title": "Request Id",
            "type": "string"
          },
          "spans": {
            "items": {
              "$ref": "#/components/schemas/SpanRecord"
            },
            "title": "Spans",
            "type": "array"
          },
          "trace_id": {
            "title": "Trace Id",
            "type": "string"
          },
          "verification": {
            "$ref": "#/components/schemas/ProvenanceVerification"
          }
        },
        "required": [
          "request_id",
          "trace_id",
          "provenance",
          "verification"
        ],
        "title": "QueryTraceResponse",
        "type": "object"
      },
      "QuotaActionResponse": {
        "description": "Result of an operator quota action (reset) — the post-reset snapshot.",
        "properties": {
          "quotas": {
            "items": {
              "$ref": "#/components/schemas/QuotaSnapshot"
            },
            "title": "Quotas",
            "type": "array"
          },
          "reset": {
            "title": "Reset",
            "type": "boolean"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          }
        },
        "required": [
          "tenant_id",
          "quotas",
          "reset"
        ],
        "title": "QuotaActionResponse",
        "type": "object"
      },
      "QuotaDimension": {
        "description": "The resource dimensions a tenant is metered on (Step 4.5).\n\nEach maps to a distinct counter in the :class:`~rag_core.spi.quota_store.\nQuotaStore`:\n\nQPS\n    Requests per second — a short sliding window guarding burst rate.\nTOKENS / COST / QUERIES\n    Monthly accruals — long sliding windows over LLM tokens consumed,\n    estimated dollar cost (tracked in micro-dollars), and request count.\nSTORAGE\n    A cumulative gauge of bytes a tenant has ingested (not time-windowed).",
        "enum": [
          "qps",
          "tokens",
          "cost",
          "queries",
          "storage"
        ],
        "title": "QuotaDimension",
        "type": "string"
      },
      "QuotaSnapshot": {
        "description": "Frozen point-in-time view of one tenant's usage on one dimension (Step 4.5).\n\nProduced by :meth:`~rag_quota.enforcer.QuotaEnforcer.snapshot`; surfaced by\nthe gateway status API (``GET /v1/status/quotas``) and the operator console.\nCarries only the tenant id (its own, never another tenant's) plus counters —\nno query or answer text — so it is safe on the status surface.  ``limit`` /\n``remaining`` are ``None`` when the dimension is uncapped; ``window_seconds``\nis ``0`` for the storage gauge.",
        "properties": {
          "dimension": {
            "$ref": "#/components/schemas/QuotaDimension"
          },
          "limit": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Limit"
          },
          "remaining": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Remaining"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          },
          "used": {
            "default": 0,
            "title": "Used",
            "type": "integer"
          },
          "window_seconds": {
            "default": 0,
            "title": "Window Seconds",
            "type": "integer"
          }
        },
        "required": [
          "tenant_id",
          "dimension"
        ],
        "title": "QuotaSnapshot",
        "type": "object"
      },
      "QuotasStatusResponse": {
        "description": "One tenant's per-dimension quota usage (Step 4.5).\n\nUnlike breakers (infra-scoped), quotas are *per tenant*, so this surface is\ntenant-aware: the tenant comes from the ``tenant_id`` query param or the\n``X-Tenant-Id`` header.  ``quotas`` reuses the domain\n:class:`~rag_core.types.QuotaSnapshot` (counters only, the tenant's own id) —\nempty when no quota enforcer is wired (quotas disabled).",
        "properties": {
          "quotas": {
            "items": {
              "$ref": "#/components/schemas/QuotaSnapshot"
            },
            "title": "Quotas",
            "type": "array"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          },
          "total": {
            "title": "Total",
            "type": "integer"
          }
        },
        "required": [
          "tenant_id",
          "quotas",
          "total"
        ],
        "title": "QuotasStatusResponse",
        "type": "object"
      },
      "RagAnnotations": {
        "description": "Retrieval metadata attached under the response's ``rag`` field.\n\nNon-standard — OpenAI clients ignore it.  RAG-aware clients read it to\nsurface citations, the query-shape the router picked, and whether the\nBM25-only fallback fired.",
        "properties": {
          "bm25_fallback": {
            "default": false,
            "title": "Bm25 Fallback",
            "type": "boolean"
          },
          "chunks_n": {
            "default": 0,
            "title": "Chunks N",
            "type": "integer"
          },
          "citations": {
            "items": {
              "$ref": "#/components/schemas/Citation"
            },
            "title": "Citations",
            "type": "array"
          },
          "enabled": {
            "default": true,
            "title": "Enabled",
            "type": "boolean"
          },
          "guard": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/GuardResult"
              },
              {
                "type": "null"
              }
            ]
          },
          "shape": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Shape"
          }
        },
        "title": "RagAnnotations",
        "type": "object"
      },
      "RagOptions": {
        "description": "Retrieval pre-fetch controls (non-standard ``rag`` request field).\n\nThese knobs mirror the retrieval-relevant fields of\n:class:`~rag_core.gateway_types.QueryRequest` so a caller gets the same\ncontrol over the RAG stage they would on ``POST /v1/query``.  When\n``enabled=False`` the gateway behaves as a plain LLM proxy (no\nretrieval, no context injection).\n\n``query`` overrides which text drives retrieval; when ``None`` the\ngateway uses the conversation's last ``user`` message.",
        "properties": {
          "corpus_ids": {
            "description": "Restrict retrieval to these corpora.  Empty = all visible.",
            "items": {
              "type": "string"
            },
            "title": "Corpus Ids",
            "type": "array"
          },
          "enabled": {
            "default": true,
            "description": "Run retrieval pre-fetch + inject context.  False = plain LLM proxy.",
            "title": "Enabled",
            "type": "boolean"
          },
          "pack": {
            "default": true,
            "description": "Apply ContextPacker budget-fit + lost-in-the-middle reorder.",
            "title": "Pack",
            "type": "boolean"
          },
          "pack_budget": {
            "default": 2048,
            "description": "Token budget passed to ContextPacker.",
            "maximum": 128000.0,
            "minimum": 64.0,
            "title": "Pack Budget",
            "type": "integer"
          },
          "query": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Override the retrieval query.  None = last user message.",
            "title": "Query"
          },
          "rerank": {
            "default": true,
            "description": "Run the cross-encoder reranker over retrieval output.",
            "title": "Rerank",
            "type": "boolean"
          },
          "top_k": {
            "default": 10,
            "description": "Maximum chunks returned from retrieval (pre-rerank).",
            "maximum": 100.0,
            "minimum": 1.0,
            "title": "Top K",
            "type": "integer"
          }
        },
        "title": "RagOptions",
        "type": "object"
      },
      "RetentionPolicy": {
        "description": "Per-data-class retention windows in days (Step 6.10).\n\n``None`` on a class means **retain indefinitely** (no purge for that class).\nThe runtime counterpart of ``cfg.compliance.retention`` — resolved per tenant\nat the boundary and consumed by the ``RetentionEnforcer``.  ``audit_days`` is\nadvisory: the tamper-evident hash chain (Step 6.6) is not purged in place —\naudit retention is the WORM **export** lifecycle — so the enforcer never drops\naudit events, it only reports the configured window.",
        "properties": {
          "audit_days": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Audit Days"
          },
          "chunks_days": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Chunks Days"
          },
          "feedback_days": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Feedback Days"
          },
          "provenance_days": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Provenance Days"
          },
          "traces_days": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Traces Days"
          }
        },
        "title": "RetentionPolicy",
        "type": "object"
      },
      "RetrieveRequest": {
        "description": "Full ``POST /v1/retrieve`` body — retrieval-only.\n\nSame identifying triple + corpus / top_k / filters as\n:class:`QueryRequest`, but no rerank / pack / generate fields:\nthis endpoint is for callers (other services, custom rerankers)\nthat want only the router's ChunkRef output.",
        "properties": {
          "corpus_ids": {
            "description": "Restrict retrieval to these corpora.  Empty list = search every corpus the principal has read access to.",
            "items": {
              "type": "string"
            },
            "title": "Corpus Ids",
            "type": "array"
          },
          "filters": {
            "additionalProperties": true,
            "description": "Free-form FilterExpr-equivalent dict for backends that translate JSON filters into their native form.  The gateway validates it against the active FilterExpr translator.",
            "title": "Filters",
            "type": "object"
          },
          "principal_id": {
            "title": "Principal Id",
            "type": "string"
          },
          "query": {
            "description": "The user's question or search input.",
            "minLength": 1,
            "title": "Query",
            "type": "string"
          },
          "request_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Optional caller-supplied request id.  When absent the gateway generates one and returns it in the response.",
            "title": "Request Id"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          },
          "top_k": {
            "default": 10,
            "description": "Maximum number of chunks returned from retrieval (pre-rerank).",
            "maximum": 100.0,
            "minimum": 1.0,
            "title": "Top K",
            "type": "integer"
          }
        },
        "required": [
          "tenant_id",
          "principal_id",
          "query"
        ],
        "title": "RetrieveRequest",
        "type": "object"
      },
      "RetrieveResponse": {
        "description": "``POST /v1/retrieve`` response envelope.\n\nRetrieval-only — :class:`ChunkRef` (ID + score + tenant) rather\nthan fully-hydrated :class:`Chunk`, so the wire payload stays\nsmall.  Callers wanting full chunks should use\n:class:`QueryResponse` (which hydrates via the reranker stage).",
        "properties": {
          "chunks": {
            "items": {
              "$ref": "#/components/schemas/ChunkRef"
            },
            "title": "Chunks",
            "type": "array"
          },
          "corpus_decision": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/CorpusRoutingDecision"
              },
              {
                "type": "null"
              }
            ]
          },
          "decision": {
            "$ref": "#/components/schemas/RoutingDecision"
          },
          "experiment": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ExperimentAssignment"
              },
              {
                "type": "null"
              }
            ]
          },
          "query": {
            "title": "Query",
            "type": "string"
          },
          "request_id": {
            "title": "Request Id",
            "type": "string"
          },
          "timings": {
            "$ref": "#/components/schemas/StageTimings"
          },
          "trace": {
            "$ref": "#/components/schemas/TraceContext"
          }
        },
        "required": [
          "request_id",
          "query",
          "decision"
        ],
        "title": "RetrieveResponse",
        "type": "object"
      },
      "RoutingDecision": {
        "description": "Frozen output of the retrieval router's decision step.\n\nStep 2.10.  Produced by\n:meth:`~rag_retrieval.router.RetrievalRouter.decide` and consumed by\n:meth:`~rag_retrieval.router.RetrievalRouter.route` (or by any caller\nthat wants to log / replay the decision separately from execution).\n\nThe three ``use_*`` booleans are the per-call routing flags handed\nto :class:`~rag_retrieval.hybrid.HybridRetriever` — they collapse the\nshape + health + caller-input signals into the form\n``HybridRetriever`` already accepts via the ``vector`` /\n``query_text`` / ``graph_seeds`` arguments (``None`` = skip).\n\n``bm25_fallback`` is set when the only healthy retrieval source is\nkeyword: it carries no semantic meaning beyond the flag itself, but\nis surfaced both in the OTel ``retrieve.route`` span and in the\nstructured-log event so operators can dashboard fallback rates.\n\n``reason`` is a short, human-readable explanation for the decision\n(e.g. ``\"shape=KEYWORD_HEAVY\"``, ``\"vector+graph degraded\"``).  It\nis advisory — never parse it in production code.",
        "properties": {
          "bm25_fallback": {
            "default": false,
            "title": "Bm25 Fallback",
            "type": "boolean"
          },
          "degraded_backends": {
            "items": {
              "type": "string"
            },
            "title": "Degraded Backends",
            "type": "array"
          },
          "reason": {
            "default": "",
            "title": "Reason",
            "type": "string"
          },
          "shape": {
            "$ref": "#/components/schemas/QueryShape"
          },
          "use_graph": {
            "title": "Use Graph",
            "type": "boolean"
          },
          "use_keyword": {
            "title": "Use Keyword",
            "type": "boolean"
          },
          "use_vector": {
            "title": "Use Vector",
            "type": "boolean"
          },
          "weights": {
            "default": [
              1.0,
              1.0,
              1.0
            ],
            "maxItems": 3,
            "minItems": 3,
            "prefixItems": [
              {
                "type": "number"
              },
              {
                "type": "number"
              },
              {
                "type": "number"
              }
            ],
            "title": "Weights",
            "type": "array"
          }
        },
        "required": [
          "shape",
          "use_vector",
          "use_keyword",
          "use_graph"
        ],
        "title": "RoutingDecision",
        "type": "object"
      },
      "ScimEmail": {
        "description": "One entry of the SCIM 2.0 multi-valued ``emails`` attribute.",
        "properties": {
          "primary": {
            "default": false,
            "title": "Primary",
            "type": "boolean"
          },
          "type": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Type"
          },
          "value": {
            "title": "Value",
            "type": "string"
          }
        },
        "required": [
          "value"
        ],
        "title": "ScimEmail",
        "type": "object"
      },
      "ScimGroup": {
        "description": "A provisioned SCIM 2.0 Group resource (RFC 7643 §4.2, Step 6.8).\n\nTenant-scoped like :class:`ScimUser`; ``display_name`` is unique within a\ntenant.  ``members`` references provisioned users by SCIM id.  Group\nmembership is what an OIDC/SAML ``groups`` claim maps onto for ACL labels.",
        "properties": {
          "displayName": {
            "title": "Displayname",
            "type": "string"
          },
          "externalId": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Externalid"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "members": {
            "items": {
              "$ref": "#/components/schemas/ScimMember"
            },
            "title": "Members",
            "type": "array"
          },
          "meta": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ScimResourceMeta"
              },
              {
                "type": "null"
              }
            ]
          },
          "schemas": {
            "default": [
              "urn:ietf:params:scim:schemas:core:2.0:Group"
            ],
            "items": {
              "type": "string"
            },
            "title": "Schemas",
            "type": "array"
          }
        },
        "required": [
          "displayName"
        ],
        "title": "ScimGroup",
        "type": "object"
      },
      "ScimGroupRef": {
        "description": "A user's group membership, as surfaced on ``User.groups`` (read-only).",
        "properties": {
          "display": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Display"
          },
          "value": {
            "title": "Value",
            "type": "string"
          }
        },
        "required": [
          "value"
        ],
        "title": "ScimGroupRef",
        "type": "object"
      },
      "ScimListResponse": {
        "description": "SCIM 2.0 ListResponse envelope (RFC 7644 §3.4.2, Step 6.8).\n\nWraps a page of provisioned resources.  ``resources`` holds each resource\nalready serialised in its SCIM wire shape (camelCase), so a Users page and a\nGroups page share one envelope.  ``total_results`` is the unpaged count;\n``start_index`` / ``items_per_page`` echo the request paging.",
        "properties": {
          "Resources": {
            "items": {
              "additionalProperties": true,
              "type": "object"
            },
            "title": "Resources",
            "type": "array"
          },
          "itemsPerPage": {
            "default": 0,
            "title": "Itemsperpage",
            "type": "integer"
          },
          "schemas": {
            "default": [
              "urn:ietf:params:scim:api:messages:2.0:ListResponse"
            ],
            "items": {
              "type": "string"
            },
            "title": "Schemas",
            "type": "array"
          },
          "startIndex": {
            "default": 1,
            "title": "Startindex",
            "type": "integer"
          },
          "totalResults": {
            "default": 0,
            "title": "Totalresults",
            "type": "integer"
          }
        },
        "title": "ScimListResponse",
        "type": "object"
      },
      "ScimMember": {
        "description": "One entry of a group's ``members`` attribute (a reference to a user).",
        "properties": {
          "display": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Display"
          },
          "value": {
            "title": "Value",
            "type": "string"
          }
        },
        "required": [
          "value"
        ],
        "title": "ScimMember",
        "type": "object"
      },
      "ScimName": {
        "description": "SCIM 2.0 ``name`` complex attribute (RFC 7643 §4.1.1).",
        "properties": {
          "familyName": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Familyname"
          },
          "formatted": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Formatted"
          },
          "givenName": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Givenname"
          }
        },
        "title": "ScimName",
        "type": "object"
      },
      "ScimPatchOp": {
        "description": "SCIM 2.0 PatchOp request body (RFC 7644 §3.5.2, Step 6.8).\n\n``operations`` is the ordered list of ``{op, path?, value}`` mutations an IdP\nsends — most importantly the deactivation patch (``op: replace`` of\n``active`` to ``false``) that revokes a user without deleting the record.",
        "properties": {
          "Operations": {
            "items": {
              "additionalProperties": true,
              "type": "object"
            },
            "title": "Operations",
            "type": "array"
          },
          "schemas": {
            "default": [
              "urn:ietf:params:scim:api:messages:2.0:PatchOp"
            ],
            "items": {
              "type": "string"
            },
            "title": "Schemas",
            "type": "array"
          }
        },
        "title": "ScimPatchOp",
        "type": "object"
      },
      "ScimResourceMeta": {
        "description": "SCIM 2.0 ``meta`` complex attribute (RFC 7643 §3.1).",
        "properties": {
          "created": {
            "format": "date-time",
            "title": "Created",
            "type": "string"
          },
          "lastModified": {
            "format": "date-time",
            "title": "Lastmodified",
            "type": "string"
          },
          "location": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Location"
          },
          "resourceType": {
            "title": "Resourcetype",
            "type": "string"
          },
          "version": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Version"
          }
        },
        "required": [
          "resourceType"
        ],
        "title": "ScimResourceMeta",
        "type": "object"
      },
      "ScimUser": {
        "description": "A provisioned SCIM 2.0 User resource (RFC 7643 §4.1, Step 6.8).\n\nPersisted through the tenant-scoped :class:`~rag_core.spi.scim_store.ScimStore`\n— tenant isolation comes from the store key (``ctx.tenant_id``), so the\nresource itself carries no tenant id and serialises as the exact SCIM wire\nshape (camelCase via field aliases).  ``user_name`` is unique within a tenant;\n``active`` is the deprovisioning switch an IdP flips to revoke access.",
        "properties": {
          "active": {
            "default": true,
            "title": "Active",
            "type": "boolean"
          },
          "displayName": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Displayname"
          },
          "emails": {
            "items": {
              "$ref": "#/components/schemas/ScimEmail"
            },
            "title": "Emails",
            "type": "array"
          },
          "externalId": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Externalid"
          },
          "groups": {
            "items": {
              "$ref": "#/components/schemas/ScimGroupRef"
            },
            "title": "Groups",
            "type": "array"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "meta": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ScimResourceMeta"
              },
              {
                "type": "null"
              }
            ]
          },
          "name": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ScimName"
              },
              {
                "type": "null"
              }
            ]
          },
          "schemas": {
            "default": [
              "urn:ietf:params:scim:schemas:core:2.0:User"
            ],
            "items": {
              "type": "string"
            },
            "title": "Schemas",
            "type": "array"
          },
          "userName": {
            "title": "Username",
            "type": "string"
          }
        },
        "required": [
          "userName"
        ],
        "title": "ScimUser",
        "type": "object"
      },
      "SignedProvenanceRecord": {
        "description": "A provenance record bundled with its signature (Step 5.1).\n\n``signature`` is ``None`` when no signing secret is configured — the record\nis still captured and retrievable, just not tamper-evident.  Production sets\n``provenance.signing_secret`` to enable signing.",
        "properties": {
          "record": {
            "$ref": "#/components/schemas/ProvenanceRecord"
          },
          "signature": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ProvenanceSignature"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "record"
        ],
        "title": "SignedProvenanceRecord",
        "type": "object"
      },
      "SpanRecord": {
        "description": "A finished OTel span captured for per-query trace replay (Step 5.1).\n\nProduced by the ``TraceCollector`` span processor (rag-observability) and\nreturned by ``GET /v1/query/{id}/trace``.  A flattened, JSON-safe view of one\nspan: its name, ids, timing, status, and ``rag.*`` attributes.  It carries no\nraw query or answer text — those are never span attributes.",
        "properties": {
          "attributes": {
            "additionalProperties": true,
            "title": "Attributes",
            "type": "object"
          },
          "duration_ms": {
            "default": 0.0,
            "title": "Duration Ms",
            "type": "number"
          },
          "end_unix_nano": {
            "default": 0,
            "title": "End Unix Nano",
            "type": "integer"
          },
          "name": {
            "title": "Name",
            "type": "string"
          },
          "parent_span_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Parent Span Id"
          },
          "span_id": {
            "title": "Span Id",
            "type": "string"
          },
          "start_unix_nano": {
            "default": 0,
            "title": "Start Unix Nano",
            "type": "integer"
          },
          "status": {
            "default": "unset",
            "title": "Status",
            "type": "string"
          },
          "trace_id": {
            "default": "",
            "title": "Trace Id",
            "type": "string"
          }
        },
        "required": [
          "name",
          "span_id"
        ],
        "title": "SpanRecord",
        "type": "object"
      },
      "SsoStatusResponse": {
        "description": "``GET /v1/status/sso`` response — federation + provisioning posture (Step 6.8).\n\nReports the global ``sso`` / ``scim`` enablement plus the **calling tenant's**\nown federation status (whether an IdP is configured for it, and which\nprotocol).  Tenant-scoped by design — it never lists other tenants' config.",
        "properties": {
          "scim_enabled": {
            "default": false,
            "title": "Scim Enabled",
            "type": "boolean"
          },
          "sso_enabled": {
            "default": false,
            "title": "Sso Enabled",
            "type": "boolean"
          },
          "tenant": {
            "$ref": "#/components/schemas/SsoTenantStatus"
          }
        },
        "required": [
          "tenant"
        ],
        "title": "SsoStatusResponse",
        "type": "object"
      },
      "SsoTenantStatus": {
        "description": "The calling tenant's SSO posture, embedded in :class:`SsoStatusResponse`.",
        "properties": {
          "configured": {
            "default": false,
            "title": "Configured",
            "type": "boolean"
          },
          "protocol": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Protocol"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          }
        },
        "required": [
          "tenant_id"
        ],
        "title": "SsoTenantStatus",
        "type": "object"
      },
      "StageTimings": {
        "description": "Wall-time attribution across the per-stage pipeline.\n\nStep 3.1.  Each field is the wall-time spent inside the named\nstage, in milliseconds.  Stages that didn't run (e.g.\n``rerank=False``) report ``None`` so consumers can distinguish\n\"skipped\" from \"ran-in-zero-ms\".",
        "properties": {
          "generate_ms": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Generate Ms"
          },
          "pack_ms": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Pack Ms"
          },
          "rerank_ms": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Rerank Ms"
          },
          "route_ms": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Route Ms"
          },
          "total_ms": {
            "default": 0.0,
            "title": "Total Ms",
            "type": "number"
          },
          "understand_ms": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Understand Ms"
          }
        },
        "title": "StageTimings",
        "type": "object"
      },
      "SubscriptionList": {
        "description": "``GET /v1/webhooks/subscriptions`` response.",
        "properties": {
          "subscriptions": {
            "items": {
              "$ref": "#/components/schemas/WebhookSubscription"
            },
            "title": "Subscriptions",
            "type": "array"
          },
          "total": {
            "default": 0,
            "title": "Total",
            "type": "integer"
          }
        },
        "title": "SubscriptionList",
        "type": "object"
      },
      "TenantStatusResponse": {
        "description": "One tenant's resolved logical-tenancy settings (Step 6.1).\n\nThe effective per-tenant view the gateway applies to each request, resolved by\nthe :class:`~rag_config.tenancy.TenantResolver` from ``cfg.tenants``.  ``known``\nis whether the tenant is declared in ``rag.yaml`` — an unknown tenant resolves\nto safe defaults (namespace = the tenant id, default PII action, no labels), so\nit is isolated rather than privileged.  Per-tenant like quotas / cost: the\ntenant comes from the ``tenant_id`` query param or the ``X-Tenant-Id`` header.",
        "properties": {
          "acl_labels": {
            "items": {
              "type": "string"
            },
            "title": "Acl Labels",
            "type": "array"
          },
          "dedicated_index": {
            "default": false,
            "title": "Dedicated Index",
            "type": "boolean"
          },
          "known": {
            "default": false,
            "title": "Known",
            "type": "boolean"
          },
          "namespace": {
            "default": "",
            "title": "Namespace",
            "type": "string"
          },
          "physical_index": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Physical Index"
          },
          "pii_action": {
            "default": "redact",
            "title": "Pii Action",
            "type": "string"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          }
        },
        "required": [
          "tenant_id"
        ],
        "title": "TenantStatusResponse",
        "type": "object"
      },
      "TraceContext": {
        "description": "OTel-compatible trace context propagated through every pipeline step.",
        "properties": {
          "parent_span_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Parent Span Id"
          },
          "sampled": {
            "default": true,
            "title": "Sampled",
            "type": "boolean"
          },
          "span_id": {
            "title": "Span Id",
            "type": "string"
          },
          "trace_id": {
            "title": "Trace Id",
            "type": "string"
          }
        },
        "title": "TraceContext",
        "type": "object"
      },
      "TrustLevel": {
        "description": "Provenance of a chunk's text — used by the prompt-injection defense.\n\n``trusted``        — first-party content authored under tenant control.\n``ingested``       — content fetched from a known external source (vetted feed,\n                     enterprise SharePoint, etc.).\n``user_supplied``  — content directly contributed by an end-user channel\n                     (web upload, chat-attached file, …) which may contain\n                     adversarial instructions.",
        "enum": [
          "trusted",
          "ingested",
          "user_supplied"
        ],
        "title": "TrustLevel",
        "type": "string"
      },
      "UpdateCorpusRequest": {
        "description": "``PATCH /v1/corpora/{id}`` body — partial update of mutable fields.\n\nPATCH semantics: only the fields present in the request change; omitted\nfields are left untouched.  ``embedding_model`` / ``embedding_dimension``\nare intentionally **not** updatable — they define the corpus's vector\nspace, and changing them would invalidate every embedding already indexed\nunder it.  ``id`` / ``tenant_id`` / ``document_count`` are likewise\nimmutable from this surface.",
        "properties": {
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "New description (omit to leave unchanged).",
            "title": "Description"
          },
          "display_name": {
            "anyOf": [
              {
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "New display name (omit to leave unchanged).",
            "title": "Display Name"
          },
          "metadata": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "description": "Replacement metadata blob (omit to leave unchanged).",
            "title": "Metadata"
          }
        },
        "title": "UpdateCorpusRequest",
        "type": "object"
      },
      "UpdateSubscriptionRequest": {
        "description": "``PATCH /v1/webhooks/subscriptions/{id}`` body — partial update.\n\nPATCH semantics: only the fields present in the request change.  The signing\n``secret`` and ``id`` are immutable from this surface (rotate the secret by\nrecreating the subscription); ``active`` toggles delivery on/off.",
        "properties": {
          "active": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "description": "Enable/disable delivery (omit to keep).",
            "title": "Active"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "New description (omit to keep).",
            "title": "Description"
          },
          "event_types": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/WebhookEventType"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "description": "Replacement event allow-list (omit to keep).",
            "title": "Event Types"
          },
          "url": {
            "anyOf": [
              {
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "New endpoint (omit to keep).",
            "title": "Url"
          }
        },
        "title": "UpdateSubscriptionRequest",
        "type": "object"
      },
      "ValidationError": {
        "properties": {
          "ctx": {
            "title": "Context",
            "type": "object"
          },
          "input": {
            "title": "Input"
          },
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "title": "Location",
            "type": "array"
          },
          "msg": {
            "title": "Message",
            "type": "string"
          },
          "type": {
            "title": "Error Type",
            "type": "string"
          }
        },
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError",
        "type": "object"
      },
      "WebhookDelivery": {
        "description": "The outcome of delivering one event to one subscription (all attempts).",
        "properties": {
          "attempts": {
            "items": {
              "$ref": "#/components/schemas/WebhookDeliveryAttempt"
            },
            "title": "Attempts",
            "type": "array"
          },
          "event_id": {
            "title": "Event Id",
            "type": "string"
          },
          "event_type": {
            "$ref": "#/components/schemas/WebhookEventType"
          },
          "status": {
            "$ref": "#/components/schemas/DeliveryStatus"
          },
          "subscription_id": {
            "title": "Subscription Id",
            "type": "string"
          },
          "url": {
            "title": "Url",
            "type": "string"
          }
        },
        "required": [
          "event_id",
          "event_type",
          "subscription_id",
          "url",
          "status"
        ],
        "title": "WebhookDelivery",
        "type": "object"
      },
      "WebhookDeliveryAttempt": {
        "description": "One HTTP POST attempt to a subscription.",
        "properties": {
          "at": {
            "format": "date-time",
            "title": "At",
            "type": "string"
          },
          "attempt": {
            "title": "Attempt",
            "type": "integer"
          },
          "duration_ms": {
            "default": 0.0,
            "title": "Duration Ms",
            "type": "number"
          },
          "error": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Error"
          },
          "ok": {
            "title": "Ok",
            "type": "boolean"
          },
          "status_code": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Status Code"
          }
        },
        "required": [
          "attempt",
          "ok"
        ],
        "title": "WebhookDeliveryAttempt",
        "type": "object"
      },
      "WebhookEvent": {
        "description": "The signed JSON body POSTed to a subscriber.\n\n``id`` is stable across retries, so subscribers dedupe on it (delivery is\nat-least-once).  ``data`` is the event-specific payload — its shape depends\non ``type`` (e.g. an ``IngestResult`` dump for ``ingest.completed``).\n``request_id`` / ``trace_id`` carry the originating request's correlation\nids so a subscriber can tie the event back to a gateway trace.",
        "properties": {
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "data": {
            "additionalProperties": true,
            "title": "Data",
            "type": "object"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "principal_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Principal Id"
          },
          "request_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Request Id"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          },
          "trace_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Trace Id"
          },
          "type": {
            "$ref": "#/components/schemas/WebhookEventType"
          }
        },
        "required": [
          "type",
          "tenant_id"
        ],
        "title": "WebhookEvent",
        "type": "object"
      },
      "WebhookEventType": {
        "description": "The catalogue of domain events the platform can emit.\n\n``ingest.completed`` and ``audit.policy_violation`` have live emitters as\nof Step 3.9 (the ingest pipeline + the policy engine).  ``drift.detected``\nand ``eval.regression`` are defined here so subscribers can register for\nthem now; their emitters land with the Phase 5 eval / observability work.",
        "enum": [
          "ingest.completed",
          "drift.detected",
          "eval.regression",
          "audit.policy_violation"
        ],
        "title": "WebhookEventType",
        "type": "string"
      },
      "WebhookSubscription": {
        "description": "A tenant-scoped delivery target.\n\n``event_types`` is the allow-list of events to deliver; an **empty** list\nmeans \"all event types\".  ``secret`` is the HMAC-SHA256 signing key — it is\nmasked by :meth:`redacted` everywhere except the one-time create response,\nso it never leaks on subsequent reads.",
        "properties": {
          "active": {
            "default": true,
            "title": "Active",
            "type": "boolean"
          },
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "description": {
            "default": "",
            "title": "Description",
            "type": "string"
          },
          "event_types": {
            "items": {
              "$ref": "#/components/schemas/WebhookEventType"
            },
            "title": "Event Types",
            "type": "array"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "metadata": {
            "additionalProperties": true,
            "title": "Metadata",
            "type": "object"
          },
          "secret": {
            "title": "Secret",
            "type": "string"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          },
          "url": {
            "title": "Url",
            "type": "string"
          }
        },
        "required": [
          "tenant_id",
          "url"
        ],
        "title": "WebhookSubscription",
        "type": "object"
      },
      "WebhookTestResult": {
        "description": "``POST /v1/webhooks/subscriptions/{id}/test`` response.",
        "properties": {
          "delivery": {
            "$ref": "#/components/schemas/WebhookDelivery"
          },
          "event": {
            "$ref": "#/components/schemas/WebhookEvent"
          }
        },
        "required": [
          "event",
          "delivery"
        ],
        "title": "WebhookTestResult",
        "type": "object"
      }
    }
  },
  "info": {
    "description": "RAG gateway.  Native routes for ingest, query, retrieve, and corpus discovery, plus OpenAI-compatible /v1/embeddings and /v1/chat/completions (with retrieval pre-fetch).  Operator status surface at /v1/status/* (health, metrics, logs tail + SSE/WS).  OpenAPI 3.1 at /openapi.json; Swagger UI at /docs.",
    "title": "AgentContextOS Gateway",
    "version": "0.10.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/healthz": {
      "get": {
        "operationId": "healthz_healthz_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": {
                    "type": "string"
                  },
                  "title": "Response Healthz Healthz Get",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "summary": "Healthz",
        "tags": [
          "health"
        ]
      }
    },
    "/readyz": {
      "get": {
        "description": "Readiness probe — all wiring happens in the app factory, so a\nserved response means the app is fully constructed and routable.",
        "operationId": "readyz_readyz_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": {
                    "type": "string"
                  },
                  "title": "Response Readyz Readyz Get",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "summary": "Readyz",
        "tags": [
          "health"
        ]
      }
    },
    "/scim/v2/Groups": {
      "get": {
        "operationId": "list_groups_scim_v2_Groups_get",
        "parameters": [
          {
            "in": "query",
            "name": "startIndex",
            "required": false,
            "schema": {
              "default": 1,
              "minimum": 1,
              "title": "Startindex",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "count",
            "required": false,
            "schema": {
              "default": 100,
              "minimum": 0,
              "title": "Count",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "filter",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Filter"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScimListResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "List Groups",
        "tags": [
          "scim"
        ]
      },
      "post": {
        "operationId": "create_group_scim_v2_Groups_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ScimGroup"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScimGroup"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Create Group",
        "tags": [
          "scim"
        ]
      }
    },
    "/scim/v2/Groups/{group_id}": {
      "delete": {
        "operationId": "delete_group_scim_v2_Groups__group_id__delete",
        "parameters": [
          {
            "in": "path",
            "name": "group_id",
            "required": true,
            "schema": {
              "title": "Group Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Delete Group",
        "tags": [
          "scim"
        ]
      },
      "get": {
        "operationId": "get_group_scim_v2_Groups__group_id__get",
        "parameters": [
          {
            "in": "path",
            "name": "group_id",
            "required": true,
            "schema": {
              "title": "Group Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScimGroup"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Get Group",
        "tags": [
          "scim"
        ]
      },
      "put": {
        "operationId": "replace_group_scim_v2_Groups__group_id__put",
        "parameters": [
          {
            "in": "path",
            "name": "group_id",
            "required": true,
            "schema": {
              "title": "Group Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ScimGroup"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScimGroup"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Replace Group",
        "tags": [
          "scim"
        ]
      }
    },
    "/scim/v2/ResourceTypes": {
      "get": {
        "operationId": "resource_types_scim_v2_ResourceTypes_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "title": "Response Resource Types Scim V2 Resourcetypes Get"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "summary": "Resource Types",
        "tags": [
          "scim"
        ]
      }
    },
    "/scim/v2/ServiceProviderConfig": {
      "get": {
        "operationId": "service_provider_config_scim_v2_ServiceProviderConfig_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "title": "Response Service Provider Config Scim V2 Serviceproviderconfig Get"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "summary": "Service Provider Config",
        "tags": [
          "scim"
        ]
      }
    },
    "/scim/v2/Users": {
      "get": {
        "operationId": "list_users_scim_v2_Users_get",
        "parameters": [
          {
            "in": "query",
            "name": "startIndex",
            "required": false,
            "schema": {
              "default": 1,
              "minimum": 1,
              "title": "Startindex",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "count",
            "required": false,
            "schema": {
              "default": 100,
              "minimum": 0,
              "title": "Count",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "filter",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Filter"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScimListResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "List Users",
        "tags": [
          "scim"
        ]
      },
      "post": {
        "operationId": "create_user_scim_v2_Users_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ScimUser"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScimUser"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Create User",
        "tags": [
          "scim"
        ]
      }
    },
    "/scim/v2/Users/{user_id}": {
      "delete": {
        "operationId": "delete_user_scim_v2_Users__user_id__delete",
        "parameters": [
          {
            "in": "path",
            "name": "user_id",
            "required": true,
            "schema": {
              "title": "User Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Delete User",
        "tags": [
          "scim"
        ]
      },
      "get": {
        "operationId": "get_user_scim_v2_Users__user_id__get",
        "parameters": [
          {
            "in": "path",
            "name": "user_id",
            "required": true,
            "schema": {
              "title": "User Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScimUser"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Get User",
        "tags": [
          "scim"
        ]
      },
      "patch": {
        "operationId": "patch_user_scim_v2_Users__user_id__patch",
        "parameters": [
          {
            "in": "path",
            "name": "user_id",
            "required": true,
            "schema": {
              "title": "User Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ScimPatchOp"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScimUser"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Patch User",
        "tags": [
          "scim"
        ]
      },
      "put": {
        "operationId": "replace_user_scim_v2_Users__user_id__put",
        "parameters": [
          {
            "in": "path",
            "name": "user_id",
            "required": true,
            "schema": {
              "title": "User Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ScimUser"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScimUser"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Replace User",
        "tags": [
          "scim"
        ]
      }
    },
    "/v1/agent": {
      "post": {
        "description": "Drive the agent loop for ``body.goal`` and stream its events.\n\nSee ``docs/reference/agent.md`` (``#post-v1agent``).",
        "operationId": "agent_v1_agent_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              },
              "text/event-stream": {}
            },
            "description": "SSE stream of AgentEvent frames (text/event-stream)."
          },
          "400": {
            "description": "Invalid request body"
          },
          "401": {
            "description": "Missing or invalid auth"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Run an agent loop over a goal, streaming events as SSE",
        "tags": [
          "agent"
        ]
      }
    },
    "/v1/audit": {
      "get": {
        "description": "Return the calling tenant's audit events (tamper-evident hash chain).",
        "operationId": "list_audit_v1_audit_get",
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 100,
              "title": "Limit",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "action",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Action"
            }
          },
          {
            "in": "query",
            "name": "outcome",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Outcome"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditListResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            },
            "description": "Missing or invalid auth"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            },
            "description": "Audit read API disabled"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "The tenant's own audit events, newest-first (Step 6.6)",
        "tags": [
          "audit"
        ]
      }
    },
    "/v1/audit/export": {
      "post": {
        "description": "Return a self-verifying export bundle of the calling tenant's events.\n\nThe bundle is content-hashed and (when ``cfg.audit.export_secret`` is set)\nHMAC-signed, so a consumer verifies it offline; ``chain_verified`` attests\nthe source log's whole-log hash chain was intact at export time.  It is the\nartifact an operator archives to immutable (WORM) storage.",
        "operationId": "export_audit_v1_audit_export_post",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditExport"
                }
              }
            },
            "description": "Successful Response"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            },
            "description": "Missing or invalid auth"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            },
            "description": "Audit read API disabled"
          }
        },
        "summary": "Signed WORM export of the tenant's audit log (Step 6.6b)",
        "tags": [
          "audit"
        ]
      }
    },
    "/v1/audit/verify": {
      "get": {
        "description": "Verify the whole-log SHA-256 hash chain — True iff no link was altered.",
        "operationId": "verify_audit_v1_audit_verify_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditVerifyResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            },
            "description": "Missing or invalid auth"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            },
            "description": "Audit read API disabled"
          }
        },
        "summary": "Whole-log hash-chain integrity check (Step 6.6)",
        "tags": [
          "audit"
        ]
      }
    },
    "/v1/billing/usage": {
      "get": {
        "description": "One tenant's accrued metered usage for the current billing period (Step 7.9).\n\nTenant resolves from the ``tenant_id`` query param, else the\n``X-Tenant-Id`` header, else ``\"default\"``.  Empty when no usage meter is\nwired (billing disabled).  Read-only — metering never rejects a request.",
        "operationId": "billing_usage_v1_billing_usage_get",
        "parameters": [
          {
            "in": "query",
            "name": "tenant_id",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Tenant Id"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillingUsageResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Billing Usage",
        "tags": [
          "status"
        ]
      }
    },
    "/v1/chat/completions": {
      "post": {
        "description": "RAG chat completion: retrieve → inject context → generate.\n\nSee ``docs/reference/openai-compat.md`` (``#post-v1chatcompletions``).",
        "operationId": "chat_completions_v1_chat_completions_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatCompletionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChatCompletionResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OpenAIError"
                }
              }
            },
            "description": "Invalid request"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OpenAIError"
                }
              }
            },
            "description": "Missing or invalid auth"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OpenAIError"
                }
              }
            },
            "description": "ACL denied"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OpenAIError"
                }
              }
            },
            "description": "Rate limit exceeded"
          },
          "502": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OpenAIError"
                }
              }
            },
            "description": "Downstream retrieval / LLM failure"
          }
        },
        "summary": "Create a chat completion with retrieval pre-fetch (OpenAI-compatible)",
        "tags": [
          "openai"
        ]
      }
    },
    "/v1/compliance/erase": {
      "post": {
        "description": "Erase (or, by default, preview) the calling tenant's data across all stores.\n\nReturns an :class:`ErasureResult` with per-data-class counts.  Deletes only\nwhen ``dry_run=false`` **and** ``confirm=true``; otherwise it is a counting\npreview (``dry_run=true`` in the result).",
        "operationId": "erase_v1_compliance_erase_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ComplianceEraseRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErasureResult"
                }
              }
            },
            "description": "Successful Response"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            },
            "description": "Missing or invalid auth"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Erase the calling tenant's data — GDPR right-to-erasure (Step 6.10)",
        "tags": [
          "compliance"
        ]
      }
    },
    "/v1/connectors/status": {
      "get": {
        "operationId": "connectors_status_v1_connectors_status_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConnectorsStatusResponse"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "summary": "Connectors Status",
        "tags": [
          "status"
        ]
      }
    },
    "/v1/corpora": {
      "get": {
        "description": "Return every corpus the calling principal can read.\n\nSee [docs/reference/gateway.md](../../../../docs/reference/gateway.md#get-v1corpora)\nfor the response shape + pagination semantics (paging is a\nPhase 3.x add — v0 returns everything visible).",
        "operationId": "list_corpora_v1_corpora_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CorpusList"
                }
              }
            },
            "description": "Successful Response"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            },
            "description": "Missing or invalid auth"
          }
        },
        "summary": "List corpora visible to the calling tenant",
        "tags": [
          "corpora"
        ]
      },
      "post": {
        "description": "Create a corpus owned by the calling tenant.\n\nThe id is minted server-side (``corpus_…``) and the tenant comes\nfrom ``ctx`` — the body carries only display fields + embedding\nmetadata, so a caller can neither pick an id nor create into\nanother tenant.  ``document_count`` starts at 0 and is maintained\nby the ingest path.",
        "operationId": "create_corpus_v1_corpora_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateCorpusRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Corpus"
                }
              }
            },
            "description": "Successful Response"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            },
            "description": "Missing or invalid auth"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Create a corpus for the calling tenant",
        "tags": [
          "corpora"
        ]
      }
    },
    "/v1/corpora/{corpus_id}": {
      "delete": {
        "description": "Delete a corpus owned by the calling tenant.\n\nCross-tenant / unknown ids return 404 — the same invisibility\nrule as ``GET`` — so a caller can't probe for or delete another\ntenant's corpora.",
        "operationId": "delete_corpus_v1_corpora__corpus_id__delete",
        "parameters": [
          {
            "in": "path",
            "name": "corpus_id",
            "required": true,
            "schema": {
              "title": "Corpus Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Successful Response"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            },
            "description": "Missing or invalid auth"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            },
            "description": "Corpus not found / not visible"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Delete a corpus",
        "tags": [
          "corpora"
        ]
      },
      "get": {
        "description": "Return metadata for one corpus, or 404 if not visible.\n\nCross-tenant lookups (the corpus exists in a different tenant)\nreturn 404 deliberately — the response shape doesn't\ndistinguish \"not found\" from \"not visible\" so attackers\ncan't probe for other tenants' corpora.",
        "operationId": "get_corpus_v1_corpora__corpus_id__get",
        "parameters": [
          {
            "in": "path",
            "name": "corpus_id",
            "required": true,
            "schema": {
              "title": "Corpus Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Corpus"
                }
              }
            },
            "description": "Successful Response"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            },
            "description": "Missing or invalid auth"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            },
            "description": "Corpus not found / not visible"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Describe a single corpus",
        "tags": [
          "corpora"
        ]
      },
      "patch": {
        "description": "Patch a corpus's mutable fields (display name / description / metadata).\n\nPATCH semantics: only the fields present in the body change.  Embedding\nmodel + dimension are immutable (they define the vector space).\nCross-tenant / unknown ids return 404 — the same invisibility rule as\n``GET`` — so a caller can't probe for or mutate another tenant's corpora.",
        "operationId": "update_corpus_v1_corpora__corpus_id__patch",
        "parameters": [
          {
            "in": "path",
            "name": "corpus_id",
            "required": true,
            "schema": {
              "title": "Corpus Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateCorpusRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Corpus"
                }
              }
            },
            "description": "Successful Response"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            },
            "description": "Missing or invalid auth"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            },
            "description": "Corpus not found / not visible"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Update a corpus",
        "tags": [
          "corpora"
        ]
      }
    },
    "/v1/embeddings": {
      "post": {
        "description": "Embed text via the wired ``Embedder`` SPI.\n\nSee ``docs/reference/openai-compat.md`` (``#post-v1embeddings``).",
        "operationId": "embeddings_v1_embeddings_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EmbeddingsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmbeddingsResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OpenAIError"
                }
              }
            },
            "description": "Invalid request"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OpenAIError"
                }
              }
            },
            "description": "Missing or invalid auth"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OpenAIError"
                }
              }
            },
            "description": "Quota / rate limit exceeded"
          }
        },
        "summary": "Create embeddings (OpenAI-compatible)",
        "tags": [
          "openai"
        ]
      }
    },
    "/v1/feedback": {
      "post": {
        "operationId": "submit_feedback_v1_feedback_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FeedbackRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeedbackAck"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            },
            "description": "Invalid signal / rating"
          }
        },
        "summary": "Submit explicit feedback or an implicit signal about a query",
        "tags": [
          "feedback"
        ]
      }
    },
    "/v1/info": {
      "get": {
        "operationId": "info_v1_info_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "title": "Response Info V1 Info Get",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "summary": "Info",
        "tags": [
          "health"
        ]
      }
    },
    "/v1/ingest/document": {
      "post": {
        "description": "Single-document ingest — multipart upload (Step 1.10).",
        "operationId": "ingest_document_v1_ingest_document_post",
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/Body_ingest_document_v1_ingest_document_post"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IngestResult"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Ingest Document",
        "tags": [
          "ingest"
        ]
      }
    },
    "/v1/models": {
      "get": {
        "description": "Advertise the wired LLM + embedder under OpenAI's model-list shape.\n\nMany OpenAI clients call this on startup to validate the endpoint.\nThe ids are the wired backends' canonical model names plus a\n``rag-gateway`` alias clients can target generically.",
        "operationId": "list_models_v1_models_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelList"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "summary": "List models (OpenAI-compatible) — reports the wired LLM + embedder",
        "tags": [
          "openai"
        ]
      }
    },
    "/v1/query": {
      "post": {
        "description": "End-to-end RAG query.\n\nRuns the Phase 2 pipeline in sequence — understanding,\nrouter, optional rerank, optional pack, optional LLM — and\nreturns the combined evidence envelope.  See\n[docs/reference/gateway.md](../../../../docs/reference/gateway.md#post-v1query).",
        "operationId": "query_v1_query_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QueryRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueryResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            },
            "description": "Invalid request body"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            },
            "description": "Missing or invalid auth"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            },
            "description": "ACL denied"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            },
            "description": "Tenant rate limit exceeded"
          },
          "502": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            },
            "description": "Downstream retrieval failure"
          }
        },
        "summary": "Full RAG query: retrieve → rerank → pack → optional LLM answer",
        "tags": [
          "queries"
        ]
      }
    },
    "/v1/query/{request_id}/trace": {
      "get": {
        "description": "Return the signed provenance record + captured spans for a query.\n\nTenant identity comes from request headers (``Authorization`` /\n``X-Tenant-Id``); a record is returned only to the tenant that produced\nit.  404 when the id is unknown to the tenant or provenance is disabled.",
        "operationId": "query_trace_v1_query__request_id__trace_get",
        "parameters": [
          {
            "in": "path",
            "name": "request_id",
            "required": true,
            "schema": {
              "title": "Request Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueryTraceResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            },
            "description": "Missing or invalid auth"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            },
            "description": "No provenance for this query id"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Per-query provenance + captured span trace (Step 5.1)",
        "tags": [
          "queries"
        ]
      }
    },
    "/v1/retrieve": {
      "post": {
        "description": "Retrieval-only subset of ``/v1/query``.\n\nUseful when the caller brings their own reranker / packer /\nLLM and just wants the policy-checked, fused chunk-ref list.",
        "operationId": "retrieve_v1_retrieve_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RetrieveRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RetrieveResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            },
            "description": "Invalid request body"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            },
            "description": "Missing or invalid auth"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            },
            "description": "ACL denied"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "502": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            },
            "description": "Downstream retrieval failure"
          }
        },
        "summary": "Retrieval-only: understanding + router; no rerank / pack / LLM",
        "tags": [
          "queries"
        ]
      }
    },
    "/v1/status/breakers": {
      "get": {
        "description": "List every per-backend circuit breaker + its current state (Step 4.4).",
        "operationId": "status_breakers_v1_status_breakers_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BreakersStatusResponse"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "summary": "Status Breakers",
        "tags": [
          "status"
        ]
      }
    },
    "/v1/status/breakers/{name}/force-close": {
      "post": {
        "description": "Force one circuit breaker CLOSED — the operator one-click recovery (Step 4.4).\n\n404 when no breaker registry is wired or the name is unknown.  If the\nbackend is still unhealthy the breaker simply re-trips on the next\nfailure run; this just gives an operator an immediate retry without\nwaiting out ``reset_timeout_s``.",
        "operationId": "force_close_breaker_v1_status_breakers__name__force_close_post",
        "parameters": [
          {
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "title": "Name",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BreakerActionResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Force Close Breaker",
        "tags": [
          "status"
        ]
      }
    },
    "/v1/status/compliance": {
      "get": {
        "description": "The live compliance posture (Step 6.10).\n\nReports which governance controls are enabled (audit / ACL / PII / BYOK /\nSSO / SCIM / quotas / retention / residency), the deployment's data region,\nand the retention windows — the machine-readable backing for the SOC 2 /\nGDPR control-mapping docs.  Carries only configuration booleans, no tenant\ndata, so it is safe on the status surface.",
        "operationId": "status_compliance_v1_status_compliance_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompliancePosture"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "summary": "Status Compliance",
        "tags": [
          "status"
        ]
      }
    },
    "/v1/status/cost": {
      "get": {
        "description": "One tenant's recent-spend anomaly verdict (Step 5.6c).\n\nTenant resolves from the ``tenant_id`` query param, else the\n``X-Tenant-Id`` header, else ``\"default\"``.  Returns\n``insufficient_data`` when cost tracking is disabled or the tenant has\nseen too few requests.  Detection only — never rejects a request.",
        "operationId": "status_cost_v1_status_cost_get",
        "parameters": [
          {
            "in": "query",
            "name": "tenant_id",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Tenant Id"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CostStatusResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Status Cost",
        "tags": [
          "status"
        ]
      }
    },
    "/v1/status/drift": {
      "get": {
        "description": "Drift report across the five monitors (Step 5.5).\n\nInfra-scoped (no tenant).  Computing the report also emits\n``drift.detected`` for any monitor that has **newly** crossed its\nthreshold (idempotent per transition).  Empty when drift is disabled.",
        "operationId": "status_drift_v1_status_drift_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DriftReport"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "summary": "Status Drift",
        "tags": [
          "status"
        ]
      }
    },
    "/v1/status/drift/{metric}/rebaseline": {
      "post": {
        "description": "Promote a monitor's current window to its reference — \"accept the new normal\".\n\nThe operator one-click \"this is the new baseline\" — 404 when drift is\ndisabled, 400 on an unknown metric.  Returns the post-rebaseline snapshot.",
        "operationId": "rebaseline_drift_v1_status_drift__metric__rebaseline_post",
        "parameters": [
          {
            "in": "path",
            "name": "metric",
            "required": true,
            "schema": {
              "title": "Metric",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DriftSnapshot"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Rebaseline Drift",
        "tags": [
          "status"
        ]
      }
    },
    "/v1/status/experiments": {
      "get": {
        "description": "A/B experiment comparisons — control vs candidate per experiment (Step 5.7).\n\nComposes the per-variant sample windows held by the ``experiment_tracker``\nwith the pure ``analyze_ab_experiment`` (lift + confidence interval).\nEmpty when experiments are disabled; a comparison below ``min_samples`` on\neither side reports ``insufficient_data``.",
        "operationId": "status_experiments_v1_status_experiments_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExperimentsStatusResponse"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "summary": "Status Experiments",
        "tags": [
          "status"
        ]
      }
    },
    "/v1/status/feedback": {
      "get": {
        "description": "One tenant's aggregate feedback for the dashboard (Step 5.4).\n\nTenant resolves from the ``tenant_id`` query param, else the\n``X-Tenant-Id`` header, else ``\"default\"``.  Returns a zeroed\n:class:`~rag_core.types.FeedbackStats` when feedback is disabled or the\ntenant has none yet.",
        "operationId": "status_feedback_v1_status_feedback_get",
        "parameters": [
          {
            "in": "query",
            "name": "tenant_id",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Tenant Id"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeedbackStats"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Status Feedback",
        "tags": [
          "status"
        ]
      }
    },
    "/v1/status/health": {
      "get": {
        "operationId": "status_health_v1_status_health_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "summary": "Status Health",
        "tags": [
          "status"
        ]
      }
    },
    "/v1/status/logs": {
      "get": {
        "operationId": "status_logs_v1_status_logs_get",
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 200,
              "title": "Limit",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "level",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Level"
            }
          },
          {
            "in": "query",
            "name": "event",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Event"
            }
          },
          {
            "in": "query",
            "name": "tenant",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Tenant"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LogsResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Status Logs",
        "tags": [
          "status"
        ]
      }
    },
    "/v1/status/logs/stream": {
      "get": {
        "operationId": "status_logs_stream_v1_status_logs_stream_get",
        "parameters": [
          {
            "in": "query",
            "name": "level",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Level"
            }
          },
          {
            "in": "query",
            "name": "event",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Event"
            }
          },
          {
            "in": "query",
            "name": "tenant",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Tenant"
            }
          },
          {
            "in": "query",
            "name": "interval_ms",
            "required": false,
            "schema": {
              "default": 1000,
              "title": "Interval Ms",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "backlog",
            "required": false,
            "schema": {
              "default": 100,
              "title": "Backlog",
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              },
              "text/event-stream": {}
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Status Logs Stream",
        "tags": [
          "status"
        ]
      }
    },
    "/v1/status/metrics": {
      "get": {
        "operationId": "status_metrics_v1_status_metrics_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetricsResponse"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "summary": "Status Metrics",
        "tags": [
          "status"
        ]
      }
    },
    "/v1/status/quotas": {
      "get": {
        "description": "One tenant's quota usage across every dimension (Step 4.5).\n\nTenant resolves from the ``tenant_id`` query param, else the\n``X-Tenant-Id`` header, else ``\"default\"``.  Empty when quotas are off.",
        "operationId": "status_quotas_v1_status_quotas_get",
        "parameters": [
          {
            "in": "query",
            "name": "tenant_id",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Tenant Id"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QuotasStatusResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Status Quotas",
        "tags": [
          "status"
        ]
      }
    },
    "/v1/status/quotas/{tenant_id}/reset": {
      "post": {
        "description": "Clear a tenant's usage on one dimension (``?dimension=qps``) or all (Step 4.5).\n\nThe operator one-click \"give them headroom now\" — 404 when quotas are\noff, 400 on an unknown dimension.  Returns the post-reset snapshot.",
        "operationId": "reset_quota_v1_status_quotas__tenant_id__reset_post",
        "parameters": [
          {
            "in": "path",
            "name": "tenant_id",
            "required": true,
            "schema": {
              "title": "Tenant Id",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "dimension",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Dimension"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QuotaActionResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Reset Quota",
        "tags": [
          "status"
        ]
      }
    },
    "/v1/status/sso": {
      "get": {
        "description": "SSO / SCIM posture for the calling tenant (Step 6.8).\n\nReports whether identity federation (``cfg.sso``) and SCIM provisioning\n(``cfg.scim``) are enabled on the gateway, plus whether *this* tenant has\nan IdP configured and which protocol it speaks.  Tenant-scoped — it never\nlists other tenants' config.  Tenant resolves from the ``tenant_id`` query\nparam, else the ``X-Tenant-Id`` header, else the gateway default.",
        "operationId": "status_sso_v1_status_sso_get",
        "parameters": [
          {
            "in": "query",
            "name": "tenant_id",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Tenant Id"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SsoStatusResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Status Sso",
        "tags": [
          "status"
        ]
      }
    },
    "/v1/status/tenant": {
      "get": {
        "description": "Resolved per-tenant logical-tenancy settings (Step 6.1).\n\nSurfaces what the ``TenantResolver`` resolves for a tenant — its\nnamespace, PII action, and ACL labels — so an operator can see the\neffective config a tenant's requests run under.  Tenant resolves from the\n``tenant_id`` query param, else the ``X-Tenant-Id`` header, else the\ngateway default.  Reports safe defaults (``known=false``) when the tenant\nis absent from ``rag.yaml`` or no resolver is wired.",
        "operationId": "status_tenant_v1_status_tenant_get",
        "parameters": [
          {
            "in": "query",
            "name": "tenant_id",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Tenant Id"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TenantStatusResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Status Tenant",
        "tags": [
          "status"
        ]
      }
    },
    "/v1/webhooks/subscriptions": {
      "get": {
        "operationId": "list_subscriptions_v1_webhooks_subscriptions_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscriptionList"
                }
              }
            },
            "description": "Successful Response"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            },
            "description": "Missing or invalid auth"
          }
        },
        "summary": "List webhook subscriptions (secrets masked)",
        "tags": [
          "webhooks"
        ]
      },
      "post": {
        "operationId": "create_subscription_v1_webhooks_subscriptions_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateSubscriptionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookSubscription"
                }
              }
            },
            "description": "Successful Response"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            },
            "description": "Missing or invalid auth"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Create a webhook subscription (signing secret returned once)",
        "tags": [
          "webhooks"
        ]
      }
    },
    "/v1/webhooks/subscriptions/{subscription_id}": {
      "delete": {
        "operationId": "delete_subscription_v1_webhooks_subscriptions__subscription_id__delete",
        "parameters": [
          {
            "in": "path",
            "name": "subscription_id",
            "required": true,
            "schema": {
              "title": "Subscription Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Successful Response"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            },
            "description": "Missing or invalid auth"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            },
            "description": "Subscription not found"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Delete a subscription",
        "tags": [
          "webhooks"
        ]
      },
      "get": {
        "operationId": "get_subscription_v1_webhooks_subscriptions__subscription_id__get",
        "parameters": [
          {
            "in": "path",
            "name": "subscription_id",
            "required": true,
            "schema": {
              "title": "Subscription Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookSubscription"
                }
              }
            },
            "description": "Successful Response"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            },
            "description": "Missing or invalid auth"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            },
            "description": "Subscription not found"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Describe a subscription (secret masked)",
        "tags": [
          "webhooks"
        ]
      },
      "patch": {
        "operationId": "update_subscription_v1_webhooks_subscriptions__subscription_id__patch",
        "parameters": [
          {
            "in": "path",
            "name": "subscription_id",
            "required": true,
            "schema": {
              "title": "Subscription Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateSubscriptionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookSubscription"
                }
              }
            },
            "description": "Successful Response"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            },
            "description": "Missing or invalid auth"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            },
            "description": "Subscription not found"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Update a subscription (secret masked)",
        "tags": [
          "webhooks"
        ]
      }
    },
    "/v1/webhooks/subscriptions/{subscription_id}/test": {
      "post": {
        "operationId": "test_subscription_v1_webhooks_subscriptions__subscription_id__test_post",
        "parameters": [
          {
            "in": "path",
            "name": "subscription_id",
            "required": true,
            "schema": {
              "title": "Subscription Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookTestResult"
                }
              }
            },
            "description": "Successful Response"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            },
            "description": "Missing or invalid auth"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GatewayError"
                }
              }
            },
            "description": "Subscription not found"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Send a synthetic test event to a subscription",
        "tags": [
          "webhooks"
        ]
      }
    }
  },
  "tags": [
    {
      "description": "Liveness + service descriptor.",
      "name": "health"
    },
    {
      "description": "Document ingestion.",
      "name": "ingest"
    },
    {
      "description": "End-to-end query + retrieval-only.",
      "name": "queries"
    },
    {
      "description": "Corpus discovery.",
      "name": "corpora"
    },
    {
      "description": "OpenAI-compatible embeddings + chat completions.",
      "name": "openai"
    },
    {
      "description": "Iterative agent runtime (SSE) — plan → act → observe.",
      "name": "agent"
    },
    {
      "description": "Online feedback & implicit signals — submit a rating / thumb / comment or a behavioural signal about a query.",
      "name": "feedback"
    },
    {
      "description": "Operator status surface — health, metrics, and a logs tail, with an SSE log stream and a WebSocket health/metrics push.",
      "name": "status"
    },
    {
      "description": "SCIM 2.0 directory provisioning — IdP-driven user / group create / update / deactivate (per-tenant bearer token).",
      "name": "scim"
    },
    {
      "description": "Compliance posture — GDPR right-to-erasure of the calling tenant's data (data retention + residency configure via rag.yaml).",
      "name": "compliance"
    }
  ]
}