openapi.json

{
  "components": {
    "parameters": {
      "AgentTokenHeader": {
        "description": "Machine-to-machine bearer token. Replaces X-Tenant-Id and X-Workspace-Id on agent-tier endpoints -- the token's claims encode the tenant + workspace + scopes. Issue via ``POST /api/v1/agent-tokens``.",
        "example": "fqt_live_aBcDeF1234567890aBcDeF1234567890",
        "in": "header",
        "name": "X-Agent-Token",
        "required": true,
        "schema": {
          "minLength": 32,
          "type": "string"
        }
      },
      "CorrelationIdHeader": {
        "description": "Optional client-supplied correlation id. The service uses this in every log line and downstream call. If absent the service mints a new UUID and echoes it in the response header.",
        "example": "550e8400-e29b-41d4-a716-446655440000",
        "in": "header",
        "name": "X-Correlation-Id",
        "required": false,
        "schema": {
          "format": "uuid",
          "type": "string"
        }
      },
      "IdempotencyKeyHeader": {
        "description": "Optional client-supplied idempotency key for mutating operations. The first request with a key persists its result; subsequent requests with the same key + same tenant return the cached response. Keys expire after 24h.",
        "example": "ingest-2026-05-23-abc123",
        "in": "header",
        "name": "Idempotency-Key",
        "required": false,
        "schema": {
          "maxLength": 256,
          "minLength": 1,
          "type": "string"
        }
      },
      "TenantIdHeader": {
        "description": "Tenant slug. Required on every non-agent endpoint -- bounds the row-level security policy and appears in every audit event. Must match the JWT tenant claim if Authorization is also present.",
        "example": "acme-corp",
        "in": "header",
        "name": "X-Tenant-Id",
        "required": true,
        "schema": {
          "maxLength": 128,
          "minLength": 1,
          "type": "string"
        }
      },
      "WorkspaceIdHeader": {
        "description": "Workspace identifier. Accepts either the workspace UUID or its slug -- the slug form lets SDKs avoid carrying UUIDs around. Used to scope every query, ingest, and schema KB operation.",
        "example": "00000000-0000-0000-0000-000000000001",
        "in": "header",
        "name": "X-Workspace-Id",
        "required": true,
        "schema": {
          "maxLength": 128,
          "minLength": 1,
          "type": "string"
        }
      }
    },
    "schemas": {
      "AgentTokenCreated": {
        "description": "Mint response: includes the full ``token`` ONCE.\n\nSubsequent reads only ever expose ``prefix`` -- the secret hash\nis stored server-side and never returned. Callers MUST\ncapture the token at mint time; there is no recovery path.",
        "properties": {
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "created_by": {
            "title": "Created By",
            "type": "string"
          },
          "expires_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Expires At"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "last_used_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Last Used At"
          },
          "name": {
            "title": "Name",
            "type": "string"
          },
          "prefix": {
            "title": "Prefix",
            "type": "string"
          },
          "rate_limit_rpm": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Rate Limit Rpm"
          },
          "revoked_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Revoked At"
          },
          "scopes": {
            "items": {
              "type": "string"
            },
            "title": "Scopes",
            "type": "array"
          },
          "token": {
            "title": "Token",
            "type": "string"
          },
          "workspace_allowlist": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Workspace Allowlist"
          }
        },
        "required": [
          "id",
          "name",
          "prefix",
          "workspace_allowlist",
          "scopes",
          "rate_limit_rpm",
          "expires_at",
          "created_at",
          "created_by",
          "revoked_at",
          "last_used_at",
          "token"
        ],
        "title": "AgentTokenCreated",
        "type": "object"
      },
      "AgentTokenMintRequest": {
        "description": "Request body for ``POST /api/v1/agent-tokens``.\n\n``workspace_allowlist`` is optional -- ``None`` means the token\ncan be used in any workspace under the tenant. ``scopes``\ndefaults to ``[\"*\"]`` (all scopes); the verify path treats\n``\"*\"`` as a wildcard. ``rate_limit_rpm`` is advisory metadata\ntoday and reserved for the per-token rate limiter we add\nlater; ``expires_at`` is enforced by the verify path.\n\nEvery requested scope must be in\n:data:`flyquery.core.services.auth.scope_catalog.ALL_SCOPES` --\nPydantic validates this before the mint hits the database and\nsurfaces an ``invalid_scope`` error envelope on the wire.",
        "properties": {
          "expires_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Expires At"
          },
          "name": {
            "maxLength": 128,
            "minLength": 1,
            "title": "Name",
            "type": "string"
          },
          "rate_limit_rpm": {
            "anyOf": [
              {
                "maximum": 10000,
                "minimum": 1,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Rate Limit Rpm"
          },
          "scopes": {
            "items": {
              "type": "string"
            },
            "title": "Scopes",
            "type": "array"
          },
          "workspace_allowlist": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Workspace Allowlist"
          }
        },
        "required": [
          "name"
        ],
        "title": "AgentTokenMintRequest",
        "type": "object"
      },
      "AgentTokenSummaryDto": {
        "description": "Token surface as listed back to user-tier callers -- secret omitted.\n\nEvery read path through ``GET /api/v1/agent-tokens`` returns\nthis shape. The raw token is *only* available on the\n:class:`AgentTokenCreated` returned by the mint endpoint and\nis never round-tripped through any other endpoint.",
        "properties": {
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "created_by": {
            "title": "Created By",
            "type": "string"
          },
          "expires_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Expires At"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "last_used_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Last Used At"
          },
          "name": {
            "title": "Name",
            "type": "string"
          },
          "prefix": {
            "title": "Prefix",
            "type": "string"
          },
          "rate_limit_rpm": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Rate Limit Rpm"
          },
          "revoked_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Revoked At"
          },
          "scopes": {
            "items": {
              "type": "string"
            },
            "title": "Scopes",
            "type": "array"
          },
          "workspace_allowlist": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Workspace Allowlist"
          }
        },
        "required": [
          "id",
          "name",
          "prefix",
          "workspace_allowlist",
          "scopes",
          "rate_limit_rpm",
          "expires_at",
          "created_at",
          "created_by",
          "revoked_at",
          "last_used_at"
        ],
        "title": "AgentTokenSummaryDto",
        "type": "object"
      },
      "AgentUsage": {
        "description": "LLM usage + cost for a single pipeline stage.\n\nSurfaced inside :class:`UsageSummary` so callers see exactly\nwhere the tokens went. ``cost_usd`` is computed by the\nfireflyframework-agentic cost tracker (per-model rate table).",
        "properties": {
          "agent": {
            "title": "Agent",
            "type": "string"
          },
          "calls": {
            "default": 0,
            "title": "Calls",
            "type": "integer"
          },
          "cost_usd": {
            "default": 0.0,
            "title": "Cost Usd",
            "type": "number"
          },
          "input_tokens": {
            "default": 0,
            "title": "Input Tokens",
            "type": "integer"
          },
          "latency_ms": {
            "default": 0.0,
            "title": "Latency Ms",
            "type": "number"
          },
          "model": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Model"
          },
          "output_tokens": {
            "default": 0,
            "title": "Output Tokens",
            "type": "integer"
          },
          "total_tokens": {
            "default": 0,
            "title": "Total Tokens",
            "type": "integer"
          }
        },
        "required": [
          "agent"
        ],
        "title": "AgentUsage",
        "type": "object"
      },
      "AnswerResponse": {
        "description": "Response from POST /api/v1/query (sync).",
        "properties": {
          "chart_hint": {
            "anyOf": [
              {
                "enum": [
                  "line",
                  "bar",
                  "table",
                  "pie",
                  "none"
                ],
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Chart Hint"
          },
          "clarification": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ClarificationFrame"
              },
              {
                "type": "null"
              }
            ],
            "default": null
          },
          "elapsed_ms": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Elapsed Ms"
          },
          "execution_status": {
            "anyOf": [
              {
                "enum": [
                  "OK",
                  "REFINED_OK",
                  "FAILED",
                  "REJECTED_BY_FIREWALL"
                ],
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Execution Status"
          },
          "explanation": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Explanation"
          },
          "grounded_summary": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Grounded Summary"
          },
          "preview": {
            "anyOf": [
              {
                "items": {
                  "additionalProperties": true,
                  "type": "object"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Preview"
          },
          "query_id": {
            "format": "uuid",
            "title": "Query Id",
            "type": "string"
          },
          "row_count": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Row Count"
          },
          "snapshot_pins": {
            "additionalProperties": {
              "type": "string"
            },
            "title": "Snapshot Pins",
            "type": "object"
          },
          "sql": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Sql"
          },
          "truncated": {
            "default": false,
            "title": "Truncated",
            "type": "boolean"
          },
          "usage": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/UsageSummary"
              },
              {
                "type": "null"
              }
            ],
            "default": null
          }
        },
        "required": [
          "query_id",
          "sql",
          "execution_status",
          "preview",
          "row_count",
          "elapsed_ms"
        ],
        "title": "AnswerResponse",
        "type": "object"
      },
      "AuditEventRead": {
        "description": "Append-only audit ledger row.",
        "properties": {
          "actor": {
            "title": "Actor",
            "type": "string"
          },
          "correlation_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Correlation Id"
          },
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "event_type": {
            "title": "Event Type",
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "payload_json": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Payload Json"
          },
          "resource_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Resource Id"
          },
          "resource_kind": {
            "title": "Resource Kind",
            "type": "string"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          },
          "workspace_id": {
            "format": "uuid",
            "title": "Workspace Id",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "workspace_id",
          "actor",
          "event_type",
          "resource_kind",
          "created_at"
        ],
        "title": "AuditEventRead",
        "type": "object"
      },
      "BatchQueryItem": {
        "description": "One question in a batch -- matches ``AnswerRequest`` minus headers.",
        "properties": {
          "conversation_id": {
            "anyOf": [
              {
                "format": "uuid",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Conversation Id"
          },
          "dataset_id": {
            "format": "uuid",
            "title": "Dataset Id",
            "type": "string"
          },
          "question": {
            "title": "Question",
            "type": "string"
          }
        },
        "required": [
          "question",
          "dataset_id"
        ],
        "title": "BatchQueryItem",
        "type": "object"
      },
      "BatchQueryRequest": {
        "description": "Request body for ``POST /api/v1/query:batch``.",
        "properties": {
          "queries": {
            "items": {
              "$ref": "#/components/schemas/BatchQueryItem"
            },
            "title": "Queries",
            "type": "array"
          }
        },
        "required": [
          "queries"
        ],
        "title": "BatchQueryRequest",
        "type": "object"
      },
      "BatchQueryResponse": {
        "description": "Response from ``POST /api/v1/query:batch``.",
        "properties": {
          "failed": {
            "title": "Failed",
            "type": "integer"
          },
          "results": {
            "items": {
              "$ref": "#/components/schemas/BatchQueryResultItem"
            },
            "title": "Results",
            "type": "array"
          },
          "succeeded": {
            "title": "Succeeded",
            "type": "integer"
          },
          "total_queries": {
            "title": "Total Queries",
            "type": "integer"
          }
        },
        "required": [
          "results",
          "total_queries",
          "succeeded",
          "failed"
        ],
        "title": "BatchQueryResponse",
        "type": "object"
      },
      "BatchQueryResultItem": {
        "description": "One outcome in a batch query response.\n\nMirrors ``AnswerResponse`` for OK results; carries ``error`` +\n``status=\"FAILED\"`` on failure so the batch never aborts on one\nbad item.",
        "properties": {
          "chart_hint": {
            "anyOf": [
              {
                "enum": [
                  "line",
                  "bar",
                  "table",
                  "pie",
                  "none"
                ],
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Chart Hint"
          },
          "elapsed_ms": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Elapsed Ms"
          },
          "error": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Error"
          },
          "execution_status": {
            "anyOf": [
              {
                "enum": [
                  "OK",
                  "REFINED_OK",
                  "FAILED",
                  "REJECTED_BY_FIREWALL"
                ],
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Execution Status"
          },
          "explanation": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Explanation"
          },
          "grounded_summary": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Grounded Summary"
          },
          "index": {
            "title": "Index",
            "type": "integer"
          },
          "preview": {
            "anyOf": [
              {
                "items": {
                  "additionalProperties": true,
                  "type": "object"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Preview"
          },
          "query_id": {
            "anyOf": [
              {
                "format": "uuid",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Query Id"
          },
          "row_count": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Row Count"
          },
          "sql": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sql"
          },
          "status": {
            "title": "Status",
            "type": "string"
          }
        },
        "required": [
          "index",
          "status"
        ],
        "title": "BatchQueryResultItem",
        "type": "object"
      },
      "BillingBreakdownItem": {
        "description": "One bucket of the billing rollup -- day, week, or month.",
        "properties": {
          "date": {
            "format": "date-time",
            "title": "Date",
            "type": "string"
          },
          "ingest_cost_cents": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              }
            ],
            "title": "Ingest Cost Cents"
          },
          "other_cost_cents": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              }
            ],
            "title": "Other Cost Cents"
          },
          "query_cost_cents": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              }
            ],
            "title": "Query Cost Cents"
          },
          "total_cost_cents": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              }
            ],
            "title": "Total Cost Cents"
          }
        },
        "required": [
          "date",
          "ingest_cost_cents",
          "query_cost_cents",
          "other_cost_cents",
          "total_cost_cents"
        ],
        "title": "BillingBreakdownItem",
        "type": "object"
      },
      "BillingRollup": {
        "description": "Response from GET /api/v1/billing.\n\n``period`` is the bucket granularity that was applied; ``date_from``\nand ``date_to`` echo the request bounds so consumers can render\n\"showing X to Y\" headers without keeping local state.",
        "properties": {
          "breakdown": {
            "items": {
              "$ref": "#/components/schemas/BillingBreakdownItem"
            },
            "title": "Breakdown",
            "type": "array"
          },
          "date_from": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Date From"
          },
          "date_to": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Date To"
          },
          "period": {
            "title": "Period",
            "type": "string"
          },
          "total_cost_cents": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              }
            ],
            "title": "Total Cost Cents"
          }
        },
        "required": [
          "period",
          "total_cost_cents",
          "breakdown"
        ],
        "title": "BillingRollup",
        "type": "object"
      },
      "BulkFileResult": {
        "description": "Per-file outcome from POST /datasets/{id}/files:bulk.",
        "properties": {
          "error": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Error"
          },
          "file_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "File Id"
          },
          "index": {
            "title": "Index",
            "type": "integer"
          },
          "original_filename": {
            "title": "Original Filename",
            "type": "string"
          },
          "status": {
            "title": "Status",
            "type": "string"
          },
          "tables": {
            "default": [],
            "items": {
              "$ref": "#/components/schemas/TableSummary"
            },
            "title": "Tables",
            "type": "array"
          }
        },
        "required": [
          "index",
          "original_filename",
          "status"
        ],
        "title": "BulkFileResult",
        "type": "object"
      },
      "BulkFileUploadResponse": {
        "description": "Response from POST /datasets/{id}/files:bulk.\n\nReturns one ``results`` entry per uploaded file. Per-file failures\ndo NOT abort the bulk -- the caller sees which files succeeded and\nwhich didn't, with the error message inline. Aggregate counts let\na UI render \"4/5 uploaded successfully\" without scanning the list.",
        "properties": {
          "failed": {
            "title": "Failed",
            "type": "integer"
          },
          "results": {
            "items": {
              "$ref": "#/components/schemas/BulkFileResult"
            },
            "title": "Results",
            "type": "array"
          },
          "succeeded": {
            "title": "Succeeded",
            "type": "integer"
          },
          "total_files": {
            "title": "Total Files",
            "type": "integer"
          }
        },
        "required": [
          "results",
          "total_files",
          "succeeded",
          "failed"
        ],
        "title": "BulkFileUploadResponse",
        "type": "object"
      },
      "CallbackConfig": {
        "description": "Webhook delivery target attached to an async ingest job.\n\nSet on job creation (``IngestJobCreate.callback`` or the\n``callback_*`` query params on ``POST /datasets/{id}/files:async``).\nOn every terminal status transition the worker writes one row to\n``flyquery_callback_outbox``; the ``CallbackWorker`` POSTs the\ncanonical :class:`IngestJobRead` to ``url`` with header\n``X-Flyquery-Signature: sha256=<hmac>`` if ``secret`` is provided.\n\nDelivery is at-least-once with exponential backoff (5 attempts:\n0s, 30s, 5m, 1h, 6h). After the last failed attempt the row is\nmarked ``DEAD`` and surfaced via ``GET /ingest-jobs/{id}/callbacks``.",
        "properties": {
          "headers": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "Extra HTTP headers merged onto every callback request.",
            "title": "Headers",
            "type": "object"
          },
          "secret": {
            "anyOf": [
              {
                "maxLength": 512,
                "minLength": 8,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Shared secret for HMAC-SHA256 over the request body.",
            "title": "Secret"
          },
          "url": {
            "format": "uri",
            "maxLength": 2083,
            "minLength": 1,
            "title": "Url",
            "type": "string"
          }
        },
        "required": [
          "url"
        ],
        "title": "CallbackConfig",
        "type": "object"
      },
      "CallbackDeliveryListResponse": {
        "description": "Paginated callback-delivery audit log.",
        "properties": {
          "items": {
            "items": {
              "$ref": "#/components/schemas/CallbackDeliveryRead"
            },
            "title": "Items",
            "type": "array"
          },
          "limit": {
            "title": "Limit",
            "type": "integer"
          },
          "offset": {
            "title": "Offset",
            "type": "integer"
          },
          "total": {
            "title": "Total",
            "type": "integer"
          }
        },
        "required": [
          "items",
          "total",
          "limit",
          "offset"
        ],
        "title": "CallbackDeliveryListResponse",
        "type": "object"
      },
      "CallbackDeliveryRead": {
        "description": "One row from flyquery_callback_outbox.\n\nReturned by ``GET /api/v1/ingest-jobs/{id}/callbacks`` so the\ncaller can audit webhook delivery without inspecting the DB.",
        "properties": {
          "attempts": {
            "title": "Attempts",
            "type": "integer"
          },
          "callback_url": {
            "title": "Callback Url",
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "event_type": {
            "title": "Event Type",
            "type": "string"
          },
          "finished_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Finished At"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "ingest_job_id": {
            "format": "uuid",
            "title": "Ingest Job Id",
            "type": "string"
          },
          "last_attempt_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Last Attempt At"
          },
          "last_error": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Last Error"
          },
          "last_status_code": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Last Status Code"
          },
          "next_attempt_at": {
            "format": "date-time",
            "title": "Next Attempt At",
            "type": "string"
          },
          "status": {
            "enum": [
              "PENDING",
              "DELIVERED",
              "FAILED",
              "DEAD"
            ],
            "title": "Status",
            "type": "string"
          }
        },
        "required": [
          "id",
          "ingest_job_id",
          "callback_url",
          "event_type",
          "status",
          "attempts",
          "last_attempt_at",
          "last_status_code",
          "last_error",
          "next_attempt_at",
          "created_at",
          "finished_at"
        ],
        "title": "CallbackDeliveryRead",
        "type": "object"
      },
      "CancelResponse": {
        "description": "Response for POST /ingest-jobs/{id}:cancel.",
        "properties": {
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "message": {
            "title": "Message",
            "type": "string"
          },
          "status": {
            "title": "Status",
            "type": "string"
          }
        },
        "required": [
          "id",
          "status",
          "message"
        ],
        "title": "CancelResponse",
        "type": "object"
      },
      "ClarificationFrame": {
        "description": "Emitted when grounding confidence is below the threshold and missing_info is set.",
        "properties": {
          "questions": {
            "items": {
              "type": "string"
            },
            "title": "Questions",
            "type": "array"
          },
          "reasons": {
            "items": {
              "type": "string"
            },
            "title": "Reasons",
            "type": "array"
          }
        },
        "required": [
          "questions"
        ],
        "title": "ClarificationFrame",
        "type": "object"
      },
      "ConversationCreate": {
        "description": "Request body for POST /api/v1/conversations.",
        "properties": {
          "title": {
            "anyOf": [
              {
                "maxLength": 500,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Title"
          }
        },
        "title": "ConversationCreate",
        "type": "object"
      },
      "ConversationRead": {
        "description": "A conversation, optionally with its turns.",
        "properties": {
          "actor": {
            "title": "Actor",
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "summary": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Summary"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          },
          "title": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Title"
          },
          "turns": {
            "items": {
              "$ref": "#/components/schemas/TurnRead"
            },
            "title": "Turns",
            "type": "array"
          },
          "updated_at": {
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          },
          "workspace_id": {
            "format": "uuid",
            "title": "Workspace Id",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "workspace_id",
          "title",
          "summary",
          "actor",
          "created_at",
          "updated_at"
        ],
        "title": "ConversationRead",
        "type": "object"
      },
      "ConversationTurnRequest": {
        "description": "Request body for POST /api/v1/conversations/{id}/turn.",
        "properties": {
          "dataset_id": {
            "format": "uuid",
            "title": "Dataset Id",
            "type": "string"
          },
          "question": {
            "maxLength": 4096,
            "minLength": 1,
            "title": "Question",
            "type": "string"
          }
        },
        "required": [
          "dataset_id",
          "question"
        ],
        "title": "ConversationTurnRequest",
        "type": "object"
      },
      "CostEventRead": {
        "description": "Append-only LLM cost ledger row.\n\n``cost_cents`` is a Decimal because partial cents are common at the\nper-call granularity (the cost tracker in fireflyframework-agentic\nrounds at aggregation time, not per row).",
        "properties": {
          "actor": {
            "title": "Actor",
            "type": "string"
          },
          "correlation_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Correlation Id"
          },
          "cost_cents": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              }
            ],
            "title": "Cost Cents"
          },
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "ingest_job_id": {
            "anyOf": [
              {
                "format": "uuid",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Ingest Job Id"
          },
          "input_tokens": {
            "title": "Input Tokens",
            "type": "integer"
          },
          "model": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Model"
          },
          "operation": {
            "title": "Operation",
            "type": "string"
          },
          "output_tokens": {
            "title": "Output Tokens",
            "type": "integer"
          },
          "query_id": {
            "anyOf": [
              {
                "format": "uuid",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Query Id"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          },
          "workspace_id": {
            "format": "uuid",
            "title": "Workspace Id",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "workspace_id",
          "actor",
          "operation",
          "input_tokens",
          "output_tokens",
          "cost_cents",
          "created_at"
        ],
        "title": "CostEventRead",
        "type": "object"
      },
      "DatasetCreate": {
        "properties": {
          "default_locale": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Default Locale"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Description"
          },
          "drift_policy": {
            "default": "AUTO",
            "enum": [
              "AUTO",
              "MANUAL"
            ],
            "title": "Drift Policy",
            "type": "string"
          },
          "ingest_policy_json": {
            "additionalProperties": true,
            "title": "Ingest Policy Json",
            "type": "object"
          },
          "metadata_json": {
            "additionalProperties": true,
            "title": "Metadata Json",
            "type": "object"
          },
          "name": {
            "maxLength": 200,
            "minLength": 1,
            "title": "Name",
            "type": "string"
          }
        },
        "required": [
          "name"
        ],
        "title": "DatasetCreate",
        "type": "object"
      },
      "DatasetRead": {
        "properties": {
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "default_locale": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Default Locale"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Description"
          },
          "drift_policy": {
            "enum": [
              "AUTO",
              "MANUAL"
            ],
            "title": "Drift Policy",
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "ingest_policy_json": {
            "additionalProperties": true,
            "title": "Ingest Policy Json",
            "type": "object"
          },
          "metadata_json": {
            "additionalProperties": true,
            "title": "Metadata Json",
            "type": "object"
          },
          "name": {
            "title": "Name",
            "type": "string"
          },
          "status": {
            "enum": [
              "ACTIVE",
              "ARCHIVED"
            ],
            "title": "Status",
            "type": "string"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          },
          "workspace_id": {
            "format": "uuid",
            "title": "Workspace Id",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "workspace_id",
          "name",
          "description",
          "drift_policy",
          "default_locale",
          "ingest_policy_json",
          "status",
          "created_at",
          "updated_at",
          "metadata_json"
        ],
        "title": "DatasetRead",
        "type": "object"
      },
      "DatasetUpdate": {
        "properties": {
          "default_locale": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Default Locale"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Description"
          },
          "drift_policy": {
            "anyOf": [
              {
                "enum": [
                  "AUTO",
                  "MANUAL"
                ],
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Drift Policy"
          },
          "ingest_policy_json": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Ingest Policy Json"
          },
          "metadata_json": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Metadata Json"
          },
          "name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Name"
          }
        },
        "title": "DatasetUpdate",
        "type": "object"
      },
      "DeriveTableRequest": {
        "description": "Request body for POST /api/v1/tables:derive.",
        "properties": {
          "dataset_id": {
            "format": "uuid",
            "title": "Dataset Id",
            "type": "string"
          },
          "name": {
            "maxLength": 200,
            "minLength": 1,
            "title": "Name",
            "type": "string"
          },
          "sql": {
            "maxLength": 65536,
            "minLength": 1,
            "title": "Sql",
            "type": "string"
          }
        },
        "required": [
          "dataset_id",
          "name",
          "sql"
        ],
        "title": "DeriveTableRequest",
        "type": "object"
      },
      "DeriveTableResponse": {
        "description": "Response from POST /api/v1/tables:derive.",
        "properties": {
          "dataset_id": {
            "format": "uuid",
            "title": "Dataset Id",
            "type": "string"
          },
          "name": {
            "title": "Name",
            "type": "string"
          },
          "table_id": {
            "format": "uuid",
            "title": "Table Id",
            "type": "string"
          }
        },
        "required": [
          "table_id",
          "name",
          "dataset_id"
        ],
        "title": "DeriveTableResponse",
        "type": "object"
      },
      "ExampleCreate": {
        "description": "Payload for creating a new example (question + SQL pair).",
        "properties": {
          "citations_json": {
            "additionalProperties": true,
            "title": "Citations Json",
            "type": "object"
          },
          "dataset_id": {
            "anyOf": [
              {
                "format": "uuid",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Dataset Id"
          },
          "generated_sql": {
            "minLength": 1,
            "title": "Generated Sql",
            "type": "string"
          },
          "question": {
            "maxLength": 4096,
            "minLength": 1,
            "title": "Question",
            "type": "string"
          }
        },
        "required": [
          "question",
          "generated_sql"
        ],
        "title": "ExampleCreate",
        "type": "object"
      },
      "ExampleRead": {
        "description": "Full read representation of a flyquery_examples row.",
        "properties": {
          "citations_json": {
            "additionalProperties": true,
            "title": "Citations Json",
            "type": "object"
          },
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "created_by": {
            "title": "Created By",
            "type": "string"
          },
          "dataset_id": {
            "anyOf": [
              {
                "format": "uuid",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Dataset Id"
          },
          "generated_sql": {
            "title": "Generated Sql",
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "last_used_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Last Used At"
          },
          "normalised_sql": {
            "title": "Normalised Sql",
            "type": "string"
          },
          "quality": {
            "enum": [
              "PROPOSED",
              "APPROVED",
              "REJECTED"
            ],
            "title": "Quality",
            "type": "string"
          },
          "question": {
            "title": "Question",
            "type": "string"
          },
          "source": {
            "enum": [
              "USER_CURATED",
              "AGENT_LEARNED"
            ],
            "title": "Source",
            "type": "string"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          },
          "usage_count": {
            "title": "Usage Count",
            "type": "integer"
          },
          "workspace_id": {
            "format": "uuid",
            "title": "Workspace Id",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "workspace_id",
          "dataset_id",
          "question",
          "generated_sql",
          "normalised_sql",
          "source",
          "quality",
          "citations_json",
          "created_at",
          "created_by",
          "last_used_at",
          "usage_count"
        ],
        "title": "ExampleRead",
        "type": "object"
      },
      "ExplainResponse": {
        "description": "Response from POST /api/v1/query:explain \u2014 Grounding + Generation only.",
        "properties": {
          "clarification": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ClarificationFrame"
              },
              {
                "type": "null"
              }
            ],
            "default": null
          },
          "confidence": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Confidence"
          },
          "grounded_summary": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Grounded Summary"
          },
          "reasoning": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Reasoning"
          },
          "sql": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Sql"
          }
        },
        "required": [
          "sql",
          "reasoning",
          "confidence"
        ],
        "title": "ExplainResponse",
        "type": "object"
      },
      "FileUploadResponse": {
        "description": "Response from POST /datasets/{id}/files.",
        "properties": {
          "file_id": {
            "title": "File Id",
            "type": "string"
          },
          "tables": {
            "items": {
              "$ref": "#/components/schemas/TableSummary"
            },
            "title": "Tables",
            "type": "array"
          }
        },
        "required": [
          "file_id",
          "tables"
        ],
        "title": "FileUploadResponse",
        "type": "object"
      },
      "GlossaryTermCreate": {
        "description": "Payload for creating a new glossary term.",
        "properties": {
          "definition": {
            "minLength": 1,
            "title": "Definition",
            "type": "string"
          },
          "related_columns": {
            "items": {
              "type": "string"
            },
            "title": "Related Columns",
            "type": "array"
          },
          "related_metrics": {
            "items": {
              "type": "string"
            },
            "title": "Related Metrics",
            "type": "array"
          },
          "synonyms": {
            "items": {
              "type": "string"
            },
            "title": "Synonyms",
            "type": "array"
          },
          "tags": {
            "items": {
              "type": "string"
            },
            "title": "Tags",
            "type": "array"
          },
          "term": {
            "maxLength": 512,
            "minLength": 1,
            "title": "Term",
            "type": "string"
          }
        },
        "required": [
          "term",
          "definition"
        ],
        "title": "GlossaryTermCreate",
        "type": "object"
      },
      "GlossaryTermRead": {
        "description": "Full read representation of a flyquery_glossary_terms row.",
        "properties": {
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "definition": {
            "title": "Definition",
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "related_columns_json": {
            "items": {
              "type": "string"
            },
            "title": "Related Columns Json",
            "type": "array"
          },
          "related_metrics_json": {
            "items": {
              "type": "string"
            },
            "title": "Related Metrics Json",
            "type": "array"
          },
          "synonyms_json": {
            "items": {
              "type": "string"
            },
            "title": "Synonyms Json",
            "type": "array"
          },
          "tags_json": {
            "items": {
              "type": "string"
            },
            "title": "Tags Json",
            "type": "array"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          },
          "term": {
            "title": "Term",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          },
          "workspace_id": {
            "format": "uuid",
            "title": "Workspace Id",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "workspace_id",
          "term",
          "definition",
          "synonyms_json",
          "tags_json",
          "related_columns_json",
          "related_metrics_json",
          "created_at",
          "updated_at"
        ],
        "title": "GlossaryTermRead",
        "type": "object"
      },
      "GlossaryTermUpdate": {
        "description": "Sparse-update payload for an existing glossary term.",
        "properties": {
          "definition": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Definition"
          },
          "related_columns": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Related Columns"
          },
          "related_metrics": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Related Metrics"
          },
          "synonyms": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Synonyms"
          },
          "tags": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Tags"
          }
        },
        "title": "GlossaryTermUpdate",
        "type": "object"
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "title": "Detail",
            "type": "array"
          }
        },
        "title": "HTTPValidationError",
        "type": "object"
      },
      "IngestEventListResponse": {
        "description": "Paginated event ledger for GET /ingest-jobs/{id}/events.",
        "properties": {
          "items": {
            "items": {
              "$ref": "#/components/schemas/IngestEventRead"
            },
            "title": "Items",
            "type": "array"
          },
          "limit": {
            "title": "Limit",
            "type": "integer"
          },
          "offset": {
            "title": "Offset",
            "type": "integer"
          },
          "total": {
            "title": "Total",
            "type": "integer"
          }
        },
        "required": [
          "items",
          "total",
          "limit",
          "offset"
        ],
        "title": "IngestEventListResponse",
        "type": "object"
      },
      "IngestEventRead": {
        "description": "One row from flyquery_ingest_events.",
        "properties": {
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "id": {
            "title": "Id",
            "type": "integer"
          },
          "ingest_job_id": {
            "format": "uuid",
            "title": "Ingest Job Id",
            "type": "string"
          },
          "message": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Message"
          },
          "payload_json": {
            "additionalProperties": true,
            "title": "Payload Json",
            "type": "object"
          },
          "stage": {
            "title": "Stage",
            "type": "string"
          },
          "status": {
            "title": "Status",
            "type": "string"
          }
        },
        "required": [
          "id",
          "ingest_job_id",
          "stage",
          "status",
          "message",
          "payload_json",
          "created_at"
        ],
        "title": "IngestEventRead",
        "type": "object"
      },
      "IngestJobCreate": {
        "description": "Request body for POST /api/v1/ingest-jobs.",
        "properties": {
          "callback": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/CallbackConfig"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Optional webhook delivered after the job reaches a terminal status (SUCCEEDED, FAILED, or CANCELLED). See :class:`CallbackConfig` for the at-least-once delivery contract."
          },
          "dataset_id": {
            "format": "uuid",
            "title": "Dataset Id",
            "type": "string"
          },
          "file_id": {
            "anyOf": [
              {
                "format": "uuid",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "File Id"
          },
          "job_kind": {
            "enum": [
              "PARSE_AND_INGEST",
              "REPARSE",
              "SAMPLE_REFRESH",
              "DESCRIBE_PASS",
              "RELATION_PASS"
            ],
            "title": "Job Kind",
            "type": "string"
          },
          "request_json": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Request Json"
          },
          "table_id": {
            "anyOf": [
              {
                "format": "uuid",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Table Id"
          }
        },
        "required": [
          "dataset_id",
          "job_kind"
        ],
        "title": "IngestJobCreate",
        "type": "object"
      },
      "IngestJobListResponse": {
        "description": "Paginated list of ingest jobs.",
        "properties": {
          "items": {
            "items": {
              "$ref": "#/components/schemas/IngestJobRead"
            },
            "title": "Items",
            "type": "array"
          },
          "limit": {
            "title": "Limit",
            "type": "integer"
          },
          "offset": {
            "title": "Offset",
            "type": "integer"
          },
          "total": {
            "title": "Total",
            "type": "integer"
          }
        },
        "required": [
          "items",
          "total",
          "limit",
          "offset"
        ],
        "title": "IngestJobListResponse",
        "type": "object"
      },
      "IngestJobRead": {
        "description": "Response for GET /api/v1/ingest-jobs/{id} and list items.",
        "properties": {
          "attempts": {
            "title": "Attempts",
            "type": "integer"
          },
          "cost_cents": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              }
            ],
            "title": "Cost Cents"
          },
          "dataset_id": {
            "format": "uuid",
            "title": "Dataset Id",
            "type": "string"
          },
          "elapsed_ms": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Elapsed Ms"
          },
          "file_id": {
            "anyOf": [
              {
                "format": "uuid",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "File Id"
          },
          "finished_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Finished At"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "job_kind": {
            "title": "Job Kind",
            "type": "string"
          },
          "request_json": {
            "additionalProperties": true,
            "title": "Request Json",
            "type": "object"
          },
          "result_json": {
            "additionalProperties": true,
            "title": "Result Json",
            "type": "object"
          },
          "snapshot_id": {
            "anyOf": [
              {
                "format": "uuid",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Snapshot Id"
          },
          "started_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Started At"
          },
          "status": {
            "title": "Status",
            "type": "string"
          },
          "table_id": {
            "anyOf": [
              {
                "format": "uuid",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Table Id"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          },
          "workspace_id": {
            "format": "uuid",
            "title": "Workspace Id",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "workspace_id",
          "dataset_id",
          "table_id",
          "file_id",
          "snapshot_id",
          "job_kind",
          "status",
          "attempts",
          "request_json",
          "result_json",
          "cost_cents",
          "elapsed_ms",
          "started_at",
          "finished_at"
        ],
        "title": "IngestJobRead",
        "type": "object"
      },
      "Paginated[AuditEventRead]": {
        "properties": {
          "has_more": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Has More"
          },
          "items": {
            "items": {
              "$ref": "#/components/schemas/AuditEventRead"
            },
            "title": "Items",
            "type": "array"
          },
          "limit": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Limit"
          },
          "offset": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Offset"
          },
          "total": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Total"
          }
        },
        "title": "Paginated[AuditEventRead]",
        "type": "object"
      },
      "Paginated[ConversationRead]": {
        "properties": {
          "has_more": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Has More"
          },
          "items": {
            "items": {
              "$ref": "#/components/schemas/ConversationRead"
            },
            "title": "Items",
            "type": "array"
          },
          "limit": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Limit"
          },
          "offset": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Offset"
          },
          "total": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Total"
          }
        },
        "title": "Paginated[ConversationRead]",
        "type": "object"
      },
      "Paginated[CostEventRead]": {
        "properties": {
          "has_more": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Has More"
          },
          "items": {
            "items": {
              "$ref": "#/components/schemas/CostEventRead"
            },
            "title": "Items",
            "type": "array"
          },
          "limit": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Limit"
          },
          "offset": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Offset"
          },
          "total": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Total"
          }
        },
        "title": "Paginated[CostEventRead]",
        "type": "object"
      },
      "Paginated[DatasetRead]": {
        "properties": {
          "has_more": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Has More"
          },
          "items": {
            "items": {
              "$ref": "#/components/schemas/DatasetRead"
            },
            "title": "Items",
            "type": "array"
          },
          "limit": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Limit"
          },
          "offset": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Offset"
          },
          "total": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Total"
          }
        },
        "title": "Paginated[DatasetRead]",
        "type": "object"
      },
      "Paginated[ExampleRead]": {
        "properties": {
          "has_more": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Has More"
          },
          "items": {
            "items": {
              "$ref": "#/components/schemas/ExampleRead"
            },
            "title": "Items",
            "type": "array"
          },
          "limit": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Limit"
          },
          "offset": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Offset"
          },
          "total": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Total"
          }
        },
        "title": "Paginated[ExampleRead]",
        "type": "object"
      },
      "Paginated[GlossaryTermRead]": {
        "properties": {
          "has_more": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Has More"
          },
          "items": {
            "items": {
              "$ref": "#/components/schemas/GlossaryTermRead"
            },
            "title": "Items",
            "type": "array"
          },
          "limit": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Limit"
          },
          "offset": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Offset"
          },
          "total": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Total"
          }
        },
        "title": "Paginated[GlossaryTermRead]",
        "type": "object"
      },
      "Paginated[QueryHistoryItem]": {
        "properties": {
          "has_more": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Has More"
          },
          "items": {
            "items": {
              "$ref": "#/components/schemas/QueryHistoryItem"
            },
            "title": "Items",
            "type": "array"
          },
          "limit": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Limit"
          },
          "offset": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Offset"
          },
          "total": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Total"
          }
        },
        "title": "Paginated[QueryHistoryItem]",
        "type": "object"
      },
      "Paginated[RelationRead]": {
        "properties": {
          "has_more": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Has More"
          },
          "items": {
            "items": {
              "$ref": "#/components/schemas/RelationRead"
            },
            "title": "Items",
            "type": "array"
          },
          "limit": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Limit"
          },
          "offset": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Offset"
          },
          "total": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Total"
          }
        },
        "title": "Paginated[RelationRead]",
        "type": "object"
      },
      "Paginated[SchemaChangeRead]": {
        "properties": {
          "has_more": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Has More"
          },
          "items": {
            "items": {
              "$ref": "#/components/schemas/SchemaChangeRead"
            },
            "title": "Items",
            "type": "array"
          },
          "limit": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Limit"
          },
          "offset": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Offset"
          },
          "total": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Total"
          }
        },
        "title": "Paginated[SchemaChangeRead]",
        "type": "object"
      },
      "Paginated[SchemaObjectRead]": {
        "properties": {
          "has_more": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Has More"
          },
          "items": {
            "items": {
              "$ref": "#/components/schemas/SchemaObjectRead"
            },
            "title": "Items",
            "type": "array"
          },
          "limit": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Limit"
          },
          "offset": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Offset"
          },
          "total": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Total"
          }
        },
        "title": "Paginated[SchemaObjectRead]",
        "type": "object"
      },
      "Paginated[SemanticDimensionRead]": {
        "properties": {
          "has_more": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Has More"
          },
          "items": {
            "items": {
              "$ref": "#/components/schemas/SemanticDimensionRead"
            },
            "title": "Items",
            "type": "array"
          },
          "limit": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Limit"
          },
          "offset": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Offset"
          },
          "total": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Total"
          }
        },
        "title": "Paginated[SemanticDimensionRead]",
        "type": "object"
      },
      "Paginated[SemanticMetricRead]": {
        "properties": {
          "has_more": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Has More"
          },
          "items": {
            "items": {
              "$ref": "#/components/schemas/SemanticMetricRead"
            },
            "title": "Items",
            "type": "array"
          },
          "limit": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Limit"
          },
          "offset": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Offset"
          },
          "total": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Total"
          }
        },
        "title": "Paginated[SemanticMetricRead]",
        "type": "object"
      },
      "Paginated[SemanticVersionRead]": {
        "properties": {
          "has_more": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Has More"
          },
          "items": {
            "items": {
              "$ref": "#/components/schemas/SemanticVersionRead"
            },
            "title": "Items",
            "type": "array"
          },
          "limit": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Limit"
          },
          "offset": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Offset"
          },
          "total": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Total"
          }
        },
        "title": "Paginated[SemanticVersionRead]",
        "type": "object"
      },
      "Paginated[SnapshotRead]": {
        "properties": {
          "has_more": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Has More"
          },
          "items": {
            "items": {
              "$ref": "#/components/schemas/SnapshotRead"
            },
            "title": "Items",
            "type": "array"
          },
          "limit": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Limit"
          },
          "offset": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Offset"
          },
          "total": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Total"
          }
        },
        "title": "Paginated[SnapshotRead]",
        "type": "object"
      },
      "Paginated[TableRead]": {
        "properties": {
          "has_more": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Has More"
          },
          "items": {
            "items": {
              "$ref": "#/components/schemas/TableRead"
            },
            "title": "Items",
            "type": "array"
          },
          "limit": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Limit"
          },
          "offset": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Offset"
          },
          "total": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Total"
          }
        },
        "title": "Paginated[TableRead]",
        "type": "object"
      },
      "Paginated[WorkspaceRead]": {
        "properties": {
          "has_more": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Has More"
          },
          "items": {
            "items": {
              "$ref": "#/components/schemas/WorkspaceRead"
            },
            "title": "Items",
            "type": "array"
          },
          "limit": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Limit"
          },
          "offset": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Offset"
          },
          "total": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Total"
          }
        },
        "title": "Paginated[WorkspaceRead]",
        "type": "object"
      },
      "PurgeAccepted": {
        "description": "202 Accepted envelope for purge-style endpoints.\n\n``status`` is always ``\"accepted\"`` (mirrors the workspaces purge\ncontract). ``tombstone_expires_at`` is a human-readable hint --\nconsumers receive an ISO-8601 timestamp when the retention job\nactually deletes the SQL row; today the value is the ``+90d``\nplaceholder (90 days mirrors ``conv_ttl_days``).",
        "properties": {
          "status": {
            "default": "accepted",
            "description": "Always 'accepted' for 202 responses.",
            "title": "Status",
            "type": "string"
          },
          "tombstone_expires_at": {
            "description": "When the SQL row is expected to be hard-deleted. ISO-8601 once a retention job is wired; today returns a coarse hint such as '+90d'.",
            "title": "Tombstone Expires At",
            "type": "string"
          }
        },
        "required": [
          "tombstone_expires_at"
        ],
        "title": "PurgeAccepted",
        "type": "object"
      },
      "QueryDetailRead": {
        "description": "Full single-query payload for `GET /api/v1/queries/{id}`.\n\nIncludes every candidate proposal, the AST classification, every\nmodel identifier used (grounding / generation / critic / explainer),\nPII findings, clarification frame, and the final error envelope if\nany. JSONB columns are passed through as Python dicts / lists.",
        "properties": {
          "ast_classification": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Ast Classification"
          },
          "candidates_json": {
            "items": {},
            "title": "Candidates Json",
            "type": "array"
          },
          "chosen_candidate_index": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Chosen Candidate Index"
          },
          "clarification_emitted": {
            "default": false,
            "title": "Clarification Emitted",
            "type": "boolean"
          },
          "clarification_json": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Clarification Json"
          },
          "cost_cents": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Cost Cents"
          },
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "dataset_id": {
            "anyOf": [
              {
                "format": "uuid",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Dataset Id"
          },
          "elapsed_ms": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Elapsed Ms"
          },
          "error_json": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Error Json"
          },
          "executed_sql": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Executed Sql"
          },
          "execution_engine": {
            "default": "duckdb",
            "title": "Execution Engine",
            "type": "string"
          },
          "execution_status": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Execution Status"
          },
          "finalised_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Finalised At"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "model_critic": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Model Critic"
          },
          "model_explainer": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Model Explainer"
          },
          "model_generation": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Model Generation"
          },
          "model_grounding": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Model Grounding"
          },
          "pii_findings_json": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Pii Findings Json"
          },
          "prior_turn_ids": {
            "items": {
              "format": "uuid",
              "type": "string"
            },
            "title": "Prior Turn Ids",
            "type": "array"
          },
          "question": {
            "title": "Question",
            "type": "string"
          },
          "retries": {
            "default": 0,
            "title": "Retries",
            "type": "integer"
          },
          "row_count": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Row Count"
          },
          "semantic_path_taken": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Semantic Path Taken"
          },
          "table_id_snapshot_pins_json": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Table Id Snapshot Pins Json"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          },
          "workspace_id": {
            "format": "uuid",
            "title": "Workspace Id",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "workspace_id",
          "question",
          "created_at"
        ],
        "title": "QueryDetailRead",
        "type": "object"
      },
      "QueryHistoryItem": {
        "description": "Compact row for `GET /api/v1/queries` (history list).\n\nHeavy JSONB columns (candidates, clarification, pii_findings) are\nomitted here so a 50-item page stays under a few KB; the detail\nendpoint exposes them via :class:`QueryDetailRead`.",
        "properties": {
          "ast_classification": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Ast Classification"
          },
          "clarification_emitted": {
            "default": false,
            "title": "Clarification Emitted",
            "type": "boolean"
          },
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "dataset_id": {
            "anyOf": [
              {
                "format": "uuid",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Dataset Id"
          },
          "elapsed_ms": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Elapsed Ms"
          },
          "executed_sql": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Executed Sql"
          },
          "execution_status": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Execution Status"
          },
          "finalised_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Finalised At"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "question": {
            "title": "Question",
            "type": "string"
          },
          "retries": {
            "default": 0,
            "title": "Retries",
            "type": "integer"
          },
          "row_count": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Row Count"
          },
          "semantic_path_taken": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Semantic Path Taken"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          },
          "workspace_id": {
            "format": "uuid",
            "title": "Workspace Id",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "workspace_id",
          "question",
          "created_at"
        ],
        "title": "QueryHistoryItem",
        "type": "object"
      },
      "QueryRequest": {
        "description": "Request body for POST /api/v1/query and /query:explain, /query:validate.",
        "properties": {
          "conversation_id": {
            "anyOf": [
              {
                "format": "uuid",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Conversation Id"
          },
          "dataset_id": {
            "format": "uuid",
            "title": "Dataset Id",
            "type": "string"
          },
          "question": {
            "maxLength": 4096,
            "minLength": 1,
            "title": "Question",
            "type": "string"
          }
        },
        "required": [
          "dataset_id",
          "question"
        ],
        "title": "QueryRequest",
        "type": "object"
      },
      "QueryResultRead": {
        "description": "Re-download envelope for `GET /api/v1/queries/{id}/result`.\n\nThe preview is always inlined. ``parquet_presigned_url`` is set\nwhen the full Parquet is still available on the object store\n(i.e. ``ttl_expires_at`` hasn't elapsed). When the TTL is past\nthe URL is ``None`` and the consumer must rerun the query.",
        "properties": {
          "parquet_presigned_url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Parquet Presigned Url"
          },
          "preview_json": {
            "title": "Preview Json"
          },
          "query_id": {
            "format": "uuid",
            "title": "Query Id",
            "type": "string"
          },
          "result_byte_size": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Result Byte Size"
          },
          "ttl_expires_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Ttl Expires At"
          }
        },
        "required": [
          "query_id",
          "preview_json"
        ],
        "title": "QueryResultRead",
        "type": "object"
      },
      "RelationApprovalRead": {
        "description": "Compact response from POST /relations/{id}:approve.",
        "properties": {
          "approved_by": {
            "title": "Approved By",
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "status": {
            "title": "Status",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          }
        },
        "required": [
          "id",
          "status",
          "approved_by",
          "updated_at"
        ],
        "title": "RelationApprovalRead",
        "type": "object"
      },
      "RelationRead": {
        "description": "One relation row, joined with its from/to table names for the API edge.",
        "properties": {
          "approved_by": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Approved By"
          },
          "confidence": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              }
            ],
            "title": "Confidence"
          },
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "dataset_id": {
            "format": "uuid",
            "title": "Dataset Id",
            "type": "string"
          },
          "from_column_name": {
            "title": "From Column Name",
            "type": "string"
          },
          "from_table_id": {
            "format": "uuid",
            "title": "From Table Id",
            "type": "string"
          },
          "from_table_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "From Table Name"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "kind": {
            "title": "Kind",
            "type": "string"
          },
          "reason": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Reason"
          },
          "status": {
            "title": "Status",
            "type": "string"
          },
          "to_column_name": {
            "title": "To Column Name",
            "type": "string"
          },
          "to_table_id": {
            "format": "uuid",
            "title": "To Table Id",
            "type": "string"
          },
          "to_table_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "To Table Name"
          },
          "updated_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Updated At"
          }
        },
        "required": [
          "id",
          "dataset_id",
          "from_table_id",
          "from_column_name",
          "to_table_id",
          "to_column_name",
          "kind",
          "confidence",
          "status",
          "created_at"
        ],
        "title": "RelationRead",
        "type": "object"
      },
      "RelationRejectionRead": {
        "description": "Compact response from POST /relations/{id}:reject.",
        "properties": {
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "status": {
            "title": "Status",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          }
        },
        "required": [
          "id",
          "status",
          "updated_at"
        ],
        "title": "RelationRejectionRead",
        "type": "object"
      },
      "ReuploadResponse": {
        "description": "Response from PUT /datasets/{ds}/tables/{id}:upload.",
        "properties": {
          "file_id": {
            "title": "File Id",
            "type": "string"
          },
          "n_columns": {
            "title": "N Columns",
            "type": "integer"
          },
          "n_rows_actual": {
            "title": "N Rows Actual",
            "type": "integer"
          },
          "snapshot_id": {
            "title": "Snapshot Id",
            "type": "string"
          }
        },
        "required": [
          "file_id",
          "snapshot_id",
          "n_columns",
          "n_rows_actual"
        ],
        "title": "ReuploadResponse",
        "type": "object"
      },
      "SchemaChangeRead": {
        "description": "Response for GET /tables/{id}/changes items.",
        "properties": {
          "after_json": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "After Json"
          },
          "approved_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Approved At"
          },
          "approved_by": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Approved By"
          },
          "before_json": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Before Json"
          },
          "change": {
            "title": "Change",
            "type": "string"
          },
          "column_name": {
            "title": "Column Name",
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "llm_rationale": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Llm Rationale"
          },
          "next_snapshot_id": {
            "format": "uuid",
            "title": "Next Snapshot Id",
            "type": "string"
          },
          "prev_snapshot_id": {
            "anyOf": [
              {
                "format": "uuid",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Prev Snapshot Id"
          },
          "table_id": {
            "format": "uuid",
            "title": "Table Id",
            "type": "string"
          }
        },
        "required": [
          "id",
          "table_id",
          "prev_snapshot_id",
          "next_snapshot_id",
          "column_name",
          "change",
          "before_json",
          "after_json",
          "llm_rationale",
          "created_at"
        ],
        "title": "SchemaChangeRead",
        "type": "object"
      },
      "SchemaObjectRead": {
        "description": "Response for GET /schema-objects/{id} or PUT /schema-objects/{id}.\n\nSee :class:`SchemaObjectUpdate` for shape contract. Reads always\nreturn canonical shapes; the validators forgive a legacy row that\nhas not yet been touched by migration 0012.",
        "properties": {
          "business_owner": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Business Owner"
          },
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "data_type": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Data Type"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Description"
          },
          "description_source": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Description Source"
          },
          "governance_json": {
            "additionalProperties": true,
            "default": {},
            "title": "Governance Json",
            "type": "object"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "is_active": {
            "title": "Is Active",
            "type": "boolean"
          },
          "is_nullable": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "title": "Is Nullable"
          },
          "kind": {
            "title": "Kind",
            "type": "string"
          },
          "last_changed_at": {
            "format": "date-time",
            "title": "Last Changed At",
            "type": "string"
          },
          "pii_source": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Pii Source"
          },
          "pii_tag": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Pii Tag"
          },
          "qualified_name": {
            "title": "Qualified Name",
            "type": "string"
          },
          "snapshot_id": {
            "format": "uuid",
            "title": "Snapshot Id",
            "type": "string"
          },
          "synonyms_json": {
            "default": [],
            "items": {
              "type": "string"
            },
            "title": "Synonyms Json",
            "type": "array"
          },
          "table_id": {
            "format": "uuid",
            "title": "Table Id",
            "type": "string"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          },
          "workspace_id": {
            "format": "uuid",
            "title": "Workspace Id",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "workspace_id",
          "table_id",
          "snapshot_id",
          "kind",
          "qualified_name",
          "data_type",
          "is_nullable",
          "description",
          "description_source",
          "pii_tag",
          "pii_source",
          "business_owner",
          "is_active",
          "created_at",
          "last_changed_at"
        ],
        "title": "SchemaObjectRead",
        "type": "object"
      },
      "SchemaObjectUpdate": {
        "description": "Request body for PUT /schema-objects/{id}.\n\n``synonyms_json`` is canonically ``list[str]``; ``governance_json``\nis canonically ``dict[str, Any]``. The validators coerce legacy\nshapes (a synonyms dict envelope, a governance array left behind\nby the ``NULL || dict`` jsonb-concat bug) so a malformed write\npayload still lands as the canonical shape.",
        "properties": {
          "business_owner": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Business Owner"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Description"
          },
          "governance_json": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Governance Json"
          },
          "pii_tag": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Pii Tag"
          },
          "synonyms_json": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Synonyms Json"
          }
        },
        "title": "SchemaObjectUpdate",
        "type": "object"
      },
      "SemanticDimensionCreate": {
        "description": "Payload for creating a new semantic dimension.\n\nThe dimension's ``type`` (categorical|time) is taken from the\n``definition_yaml`` body, not a separate request field.",
        "properties": {
          "dataset_id": {
            "format": "uuid",
            "title": "Dataset Id",
            "type": "string"
          },
          "definition_yaml": {
            "minLength": 1,
            "title": "Definition Yaml",
            "type": "string"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Description"
          },
          "label": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Label"
          },
          "name": {
            "maxLength": 256,
            "minLength": 1,
            "title": "Name",
            "type": "string"
          }
        },
        "required": [
          "dataset_id",
          "name",
          "definition_yaml"
        ],
        "title": "SemanticDimensionCreate",
        "type": "object"
      },
      "SemanticDimensionRead": {
        "description": "Full read representation of a flyquery_semantic_dimensions row.",
        "properties": {
          "compiled_sql_template": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Compiled Sql Template"
          },
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "current_version": {
            "title": "Current Version",
            "type": "integer"
          },
          "dataset_id": {
            "format": "uuid",
            "title": "Dataset Id",
            "type": "string"
          },
          "definition_yaml": {
            "title": "Definition Yaml",
            "type": "string"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Description"
          },
          "dimension_type": {
            "enum": [
              "categorical",
              "time"
            ],
            "title": "Dimension Type",
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "label": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Label"
          },
          "metadata_json": {
            "additionalProperties": true,
            "title": "Metadata Json",
            "type": "object"
          },
          "name": {
            "title": "Name",
            "type": "string"
          },
          "status": {
            "enum": [
              "DRAFT",
              "PUBLISHED",
              "RETIRED"
            ],
            "title": "Status",
            "type": "string"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          },
          "workspace_id": {
            "format": "uuid",
            "title": "Workspace Id",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "workspace_id",
          "dataset_id",
          "name",
          "label",
          "description",
          "definition_yaml",
          "compiled_sql_template",
          "dimension_type",
          "status",
          "current_version",
          "created_at",
          "updated_at"
        ],
        "title": "SemanticDimensionRead",
        "type": "object"
      },
      "SemanticDimensionUpdate": {
        "description": "Sparse-update payload for an existing semantic dimension.",
        "properties": {
          "definition_yaml": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Definition Yaml"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Description"
          },
          "label": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Label"
          }
        },
        "title": "SemanticDimensionUpdate",
        "type": "object"
      },
      "SemanticMetricCreate": {
        "description": "Payload for creating a new semantic metric.",
        "properties": {
          "dataset_id": {
            "format": "uuid",
            "title": "Dataset Id",
            "type": "string"
          },
          "definition_yaml": {
            "minLength": 1,
            "title": "Definition Yaml",
            "type": "string"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Description"
          },
          "label": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Label"
          },
          "metric_type": {
            "default": "SIMPLE",
            "enum": [
              "SIMPLE",
              "RATIO",
              "DERIVED",
              "CUMULATIVE"
            ],
            "title": "Metric Type",
            "type": "string"
          },
          "name": {
            "maxLength": 256,
            "minLength": 1,
            "title": "Name",
            "type": "string"
          }
        },
        "required": [
          "dataset_id",
          "name",
          "definition_yaml"
        ],
        "title": "SemanticMetricCreate",
        "type": "object"
      },
      "SemanticMetricRead": {
        "description": "Full read representation of a flyquery_semantic_metrics row.",
        "properties": {
          "compiled_sql_template": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Compiled Sql Template"
          },
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "current_version": {
            "title": "Current Version",
            "type": "integer"
          },
          "dataset_id": {
            "format": "uuid",
            "title": "Dataset Id",
            "type": "string"
          },
          "definition_yaml": {
            "title": "Definition Yaml",
            "type": "string"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Description"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "label": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Label"
          },
          "metadata_json": {
            "additionalProperties": true,
            "title": "Metadata Json",
            "type": "object"
          },
          "metric_type": {
            "enum": [
              "SIMPLE",
              "RATIO",
              "DERIVED",
              "CUMULATIVE"
            ],
            "title": "Metric Type",
            "type": "string"
          },
          "name": {
            "title": "Name",
            "type": "string"
          },
          "status": {
            "enum": [
              "DRAFT",
              "PUBLISHED",
              "RETIRED"
            ],
            "title": "Status",
            "type": "string"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          },
          "workspace_id": {
            "format": "uuid",
            "title": "Workspace Id",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "workspace_id",
          "dataset_id",
          "name",
          "label",
          "description",
          "definition_yaml",
          "compiled_sql_template",
          "metric_type",
          "status",
          "current_version",
          "created_at",
          "updated_at"
        ],
        "title": "SemanticMetricRead",
        "type": "object"
      },
      "SemanticMetricUpdate": {
        "description": "Sparse-update payload for an existing semantic metric.",
        "properties": {
          "definition_yaml": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Definition Yaml"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Description"
          },
          "label": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Label"
          },
          "metric_type": {
            "anyOf": [
              {
                "enum": [
                  "SIMPLE",
                  "RATIO",
                  "DERIVED",
                  "CUMULATIVE"
                ],
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Metric Type"
          }
        },
        "title": "SemanticMetricUpdate",
        "type": "object"
      },
      "SemanticVersionRead": {
        "description": "Read representation of a flyquery_semantic_versions row.\n\nField names follow the documented payload (``version_number``,\n``metric_id``); the underlying columns are ``version`` / ``parent_id``\nand are mapped via validation aliases.",
        "properties": {
          "compiled_sql_template": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Compiled Sql Template"
          },
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "created_by": {
            "title": "Created By",
            "type": "string"
          },
          "definition_yaml": {
            "title": "Definition Yaml",
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "kind": {
            "title": "Kind",
            "type": "string"
          },
          "parent_id": {
            "format": "uuid",
            "title": "Parent Id",
            "type": "string"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          },
          "version": {
            "title": "Version",
            "type": "integer"
          },
          "workspace_id": {
            "format": "uuid",
            "title": "Workspace Id",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "workspace_id",
          "kind",
          "parent_id",
          "version",
          "definition_yaml",
          "compiled_sql_template",
          "created_by",
          "created_at"
        ],
        "title": "SemanticVersionRead",
        "type": "object"
      },
      "SnapshotRead": {
        "description": "Response for GET /tables/{id}/snapshots items.",
        "properties": {
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "n_columns": {
            "title": "N Columns",
            "type": "integer"
          },
          "n_rows_actual": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "N Rows Actual"
          },
          "n_rows_estimate": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "N Rows Estimate"
          },
          "parquet_byte_size": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Parquet Byte Size"
          },
          "status": {
            "title": "Status",
            "type": "string"
          },
          "table_id": {
            "format": "uuid",
            "title": "Table Id",
            "type": "string"
          },
          "taken_at": {
            "format": "date-time",
            "title": "Taken At",
            "type": "string"
          },
          "triggered_by": {
            "title": "Triggered By",
            "type": "string"
          }
        },
        "required": [
          "id",
          "table_id",
          "taken_at",
          "n_columns",
          "n_rows_actual",
          "n_rows_estimate",
          "parquet_byte_size",
          "status",
          "triggered_by"
        ],
        "title": "SnapshotRead",
        "type": "object"
      },
      "SqlExecuteRequest": {
        "description": "Request body for POST /api/v1/sql:execute.",
        "properties": {
          "dataset_id": {
            "format": "uuid",
            "title": "Dataset Id",
            "type": "string"
          },
          "sql": {
            "maxLength": 65536,
            "minLength": 1,
            "title": "Sql",
            "type": "string"
          }
        },
        "required": [
          "dataset_id",
          "sql"
        ],
        "title": "SqlExecuteRequest",
        "type": "object"
      },
      "SqlExecuteResponse": {
        "description": "Response from POST /api/v1/sql:execute (sync).",
        "properties": {
          "ast_classification": {
            "title": "Ast Classification",
            "type": "string"
          },
          "elapsed_ms": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Elapsed Ms"
          },
          "execution_status": {
            "enum": [
              "OK",
              "FAILED",
              "REJECTED_BY_FIREWALL"
            ],
            "title": "Execution Status",
            "type": "string"
          },
          "preview": {
            "anyOf": [
              {
                "items": {
                  "additionalProperties": true,
                  "type": "object"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Preview"
          },
          "query_id": {
            "format": "uuid",
            "title": "Query Id",
            "type": "string"
          },
          "row_count": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Row Count"
          },
          "sql": {
            "title": "Sql",
            "type": "string"
          },
          "truncated": {
            "default": false,
            "title": "Truncated",
            "type": "boolean"
          }
        },
        "required": [
          "query_id",
          "sql",
          "ast_classification",
          "execution_status",
          "preview",
          "row_count",
          "elapsed_ms"
        ],
        "title": "SqlExecuteResponse",
        "type": "object"
      },
      "TableRead": {
        "description": "Response for GET /tables/{id}.",
        "properties": {
          "business_owner": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Business Owner"
          },
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "current_snapshot_id": {
            "anyOf": [
              {
                "format": "uuid",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Current Snapshot Id"
          },
          "dataset_id": {
            "format": "uuid",
            "title": "Dataset Id",
            "type": "string"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Description"
          },
          "description_source": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Description Source"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "is_active": {
            "title": "Is Active",
            "type": "boolean"
          },
          "kind": {
            "title": "Kind",
            "type": "string"
          },
          "n_columns": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "N Columns"
          },
          "name": {
            "title": "Name",
            "type": "string"
          },
          "qualified_name": {
            "title": "Qualified Name",
            "type": "string"
          },
          "sheet_or_json_path": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Sheet Or Json Path"
          },
          "source_file_id": {
            "anyOf": [
              {
                "format": "uuid",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Source File Id"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          },
          "workspace_id": {
            "format": "uuid",
            "title": "Workspace Id",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "workspace_id",
          "dataset_id",
          "source_file_id",
          "name",
          "qualified_name",
          "kind",
          "sheet_or_json_path",
          "current_snapshot_id",
          "description",
          "description_source",
          "business_owner",
          "is_active",
          "created_at",
          "updated_at"
        ],
        "title": "TableRead",
        "type": "object"
      },
      "TableSummary": {
        "description": "Summary of a table created/updated by an upload.",
        "properties": {
          "n_columns": {
            "title": "N Columns",
            "type": "integer"
          },
          "n_rows_estimate": {
            "title": "N Rows Estimate",
            "type": "integer"
          },
          "name": {
            "title": "Name",
            "type": "string"
          },
          "table_id": {
            "title": "Table Id",
            "type": "string"
          }
        },
        "required": [
          "table_id",
          "name",
          "n_columns",
          "n_rows_estimate"
        ],
        "title": "TableSummary",
        "type": "object"
      },
      "TurnRead": {
        "description": "Single conversation turn.",
        "properties": {
          "conversation_id": {
            "format": "uuid",
            "title": "Conversation Id",
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "elapsed_ms": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Elapsed Ms"
          },
          "executed_sql": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Executed Sql"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "no_answer": {
            "title": "No Answer",
            "type": "boolean"
          },
          "question": {
            "title": "Question",
            "type": "string"
          },
          "snapshot_pins_json": {
            "additionalProperties": true,
            "title": "Snapshot Pins Json",
            "type": "object"
          },
          "summary": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Summary"
          },
          "table_qnames_json": {
            "items": {
              "type": "string"
            },
            "title": "Table Qnames Json",
            "type": "array"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          },
          "turn_index": {
            "title": "Turn Index",
            "type": "integer"
          },
          "workspace_id": {
            "format": "uuid",
            "title": "Workspace Id",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "workspace_id",
          "conversation_id",
          "turn_index",
          "question",
          "executed_sql",
          "summary",
          "no_answer",
          "elapsed_ms",
          "created_at"
        ],
        "title": "TurnRead",
        "type": "object"
      },
      "UsageSummary": {
        "description": "Aggregated cost + latency across the whole pipeline.\n\nReturned on every query / ingest response so clients can\nshow consumption to end users and stream into a billing\npipeline. The per-stage breakdown stays in ``by_agent`` for\ndebugging.",
        "properties": {
          "by_agent": {
            "items": {
              "$ref": "#/components/schemas/AgentUsage"
            },
            "title": "By Agent",
            "type": "array"
          },
          "total_cost_usd": {
            "default": 0.0,
            "title": "Total Cost Usd",
            "type": "number"
          },
          "total_input_tokens": {
            "default": 0,
            "title": "Total Input Tokens",
            "type": "integer"
          },
          "total_latency_ms": {
            "default": 0.0,
            "title": "Total Latency Ms",
            "type": "number"
          },
          "total_output_tokens": {
            "default": 0,
            "title": "Total Output Tokens",
            "type": "integer"
          },
          "total_tokens": {
            "default": 0,
            "title": "Total Tokens",
            "type": "integer"
          }
        },
        "title": "UsageSummary",
        "type": "object"
      },
      "ValidateResponse": {
        "description": "Response from POST /api/v1/query:validate \u2014 includes AST + scope check.",
        "properties": {
          "ast_classification": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Ast Classification"
          },
          "clarification": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ClarificationFrame"
              },
              {
                "type": "null"
              }
            ],
            "default": null
          },
          "scope_error": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Scope Error"
          },
          "single_statement": {
            "default": true,
            "title": "Single Statement",
            "type": "boolean"
          },
          "sql": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Sql"
          },
          "table_refs": {
            "items": {
              "type": "string"
            },
            "title": "Table Refs",
            "type": "array"
          }
        },
        "required": [
          "sql",
          "ast_classification"
        ],
        "title": "ValidateResponse",
        "type": "object"
      },
      "ValidationError": {
        "properties": {
          "detail": {
            "items": {
              "properties": {
                "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"
              ],
              "type": "object"
            },
            "title": "Detail",
            "type": "array"
          }
        },
        "required": [
          "detail"
        ],
        "title": "ValidationError",
        "type": "object"
      },
      "WorkspaceCreate": {
        "properties": {
          "allow_direct_sql": {
            "default": false,
            "title": "Allow Direct Sql",
            "type": "boolean"
          },
          "default_locale": {
            "default": "en-US",
            "title": "Default Locale",
            "type": "string"
          },
          "kms_key_uri": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Kms Key Uri"
          },
          "metadata_json": {
            "additionalProperties": true,
            "title": "Metadata Json",
            "type": "object"
          },
          "name": {
            "maxLength": 200,
            "minLength": 1,
            "title": "Name",
            "type": "string"
          },
          "retention_days": {
            "anyOf": [
              {
                "minimum": 1,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Retention Days"
          },
          "slug": {
            "maxLength": 64,
            "minLength": 1,
            "title": "Slug",
            "type": "string"
          }
        },
        "required": [
          "slug",
          "name"
        ],
        "title": "WorkspaceCreate",
        "type": "object"
      },
      "WorkspaceRead": {
        "properties": {
          "allow_direct_sql": {
            "title": "Allow Direct Sql",
            "type": "boolean"
          },
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "default_locale": {
            "title": "Default Locale",
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "kms_key_uri": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Kms Key Uri"
          },
          "metadata_json": {
            "additionalProperties": true,
            "title": "Metadata Json",
            "type": "object"
          },
          "name": {
            "title": "Name",
            "type": "string"
          },
          "retention_days": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Retention Days"
          },
          "slug": {
            "title": "Slug",
            "type": "string"
          },
          "status": {
            "enum": [
              "ACTIVE",
              "ARCHIVED",
              "PURGING"
            ],
            "title": "Status",
            "type": "string"
          },
          "storage_used_bytes": {
            "title": "Storage Used Bytes",
            "type": "integer"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "slug",
          "name",
          "kms_key_uri",
          "retention_days",
          "allow_direct_sql",
          "default_locale",
          "storage_used_bytes",
          "status",
          "created_at",
          "updated_at",
          "metadata_json"
        ],
        "title": "WorkspaceRead",
        "type": "object"
      },
      "WorkspaceStats": {
        "description": "Response from GET /api/v1/stats -- compact workspace summary.",
        "properties": {
          "dataset_count": {
            "title": "Dataset Count",
            "type": "integer"
          },
          "ingest_job_count_pending": {
            "title": "Ingest Job Count Pending",
            "type": "integer"
          },
          "query_count_last_30d": {
            "title": "Query Count Last 30D",
            "type": "integer"
          },
          "storage_used_bytes": {
            "title": "Storage Used Bytes",
            "type": "integer"
          },
          "table_count": {
            "title": "Table Count",
            "type": "integer"
          },
          "token_count_last_30d": {
            "title": "Token Count Last 30D",
            "type": "integer"
          }
        },
        "required": [
          "storage_used_bytes",
          "dataset_count",
          "table_count",
          "query_count_last_30d",
          "token_count_last_30d",
          "ingest_job_count_pending"
        ],
        "title": "WorkspaceStats",
        "type": "object"
      },
      "WorkspaceUpdate": {
        "properties": {
          "allow_direct_sql": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Allow Direct Sql"
          },
          "default_locale": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Default Locale"
          },
          "kms_key_uri": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Kms Key Uri"
          },
          "metadata_json": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Metadata Json"
          },
          "name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Name"
          },
          "retention_days": {
            "anyOf": [
              {
                "minimum": 1,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Retention Days"
          }
        },
        "title": "WorkspaceUpdate",
        "type": "object"
      }
    },
    "securitySchemes": {
      "AgentToken": {
        "description": "Bearer token for the agent tier. Required on every ``/api/v1/agent/*`` operation. Replaces tenant + workspace headers -- the token's claims carry both.",
        "in": "header",
        "name": "X-Agent-Token",
        "type": "apiKey"
      },
      "TenantContext": {
        "description": "Non-agent operations require ``X-Tenant-Id`` + ``X-Workspace-Id`` headers. Treated as an apiKey scheme so Swagger UI's `Authorize` dialog can prefill them across all requests.",
        "in": "header",
        "name": "X-Tenant-Id",
        "type": "apiKey"
      },
      "WorkspaceContext": {
        "description": "Companion header to TenantContext (accepts UUID or slug).",
        "in": "header",
        "name": "X-Workspace-Id",
        "type": "apiKey"
      }
    }
  },
  "info": {
    "contact": {
      "name": "Firefly Framework",
      "url": "https://github.com/fireflyframework/flyquery"
    },
    "description": "Operational Structured-Data Intelligence (upload-driven) -- multi-tenant ingestion + Text-to-SQL over user-uploaded structured files (CSV / TSV / XLSX / XLS / ODS / JSON / JSONL / Parquet / Avro / ORC / Arrow / Feather + .gz/.zip/.bz2 variants). Materialises uploads to Parquet on object storage; indexes a long-lived schema knowledge base; answers natural-language questions via a multi-agent pipeline. Part of Firefly Framework.",
    "license": {
      "name": "Apache-2.0",
      "url": "https://github.com/fireflyframework/flyquery/blob/main/LICENSE"
    },
    "title": "flyquery",
    "version": "26.10.4"
  },
  "openapi": "3.1.0",
  "paths": {
    "/api/v1/agent-tokens": {
      "get": {
        "description": "Returns the summary shape only -- the secret is never\nround-tripped on this endpoint.",
        "operationId": "list_tokens",
        "parameters": [
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/AgentTokenSummaryDto"
                  },
                  "type": "array"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "List tokens for the current tenant (newest first).",
        "tags": [
          "AgentTokens"
        ]
      },
      "post": {
        "description": "Returns 201 with the full ``token`` populated. The token is\nonly returned this once -- subsequent reads expose only\n``prefix``. Refuses agent-tier callers with\n``403 agent_cannot_mint``.",
        "operationId": "mint",
        "parameters": [
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentTokenMintRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentTokenCreated"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Mint a new agent token.",
        "tags": [
          "AgentTokens"
        ]
      }
    },
    "/api/v1/agent-tokens/{token_id}": {
      "delete": {
        "description": "Unknown ``token_id`` returns ``404 resource_not_found``.",
        "operationId": "revoke",
        "parameters": [
          {
            "in": "path",
            "name": "token_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "responses": {
          "204": {
            "description": "No Content"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Revoke a token. Idempotent -- already-revoked is a no-op (204).",
        "tags": [
          "AgentTokens"
        ]
      }
    },
    "/api/v1/agent/conversations": {
      "get": {
        "operationId": "list_conversations",
        "parameters": [
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Paginated[ConversationRead]"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "List conversations for the agent's workspace (newest first).",
        "tags": [
          "AgentConversations"
        ]
      },
      "post": {
        "description": "Replay-dedup'd via ``Idempotency-Key`` (required). A retried\ncreate otherwise allocates duplicate empty conversations the\nagent has no way to clean up.",
        "operationId": "create",
        "parameters": [
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConversationCreate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConversationRead"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Create a conversation owned by the calling agent.",
        "tags": [
          "AgentConversations"
        ]
      }
    },
    "/api/v1/agent/conversations/{conversation_id}": {
      "get": {
        "operationId": "read",
        "parameters": [
          {
            "in": "path",
            "name": "conversation_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConversationRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Fetch a conversation with its turns.",
        "tags": [
          "AgentConversations"
        ]
      }
    },
    "/api/v1/agent/conversations/{conversation_id}/turn": {
      "post": {
        "description": "Two scopes are required at the agent layer:\n``flyquery.conversations:write`` (this is a mutating turn\nwrite) and the underlying ``flyquery.query:read`` (the pipeline\nexecutes a query). We verify the conversations scope here and\ndelegate the query-tier check to the pipeline's scope guard.\n\nReplay-dedup'd via ``Idempotency-Key`` (required) -- the\n4-agent pipeline is the costliest endpoint in the API.",
        "operationId": "post_turn",
        "parameters": [
          {
            "in": "path",
            "name": "conversation_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConversationTurnRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnswerResponse"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Run a drill-down turn through the full query pipeline.",
        "tags": [
          "AgentConversations"
        ]
      }
    },
    "/api/v1/agent/datasets": {
      "get": {
        "operationId": "list_datasets",
        "parameters": [
          {
            "in": "query",
            "name": "q",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "name",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "workspace_id",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 100,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "offset",
            "required": false,
            "schema": {
              "default": 0,
              "type": "integer"
            }
          },
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Paginated[DatasetRead]"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Search / filter datasets visible to this agent's tenant.",
        "tags": [
          "AgentDatasets"
        ]
      }
    },
    "/api/v1/agent/datasets/by-name/{name}": {
      "get": {
        "operationId": "read_by_name",
        "parameters": [
          {
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatasetRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Resolve a dataset by ``(tenant, workspace, name)``.",
        "tags": [
          "AgentDatasets"
        ]
      }
    },
    "/api/v1/agent/datasets/{dataset_id}": {
      "get": {
        "operationId": "read",
        "parameters": [
          {
            "in": "path",
            "name": "dataset_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatasetRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Fetch a single dataset by id.",
        "tags": [
          "AgentDatasets"
        ]
      }
    },
    "/api/v1/agent/datasets/{dataset_id}/relations": {
      "get": {
        "operationId": "list_relations",
        "parameters": [
          {
            "in": "path",
            "name": "dataset_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Paginated[RelationRead]"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "tags": [
          "AgentRelations"
        ]
      }
    },
    "/api/v1/agent/datasets/{dataset_id}/tables": {
      "get": {
        "operationId": "list_tables",
        "parameters": [
          {
            "in": "path",
            "name": "dataset_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Paginated[TableRead]"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "tags": [
          "AgentTables"
        ]
      }
    },
    "/api/v1/agent/examples": {
      "get": {
        "description": ":param http_request: Starlette request\n:param quality: optional quality filter (PROPOSED/APPROVED/REJECTED)\n:param dataset_id: optional dataset filter\n:param limit: page size (default 100)\n:param offset: starting offset (default 0)\n:return: Paginated[ExampleRead]",
        "operationId": "list_examples",
        "parameters": [
          {
            "in": "query",
            "name": "quality",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "dataset_id",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 100,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "offset",
            "required": false,
            "schema": {
              "default": 0,
              "type": "integer"
            }
          },
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Paginated[ExampleRead]"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "List examples for the caller's workspace (agent-tier).",
        "tags": [
          "AgentExamples"
        ]
      },
      "post": {
        "description": "Replay-dedup'd via ``Idempotency-Key`` (required). Without\nthis gate an agent retrying a network blip would persist\nduplicate (question, SQL) PROPOSED rows that an operator\nwould then have to manually reject.",
        "operationId": "create",
        "parameters": [
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExampleCreate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExampleRead"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Create an example (agent-tier \u2014 source=AGENT_LEARNED, quality=PROPOSED).",
        "tags": [
          "AgentExamples"
        ]
      }
    },
    "/api/v1/agent/glossary": {
      "get": {
        "operationId": "list_terms",
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 100,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "offset",
            "required": false,
            "schema": {
              "default": 0,
              "type": "integer"
            }
          },
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Paginated[GlossaryTermRead]"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "List glossary terms for the caller's workspace (agent-tier).",
        "tags": [
          "AgentGlossary"
        ]
      },
      "post": {
        "operationId": "create",
        "parameters": [
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GlossaryTermCreate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GlossaryTermRead"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Create a glossary term (agent-tier).",
        "tags": [
          "AgentGlossary"
        ]
      }
    },
    "/api/v1/agent/glossary/{term_id}": {
      "delete": {
        "operationId": "delete",
        "parameters": [
          {
            "in": "path",
            "name": "term_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "responses": {
          "204": {
            "description": "No Content"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Hard-delete a glossary term (agent-tier).",
        "tags": [
          "AgentGlossary"
        ]
      },
      "get": {
        "operationId": "get_term",
        "parameters": [
          {
            "in": "path",
            "name": "term_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GlossaryTermRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Fetch a single glossary term (agent-tier).",
        "tags": [
          "AgentGlossary"
        ]
      },
      "put": {
        "operationId": "update",
        "parameters": [
          {
            "in": "path",
            "name": "term_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GlossaryTermUpdate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GlossaryTermRead"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Sparse-update a glossary term (agent-tier).",
        "tags": [
          "AgentGlossary"
        ]
      }
    },
    "/api/v1/agent/ingest-jobs": {
      "get": {
        "operationId": "list_jobs",
        "parameters": [
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IngestJobListResponse"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "tags": [
          "AgentIngestJobs"
        ]
      },
      "post": {
        "operationId": "create_job",
        "parameters": [
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "responses": {
          "201": {
            "description": "Successful response"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Start a background ingestion job (REPARSE/SAMPLE_REFRESH/...).",
        "tags": [
          "AgentIngestJobs"
        ]
      }
    },
    "/api/v1/agent/ingest-jobs/{job_id}": {
      "get": {
        "operationId": "get_job",
        "parameters": [
          {
            "in": "path",
            "name": "job_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IngestJobRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "tags": [
          "AgentIngestJobs"
        ]
      }
    },
    "/api/v1/agent/ingest-jobs/{job_id}/events": {
      "get": {
        "operationId": "list_events",
        "parameters": [
          {
            "in": "path",
            "name": "job_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IngestEventListResponse"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "tags": [
          "AgentIngestJobs"
        ]
      }
    },
    "/api/v1/agent/ingest-jobs/{job_id}/stream": {
      "get": {
        "operationId": "stream_job",
        "parameters": [
          {
            "in": "path",
            "name": "job_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "SSE progress stream. The underlying delegate handles framing,",
        "tags": [
          "AgentIngestJobs"
        ]
      }
    },
    "/api/v1/agent/ingest-jobs/{job_id}:cancel": {
      "post": {
        "description": "Replay-dedup'd via ``Idempotency-Key`` (required). The\nunderlying service is itself idempotent on terminal jobs, but\nwe still cache the response so a retried cancel returns the\nsame wire envelope (same ``status`` field).",
        "operationId": "cancel_job",
        "parameters": [
          {
            "in": "path",
            "name": "job_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CancelResponse"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Cooperatively cancel a running job.",
        "tags": [
          "AgentIngestJobs"
        ]
      }
    },
    "/api/v1/agent/query": {
      "post": {
        "description": "Replay-dedup'd via ``Idempotency-Key``. The header is *required*\non the agent surface so an at-least-once delivery agent (which\nretries on network error) doesn't burn budget by re-running the\nsame multi-LLM pipeline twice.\n\n:param http_request: Starlette request (provides tenant context + agent token)\n:param body: validated QueryRequest\n:return: AnswerResponse",
        "operationId": "query",
        "parameters": [
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QueryRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnswerResponse"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Run the full NL \u2192 SQL \u2192 result pipeline (agent-tier).",
        "tags": [
          "AgentQuery"
        ]
      }
    },
    "/api/v1/agent/query/stream": {
      "post": {
        "description": ":param http_request: Starlette request\n:param body: validated QueryRequest\n:return: StreamingResponse with text/event-stream",
        "operationId": "stream",
        "parameters": [
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QueryRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "text/event-stream": {
                "schema": {
                  "description": "One SSE frame per event. Frames carry ``event:`` + ``data:`` (JSON-encoded) lines.",
                  "format": "event-stream",
                  "type": "string"
                }
              }
            },
            "description": "Server-Sent Events stream. Each frame follows the SSE wire format ``event: <name>\\ndata: <json>\\n\\n``. See ``docs/api-reference.md`` section 8 for the per-endpoint event catalogue."
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Run the pipeline as SSE stream (agent-tier).",
        "tags": [
          "AgentQuery"
        ]
      }
    },
    "/api/v1/agent/query:batch": {
      "post": {
        "description": "Delegates to the user-tier ``QueryController.batch`` by\ninstantiating it inline (same pattern as :meth:`stream`).\nReplay-dedup'd via ``Idempotency-Key`` (required) -- a batch\nis N parallel multi-LLM pipelines, the costliest single\nrequest shape in the API.",
        "operationId": "batch",
        "parameters": [
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BatchQueryRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchQueryResponse"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Agent-tier mirror of POST /api/v1/query:batch.",
        "tags": [
          "AgentQuery"
        ]
      }
    },
    "/api/v1/agent/query:explain": {
      "post": {
        "description": ":param http_request: Starlette request\n:param body: validated QueryRequest\n:return: ExplainResponse with candidate SQL and reasoning",
        "operationId": "explain",
        "parameters": [
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QueryRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExplainResponse"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Run Grounding + Generation only (agent-tier).",
        "tags": [
          "AgentQuery"
        ]
      }
    },
    "/api/v1/agent/query:validate": {
      "post": {
        "description": ":param http_request: Starlette request\n:param body: validated QueryRequest\n:return: ValidateResponse",
        "operationId": "validate",
        "parameters": [
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QueryRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidateResponse"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Run Grounding + Generation + AST + ScopeGuard (agent-tier).",
        "tags": [
          "AgentQuery"
        ]
      }
    },
    "/api/v1/agent/schema-objects/{object_id}": {
      "get": {
        "operationId": "get_schema_object",
        "parameters": [
          {
            "in": "path",
            "name": "object_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SchemaObjectRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "tags": [
          "AgentTables"
        ]
      }
    },
    "/api/v1/agent/semantic/dimensions": {
      "get": {
        "operationId": "list_dimensions",
        "parameters": [
          {
            "in": "query",
            "name": "dataset_id",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 100,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "offset",
            "required": false,
            "schema": {
              "default": 0,
              "type": "integer"
            }
          },
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Paginated[SemanticDimensionRead]"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "List dimensions for the caller's workspace (agent-tier).",
        "tags": [
          "AgentSemanticDimensions"
        ]
      },
      "post": {
        "operationId": "create",
        "parameters": [
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SemanticDimensionCreate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SemanticDimensionRead"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Create a dimension in DRAFT (agent-tier).",
        "tags": [
          "AgentSemanticDimensions"
        ]
      }
    },
    "/api/v1/agent/semantic/dimensions/{dimension_id}": {
      "get": {
        "operationId": "get_dimension",
        "parameters": [
          {
            "in": "path",
            "name": "dimension_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SemanticDimensionRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Fetch a single dimension (agent-tier).",
        "tags": [
          "AgentSemanticDimensions"
        ]
      },
      "put": {
        "operationId": "update",
        "parameters": [
          {
            "in": "path",
            "name": "dimension_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SemanticDimensionUpdate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SemanticDimensionRead"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Sparse-update a dimension (agent-tier).",
        "tags": [
          "AgentSemanticDimensions"
        ]
      }
    },
    "/api/v1/agent/semantic/dimensions/{dimension_id}/history": {
      "get": {
        "operationId": "history",
        "parameters": [
          {
            "in": "path",
            "name": "dimension_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Paginated[SemanticVersionRead]"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Return version history for a dimension (agent-tier).",
        "tags": [
          "AgentSemanticDimensions"
        ]
      }
    },
    "/api/v1/agent/semantic/dimensions/{dimension_id}:publish": {
      "post": {
        "operationId": "publish",
        "parameters": [
          {
            "in": "path",
            "name": "dimension_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SemanticDimensionRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Publish a dimension (agent-tier).",
        "tags": [
          "AgentSemanticDimensions"
        ]
      }
    },
    "/api/v1/agent/semantic/dimensions/{dimension_id}:retire": {
      "post": {
        "operationId": "retire",
        "parameters": [
          {
            "in": "path",
            "name": "dimension_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SemanticDimensionRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Retire a dimension (agent-tier).",
        "tags": [
          "AgentSemanticDimensions"
        ]
      }
    },
    "/api/v1/agent/semantic/metrics": {
      "get": {
        "operationId": "list_metrics",
        "parameters": [
          {
            "in": "query",
            "name": "dataset_id",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 100,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "offset",
            "required": false,
            "schema": {
              "default": 0,
              "type": "integer"
            }
          },
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Paginated[SemanticMetricRead]"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "List metrics for the caller's workspace (agent-tier).",
        "tags": [
          "AgentSemanticMetrics"
        ]
      },
      "post": {
        "operationId": "create",
        "parameters": [
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SemanticMetricCreate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SemanticMetricRead"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Create a metric in DRAFT (agent-tier).",
        "tags": [
          "AgentSemanticMetrics"
        ]
      }
    },
    "/api/v1/agent/semantic/metrics/{metric_id}": {
      "get": {
        "operationId": "get_metric",
        "parameters": [
          {
            "in": "path",
            "name": "metric_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SemanticMetricRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Fetch a single metric (agent-tier).",
        "tags": [
          "AgentSemanticMetrics"
        ]
      },
      "put": {
        "operationId": "update",
        "parameters": [
          {
            "in": "path",
            "name": "metric_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SemanticMetricUpdate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SemanticMetricRead"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Sparse-update a metric (agent-tier).",
        "tags": [
          "AgentSemanticMetrics"
        ]
      }
    },
    "/api/v1/agent/semantic/metrics/{metric_id}/history": {
      "get": {
        "operationId": "history",
        "parameters": [
          {
            "in": "path",
            "name": "metric_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Paginated[SemanticVersionRead]"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Return version history for a metric (agent-tier).",
        "tags": [
          "AgentSemanticMetrics"
        ]
      }
    },
    "/api/v1/agent/semantic/metrics/{metric_id}:publish": {
      "post": {
        "operationId": "publish",
        "parameters": [
          {
            "in": "path",
            "name": "metric_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SemanticMetricRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Publish a metric (agent-tier).",
        "tags": [
          "AgentSemanticMetrics"
        ]
      }
    },
    "/api/v1/agent/semantic/metrics/{metric_id}:retire": {
      "post": {
        "operationId": "retire",
        "parameters": [
          {
            "in": "path",
            "name": "metric_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SemanticMetricRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Retire a metric (agent-tier).",
        "tags": [
          "AgentSemanticMetrics"
        ]
      }
    },
    "/api/v1/agent/sql:execute": {
      "post": {
        "description": "Replay-dedup'd via ``Idempotency-Key`` -- required, because a\nretried direct-SQL execution would re-scan the dataset and\nburn query budget for no caller benefit.",
        "operationId": "execute",
        "parameters": [
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SqlExecuteRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SqlExecuteResponse"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Execute SQL directly (agent-tier).",
        "tags": [
          "AgentSqlExecute"
        ]
      }
    },
    "/api/v1/agent/sql:execute/stream": {
      "post": {
        "description": ":param http_request: Starlette request\n:param body: validated SqlExecuteRequest\n:return: StreamingResponse with text/event-stream",
        "operationId": "execute_stream",
        "parameters": [
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SqlExecuteRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "text/event-stream": {
                "schema": {
                  "description": "One SSE frame per event. Frames carry ``event:`` + ``data:`` (JSON-encoded) lines.",
                  "format": "event-stream",
                  "type": "string"
                }
              }
            },
            "description": "Server-Sent Events stream. Each frame follows the SSE wire format ``event: <name>\\ndata: <json>\\n\\n``. See ``docs/api-reference.md`` section 8 for the per-endpoint event catalogue."
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Execute SQL as SSE stream (agent-tier).",
        "tags": [
          "AgentSqlExecute"
        ]
      }
    },
    "/api/v1/agent/tables": {
      "get": {
        "operationId": "search_tables",
        "parameters": [
          {
            "in": "query",
            "name": "q",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "name",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "dataset_id",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "kind",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "is_active",
            "required": false,
            "schema": {
              "default": null,
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 100,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "offset",
            "required": false,
            "schema": {
              "default": 0,
              "type": "integer"
            }
          },
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Paginated[TableRead]"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "tags": [
          "AgentTables"
        ]
      }
    },
    "/api/v1/agent/tables/by-name/{name}": {
      "get": {
        "operationId": "get_table_by_name",
        "parameters": [
          {
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "dataset_id",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TableRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "tags": [
          "AgentTables"
        ]
      }
    },
    "/api/v1/agent/tables/{table_id}": {
      "get": {
        "operationId": "get_table",
        "parameters": [
          {
            "in": "path",
            "name": "table_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TableRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "tags": [
          "AgentTables"
        ]
      }
    },
    "/api/v1/agent/tables/{table_id}/changes": {
      "get": {
        "operationId": "list_changes",
        "parameters": [
          {
            "in": "path",
            "name": "table_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Paginated[SchemaChangeRead]"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "tags": [
          "AgentTables"
        ]
      }
    },
    "/api/v1/agent/tables/{table_id}/objects": {
      "get": {
        "operationId": "list_objects",
        "parameters": [
          {
            "in": "path",
            "name": "table_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Paginated[SchemaObjectRead]"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "tags": [
          "AgentTables"
        ]
      }
    },
    "/api/v1/agent/tables/{table_id}/snapshots": {
      "get": {
        "operationId": "list_snapshots",
        "parameters": [
          {
            "in": "path",
            "name": "table_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Paginated[SnapshotRead]"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "tags": [
          "AgentTables"
        ]
      }
    },
    "/api/v1/agent/version": {
      "get": {
        "description": "Requires a valid ``X-Agent-Token`` with ``flyquery.audit:read`` scope.\nMissing or invalid tokens return 401 / 403 respectively.",
        "operationId": "version",
        "parameters": [
          {
            "$ref": "#/components/parameters/AgentTokenHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Return service name + CalVer version tag.",
        "tags": [
          "AgentVersion"
        ]
      }
    },
    "/api/v1/audit-events": {
      "get": {
        "description": "Filters\n-------\n* ``event_type``    -- exact match (e.g. ``dataset.created``)\n* ``actor``         -- exact match\n* ``resource_kind`` -- exact match (``dataset`` / ``agent_token`` / ...)\n* ``date_from``     -- inclusive lower bound on ``created_at``\n* ``date_to``       -- exclusive upper bound on ``created_at``",
        "operationId": "list_events",
        "parameters": [
          {
            "in": "query",
            "name": "event_type",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "actor",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "resource_kind",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "date_from",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "date_to",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 100,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "offset",
            "required": false,
            "schema": {
              "default": 0,
              "type": "integer"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Paginated[AuditEventRead]"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "List audit events for the caller's workspace, newest first.",
        "tags": [
          "AuditEvents"
        ]
      }
    },
    "/api/v1/billing": {
      "get": {
        "description": "Query params\n------------\n* ``period``    -- ``day`` (default) / ``week`` / ``month``\n* ``date_from`` -- inclusive lower bound on ``created_at``\n* ``date_to``   -- exclusive upper bound on ``created_at``\n\nResponse shape: :class:`BillingRollup`. Buckets with zero\ncost are omitted from the breakdown (no empty days).",
        "operationId": "rollup",
        "parameters": [
          {
            "in": "query",
            "name": "period",
            "required": false,
            "schema": {
              "default": "day",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "date_from",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "date_to",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillingRollup"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Aggregate LLM cost into ``day`` / ``week`` / ``month`` buckets.",
        "tags": [
          "Billing"
        ]
      }
    },
    "/api/v1/conversations": {
      "get": {
        "description": "Service does not currently return a total; ``has_more`` is\ninferred from page size (``len(items) >= limit`` -> assume\nthere may be more).",
        "operationId": "list_conversations",
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 100,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "offset",
            "required": false,
            "schema": {
              "default": 0,
              "type": "integer"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Paginated[ConversationRead]"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "List conversations for the caller's workspace, newest first.",
        "tags": [
          "Conversations"
        ]
      },
      "post": {
        "description": ":param http_request: Starlette request (tenant context headers)\n:param body: optional title\n:return: the new ConversationRead (no turns yet)",
        "operationId": "create",
        "parameters": [
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConversationCreate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConversationRead"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Create a new conversation.",
        "tags": [
          "Conversations"
        ]
      }
    },
    "/api/v1/conversations/{conversation_id}": {
      "get": {
        "description": ":param conversation_id: conversation UUID\n:return: ConversationRead including turns list\n:raises ResourceNotFound: when conversation does not exist",
        "operationId": "read",
        "parameters": [
          {
            "in": "path",
            "name": "conversation_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConversationRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Fetch a conversation with all its turns.",
        "tags": [
          "Conversations"
        ]
      }
    },
    "/api/v1/conversations/{conversation_id}/turn": {
      "post": {
        "description": "Loads the prior turn's ``executed_sql + table_qnames + snapshot_pins``\nand passes them into the query pipeline as drill-down context.\n\n:param http_request: Starlette request\n:param conversation_id: conversation UUID\n:param body: dataset_id + question\n:return: AnswerResponse from the full pipeline",
        "operationId": "post_turn",
        "parameters": [
          {
            "in": "path",
            "name": "conversation_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConversationTurnRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnswerResponse"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Ask a follow-up question inside an existing conversation.",
        "tags": [
          "Conversations"
        ]
      }
    },
    "/api/v1/cost-events": {
      "get": {
        "description": "Filters\n-------\n* ``actor``     -- exact match\n* ``model``     -- exact match (``anthropic:claude-sonnet-4-6`` etc.)\n* ``operation`` -- exact match (``grounding`` / ``generation`` / ...)\n* ``date_from`` -- inclusive lower bound on ``created_at``\n* ``date_to``   -- exclusive upper bound on ``created_at``",
        "operationId": "list_events",
        "parameters": [
          {
            "in": "query",
            "name": "actor",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "model",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "operation",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "date_from",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "date_to",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 100,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "offset",
            "required": false,
            "schema": {
              "default": 0,
              "type": "integer"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Paginated[CostEventRead]"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "List cost events for the caller's workspace, newest first.",
        "tags": [
          "CostEvents"
        ]
      }
    },
    "/api/v1/datasets": {
      "get": {
        "description": "Query parameters\n----------------\n* ``q``            -- free-text substring against ``name`` or\n``description`` (case-insensitive ``ILIKE``).\n* ``name``         -- exact match -- gives you name-based lookup\nwith zero extra round-trips.\n* ``status``       -- ``ACTIVE`` / ``ARCHIVED`` / ``PURGING``.\n* ``workspace_id`` -- restrict to a single workspace; defaults to\n``X-Workspace-Id`` header. Pass another UUID\nexplicitly to override the header.\n* ``limit``        -- page size, clamped to [1, 1000]. Default 100.\n* ``offset``       -- starting offset. Default 0.\n\nResponse envelope: ``{items, total, limit, offset, has_more}``.",
        "operationId": "list_datasets",
        "parameters": [
          {
            "in": "query",
            "name": "q",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "name",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "workspace_id",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 100,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "offset",
            "required": false,
            "schema": {
              "default": 0,
              "type": "integer"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Paginated[DatasetRead]"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Search/filter datasets for the caller's tenant.",
        "tags": [
          "Datasets"
        ]
      },
      "post": {
        "operationId": "create",
        "parameters": [
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DatasetCreate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatasetRead"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Create a dataset; tenant + workspace come from request headers.",
        "tags": [
          "Datasets"
        ]
      }
    },
    "/api/v1/datasets/by-name/{name}": {
      "get": {
        "description": "Reads the workspace scope from ``X-Workspace-Id``. Datasets enforce\n``UNIQUE(workspace_id, name)`` so the lookup always returns 0 or 1.",
        "operationId": "read_by_name",
        "parameters": [
          {
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatasetRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Resolve a dataset by ``(tenant_id, workspace_id, name)``.",
        "tags": [
          "Datasets"
        ]
      }
    },
    "/api/v1/datasets/{dataset_id}": {
      "delete": {
        "description": "Soft-delete only -- the underlying Parquet sample / snapshot /\nresult blobs stay on the object store. Use\n``DELETE /datasets/{id}:purge`` to additionally reclaim storage.",
        "operationId": "archive",
        "parameters": [
          {
            "in": "path",
            "name": "dataset_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatasetRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Archive a dataset (set status=ARCHIVED).",
        "tags": [
          "Datasets"
        ]
      },
      "get": {
        "operationId": "read",
        "parameters": [
          {
            "in": "path",
            "name": "dataset_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatasetRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Fetch a single dataset by id. Returns 404 if not found.",
        "tags": [
          "Datasets"
        ]
      },
      "put": {
        "operationId": "update",
        "parameters": [
          {
            "in": "path",
            "name": "dataset_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DatasetUpdate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatasetRead"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Sparse-update a dataset. Only fields present in body are changed.",
        "tags": [
          "Datasets"
        ]
      }
    },
    "/api/v1/datasets/{dataset_id}/files": {
      "post": {
        "operationId": "upload_file",
        "parameters": [
          {
            "in": "path",
            "name": "dataset_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FileUploadResponse"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Accept a multipart file upload and run the synchronous ingestion pipeline.",
        "tags": [
          "Files"
        ]
      }
    },
    "/api/v1/datasets/{dataset_id}/files:async": {
      "post": {
        "description": "Stage 1 (receive: caps check, hash, format detect, store bytes,\nwrite ``flyquery_files`` row, track workspace storage) runs\n*synchronously* -- it's bounded by IO + a single Postgres\ninsert, not by parse/profile/describe cost. Stages 2-10 are\nqueued as a ``PARSE_AND_INGEST`` ingest job that the worker\nconsumes; the response 202 carries the ``job_id`` plus a\n``Location`` header so clients can poll\n``GET /ingest-jobs/{job_id}`` or stream\n``GET /ingest-jobs/{job_id}/stream``.\n\nUse this in place of the synchronous endpoint when a single\nfile exceeds the request-timeout budget of the deployment\n(typically anything above a few MB with cold-cache LLM\ndescribe calls).\n\nStage 1's SHA-256 content hash provides natural dedup at the\nfile level -- re-uploading the same bytes is detected at\n``flyquery_files`` UNIQUE-on-(tenant, dataset, content_hash)\n-- so we do NOT layer Idempotency-Key replay caching here;\nthe underlying ``IngestJobService`` is also idempotent by\nconstruction.",
        "operationId": "upload_file_async",
        "parameters": [
          {
            "in": "path",
            "name": "dataset_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "responses": {
          "202": {
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Async alternative to ``POST /datasets/{ds}/files``.",
        "tags": [
          "Files"
        ]
      }
    },
    "/api/v1/datasets/{dataset_id}/files:bulk": {
      "post": {
        "description": "Each ``files`` part is processed through the same per-file pipeline\nas ``POST /files`` (receive -> parse -> reconcile -> sample ->\nprofile -> describe -> embed -> publish), and the per-file results\nrun **in parallel** through ``asyncio.gather`` -- a 5-file upload\nfinishes in roughly the time of a single file.\n\nPer-file failures do NOT abort the bulk. The response carries one\n``BulkFileResult`` per submitted file with either ``status=\"OK\"``\n+ ``file_id`` + ``tables`` or ``status=\"FAILED\"`` + ``error``.\nAggregate ``succeeded`` / ``failed`` counts let a UI render\nprogress without scanning the list.\n\nReplay-dedup'd via ``Idempotency-Key`` when present (optional on\nuser tier). A retried bulk upload with the same key returns the\ncached envelope without re-ingesting -- important because the\npipeline is heavy (parse + profile + describe + embed per file)\nand a duplicate run would double-write Parquet snapshots.",
        "operationId": "upload_files_bulk",
        "parameters": [
          {
            "in": "path",
            "name": "dataset_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkFileUploadResponse"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Accept multiple files in one multipart request and ingest each.",
        "tags": [
          "Files"
        ]
      }
    },
    "/api/v1/datasets/{dataset_id}/relations": {
      "get": {
        "description": "Optional ``status`` filter restricts to one of ``PROPOSED``,\n``APPROVED``, ``REJECTED``.",
        "operationId": "list_relations",
        "parameters": [
          {
            "in": "path",
            "name": "dataset_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Paginated[RelationRead]"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "List relations for a dataset (all statuses by default).",
        "tags": [
          "Relations"
        ]
      }
    },
    "/api/v1/datasets/{dataset_id}/tables": {
      "get": {
        "operationId": "list_tables",
        "parameters": [
          {
            "in": "path",
            "name": "dataset_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Paginated[TableRead]"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "tags": [
          "Tables"
        ]
      }
    },
    "/api/v1/datasets/{dataset_id}/tables/{table_id}:upload": {
      "put": {
        "operationId": "reupload_file",
        "parameters": [
          {
            "in": "path",
            "name": "dataset_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "table_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReuploadResponse"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Re-upload into an existing table slot; creates a new snapshot.",
        "tags": [
          "Files"
        ]
      }
    },
    "/api/v1/datasets/{dataset_id}:purge": {
      "delete": {
        "description": "Walks ``flyquery/{tenant}/{workspace}/{dataset}/`` on the object\nstore and removes every key -- samples, snapshots, derived\nParquets, query results. Returns 202 with a tombstone hint.\n\nThe SQL row stays in place with ``status=PURGING`` so audit /\nlineage references survive. A separate retention job (90-day\nwindow, mirroring ``conv_ttl_days``) is responsible for the\nfinal row delete.",
        "operationId": "purge",
        "parameters": [
          {
            "in": "path",
            "name": "dataset_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PurgeAccepted"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Hard-delete: flip status to PURGING and reclaim every blob.",
        "tags": [
          "Datasets"
        ]
      }
    },
    "/api/v1/examples": {
      "get": {
        "operationId": "list_examples",
        "parameters": [
          {
            "in": "query",
            "name": "quality",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "dataset_id",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 100,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "offset",
            "required": false,
            "schema": {
              "default": 0,
              "type": "integer"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Paginated[ExampleRead]"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "List examples for the caller's workspace, with optional filters.",
        "tags": [
          "Examples"
        ]
      },
      "post": {
        "operationId": "create",
        "parameters": [
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExampleCreate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExampleRead"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Create an example; defaults to source=USER_CURATED, quality=PROPOSED.",
        "tags": [
          "Examples"
        ]
      }
    },
    "/api/v1/examples/{example_id}": {
      "get": {
        "operationId": "get_example",
        "parameters": [
          {
            "in": "path",
            "name": "example_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExampleRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Fetch a single example by id. Returns 404 if not found.",
        "tags": [
          "Examples"
        ]
      }
    },
    "/api/v1/examples/{example_id}:approve": {
      "post": {
        "operationId": "approve",
        "parameters": [
          {
            "in": "path",
            "name": "example_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExampleRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Approve an example (quality \u2192 APPROVED).",
        "tags": [
          "Examples"
        ]
      }
    },
    "/api/v1/examples/{example_id}:reject": {
      "post": {
        "operationId": "reject",
        "parameters": [
          {
            "in": "path",
            "name": "example_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExampleRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Reject an example (quality \u2192 REJECTED).",
        "tags": [
          "Examples"
        ]
      }
    },
    "/api/v1/glossary": {
      "get": {
        "description": "``total`` is not populated -- the underlying service does not\ncompute a COUNT(*); consumers use ``has_more`` to decide\nwhether to fetch another page.",
        "operationId": "list_terms",
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 100,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "offset",
            "required": false,
            "schema": {
              "default": 0,
              "type": "integer"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Paginated[GlossaryTermRead]"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Return paginated glossary terms for the caller's workspace.",
        "tags": [
          "Glossary"
        ]
      },
      "post": {
        "operationId": "create",
        "parameters": [
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GlossaryTermCreate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GlossaryTermRead"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Create a glossary term; (workspace_id, term) must be unique.",
        "tags": [
          "Glossary"
        ]
      }
    },
    "/api/v1/glossary/{term_id}": {
      "delete": {
        "operationId": "delete",
        "parameters": [
          {
            "in": "path",
            "name": "term_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "responses": {
          "204": {
            "description": "No Content"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Hard-delete a glossary term.",
        "tags": [
          "Glossary"
        ]
      },
      "get": {
        "operationId": "get_term",
        "parameters": [
          {
            "in": "path",
            "name": "term_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GlossaryTermRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Fetch a single glossary term by id. Returns 404 if not found.",
        "tags": [
          "Glossary"
        ]
      },
      "put": {
        "operationId": "update",
        "parameters": [
          {
            "in": "path",
            "name": "term_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GlossaryTermUpdate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GlossaryTermRead"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Sparse-update a glossary term.",
        "tags": [
          "Glossary"
        ]
      }
    },
    "/api/v1/ingest-jobs": {
      "get": {
        "operationId": "list_jobs",
        "parameters": [
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IngestJobListResponse"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "List ingest jobs with optional filters.",
        "tags": [
          "IngestJobs"
        ]
      },
      "post": {
        "description": "``body`` is declared as ``Valid[Body[IngestJobCreate]]`` (not\nread from ``http_request.json()``) so FastAPI / pyfly publish\nthe request schema into ``openapi.json`` -- the older manual\ndecode kept ``IngestJobCreate`` (and now the nested\n``CallbackConfig`` field) invisible to SDK generators.",
        "operationId": "create_job",
        "parameters": [
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/IngestJobCreate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IngestJobRead"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Start a background ingestion job (REPARSE/SAMPLE_REFRESH/DESCRIBE_PASS/RELATION_PASS).",
        "tags": [
          "IngestJobs"
        ]
      }
    },
    "/api/v1/ingest-jobs/{job_id}": {
      "get": {
        "operationId": "get_job",
        "parameters": [
          {
            "in": "path",
            "name": "job_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IngestJobRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Get a single ingest job.",
        "tags": [
          "IngestJobs"
        ]
      }
    },
    "/api/v1/ingest-jobs/{job_id}/callbacks": {
      "get": {
        "description": "Returns one row per outbox entry: the URL we posted to, the\nterminal event we tried to deliver (``ingest.succeeded`` or\n``ingest.failed``), the current status (``PENDING``,\n``DELIVERED``, ``FAILED``, ``DEAD``), the attempt count + the\nlast HTTP status code / error, and the next scheduled retry.\n\nCallers SHOULD poll this endpoint after a webhook outage to\nconfirm that the in-flight retry storm has cleared (DEAD rows\nrequire manual replay or a follow-up REPARSE job).",
        "operationId": "list_callbacks",
        "parameters": [
          {
            "in": "path",
            "name": "job_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallbackDeliveryListResponse"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Audit log of webhook delivery attempts for this job.",
        "tags": [
          "IngestJobs"
        ]
      }
    },
    "/api/v1/ingest-jobs/{job_id}/events": {
      "get": {
        "operationId": "list_events",
        "parameters": [
          {
            "in": "path",
            "name": "job_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IngestEventListResponse"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Paginated event ledger for a job.",
        "tags": [
          "IngestJobs"
        ]
      }
    },
    "/api/v1/ingest-jobs/{job_id}/stream": {
      "get": {
        "description": "Mirrors canon's ingest_jobs_controller SSE pattern:\n1. Emit all existing events for the job (catch-up replay)\n2. Poll for new events every 250ms\n3. Close stream when a ``final`` or ``error`` event is emitted\n4. Hard timeout at _SSE_MAX_SECONDS to avoid connection leak",
        "operationId": "stream_job",
        "parameters": [
          {
            "in": "path",
            "name": "job_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "text/event-stream": {
                "schema": {
                  "description": "One SSE frame per event. Frames carry ``event:`` + ``data:`` (JSON-encoded) lines.",
                  "format": "event-stream",
                  "type": "string"
                }
              }
            },
            "description": "Server-Sent Events stream. Each frame follows the SSE wire format ``event: <name>\\ndata: <json>\\n\\n``. See ``docs/api-reference.md`` section 8 for the per-endpoint event catalogue."
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "SSE stream for real-time job progress.",
        "tags": [
          "IngestJobs"
        ]
      }
    },
    "/api/v1/ingest-jobs/{job_id}:cancel": {
      "post": {
        "operationId": "cancel_job",
        "parameters": [
          {
            "in": "path",
            "name": "job_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CancelResponse"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Cooperatively cancel a job (idempotent for terminal jobs).",
        "tags": [
          "IngestJobs"
        ]
      }
    },
    "/api/v1/queries": {
      "get": {
        "description": "Filters\n-------\n* ``dataset_id``           -- restrict to one dataset\n* ``execution_status``     -- ``OK`` / ``REJECTED_BY_FIREWALL`` / ``FAILED`` / ...\n* ``semantic_path_taken``  -- e.g. ``\"sql\"`` vs ``\"semantic-layer\"``\n* ``date_from``            -- inclusive lower bound on ``created_at``\n* ``date_to``              -- exclusive upper bound on ``created_at``\n\nPage size is clamped to ``[1, 200]``. Each item is the compact\nhistory shape (no heavy JSONB columns). Use\n``GET /queries/{id}`` for the full row.",
        "operationId": "list_queries",
        "parameters": [
          {
            "in": "query",
            "name": "dataset_id",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "execution_status",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "semantic_path_taken",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "date_from",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "date_to",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 50,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "offset",
            "required": false,
            "schema": {
              "default": 0,
              "type": "integer"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Paginated[QueryHistoryItem]"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "List queries for the caller's workspace, newest first.",
        "tags": [
          "Queries"
        ]
      }
    },
    "/api/v1/queries/{query_id}": {
      "get": {
        "description": "Returns 404 if the query doesn't belong to the caller's\n``(tenant, workspace)`` -- not just \"not found\", but also\n\"exists but wrong tenant\" (cross-tenant probing is the same\n404 as missing).",
        "operationId": "get_query",
        "parameters": [
          {
            "in": "path",
            "name": "query_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueryDetailRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Fetch a single query with every candidate, retry, and model id.",
        "tags": [
          "Queries"
        ]
      }
    },
    "/api/v1/queries/{query_id}/result": {
      "get": {
        "description": "The preview is always inlined. The presigned Parquet URL is\n``None`` when the TTL has elapsed (default 24h) -- consumers\nmust rerun the query in that case. The presign TTL itself is\nbounded by ``object_store_presign_ttl_s`` (default 24h).\n\nReturns 404 if either the query OR its result row doesn't\nexist for this tenant.",
        "operationId": "get_query_result",
        "parameters": [
          {
            "in": "path",
            "name": "query_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueryResultRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Re-download a previously-executed query's preview + parquet.",
        "tags": [
          "Queries"
        ]
      }
    },
    "/api/v1/query": {
      "post": {
        "description": ":param http_request: Starlette request (provides tenant context headers)\n:param body: validated QueryRequest\n:return: AnswerResponse with SQL, preview rows, chart hint, and explanation",
        "operationId": "query",
        "parameters": [
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QueryRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnswerResponse"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Run the full NL \u2192 SQL \u2192 result pipeline and return a synchronous answer.",
        "tags": [
          "Query"
        ]
      }
    },
    "/api/v1/query/stream": {
      "post": {
        "description": "Event sequence:\n1. ``schema_linked``   \u2014 after grounding completes\n2. ``clarification``   \u2014 (optional) when confidence < threshold + missing_info\n3. ``sql_generated``   \u2014 after generation\n4. ``executed``        \u2014 after DuckDB execution\n5. ``explained``       \u2014 after ExplainerAgent\n6. ``final``           \u2014 full AnswerResponse JSON\n\n:param http_request: Starlette request\n:param body: validated QueryRequest (body already consumed by pyfly)\n:return: StreamingResponse with ``text/event-stream`` content type",
        "operationId": "stream",
        "parameters": [
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QueryRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "text/event-stream": {
                "schema": {
                  "description": "One SSE frame per event. Frames carry ``event:`` + ``data:`` (JSON-encoded) lines.",
                  "format": "event-stream",
                  "type": "string"
                }
              }
            },
            "description": "Server-Sent Events stream. Each frame follows the SSE wire format ``event: <name>\\ndata: <json>\\n\\n``. See ``docs/api-reference.md`` section 8 for the per-endpoint event catalogue."
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Run the full pipeline as a Server-Sent Events stream.",
        "tags": [
          "Query"
        ]
      }
    },
    "/api/v1/query:batch": {
      "post": {
        "description": "Each item runs the same pipeline as ``POST /api/v1/query``, fanned\nout via ``asyncio.gather`` with a Semaphore-style concurrency cap\n(mirrors the bulk-file endpoint). Per-question failures do NOT\nabort the batch -- failed items carry ``status=\"FAILED\"`` +\n``error`` and the response aggregates ``succeeded`` / ``failed``\ncounts.\n\nUse this for dashboard refreshes (one batch with N panel queries),\ncomparison reports (same question against M datasets), or SDK\ncallers that want to amortise auth + tenant context across many\nquestions.\n\nReplay-dedup'd via ``Idempotency-Key`` when present (optional on\nthe user tier). A retried batch with the same key returns the\ncached aggregate without re-running any question -- important\nwhen a single batch represents tens of LLM calls.",
        "operationId": "batch",
        "parameters": [
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BatchQueryRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchQueryResponse"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Run multiple NL questions in parallel through the full pipeline.",
        "tags": [
          "Query"
        ]
      }
    },
    "/api/v1/query:explain": {
      "post": {
        "description": "Useful for previewing the generated SQL without paying execution costs.\n\n:param http_request: Starlette request\n:param body: validated QueryRequest\n:return: ExplainResponse with candidate SQL and reasoning",
        "operationId": "explain",
        "parameters": [
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QueryRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExplainResponse"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Run Grounding + Generation but stop before AST/execution.",
        "tags": [
          "Query"
        ]
      }
    },
    "/api/v1/query:validate": {
      "post": {
        "description": "Returns the classification and any scope error without executing the SQL.\n\n:param http_request: Starlette request\n:param body: validated QueryRequest\n:return: ValidateResponse with AST classification and optional scope_error",
        "operationId": "validate",
        "parameters": [
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QueryRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidateResponse"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Run Grounding + Generation + AST classification + ScopeGuard check.",
        "tags": [
          "Query"
        ]
      }
    },
    "/api/v1/relations/{relation_id}:approve": {
      "post": {
        "operationId": "approve_relation",
        "parameters": [
          {
            "in": "path",
            "name": "relation_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RelationApprovalRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Approve a PROPOSED relation.",
        "tags": [
          "Relations"
        ]
      }
    },
    "/api/v1/relations/{relation_id}:reject": {
      "post": {
        "operationId": "reject_relation",
        "parameters": [
          {
            "in": "path",
            "name": "relation_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RelationRejectionRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Reject a PROPOSED relation.",
        "tags": [
          "Relations"
        ]
      }
    },
    "/api/v1/schema-changes/{change_id}:confirm": {
      "post": {
        "description": "Validates that the change exists and is in state RENAMED_CANDIDATE.\nSets approved_by (the current actor / tenant_id), approved_at (now),\nchange = 'RENAMED'.\nAlso updates last_changed_at on the corresponding schema_objects column row.",
        "operationId": "confirm",
        "parameters": [
          {
            "in": "path",
            "name": "change_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SchemaChangeRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Flip a RENAMED_CANDIDATE row to RENAMED.",
        "tags": [
          "SchemaChanges"
        ]
      }
    },
    "/api/v1/schema-objects/{object_id}": {
      "get": {
        "operationId": "get_object",
        "parameters": [
          {
            "in": "path",
            "name": "object_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SchemaObjectRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Get a single schema object by ID.",
        "tags": [
          "SchemaObjects"
        ]
      },
      "put": {
        "description": "Sets description_source='HUMAN' when description is provided.\nSets pii_source='HUMAN' when pii_tag is provided.",
        "operationId": "update_object",
        "parameters": [
          {
            "in": "path",
            "name": "object_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SchemaObjectUpdate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SchemaObjectRead"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Update human-set fields on a schema object.",
        "tags": [
          "SchemaObjects"
        ]
      }
    },
    "/api/v1/semantic/dimensions": {
      "get": {
        "operationId": "list_dimensions",
        "parameters": [
          {
            "in": "query",
            "name": "dataset_id",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 100,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "offset",
            "required": false,
            "schema": {
              "default": 0,
              "type": "integer"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Paginated[SemanticDimensionRead]"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "List semantic dimensions for the caller's workspace (optional status filter).",
        "tags": [
          "SemanticDimensions"
        ]
      },
      "post": {
        "operationId": "create",
        "parameters": [
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SemanticDimensionCreate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SemanticDimensionRead"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Create a new semantic dimension in DRAFT status.",
        "tags": [
          "SemanticDimensions"
        ]
      }
    },
    "/api/v1/semantic/dimensions/{dimension_id}": {
      "get": {
        "operationId": "get_dimension",
        "parameters": [
          {
            "in": "path",
            "name": "dimension_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SemanticDimensionRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Fetch a single semantic dimension by id.",
        "tags": [
          "SemanticDimensions"
        ]
      },
      "put": {
        "operationId": "update",
        "parameters": [
          {
            "in": "path",
            "name": "dimension_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SemanticDimensionUpdate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SemanticDimensionRead"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Sparse-update a dimension; re-validates + recompiles if published.",
        "tags": [
          "SemanticDimensions"
        ]
      }
    },
    "/api/v1/semantic/dimensions/{dimension_id}/history": {
      "get": {
        "operationId": "history",
        "parameters": [
          {
            "in": "path",
            "name": "dimension_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Paginated[SemanticVersionRead]"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Return version history for a dimension, oldest first.",
        "tags": [
          "SemanticDimensions"
        ]
      }
    },
    "/api/v1/semantic/dimensions/{dimension_id}:publish": {
      "post": {
        "operationId": "publish",
        "parameters": [
          {
            "in": "path",
            "name": "dimension_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SemanticDimensionRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Validate, compile, and publish a dimension (status \u2192 PUBLISHED).",
        "tags": [
          "SemanticDimensions"
        ]
      }
    },
    "/api/v1/semantic/dimensions/{dimension_id}:retire": {
      "post": {
        "operationId": "retire",
        "parameters": [
          {
            "in": "path",
            "name": "dimension_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SemanticDimensionRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Retire a dimension (status \u2192 RETIRED).",
        "tags": [
          "SemanticDimensions"
        ]
      }
    },
    "/api/v1/semantic/metrics": {
      "get": {
        "operationId": "list_metrics",
        "parameters": [
          {
            "in": "query",
            "name": "dataset_id",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 100,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "offset",
            "required": false,
            "schema": {
              "default": 0,
              "type": "integer"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Paginated[SemanticMetricRead]"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "List semantic metrics for the caller's workspace (optional status filter).",
        "tags": [
          "SemanticMetrics"
        ]
      },
      "post": {
        "operationId": "create",
        "parameters": [
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SemanticMetricCreate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SemanticMetricRead"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Create a new semantic metric in DRAFT status.",
        "tags": [
          "SemanticMetrics"
        ]
      }
    },
    "/api/v1/semantic/metrics/{metric_id}": {
      "get": {
        "operationId": "get_metric",
        "parameters": [
          {
            "in": "path",
            "name": "metric_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SemanticMetricRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Fetch a single semantic metric by id.",
        "tags": [
          "SemanticMetrics"
        ]
      },
      "put": {
        "operationId": "update",
        "parameters": [
          {
            "in": "path",
            "name": "metric_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SemanticMetricUpdate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SemanticMetricRead"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Sparse-update a metric; re-validates + recompiles if published.",
        "tags": [
          "SemanticMetrics"
        ]
      }
    },
    "/api/v1/semantic/metrics/{metric_id}/history": {
      "get": {
        "description": "History is intentionally returned in full -- versions are bounded\nper metric (typically &lt; 50) and chronology is the consumer's\nwhole point. ``total = len(items)`` and ``has_more = False``.",
        "operationId": "history",
        "parameters": [
          {
            "in": "path",
            "name": "metric_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Paginated[SemanticVersionRead]"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Return version history for a metric, oldest first.",
        "tags": [
          "SemanticMetrics"
        ]
      }
    },
    "/api/v1/semantic/metrics/{metric_id}:publish": {
      "post": {
        "operationId": "publish",
        "parameters": [
          {
            "in": "path",
            "name": "metric_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SemanticMetricRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Validate, compile, and publish a metric (status \u2192 PUBLISHED).",
        "tags": [
          "SemanticMetrics"
        ]
      }
    },
    "/api/v1/semantic/metrics/{metric_id}:retire": {
      "post": {
        "operationId": "retire",
        "parameters": [
          {
            "in": "path",
            "name": "metric_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SemanticMetricRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Retire a metric (status \u2192 RETIRED).",
        "tags": [
          "SemanticMetrics"
        ]
      }
    },
    "/api/v1/sql:execute": {
      "post": {
        "description": "Requires the workspace flag ``allow_direct_sql=true``. The SQL is\nAST-classified and scope-checked; the agent pipeline is skipped.\n\n:param http_request: Starlette request\n:param body: validated SqlExecuteRequest\n:return: SqlExecuteResponse with preview rows and execution metadata\n:raises DirectSqlForbidden: when workspace.allow_direct_sql is False",
        "operationId": "execute",
        "parameters": [
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SqlExecuteRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SqlExecuteResponse"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Execute a SQL statement directly against the workspace's dataset Parquet.",
        "tags": [
          "SqlExecute"
        ]
      }
    },
    "/api/v1/sql:execute/stream": {
      "post": {
        "description": "Event sequence:\n1. ``ast_classified`` \u2014 AST result + scope check outcome\n2. ``executed``       \u2014 DuckDB result\n3. ``final``          \u2014 full SqlExecuteResponse JSON\n\n:param http_request: Starlette request\n:param body: validated SqlExecuteRequest\n:return: StreamingResponse with ``text/event-stream``",
        "operationId": "execute_stream",
        "parameters": [
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SqlExecuteRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "text/event-stream": {
                "schema": {
                  "description": "One SSE frame per event. Frames carry ``event:`` + ``data:`` (JSON-encoded) lines.",
                  "format": "event-stream",
                  "type": "string"
                }
              }
            },
            "description": "Server-Sent Events stream. Each frame follows the SSE wire format ``event: <name>\\ndata: <json>\\n\\n``. See ``docs/api-reference.md`` section 8 for the per-endpoint event catalogue."
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Execute SQL and stream progress as Server-Sent Events.",
        "tags": [
          "SqlExecute"
        ]
      }
    },
    "/api/v1/stats": {
      "get": {
        "operationId": "workspace_summary",
        "parameters": [
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkspaceStats"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Return storage + counts for the caller's workspace.",
        "tags": [
          "Stats"
        ]
      }
    },
    "/api/v1/tables": {
      "get": {
        "description": "Query parameters\n----------------\n* ``q``          -- substring match on ``name`` or ``qualified_name``\n(case-insensitive ``ILIKE``).\n* ``name``       -- exact match on ``name``.\n* ``dataset_id`` -- restrict to a single dataset.\n* ``kind``       -- ``UPLOADED`` / ``VIEW`` / ``DERIVED``.\n* ``is_active``  -- default ``true``; pass ``false`` to include\narchived tables.\n* ``limit``      -- page size, clamped to [1, 1000]. Default 100.\n* ``offset``     -- starting offset. Default 0.\n\nResponse envelope: ``Paginated[TableRead]``.",
        "operationId": "search_tables",
        "parameters": [
          {
            "in": "query",
            "name": "q",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "name",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "dataset_id",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "kind",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "is_active",
            "required": false,
            "schema": {
              "default": null,
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 100,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "offset",
            "required": false,
            "schema": {
              "default": 0,
              "type": "integer"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Paginated[TableRead]"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Search/filter tables across the caller's workspace.",
        "tags": [
          "Tables"
        ]
      }
    },
    "/api/v1/tables/by-name/{name}": {
      "get": {
        "description": "Pass ``?dataset_id=...`` to scope the lookup to a single dataset.\nReturns 404 if the name is ambiguous (matches multiple datasets)\nor no match is found.",
        "operationId": "get_table_by_name",
        "parameters": [
          {
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "dataset_id",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TableRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Resolve a table by ``name`` within the caller's workspace.",
        "tags": [
          "Tables"
        ]
      }
    },
    "/api/v1/tables/{table_id}": {
      "get": {
        "operationId": "get_table",
        "parameters": [
          {
            "in": "path",
            "name": "table_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TableRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "tags": [
          "Tables"
        ]
      }
    },
    "/api/v1/tables/{table_id}/changes": {
      "get": {
        "operationId": "list_changes",
        "parameters": [
          {
            "in": "path",
            "name": "table_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Paginated[SchemaChangeRead]"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "tags": [
          "Tables"
        ]
      }
    },
    "/api/v1/tables/{table_id}/objects": {
      "get": {
        "operationId": "list_objects",
        "parameters": [
          {
            "in": "path",
            "name": "table_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Paginated[SchemaObjectRead]"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "List schema_objects for the table's current snapshot.",
        "tags": [
          "Tables"
        ]
      }
    },
    "/api/v1/tables/{table_id}/snapshots": {
      "get": {
        "operationId": "list_snapshots",
        "parameters": [
          {
            "in": "path",
            "name": "table_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Paginated[SnapshotRead]"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "tags": [
          "Tables"
        ]
      }
    },
    "/api/v1/tables:derive": {
      "post": {
        "description": ":param http_request: Starlette request (tenant context headers)\n:param body: dataset_id + name + sql (must be a SELECT)\n:return: DeriveTableResponse with the new table_id\n:raises DeriveTableForbidden: when sql is not a SELECT\n:raises DeriveTableError: when DuckDB execution fails",
        "operationId": "derive",
        "parameters": [
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeriveTableRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeriveTableResponse"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Materialise a SELECT result as a new DERIVED table.",
        "tags": [
          "TablesDerive"
        ]
      }
    },
    "/api/v1/version": {
      "get": {
        "operationId": "version",
        "parameters": [
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Return service name + CalVer version tag.",
        "tags": [
          "Version"
        ]
      }
    },
    "/api/v1/workspaces": {
      "get": {
        "description": "Query parameters\n----------------\n* ``q``      -- free-text substring match against ``slug`` or ``name``\n(case-insensitive ``ILIKE``).\n* ``slug``   -- exact match on ``slug`` -- gives you slug-based lookup\nwith zero extra round trips.\n* ``status`` -- exact match (``ACTIVE``, ``ARCHIVED``, ``PURGING``).\n* ``limit``  -- page size, clamped to [1, 1000]. Default 100.\n* ``offset`` -- starting offset. Default 0.\n\nReturns :class:`~flyquery.interfaces.pagination.Paginated`\nwith ``total`` populated from the un-paginated match count.",
        "operationId": "list_workspaces",
        "parameters": [
          {
            "in": "query",
            "name": "q",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "slug",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "default": null,
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 100,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "offset",
            "required": false,
            "schema": {
              "default": 0,
              "type": "integer"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Paginated[WorkspaceRead]"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Search/filter workspaces for the caller's tenant.",
        "tags": [
          "Workspaces"
        ]
      },
      "post": {
        "operationId": "create",
        "parameters": [
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WorkspaceCreate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkspaceRead"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Create a workspace; tenant comes from ``X-Tenant-Id`` header.",
        "tags": [
          "Workspaces"
        ]
      }
    },
    "/api/v1/workspaces/by-slug/{slug}": {
      "get": {
        "description": "Lets SDKs and CLIs resolve a workspace from a memorable identifier\ninstead of carrying around a UUID. Returns 404 if no match.",
        "operationId": "read_by_slug",
        "parameters": [
          {
            "in": "path",
            "name": "slug",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkspaceRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Fetch a workspace by its ``(tenant_id, slug)`` natural key.",
        "tags": [
          "Workspaces"
        ]
      }
    },
    "/api/v1/workspaces/{workspace_id}": {
      "get": {
        "operationId": "read",
        "parameters": [
          {
            "in": "path",
            "name": "workspace_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkspaceRead"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Fetch a single workspace by id. Returns 404 if not found.",
        "tags": [
          "Workspaces"
        ]
      },
      "put": {
        "operationId": "update",
        "parameters": [
          {
            "in": "path",
            "name": "workspace_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WorkspaceUpdate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkspaceRead"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Sparse-update a workspace. Only fields present in body are changed.",
        "tags": [
          "Workspaces"
        ]
      }
    },
    "/api/v1/workspaces/{workspace_id}:purge": {
      "delete": {
        "description": "Returns 202 Accepted with a tombstone placeholder.",
        "operationId": "purge",
        "parameters": [
          {
            "in": "path",
            "name": "workspace_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/TenantIdHeader"
          },
          {
            "$ref": "#/components/parameters/WorkspaceIdHeader"
          },
          {
            "$ref": "#/components/parameters/CorrelationIdHeader"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyHeader"
          }
        ],
        "responses": {
          "202": {
            "description": "Successful response"
          }
        },
        "security": [
          {
            "TenantContext": [],
            "WorkspaceContext": []
          }
        ],
        "summary": "Purge a workspace: mark PURGING + walk + delete all blobs.",
        "tags": [
          "Workspaces"
        ]
      }
    }
  },
  "servers": [
    {
      "description": "This service",
      "url": "/"
    }
  ],
  "tags": [
    {
      "name": "AgentConversations"
    },
    {
      "name": "AgentDatasets"
    },
    {
      "name": "AgentExamples"
    },
    {
      "name": "AgentGlossary"
    },
    {
      "name": "AgentIngestJobs"
    },
    {
      "name": "AgentQuery"
    },
    {
      "name": "AgentRelations"
    },
    {
      "name": "AgentSemanticDimensions"
    },
    {
      "name": "AgentSemanticMetrics"
    },
    {
      "name": "AgentSqlExecute"
    },
    {
      "name": "AgentTables"
    },
    {
      "name": "AgentTokens"
    },
    {
      "name": "AuditEvents"
    },
    {
      "name": "Billing"
    },
    {
      "name": "Conversations"
    },
    {
      "name": "CostEvents"
    },
    {
      "name": "Datasets"
    },
    {
      "name": "Examples"
    },
    {
      "name": "Files"
    },
    {
      "name": "Glossary"
    },
    {
      "name": "IngestJobs"
    },
    {
      "name": "Queries"
    },
    {
      "description": "Hybrid search + grounded retrieval-augmented answering. ``/search`` returns the raw RRF-fused hit list (BM25 + dense vectors). ``/query`` runs the same retrieval, then asks the configured answer model to write an answer using ONLY the retrieved chunks -- citations include only the chunks the model actually relied on. Both surfaces share the same filter model (source_id, knowledge_item_id, domain, jurisdiction, tags, statuses).",
      "name": "Query"
    },
    {
      "name": "Relations"
    },
    {
      "name": "SchemaChanges"
    },
    {
      "name": "SchemaObjects"
    },
    {
      "name": "SemanticDimensions"
    },
    {
      "name": "SemanticMetrics"
    },
    {
      "name": "SqlExecute"
    },
    {
      "name": "Stats"
    },
    {
      "name": "Tables"
    },
    {
      "name": "TablesDerive"
    },
    {
      "name": "AgentVersion"
    },
    {
      "description": "Service identity, model selection, and backend choices. Surfaces the deployed CalVer, the embedding + answer model ids actually in use, the vector backend (pgvector by default), and the EDA adapter. Used by smoke tests and operations dashboards.",
      "name": "Version"
    },
    {
      "name": "Workspaces"
    }
  ]
}