openapi.json

{
  "components": {
    "parameters": {
      "IdempotencyKey": {
        "description": "Mandatory on every agent-tier POST / PUT / DELETE (``400 missing_idempotency_key`` otherwise). A replay with the same key within the store TTL returns the original response without re-dispatching; keys are namespaced per ``(tenant, route scope)``.",
        "in": "header",
        "name": "Idempotency-Key",
        "required": true,
        "schema": {
          "maxLength": 255,
          "type": "string"
        }
      },
      "XCorrelationId": {
        "description": "Caller-supplied correlation id echoed into audit rows, cost events and the async-ingest webhook. A uuid4 hex is generated when absent.",
        "in": "header",
        "name": "X-Correlation-Id",
        "required": false,
        "schema": {
          "type": "string"
        }
      },
      "XTenantId": {
        "description": "Tenant slug that scopes every row the request may see or write. Missing or malformed -> ``400 missing_tenant_context``.",
        "in": "header",
        "name": "X-Tenant-Id",
        "required": true,
        "schema": {
          "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$",
          "type": "string"
        }
      },
      "XWorkspaceId": {
        "description": "Workspace slug within the tenant. Required on every tenant route for header uniformity, including the workspace CRUD routes where the path id is authoritative (``:purge`` demands they agree).",
        "in": "header",
        "name": "X-Workspace-Id",
        "required": true,
        "schema": {
          "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$",
          "type": "string"
        }
      }
    },
    "schemas": {
      "AcceptCandidateRequest": {
        "description": "Materialise the candidate as a new knowledge version.\n\n``target_item_id`` is optional. If set, the candidate is appended\nas a new version on the existing item; if omitted, a new\nknowledge item is created.",
        "properties": {
          "actor": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Actor"
          },
          "note": {
            "anyOf": [
              {
                "maxLength": 2000,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Note"
          },
          "publish": {
            "default": true,
            "title": "Publish",
            "type": "boolean"
          },
          "target_item_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Target Item Id"
          }
        },
        "title": "AcceptCandidateRequest",
        "type": "object"
      },
      "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.",
        "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"
      },
      "AnswerRequest": {
        "description": "RAG-answer request.\n\nThe answerer fetches the top hits via the same hybrid retrieval\nused by ``/search``, then asks the configured answer model to\nwrite an answer using ONLY those chunks. The response carries\nthe answer + the chunks the model actually cited; the model is\nprompted to set ``no_answer=true`` when the chunks don't support\na confident answer rather than confabulate.",
        "properties": {
          "domains": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/Domain"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Restrict to chunks whose source belongs to one of these domains.",
            "examples": [
              [
                "process",
                "compliance"
              ]
            ],
            "title": "Domains"
          },
          "extended_reasoning": {
            "default": false,
            "description": "RLM only: when true, the CodeAct engine runs at TWICE the configured iteration budget (``FLYCANON_RLM_MAX_ITERS`` * 2) for this request -- a per-request lever for harder multi-fact questions that need more turns to gather and verify evidence, without raising the global default for all traffic. Ignored by the RAG engine, which is single-shot.",
            "title": "Extended Reasoning",
            "type": "boolean"
          },
          "instructions": {
            "anyOf": [
              {
                "maxLength": 4000,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Optional system-level steering appended to the answer prompt. Use for caller-specific tone (``answer in Spanish``, ``use bullet points``) or workflow context.",
            "title": "Instructions"
          },
          "jurisdictions": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/Jurisdiction"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Jurisdictions"
          },
          "knowledge_item_ids": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Restrict to chunks cited by these knowledge items.",
            "title": "Knowledge Item Ids"
          },
          "model": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Override the configured answer model (``<provider>:<model>``). Defaults to ``FLYCANON_ANSWER_MODEL``. On primary failure the service falls back to ``FLYCANON_ANSWER_FALLBACK_MODEL`` when configured.",
            "examples": [
              "anthropic:claude-sonnet-4-6",
              "openai:gpt-4o"
            ],
            "title": "Model"
          },
          "question": {
            "description": "The user's question. Plain natural language.",
            "examples": [
              "Summarise the scope section in three sentences."
            ],
            "maxLength": 2000,
            "minLength": 1,
            "title": "Question",
            "type": "string"
          },
          "source_ids": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Restrict retrieval to chunks of these sources.",
            "examples": [
              [
                "0b06a8e6-37e7-4f7b-a8f1-7e2a6f7e5d11"
              ]
            ],
            "title": "Source Ids"
          },
          "statuses": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/KnowledgeStatus"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Restrict to chunks belonging to knowledge items in these lifecycle states. Defaults to ``published`` items only when omitted upstream.",
            "title": "Statuses"
          },
          "tags": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Tags"
          },
          "top_k": {
            "default": 8,
            "description": "Number of retrieval hits passed to the answer model as grounding context. Larger values widen the available evidence but raise input tokens; the default is sized for sub-second answers on small corpora.",
            "maximum": 40,
            "minimum": 1,
            "title": "Top K",
            "type": "integer"
          }
        },
        "required": [
          "question"
        ],
        "title": "AnswerRequest",
        "type": "object"
      },
      "AnswerResponse": {
        "properties": {
          "answer": {
            "description": "The grounded answer. Free-form text; the prompt instructs the model to use only the supplied chunks.",
            "title": "Answer",
            "type": "string"
          },
          "citations": {
            "description": "Chunks the model explicitly cited -- a subset of the retrieved top-k. Each :class:`Hit` is hydrated with the verbatim chunk content + the source pointer so callers render the citation badge without a follow-up call.",
            "items": {
              "$ref": "#/components/schemas/Hit"
            },
            "title": "Citations",
            "type": "array"
          },
          "elapsed_ms": {
            "minimum": 0,
            "title": "Elapsed Ms",
            "type": "integer"
          },
          "model": {
            "description": "Provider:model identifier actually used (after fallback).",
            "title": "Model",
            "type": "string"
          },
          "no_answer": {
            "default": false,
            "description": "True when the retrieval window did not contain a confident answer. Callers should treat the answer text as an explanatory note rather than a substantive answer.",
            "title": "No Answer",
            "type": "boolean"
          }
        },
        "required": [
          "answer",
          "citations",
          "model",
          "elapsed_ms"
        ],
        "title": "AnswerResponse",
        "type": "object"
      },
      "AuditEvent": {
        "description": "Single audit-log row.",
        "properties": {
          "actor": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Stable identifier of the human or service that performed the action.",
            "title": "Actor"
          },
          "correlation_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Correlation Id"
          },
          "event_type": {
            "description": "Stable, snake-case identifier of the mutation.",
            "examples": [
              "source.ingested",
              "knowledge.published",
              "candidate.accepted"
            ],
            "title": "Event Type",
            "type": "string"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "occurred_at": {
            "format": "date-time",
            "title": "Occurred At",
            "type": "string"
          },
          "payload": {
            "additionalProperties": true,
            "title": "Payload",
            "type": "object"
          },
          "subject_id": {
            "description": "Primary entity touched by this event.",
            "title": "Subject Id",
            "type": "string"
          },
          "subject_kind": {
            "description": "Type of subject: ``source`` | ``knowledge`` | ``candidate`` | ``taxonomy``.",
            "title": "Subject Kind",
            "type": "string"
          }
        },
        "required": [
          "id",
          "occurred_at",
          "event_type",
          "subject_id",
          "subject_kind"
        ],
        "title": "AuditEvent",
        "type": "object"
      },
      "AuditPage": {
        "properties": {
          "items": {
            "items": {
              "$ref": "#/components/schemas/AuditEvent"
            },
            "title": "Items",
            "type": "array"
          },
          "limit": {
            "maximum": 500,
            "minimum": 1,
            "title": "Limit",
            "type": "integer"
          },
          "offset": {
            "minimum": 0,
            "title": "Offset",
            "type": "integer"
          },
          "total": {
            "minimum": 0,
            "title": "Total",
            "type": "integer"
          }
        },
        "required": [
          "items",
          "total",
          "offset",
          "limit"
        ],
        "title": "AuditPage",
        "type": "object"
      },
      "BillingReport": {
        "description": "``GET /api/v1/billing`` envelope -- aggregated rows + totals.",
        "properties": {
          "rows": {
            "description": "One row per (group_by combination); the order matches the SQL aggregate.",
            "items": {
              "$ref": "#/components/schemas/BillingRow"
            },
            "title": "Rows",
            "type": "array"
          },
          "total_calls": {
            "default": 0,
            "description": "Sum of ``rows[*].calls`` for the same filter window.",
            "minimum": 0,
            "title": "Total Calls",
            "type": "integer"
          },
          "total_cost_usd": {
            "default": "0",
            "description": "Sum of ``rows[*].cost_usd`` for the same filter window.",
            "title": "Total Cost Usd",
            "type": "string"
          }
        },
        "title": "BillingReport",
        "type": "object"
      },
      "BillingRow": {
        "description": "One row of the aggregated billing report.\n\nGroup columns echo the request's ``group_by`` selection\n(``date`` / ``model`` / ``agent_name``). The summed columns\nare always present. Scope (tenant + workspace) is fixed via\nrequest headers and never appears in ``group_by``.",
        "properties": {
          "calls": {
            "description": "Number of ``canon_cost_events`` rows that landed in this bucket.",
            "minimum": 0,
            "title": "Calls",
            "type": "integer"
          },
          "cost_usd": {
            "description": "Total cost in USD, serialised as a decimal string for precision.",
            "title": "Cost Usd",
            "type": "string"
          },
          "group": {
            "additionalProperties": true,
            "description": "Group-column values keyed by name (matches the request's ``group_by`` selection).",
            "title": "Group",
            "type": "object"
          },
          "input_tokens": {
            "description": "Sum of input tokens across calls in this bucket.",
            "minimum": 0,
            "title": "Input Tokens",
            "type": "integer"
          },
          "output_tokens": {
            "description": "Sum of output tokens across calls in this bucket.",
            "minimum": 0,
            "title": "Output Tokens",
            "type": "integer"
          },
          "total_tokens": {
            "description": "``input_tokens + output_tokens`` (denormalised).",
            "minimum": 0,
            "title": "Total Tokens",
            "type": "integer"
          }
        },
        "required": [
          "input_tokens",
          "output_tokens",
          "total_tokens",
          "cost_usd",
          "calls"
        ],
        "title": "BillingRow",
        "type": "object"
      },
      "BillingSummary": {
        "description": "Rolling-window cost snapshot.\n\nReturned by ``GET /api/v1/billing/summary``. Three windows are\npopulated unconditionally so a status banner can display them\nside by side; missing data turns into a zero row, not a 404.",
        "properties": {
          "generated_at": {
            "description": "UTC timestamp the snapshot was computed.",
            "format": "date-time",
            "title": "Generated At",
            "type": "string"
          },
          "last_24h": {
            "$ref": "#/components/schemas/BillingWindow",
            "description": "Trailing 24-hour window."
          },
          "last_30d": {
            "$ref": "#/components/schemas/BillingWindow",
            "description": "Trailing 30-day window."
          },
          "last_7d": {
            "$ref": "#/components/schemas/BillingWindow",
            "description": "Trailing 7-day window."
          }
        },
        "required": [
          "generated_at",
          "last_24h",
          "last_7d",
          "last_30d"
        ],
        "title": "BillingSummary",
        "type": "object"
      },
      "BillingWindow": {
        "description": "One window inside :class:`BillingSummary` (24h / 7d / 30d).",
        "properties": {
          "calls": {
            "description": "Number of ``canon_cost_events`` rows in the window.",
            "minimum": 0,
            "title": "Calls",
            "type": "integer"
          },
          "cost_usd": {
            "description": "Window total in USD (decimal string).",
            "title": "Cost Usd",
            "type": "string"
          },
          "input_tokens": {
            "description": "Sum of input tokens across the window.",
            "minimum": 0,
            "title": "Input Tokens",
            "type": "integer"
          },
          "output_tokens": {
            "description": "Sum of output tokens across the window.",
            "minimum": 0,
            "title": "Output Tokens",
            "type": "integer"
          },
          "since": {
            "description": "Lower bound (UTC) of the window. ``until`` is implicitly ``generated_at``.",
            "format": "date-time",
            "title": "Since",
            "type": "string"
          },
          "top_model": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Most expensive model identifier in this window (``null`` if no rows).",
            "title": "Top Model"
          },
          "top_model_cost_usd": {
            "default": "0",
            "description": "USD spend on ``top_model`` in this window.",
            "title": "Top Model Cost Usd",
            "type": "string"
          },
          "total_tokens": {
            "description": "``input_tokens + output_tokens``.",
            "minimum": 0,
            "title": "Total Tokens",
            "type": "integer"
          }
        },
        "required": [
          "since",
          "calls",
          "input_tokens",
          "output_tokens",
          "total_tokens",
          "cost_usd"
        ],
        "title": "BillingWindow",
        "type": "object"
      },
      "BulkSourceResult": {
        "description": "Per-entry outcome of a bulk ingest call.\n\nEither ``source`` is populated (on success) or\n``error_code`` + ``error_message`` are (on failure). The\n``index`` field matches the input array position so callers\ncan correlate failures with their batch.",
        "properties": {
          "error_code": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Error Code"
          },
          "error_message": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Error Message"
          },
          "index": {
            "description": "Position in the request array.",
            "minimum": 0,
            "title": "Index",
            "type": "integer"
          },
          "source": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/SourceRecord"
              },
              {
                "type": "null"
              }
            ],
            "default": null
          },
          "status": {
            "description": "``succeeded`` or ``failed`` for this entry.",
            "examples": [
              "succeeded",
              "failed"
            ],
            "title": "Status",
            "type": "string"
          }
        },
        "required": [
          "index",
          "status"
        ],
        "title": "BulkSourceResult",
        "type": "object"
      },
      "BulkSourcesResponse": {
        "description": "Aggregate response for ``POST /api/v1/sources:bulk``.\n\nEntries are processed sequentially -- failures are isolated to\ntheir own entry and never abort the batch. The caller inspects\neach ``BulkSourceResult`` to retry / inspect failures.",
        "properties": {
          "failed": {
            "minimum": 0,
            "title": "Failed",
            "type": "integer"
          },
          "results": {
            "items": {
              "$ref": "#/components/schemas/BulkSourceResult"
            },
            "title": "Results",
            "type": "array"
          },
          "succeeded": {
            "minimum": 0,
            "title": "Succeeded",
            "type": "integer"
          },
          "total": {
            "minimum": 0,
            "title": "Total",
            "type": "integer"
          }
        },
        "required": [
          "total",
          "succeeded",
          "failed"
        ],
        "title": "BulkSourcesResponse",
        "type": "object"
      },
      "BulkSubmitSourcesPayload": {
        "description": "Wire payload for ``POST /api/v1/sources:bulk``.\n\nCarries up to ``MAX_BULK_SOURCES`` source submissions in a\nsingle request. Each entry is processed independently -- a\nparse / normalisation failure on one entry does not abort the\nbatch.",
        "properties": {
          "sources": {
            "description": "Up to 100 source submissions. Each entry is the same shape as the JSON body of ``POST /api/v1/sources``.",
            "items": {
              "$ref": "#/components/schemas/SubmitSourceJsonPayload"
            },
            "maxItems": 100,
            "minItems": 1,
            "title": "Sources",
            "type": "array"
          }
        },
        "required": [
          "sources"
        ],
        "title": "BulkSubmitSourcesPayload",
        "type": "object"
      },
      "CandidateRecord": {
        "description": "Public view of a candidate row.",
        "properties": {
          "actor": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Actor"
          },
          "body": {
            "title": "Body",
            "type": "string"
          },
          "citations": {
            "items": {
              "$ref": "#/components/schemas/Citation"
            },
            "title": "Citations",
            "type": "array"
          },
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "decided_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Decided At"
          },
          "domain": {
            "$ref": "#/components/schemas/Domain"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "jurisdiction": {
            "$ref": "#/components/schemas/Jurisdiction",
            "default": "GLOBAL"
          },
          "materialised_knowledge_item_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Materialised Knowledge Item Id"
          },
          "materialised_version": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Materialised Version"
          },
          "metadata": {
            "additionalProperties": true,
            "title": "Metadata",
            "type": "object"
          },
          "rationale": {
            "anyOf": [
              {
                "maxLength": 4000,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Rationale"
          },
          "score": {
            "anyOf": [
              {
                "maximum": 1.0,
                "minimum": 0.0,
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Consolidator's self-reported confidence in this proposal.",
            "title": "Score"
          },
          "source_id": {
            "title": "Source Id",
            "type": "string"
          },
          "status": {
            "$ref": "#/components/schemas/CandidateStatus"
          },
          "summary": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Summary"
          },
          "tags": {
            "items": {
              "type": "string"
            },
            "title": "Tags",
            "type": "array"
          },
          "title": {
            "title": "Title",
            "type": "string"
          }
        },
        "required": [
          "id",
          "status",
          "source_id",
          "title",
          "body",
          "domain",
          "created_at"
        ],
        "title": "CandidateRecord",
        "type": "object"
      },
      "CandidateStats": {
        "description": "Pre-canonical LLM proposals by status.",
        "properties": {
          "by_status": {
            "additionalProperties": {
              "type": "integer"
            },
            "title": "By Status",
            "type": "object"
          },
          "total": {
            "minimum": 0,
            "title": "Total",
            "type": "integer"
          }
        },
        "required": [
          "total"
        ],
        "title": "CandidateStats",
        "type": "object"
      },
      "CandidateStatus": {
        "enum": [
          "proposed",
          "accepted",
          "rejected",
          "merged"
        ],
        "title": "CandidateStatus",
        "type": "string"
      },
      "CandidatesPage": {
        "properties": {
          "items": {
            "items": {
              "$ref": "#/components/schemas/CandidateRecord"
            },
            "title": "Items",
            "type": "array"
          },
          "limit": {
            "maximum": 500,
            "minimum": 1,
            "title": "Limit",
            "type": "integer"
          },
          "offset": {
            "minimum": 0,
            "title": "Offset",
            "type": "integer"
          },
          "total": {
            "minimum": 0,
            "title": "Total",
            "type": "integer"
          }
        },
        "required": [
          "items",
          "total",
          "offset",
          "limit"
        ],
        "title": "CandidatesPage",
        "type": "object"
      },
      "ChunkStats": {
        "description": "Coverage of the retrieval index.",
        "properties": {
          "by_embedding_model": {
            "additionalProperties": {
              "type": "integer"
            },
            "description": "Chunk count per ``<provider>:<model>`` identifier. During a ``flycanon reindex`` the corpus is split across two identifiers and the split moving is the run making progress.",
            "title": "By Embedding Model",
            "type": "object"
          },
          "embedded": {
            "minimum": 0,
            "title": "Embedded",
            "type": "integer"
          },
          "embedded_pct": {
            "description": "Percentage of chunks that have been embedded (``embedding_model`` is set).",
            "maximum": 100.0,
            "minimum": 0.0,
            "title": "Embedded Pct",
            "type": "number"
          },
          "total": {
            "minimum": 0,
            "title": "Total",
            "type": "integer"
          }
        },
        "required": [
          "total",
          "embedded",
          "embedded_pct"
        ],
        "title": "ChunkStats",
        "type": "object"
      },
      "Citation": {
        "description": "A pointer from a knowledge version to a source span.\n\n``source_id`` identifies the source the citation refers to.\n``chunk_id`` points at the specific chunk that backs the claim,\nwhen one applies. ``quote`` is the verbatim text the\nconsolidation stage extracted; it is informative, not normative.",
        "properties": {
          "chunk_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Chunk Id"
          },
          "page": {
            "anyOf": [
              {
                "minimum": 1,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "1-based page index, when applicable.",
            "title": "Page"
          },
          "quote": {
            "anyOf": [
              {
                "maxLength": 4000,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Quote"
          },
          "relevance": {
            "anyOf": [
              {
                "maximum": 1.0,
                "minimum": 0.0,
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Relevance"
          },
          "source_id": {
            "title": "Source Id",
            "type": "string"
          }
        },
        "required": [
          "source_id"
        ],
        "title": "Citation",
        "type": "object"
      },
      "ConflictScanRequest": {
        "description": "``POST /api/v1/knowledge:detect-conflicts`` body.\n\n``actor`` is intentionally NOT a body field: the audit actor is\nderived from the request context (the JWT subject or agent-token\nprefix).",
        "properties": {
          "domain": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Domain"
          },
          "max_items": {
            "default": 50,
            "maximum": 500,
            "minimum": 2,
            "title": "Max Items",
            "type": "integer"
          },
          "min_similarity": {
            "default": 0.85,
            "maximum": 1.0,
            "minimum": 0.5,
            "title": "Min Similarity",
            "type": "number"
          }
        },
        "title": "ConflictScanRequest",
        "type": "object"
      },
      "ConflictScanResponse": {
        "properties": {
          "candidate_ids": {
            "items": {
              "type": "string"
            },
            "title": "Candidate Ids",
            "type": "array"
          },
          "conflicts_found": {
            "minimum": 0,
            "title": "Conflicts Found",
            "type": "integer"
          },
          "pairs_evaluated": {
            "minimum": 0,
            "title": "Pairs Evaluated",
            "type": "integer"
          },
          "relation_ids": {
            "description": "Knowledge-graph ``conflicts_with`` edge ids materialised alongside the inbox candidates. Empty when the detector is wired without a KnowledgeRelationService binding.",
            "items": {
              "type": "string"
            },
            "title": "Relation Ids",
            "type": "array"
          }
        },
        "required": [
          "pairs_evaluated",
          "conflicts_found"
        ],
        "title": "ConflictScanResponse",
        "type": "object"
      },
      "Conversation": {
        "description": "Public view of a conversation + its turn history.",
        "properties": {
          "actor": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Actor"
          },
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "model": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Model"
          },
          "summary": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Rolling synopsis of prior turns. Prepended to the next turn's prompt so long sessions stay within the model's context window.",
            "title": "Summary"
          },
          "title": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Title"
          },
          "turns": {
            "items": {
              "$ref": "#/components/schemas/ConversationTurn"
            },
            "title": "Turns",
            "type": "array"
          },
          "updated_at": {
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          }
        },
        "required": [
          "id",
          "created_at",
          "updated_at"
        ],
        "title": "Conversation",
        "type": "object"
      },
      "ConversationTurn": {
        "description": "One turn in a conversation.",
        "properties": {
          "answer": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Answer"
          },
          "citations": {
            "items": {
              "$ref": "#/components/schemas/Hit"
            },
            "title": "Citations",
            "type": "array"
          },
          "conversation_id": {
            "title": "Conversation Id",
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "elapsed_ms": {
            "anyOf": [
              {
                "minimum": 0,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Elapsed Ms"
          },
          "id": {
            "title": "Id",
            "type": "integer"
          },
          "model": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Model"
          },
          "no_answer": {
            "default": false,
            "title": "No Answer",
            "type": "boolean"
          },
          "question": {
            "title": "Question",
            "type": "string"
          },
          "turn_index": {
            "minimum": 1,
            "title": "Turn Index",
            "type": "integer"
          }
        },
        "required": [
          "id",
          "conversation_id",
          "turn_index",
          "question",
          "created_at"
        ],
        "title": "ConversationTurn",
        "type": "object"
      },
      "CorpusStats": {
        "description": "``GET /api/v1/stats`` envelope -- one round-trip for ops dashboards.",
        "properties": {
          "candidates": {
            "$ref": "#/components/schemas/CandidateStats"
          },
          "chunks": {
            "$ref": "#/components/schemas/ChunkStats"
          },
          "cost": {
            "$ref": "#/components/schemas/CostStreamStats"
          },
          "generated_at": {
            "format": "date-time",
            "title": "Generated At",
            "type": "string"
          },
          "ingest_jobs": {
            "$ref": "#/components/schemas/JobStats"
          },
          "knowledge_items": {
            "$ref": "#/components/schemas/KnowledgeItemStats"
          },
          "knowledge_versions": {
            "description": "Total rows across ``canon_knowledge_versions``.",
            "minimum": 0,
            "title": "Knowledge Versions",
            "type": "integer"
          },
          "sources": {
            "$ref": "#/components/schemas/SourceStats"
          }
        },
        "required": [
          "generated_at",
          "sources",
          "knowledge_items",
          "knowledge_versions",
          "candidates",
          "chunks",
          "ingest_jobs",
          "cost"
        ],
        "title": "CorpusStats",
        "type": "object"
      },
      "CostEvent": {
        "description": "One ``canon_cost_events`` row, surfaced as a public DTO.\n\nMirrors the persistence schema; ``cost_usd`` is serialised as a\nstring so JSON consumers don't lose precision the way IEEE-754\nfloats would on six-decimal monetary values.",
        "properties": {
          "actor": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Caller identity for audit / forensics (JWT subject or agent-token prefix). NOT a scope key -- the (tenant, workspace) headers drive scoping.",
            "title": "Actor"
          },
          "agent_name": {
            "description": "Which agent ran (e.g. ``flycanon-answerer``, ``flycanon-conflict-judge``).",
            "title": "Agent Name",
            "type": "string"
          },
          "correlation_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "W3C correlation id -- pivot back into the audit log with this.",
            "title": "Correlation Id"
          },
          "cost_usd": {
            "description": "Cost in USD as a decimal string (6-place precision).",
            "title": "Cost Usd",
            "type": "string"
          },
          "id": {
            "description": "Monotonic row id (also serves as the pagination cursor).",
            "title": "Id",
            "type": "integer"
          },
          "input_tokens": {
            "description": "Input tokens captured from the agent's usage block.",
            "minimum": 0,
            "title": "Input Tokens",
            "type": "integer"
          },
          "latency_ms": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "End-to-end latency of the call. ``null`` only when the middleware couldn't capture it.",
            "title": "Latency Ms"
          },
          "model": {
            "description": "Model identifier (e.g. ``anthropic:claude-sonnet-4-6``).",
            "title": "Model",
            "type": "string"
          },
          "occurred_at": {
            "description": "UTC timestamp of the call completion.",
            "format": "date-time",
            "title": "Occurred At",
            "type": "string"
          },
          "output_tokens": {
            "description": "Output tokens captured from the agent's usage block.",
            "minimum": 0,
            "title": "Output Tokens",
            "type": "integer"
          },
          "subject_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Id of the subject the call attributed to.",
            "title": "Subject Id"
          },
          "subject_kind": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Optional breadcrumb keying the spend to a domain entity (``source`` / ``knowledge_item`` / ``conversation`` / ...). Powers ``/api/v1/billing/by-subject``.",
            "title": "Subject Kind"
          },
          "total_tokens": {
            "description": "``input_tokens + output_tokens``.",
            "minimum": 0,
            "title": "Total Tokens",
            "type": "integer"
          }
        },
        "required": [
          "id",
          "agent_name",
          "model",
          "input_tokens",
          "output_tokens",
          "total_tokens",
          "cost_usd",
          "occurred_at"
        ],
        "title": "CostEvent",
        "type": "object"
      },
      "CostEventsPage": {
        "description": "Page of cost events (drill-down view of the aggregated report).",
        "properties": {
          "limit": {
            "description": "Page size requested by the caller (1-500).",
            "minimum": 1,
            "title": "Limit",
            "type": "integer"
          },
          "offset": {
            "description": "0-based offset of the first row in the page.",
            "minimum": 0,
            "title": "Offset",
            "type": "integer"
          },
          "rows": {
            "description": "One row per call, sorted by ``occurred_at`` descending.",
            "items": {
              "$ref": "#/components/schemas/CostEvent"
            },
            "title": "Rows",
            "type": "array"
          }
        },
        "required": [
          "limit",
          "offset"
        ],
        "title": "CostEventsPage",
        "type": "object"
      },
      "CostStreamStats": {
        "description": "Quick spend headline for the inventory panel.\n\nDetailed breakdowns live behind ``/api/v1/billing/*``; this is the\nrollup a dashboard can show alongside the corpus counters.",
        "properties": {
          "cost_usd_24h": {
            "description": "Decimal USD spent in the last 24 hours.",
            "title": "Cost Usd 24H",
            "type": "string"
          },
          "cost_usd_30d": {
            "description": "Decimal USD spent in the last 30 days.",
            "title": "Cost Usd 30D",
            "type": "string"
          },
          "total_events": {
            "minimum": 0,
            "title": "Total Events",
            "type": "integer"
          }
        },
        "required": [
          "total_events",
          "cost_usd_24h",
          "cost_usd_30d"
        ],
        "title": "CostStreamStats",
        "type": "object"
      },
      "CreateConversationRequest": {
        "description": "Open a fresh conversation.\n\n``actor`` is intentionally NOT a body field: the conversation's\nactor is derived from the request context (the JWT subject or\nagent-token prefix).",
        "properties": {
          "metadata": {
            "additionalProperties": true,
            "title": "Metadata",
            "type": "object"
          },
          "model": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Override the configured answer model for this conversation. Defaults to ``FLYCANON_ANSWER_MODEL``.",
            "title": "Model"
          },
          "title": {
            "anyOf": [
              {
                "maxLength": 512,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Title"
          }
        },
        "title": "CreateConversationRequest",
        "type": "object"
      },
      "CreateKnowledgeRequest": {
        "description": "Direct knowledge creation (bypassing the candidate pipeline).\n\nUse ``POST /api/v1/candidates/{id}:accept`` instead when the\nknowledge originates from a candidate proposal; this endpoint is\nfor callers that own the canonical content already.",
        "properties": {
          "actor": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Stable identifier of the human or service performing the action.",
            "title": "Actor"
          },
          "body": {
            "minLength": 1,
            "title": "Body",
            "type": "string"
          },
          "citations": {
            "items": {
              "$ref": "#/components/schemas/Citation"
            },
            "title": "Citations",
            "type": "array"
          },
          "domain": {
            "$ref": "#/components/schemas/Domain"
          },
          "jurisdiction": {
            "$ref": "#/components/schemas/Jurisdiction",
            "default": "GLOBAL"
          },
          "metadata": {
            "additionalProperties": true,
            "title": "Metadata",
            "type": "object"
          },
          "publish": {
            "default": true,
            "description": "Publish immediately. Set False to land the version in ``draft``.",
            "title": "Publish",
            "type": "boolean"
          },
          "summary": {
            "anyOf": [
              {
                "maxLength": 4000,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Summary"
          },
          "tags": {
            "items": {
              "type": "string"
            },
            "title": "Tags",
            "type": "array"
          },
          "title": {
            "maxLength": 512,
            "minLength": 1,
            "title": "Title",
            "type": "string"
          }
        },
        "required": [
          "title",
          "body",
          "domain"
        ],
        "title": "CreateKnowledgeRequest",
        "type": "object"
      },
      "CreateRelationRequest": {
        "description": "Attach a new relation rooted at the path's ``{item_id}``.",
        "properties": {
          "actor": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Stable identifier of the person/service asserting the link.",
            "title": "Actor"
          },
          "kind": {
            "$ref": "#/components/schemas/RelationKind",
            "description": "Semantic of the edge. See :class:`RelationKind`."
          },
          "note": {
            "anyOf": [
              {
                "maxLength": 4000,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Free-form note. Surfaced in the graph viz tooltips.",
            "title": "Note"
          },
          "since_version": {
            "anyOf": [
              {
                "minimum": 1,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Optional knowledge_version of the FROM item the relation becomes effective from. Lets timelines hide an edge that wasn't asserted yet at version N.",
            "title": "Since Version"
          },
          "to_item_id": {
            "description": "Target knowledge item id.",
            "title": "To Item Id",
            "type": "string"
          }
        },
        "required": [
          "to_item_id",
          "kind"
        ],
        "title": "CreateRelationRequest",
        "type": "object"
      },
      "CreateTaxonomyNodeRequest": {
        "description": "Append a new node under an existing parent.",
        "properties": {
          "description": {
            "anyOf": [
              {
                "maxLength": 2000,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Description"
          },
          "domain": {
            "$ref": "#/components/schemas/Domain",
            "description": "Domain the node belongs to."
          },
          "label": {
            "maxLength": 256,
            "minLength": 1,
            "title": "Label",
            "type": "string"
          },
          "parent_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Parent node id. ``None`` creates a new root.",
            "title": "Parent Id"
          },
          "slug": {
            "description": "Stable, kebab-case identifier.",
            "maxLength": 128,
            "minLength": 1,
            "title": "Slug",
            "type": "string"
          }
        },
        "required": [
          "slug",
          "label",
          "domain"
        ],
        "title": "CreateTaxonomyNodeRequest",
        "type": "object"
      },
      "CreateTurnRequest": {
        "description": "Append a turn to an existing conversation.",
        "properties": {
          "instructions": {
            "anyOf": [
              {
                "maxLength": 4000,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Optional system-level steering appended to the answer prompt.",
            "title": "Instructions"
          },
          "question": {
            "description": "The user's next question. Plain natural language.",
            "maxLength": 4000,
            "minLength": 1,
            "title": "Question",
            "type": "string"
          },
          "top_k": {
            "default": 8,
            "description": "Retrieval window size for this turn.",
            "maximum": 40,
            "minimum": 1,
            "title": "Top K",
            "type": "integer"
          }
        },
        "required": [
          "question"
        ],
        "title": "CreateTurnRequest",
        "type": "object"
      },
      "Domain": {
        "enum": [
          "legal",
          "compliance",
          "process",
          "network",
          "ai_platform",
          "executive",
          "hr",
          "cto",
          "engineering",
          "security",
          "other"
        ],
        "title": "Domain",
        "type": "string"
      },
      "FieldChange": {
        "description": "One field's old -> new transition between two versions.",
        "properties": {
          "after": {
            "anyOf": [
              {},
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "After"
          },
          "before": {
            "anyOf": [
              {},
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Before"
          },
          "field": {
            "description": "Name of the changed field.",
            "title": "Field",
            "type": "string"
          }
        },
        "required": [
          "field"
        ],
        "title": "FieldChange",
        "type": "object"
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "title": "Detail",
            "type": "array"
          }
        },
        "title": "HTTPValidationError",
        "type": "object"
      },
      "Hit": {
        "description": "Single retrieval hit.\n\nReturned by both ``/search`` (as the page-level list) and\n``/query`` (as the citation list -- the chunks the answer model\nrelied on).",
        "properties": {
          "bm25_rank": {
            "anyOf": [
              {
                "minimum": 1,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Rank in the BM25 ranking when present, else None.",
            "title": "Bm25 Rank"
          },
          "chunk_id": {
            "description": "Stable id of the matched chunk.",
            "title": "Chunk Id",
            "type": "string"
          },
          "content": {
            "description": "Verbatim chunk text. Suitable for direct display in a UI; the caller does not need to re-fetch ``canon_chunks``.",
            "title": "Content",
            "type": "string"
          },
          "knowledge_item_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Populated when the chunk is cited by a published knowledge version -- lets callers jump directly to ``/api/v1/knowledge/{id}`` for the canonical record.",
            "title": "Knowledge Item Id"
          },
          "knowledge_version": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Knowledge Version"
          },
          "metadata": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "Free-form chunk metadata projected from the corpus index. The structured fields ``source_filename`` / ``source_title`` / ``source_kind`` / ``section_path`` / ``page`` are exposed as top-level attributes; this dict carries everything else the loader emitted.",
            "examples": [
              {
                "source_kind": "pdf"
              }
            ],
            "title": "Metadata",
            "type": "object"
          },
          "page": {
            "anyOf": [
              {
                "minimum": 1,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "1-based page number when the chunk's source has paginated layout (PDF, PPTX). ``null`` otherwise.",
            "examples": [
              2
            ],
            "title": "Page"
          },
          "score": {
            "description": "Reciprocal Rank Fusion score. Combines BM25 + vector rankings using the standard ``1 / (k + rank)`` formula with ``k = settings.retrieval_rrf_k`` (default 60). Higher is better; absolute values are comparable across queries within a single request but not across requests with different ``per_query_k`` or filters.",
            "examples": [
              0.6184
            ],
            "title": "Score",
            "type": "number"
          },
          "section_path": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Section breadcrumb derived from the document headings (``Scope > In scope``, ``9) Repositorio + Controlador WebFlux``, ...). Mirrors ``canon_chunks.section_path``.",
            "examples": [
              "Scope > In scope"
            ],
            "title": "Section Path"
          },
          "source_filename": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Original filename the source was ingested as (``Manifiesto.pdf``, ``Cleargate.docx``, ...). Lets a UI render a human-readable label without a second ``/api/v1/sources/{id}`` round-trip.",
            "examples": [
              "Cleargate Business Idea.docx"
            ],
            "title": "Source Filename"
          },
          "source_id": {
            "description": "Id of the source the chunk belongs to.",
            "title": "Source Id",
            "type": "string"
          },
          "source_kind": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "``SourceKind`` value of the source the chunk came from (``pdf`` / ``docx`` / ``pptx`` / ``image`` / ...). Lets the caller pick a file-type icon without re-fetching.",
            "examples": [
              "pdf"
            ],
            "title": "Source Kind"
          },
          "source_title": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Caller-supplied ``metadata.title`` or, when absent, the extractor-derived title from the document's embedded metadata (PyMuPDF / python-docx / python-pptx). Use as the citation label in answer UIs.",
            "examples": [
              "Cleargate Business Idea"
            ],
            "title": "Source Title"
          },
          "source_uri": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Original URI of the source when it was submitted via URL rather than inline bytes. ``null`` for inline uploads.",
            "title": "Source Uri"
          },
          "vector_rank": {
            "anyOf": [
              {
                "minimum": 1,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Rank in the dense-vector ranking when present, else None.",
            "title": "Vector Rank"
          }
        },
        "required": [
          "chunk_id",
          "source_id",
          "content",
          "score"
        ],
        "title": "Hit",
        "type": "object"
      },
      "IngestJob": {
        "description": "Public view of a ``canon_ingest_jobs`` row.",
        "properties": {
          "actor": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Caller identity captured at submit. Surfaces on the audit + billing trails.",
            "title": "Actor"
          },
          "attempts": {
            "description": "How many times the worker has tried this job (bumped on each retry).",
            "minimum": 0,
            "title": "Attempts",
            "type": "integer"
          },
          "callback_url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Optional webhook URL the worker POSTs to on completion / failure. Receives a ``{job_id, status, source_id, error_code, error_message, occurred_at}`` body.",
            "title": "Callback Url"
          },
          "content_sha256": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "SHA-256 of the raw payload; null until the worker has hashed the content.",
            "title": "Content Sha256"
          },
          "content_type": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Declared content type from the submit request (server still re-sniffs the magic bytes).",
            "title": "Content Type"
          },
          "correlation_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "W3C correlation id from the originating request -- pivot back to the audit log with this.",
            "title": "Correlation Id"
          },
          "created_at": {
            "description": "UTC timestamp of submit.",
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "error_code": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Stable error code matching the RFC 7807 ``code`` field. Populated on ``failed``.",
            "title": "Error Code"
          },
          "error_message": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Human-readable failure detail. Populated on ``failed``.",
            "title": "Error Message"
          },
          "filename": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Original filename declared at submit time, when available.",
            "title": "Filename"
          },
          "finished_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "UTC timestamp of the terminal transition (``succeeded`` or ``failed``).",
            "title": "Finished At"
          },
          "id": {
            "description": "Stable job id assigned at submit time.",
            "title": "Id",
            "type": "string"
          },
          "source_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Resolved source id once intake completes. ``null`` while the job is queued or running.",
            "title": "Source Id"
          },
          "started_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "UTC timestamp when the worker picked the job up (``null`` while still queued).",
            "title": "Started At"
          },
          "status": {
            "description": "Lifecycle state: ``queued`` (worker hasn't picked it up yet) | ``running`` (intake pipeline executing) | ``succeeded`` (``source_id`` is populated) | ``failed`` (``error_code`` / ``error_message`` carry the typed failure).",
            "examples": [
              "queued",
              "running",
              "succeeded",
              "failed"
            ],
            "title": "Status",
            "type": "string"
          },
          "updated_at": {
            "description": "UTC timestamp of the last row mutation.",
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          },
          "uri": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Optional source URI captured at submit (mirrors ``SourceRecord.uri``).",
            "title": "Uri"
          }
        },
        "required": [
          "id",
          "status",
          "attempts",
          "created_at",
          "updated_at"
        ],
        "title": "IngestJob",
        "type": "object"
      },
      "IngestJobsPage": {
        "description": "Paged view of recent ingest jobs (``GET /api/v1/ingest-jobs``).",
        "properties": {
          "items": {
            "description": "One row per job in the requested page.",
            "items": {
              "$ref": "#/components/schemas/IngestJob"
            },
            "title": "Items",
            "type": "array"
          },
          "limit": {
            "description": "Page size requested by the caller (1-500).",
            "maximum": 500,
            "minimum": 1,
            "title": "Limit",
            "type": "integer"
          },
          "offset": {
            "description": "0-based offset of the first row in ``items``.",
            "minimum": 0,
            "title": "Offset",
            "type": "integer"
          },
          "total": {
            "description": "Total jobs matching the filter (before pagination).",
            "minimum": 0,
            "title": "Total",
            "type": "integer"
          }
        },
        "required": [
          "items",
          "total",
          "offset",
          "limit"
        ],
        "title": "IngestJobsPage",
        "type": "object"
      },
      "JobStats": {
        "description": "Async-ingest queue health.",
        "properties": {
          "avg_attempts": {
            "minimum": 0.0,
            "title": "Avg Attempts",
            "type": "number"
          },
          "by_status": {
            "additionalProperties": {
              "type": "integer"
            },
            "title": "By Status",
            "type": "object"
          },
          "total": {
            "minimum": 0,
            "title": "Total",
            "type": "integer"
          }
        },
        "required": [
          "total",
          "avg_attempts"
        ],
        "title": "JobStats",
        "type": "object"
      },
      "Jurisdiction": {
        "enum": [
          "GLOBAL",
          "EU",
          "LATAM",
          "EMEA",
          "APAC",
          "AMER",
          "ES",
          "PT",
          "FR",
          "DE",
          "IT",
          "NL",
          "UK",
          "US",
          "MX",
          "BR",
          "AR",
          "CO",
          "CL"
        ],
        "title": "Jurisdiction",
        "type": "string"
      },
      "KnowledgeItem": {
        "description": "Canonical pointer to the current version of a knowledge item.",
        "properties": {
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "current_version": {
            "minimum": 1,
            "title": "Current Version",
            "type": "integer"
          },
          "domain": {
            "$ref": "#/components/schemas/Domain"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "jurisdiction": {
            "$ref": "#/components/schemas/Jurisdiction",
            "default": "GLOBAL"
          },
          "retired_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Retired At"
          },
          "status": {
            "$ref": "#/components/schemas/KnowledgeStatus"
          },
          "summary": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Summary"
          },
          "tags": {
            "items": {
              "type": "string"
            },
            "title": "Tags",
            "type": "array"
          },
          "title": {
            "title": "Title",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          }
        },
        "required": [
          "id",
          "status",
          "current_version",
          "title",
          "domain",
          "created_at",
          "updated_at"
        ],
        "title": "KnowledgeItem",
        "type": "object"
      },
      "KnowledgeItemStats": {
        "description": "Counts of canonical knowledge items by status + domain.",
        "properties": {
          "by_domain": {
            "additionalProperties": {
              "type": "integer"
            },
            "title": "By Domain",
            "type": "object"
          },
          "by_status": {
            "additionalProperties": {
              "type": "integer"
            },
            "title": "By Status",
            "type": "object"
          },
          "total": {
            "minimum": 0,
            "title": "Total",
            "type": "integer"
          }
        },
        "required": [
          "total"
        ],
        "title": "KnowledgeItemStats",
        "type": "object"
      },
      "KnowledgeItemsPage": {
        "description": "Paged list of knowledge items.",
        "properties": {
          "items": {
            "items": {
              "$ref": "#/components/schemas/KnowledgeItem"
            },
            "title": "Items",
            "type": "array"
          },
          "limit": {
            "maximum": 500,
            "minimum": 1,
            "title": "Limit",
            "type": "integer"
          },
          "offset": {
            "minimum": 0,
            "title": "Offset",
            "type": "integer"
          },
          "total": {
            "minimum": 0,
            "title": "Total",
            "type": "integer"
          }
        },
        "required": [
          "items",
          "total",
          "offset",
          "limit"
        ],
        "title": "KnowledgeItemsPage",
        "type": "object"
      },
      "KnowledgeRelation": {
        "description": "Public view of a ``canon_knowledge_relations`` row.",
        "properties": {
          "actor": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Actor"
          },
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "from_item_id": {
            "title": "From Item Id",
            "type": "string"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "kind": {
            "$ref": "#/components/schemas/RelationKind"
          },
          "note": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Note"
          },
          "since_version": {
            "anyOf": [
              {
                "minimum": 1,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Since Version"
          },
          "to_item_id": {
            "title": "To Item Id",
            "type": "string"
          }
        },
        "required": [
          "id",
          "from_item_id",
          "to_item_id",
          "kind",
          "created_at"
        ],
        "title": "KnowledgeRelation",
        "type": "object"
      },
      "KnowledgeRelations": {
        "description": "Outgoing + incoming relations for a single knowledge item.\n\nReturned by ``GET /api/v1/knowledge/{id}/relations``. Splits the\nlist by direction so a UI can render distinct ``Depends on`` and\n``Required by`` sections without filtering client-side.",
        "properties": {
          "incoming": {
            "items": {
              "$ref": "#/components/schemas/KnowledgeRelation"
            },
            "title": "Incoming",
            "type": "array"
          },
          "item_id": {
            "title": "Item Id",
            "type": "string"
          },
          "outgoing": {
            "items": {
              "$ref": "#/components/schemas/KnowledgeRelation"
            },
            "title": "Outgoing",
            "type": "array"
          }
        },
        "required": [
          "item_id"
        ],
        "title": "KnowledgeRelations",
        "type": "object"
      },
      "KnowledgeStatus": {
        "enum": [
          "draft",
          "published",
          "superseded",
          "retired"
        ],
        "title": "KnowledgeStatus",
        "type": "string"
      },
      "KnowledgeVersion": {
        "description": "A single revision of a knowledge item.",
        "properties": {
          "body": {
            "description": "Canonical content -- markdown is the recommended format.",
            "title": "Body",
            "type": "string"
          },
          "citations": {
            "items": {
              "$ref": "#/components/schemas/Citation"
            },
            "title": "Citations",
            "type": "array"
          },
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "created_by": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Created By"
          },
          "domain": {
            "$ref": "#/components/schemas/Domain"
          },
          "jurisdiction": {
            "$ref": "#/components/schemas/Jurisdiction",
            "default": "GLOBAL"
          },
          "knowledge_item_id": {
            "title": "Knowledge Item Id",
            "type": "string"
          },
          "metadata": {
            "additionalProperties": true,
            "title": "Metadata",
            "type": "object"
          },
          "status": {
            "$ref": "#/components/schemas/KnowledgeStatus"
          },
          "summary": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Summary"
          },
          "superseded_by_version": {
            "anyOf": [
              {
                "minimum": 1,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Superseded By Version"
          },
          "supersedes_version": {
            "anyOf": [
              {
                "minimum": 1,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Supersedes Version"
          },
          "tags": {
            "items": {
              "type": "string"
            },
            "title": "Tags",
            "type": "array"
          },
          "title": {
            "title": "Title",
            "type": "string"
          },
          "version": {
            "minimum": 1,
            "title": "Version",
            "type": "integer"
          }
        },
        "required": [
          "knowledge_item_id",
          "version",
          "status",
          "title",
          "body",
          "domain",
          "created_at"
        ],
        "title": "KnowledgeVersion",
        "type": "object"
      },
      "KnowledgeVersionDiff": {
        "description": "Diff between two versions of the same knowledge item.\n\nReturned by ``GET /api/v1/knowledge/{id}/diff?from=X&to=Y``.\nThe body diff is a Unix-style unified diff with three lines of\ncontext (the same shape ``git diff`` emits) so an audit tool or\na UI can render it without parsing the wire form. Per-field\nchanges cover the scalar columns that don't fit in a body diff\n(title, summary, domain, jurisdiction, tags). Citations are\ndiffed at the set level since their order does not carry\ncanonical meaning.",
        "properties": {
          "body_diff": {
            "description": "Unified diff of the version body. Empty string when the two versions share an identical body.",
            "title": "Body Diff",
            "type": "string"
          },
          "citations_added": {
            "items": {
              "$ref": "#/components/schemas/Citation"
            },
            "title": "Citations Added",
            "type": "array"
          },
          "citations_removed": {
            "items": {
              "$ref": "#/components/schemas/Citation"
            },
            "title": "Citations Removed",
            "type": "array"
          },
          "field_changes": {
            "description": "Scalar-field changes (title, summary, domain, jurisdiction, tags).",
            "items": {
              "$ref": "#/components/schemas/FieldChange"
            },
            "title": "Field Changes",
            "type": "array"
          },
          "from_version": {
            "minimum": 1,
            "title": "From Version",
            "type": "integer"
          },
          "knowledge_item_id": {
            "title": "Knowledge Item Id",
            "type": "string"
          },
          "to_version": {
            "minimum": 1,
            "title": "To Version",
            "type": "integer"
          }
        },
        "required": [
          "knowledge_item_id",
          "from_version",
          "to_version",
          "body_diff"
        ],
        "title": "KnowledgeVersionDiff",
        "type": "object"
      },
      "LatencyReport": {
        "description": "``GET /api/v1/billing/latency`` envelope.",
        "properties": {
          "rows": {
            "description": "One row per group bucket. Sorted by sample count descending.",
            "items": {
              "$ref": "#/components/schemas/LatencyRow"
            },
            "title": "Rows",
            "type": "array"
          }
        },
        "title": "LatencyReport",
        "type": "object"
      },
      "LatencyRow": {
        "description": "Latency percentiles per group bucket.",
        "properties": {
          "avg_ms": {
            "description": "Arithmetic mean of ``latency_ms`` across samples.",
            "minimum": 0,
            "title": "Avg Ms",
            "type": "integer"
          },
          "count": {
            "description": "Number of samples in this bucket.",
            "minimum": 0,
            "title": "Count",
            "type": "integer"
          },
          "group": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "Group-column values keyed by name (matches the request's ``group_by`` selection).",
            "title": "Group",
            "type": "object"
          },
          "max_ms": {
            "description": "Worst observed latency in the bucket.",
            "minimum": 0,
            "title": "Max Ms",
            "type": "integer"
          },
          "p50_ms": {
            "description": "50th percentile (median).",
            "minimum": 0,
            "title": "P50 Ms",
            "type": "integer"
          },
          "p95_ms": {
            "description": "95th percentile.",
            "minimum": 0,
            "title": "P95 Ms",
            "type": "integer"
          },
          "p99_ms": {
            "description": "99th percentile.",
            "minimum": 0,
            "title": "P99 Ms",
            "type": "integer"
          }
        },
        "required": [
          "count",
          "avg_ms",
          "p50_ms",
          "p95_ms",
          "p99_ms",
          "max_ms"
        ],
        "title": "LatencyRow",
        "type": "object"
      },
      "ProposeCandidateRequest": {
        "description": "Trigger consolidation against a source (synchronous).\n\nThe handler reads up to ``max_chunks`` chunks from the source,\nruns the consolidation prompt, and persists the resulting\ncandidates. Callers receive the list of newly proposed records;\nno candidate is auto-accepted.",
        "properties": {
          "actor": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Actor"
          },
          "domain": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Domain"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Restrict the proposal to this domain."
          },
          "instructions": {
            "anyOf": [
              {
                "maxLength": 4000,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Optional caller instructions appended to the consolidation prompt.",
            "title": "Instructions"
          },
          "jurisdiction": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Jurisdiction"
              },
              {
                "type": "null"
              }
            ],
            "default": null
          },
          "max_chunks": {
            "default": 40,
            "maximum": 500,
            "minimum": 1,
            "title": "Max Chunks",
            "type": "integer"
          },
          "source_id": {
            "title": "Source Id",
            "type": "string"
          }
        },
        "required": [
          "source_id"
        ],
        "title": "ProposeCandidateRequest",
        "type": "object"
      },
      "Provenance": {
        "description": "Resolved citation graph for a knowledge version.\n\nReturned by ``GET /api/v1/knowledge/{id}/provenance``. Carries\nevery citation row, the source records they point at, and the\nfull version chain so callers can reconstruct the\nwhy-this-is-canonical story without follow-up calls.",
        "properties": {
          "citations": {
            "items": {
              "$ref": "#/components/schemas/Citation"
            },
            "title": "Citations",
            "type": "array"
          },
          "history": {
            "items": {
              "$ref": "#/components/schemas/KnowledgeVersion"
            },
            "title": "History",
            "type": "array"
          },
          "knowledge_item_id": {
            "title": "Knowledge Item Id",
            "type": "string"
          },
          "sources": {
            "description": "Compact source views (id, kind, title, content_sha256).",
            "items": {
              "additionalProperties": true,
              "type": "object"
            },
            "title": "Sources",
            "type": "array"
          },
          "version": {
            "title": "Version",
            "type": "integer"
          }
        },
        "required": [
          "knowledge_item_id",
          "version",
          "citations"
        ],
        "title": "Provenance",
        "type": "object"
      },
      "RejectCandidateRequest": {
        "properties": {
          "actor": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Actor"
          },
          "reason": {
            "maxLength": 2000,
            "minLength": 1,
            "title": "Reason",
            "type": "string"
          }
        },
        "required": [
          "reason"
        ],
        "title": "RejectCandidateRequest",
        "type": "object"
      },
      "RelationKind": {
        "description": "Semantic kind of a knowledge_item -> knowledge_item edge.\n\n* ``related`` -- soft \"see also\" link. Symmetrical in intent\n  but stored as a single directed row so the API stays\n  consistent with the directional kinds.\n* ``depends_on`` -- ``from`` is only valid while ``to`` is.\n  Surfaces in the inbox when ``to`` is updated / retired.\n* ``conflicts_with`` -- ``from`` and ``to`` make\n  contradicting canonical claims. Typically populated by the\n  conflict-detection background job.\n* ``replaces`` -- ``from`` formally replaces ``to``\n  (cross-item supersession; the item-level\n  ``superseded_by_item_id`` already exists, ``replaces`` lets\n  multiple items collectively replace a legacy one).",
        "enum": [
          "related",
          "depends_on",
          "conflicts_with",
          "replaces"
        ],
        "title": "RelationKind",
        "type": "string"
      },
      "RetireKnowledgeRequest": {
        "description": "Withdraw a knowledge item from circulation.",
        "properties": {
          "actor": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Actor"
          },
          "reason": {
            "maxLength": 2000,
            "minLength": 1,
            "title": "Reason",
            "type": "string"
          }
        },
        "required": [
          "reason"
        ],
        "title": "RetireKnowledgeRequest",
        "type": "object"
      },
      "SearchRequest": {
        "description": "Hybrid-retrieval request body.\n\nCarries the query string + retrieval knobs. The defaults track\n:class:`CanonSettings.retrieval_top_k` /\n:class:`CanonSettings.retrieval_per_query_k`.",
        "properties": {
          "domains": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/Domain"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Restrict to chunks whose source belongs to one of these domains.",
            "examples": [
              [
                "process",
                "compliance"
              ]
            ],
            "title": "Domains"
          },
          "jurisdictions": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/Jurisdiction"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Jurisdictions"
          },
          "knowledge_item_ids": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Restrict to chunks cited by these knowledge items.",
            "title": "Knowledge Item Ids"
          },
          "per_query_k": {
            "anyOf": [
              {
                "maximum": 500,
                "minimum": 1,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Per-modality (BM25 / vector) result cap before RRF fusion. Defaults to ``settings.retrieval_per_query_k`` (30). Raise it when filters drop most candidates.",
            "title": "Per Query K"
          },
          "query": {
            "description": "The free-form query. The retriever runs the query verbatim against BM25 and against the dense-vector projection (after embedding via the configured embedding model). Use plain natural language; no operator-style boolean syntax is required.",
            "examples": [
              "What does the document say about scope?"
            ],
            "maxLength": 2000,
            "minLength": 1,
            "title": "Query",
            "type": "string"
          },
          "source_ids": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Restrict retrieval to chunks of these sources.",
            "examples": [
              [
                "0b06a8e6-37e7-4f7b-a8f1-7e2a6f7e5d11"
              ]
            ],
            "title": "Source Ids"
          },
          "statuses": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/KnowledgeStatus"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Restrict to chunks belonging to knowledge items in these lifecycle states. Defaults to ``published`` items only when omitted upstream.",
            "title": "Statuses"
          },
          "tags": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Tags"
          },
          "top_k": {
            "default": 10,
            "description": "Maximum number of fused hits to return. The retriever widens internally by 3x for post-filter trimming, so this value is the final ceiling regardless of filters.",
            "maximum": 200,
            "minimum": 1,
            "title": "Top K",
            "type": "integer"
          }
        },
        "required": [
          "query"
        ],
        "title": "SearchRequest",
        "type": "object"
      },
      "SearchResponse": {
        "properties": {
          "elapsed_ms": {
            "description": "Wall-clock time spent in the retrieval pipeline (embed query + BM25 + vector + RRF fuse + hydrate). Does not include controller serialisation.",
            "minimum": 0,
            "title": "Elapsed Ms",
            "type": "integer"
          },
          "hits": {
            "description": "Fused hit list, highest score first.",
            "items": {
              "$ref": "#/components/schemas/Hit"
            },
            "title": "Hits",
            "type": "array"
          }
        },
        "required": [
          "hits",
          "elapsed_ms"
        ],
        "title": "SearchResponse",
        "type": "object"
      },
      "SourceKind": {
        "enum": [
          "docx",
          "xlsx",
          "pptx",
          "pdf",
          "rtf",
          "odt",
          "ods",
          "odp",
          "html",
          "markdown",
          "text",
          "csv",
          "tsv",
          "json",
          "xml",
          "epub",
          "image",
          "archive",
          "email",
          "transcript",
          "url",
          "unknown",
          "discovery"
        ],
        "title": "SourceKind",
        "type": "string"
      },
      "SourceMetadata": {
        "description": "Caller-supplied metadata that travels with a source.\n\nThe intake pipeline only fills in fields the caller did not\nspecify -- ``content_type`` from the upload's MIME, ``title``\nfrom the document properties when present, ``language`` from\nthe loader's detection. The :class:`SourceMetadata.extra` dict\nis a free-form passthrough preserved on the source row's\n``metadata_json`` column so downstream projections can use any\ncustom field without a schema change.",
        "properties": {
          "author": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Document author or originator. Free text.",
            "examples": [
              "Elena Boffa Tarlatta"
            ],
            "title": "Author"
          },
          "domain": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Domain"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Operational domain the source belongs to. Mirrors the workshop persona map -- one of legal / compliance / process / network / ai_platform / executive / hr / cto / engineering / security / other. When omitted, the candidate consolidation stage picks the best fit.",
            "examples": [
              "process"
            ]
          },
          "extra": {
            "additionalProperties": true,
            "description": "Caller-defined fields preserved on the source row's metadata_json. The intake pipeline does not interpret them; they ride through to the audit trail and the provenance graph.",
            "examples": [
              {
                "release": "26.05",
                "team": "operations-transformation"
              }
            ],
            "title": "Extra",
            "type": "object"
          },
          "jurisdiction": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Jurisdiction"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Geographic / legal scope of the source. ISO 3166-1 alpha-2 country codes plus EU / EMEA / LATAM / APAC / AMER / GLOBAL shorthands.",
            "examples": [
              "ES",
              "EU",
              "GLOBAL"
            ]
          },
          "language": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "ISO 639-1 language hint (``es``, ``en``, ``pt``, ...). Auto-detected from the loader when omitted; used as the default OCR ``-l`` argument for raster sources.",
            "examples": [
              "es",
              "en"
            ],
            "title": "Language"
          },
          "tags": {
            "description": "Free-form tags for downstream filtering. Applied as a metadata column on every chunk so retrieval can scope by tag without a join.",
            "examples": [
              [
                "mvp",
                "workshop"
              ]
            ],
            "items": {
              "type": "string"
            },
            "title": "Tags",
            "type": "array"
          },
          "title": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Human-readable title for the source. Surfaces on the /api/v1/sources list view, the provenance graph, and every audit row that references this source.",
            "examples": [
              "CANON Operational Knowledge -- MVP scope"
            ],
            "title": "Title"
          }
        },
        "title": "SourceMetadata",
        "type": "object"
      },
      "SourceRecord": {
        "description": "Public view of a ``canon_sources`` row.\n\nReturned by ``POST /api/v1/sources`` (201) and ``GET /api/v1/sources/{id}``.\nCarries enough state for downstream consumers to subscribe to\nlifecycle events and reconstruct the intake path without a\nsecond round-trip.",
        "properties": {
          "content_bytes": {
            "description": "Size of the canonical bytes after normalisation.",
            "examples": [
              915450
            ],
            "minimum": 0,
            "title": "Content Bytes",
            "type": "integer"
          },
          "content_sha256": {
            "description": "SHA-256 of the canonical bytes (after binary normalisation). Used as the idempotency anchor -- two uploads of the same bytes share a SourceRecord.",
            "examples": [
              "8b3c0d1a9f4b..."
            ],
            "title": "Content Sha256",
            "type": "string"
          },
          "created_at": {
            "description": "When the row was first persisted.",
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "error_code": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Stable machine-readable failure code (e.g. ``unsupported_binary``, ``encrypted_pdf``, ``empty_source``) set when ``status == failed``.",
            "title": "Error Code"
          },
          "error_message": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Error Message"
          },
          "filename": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Original filename when uploaded; None for URL-fetched sources.",
            "examples": [
              "CANON-Operational-Knowledge.docx"
            ],
            "title": "Filename"
          },
          "id": {
            "description": "Stable string UUID assigned at intake.",
            "examples": [
              "0b06a8e6-37e7-4f7b-a8f1-7e2a6f7e5d11"
            ],
            "title": "Id",
            "type": "string"
          },
          "ingested_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "When ``status`` flipped to ``ingested`` (None on failure).",
            "title": "Ingested At"
          },
          "kind": {
            "$ref": "#/components/schemas/SourceKind",
            "description": "Canonical source format detected by the binary normaliser.",
            "examples": [
              "docx"
            ]
          },
          "metadata": {
            "$ref": "#/components/schemas/SourceMetadata",
            "description": "Caller-supplied metadata + loader-extracted fields (``title``, ``language``, ``page_count``, plus the binary normaliser's artifact ancestry when applicable)."
          },
          "n_chunks": {
            "default": 0,
            "description": "Number of retrieval-grade chunks emitted by the chunker. Each chunk lands in ``canon_chunks`` and is indexed for BM25 + vector retrieval.",
            "examples": [
              84
            ],
            "minimum": 0,
            "title": "N Chunks",
            "type": "integer"
          },
          "status": {
            "$ref": "#/components/schemas/SourceStatus",
            "description": "Lifecycle state. Terminal: ``ingested`` on success, ``failed`` when normalisation / loading rejected the bytes (``error_code`` carries the reason), ``superseded`` when a later upload of the same content hash replaces this row.",
            "examples": [
              "ingested"
            ]
          },
          "updated_at": {
            "description": "Last mutation timestamp; auto-bumped on status changes.",
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          },
          "uri": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Origin URI when the caller referenced one.",
            "title": "Uri"
          }
        },
        "required": [
          "id",
          "kind",
          "status",
          "content_sha256",
          "content_bytes",
          "created_at",
          "updated_at"
        ],
        "title": "SourceRecord",
        "type": "object"
      },
      "SourceStats": {
        "description": "Counts + total bytes for ``canon_sources``.",
        "properties": {
          "by_kind": {
            "additionalProperties": {
              "type": "integer"
            },
            "description": "Counts per ``SourceRow.kind`` (one of the routing-matrix labels).",
            "title": "By Kind",
            "type": "object"
          },
          "by_status": {
            "additionalProperties": {
              "type": "integer"
            },
            "description": "Counts per ``SourceRow.status`` (ingested / failed / superseded / \u2026).",
            "title": "By Status",
            "type": "object"
          },
          "total": {
            "minimum": 0,
            "title": "Total",
            "type": "integer"
          },
          "total_bytes": {
            "description": "Sum of ``content_bytes`` across all source rows.",
            "minimum": 0,
            "title": "Total Bytes",
            "type": "integer"
          }
        },
        "required": [
          "total",
          "total_bytes"
        ],
        "title": "SourceStats",
        "type": "object"
      },
      "SourceStatus": {
        "enum": [
          "pending",
          "ingesting",
          "ingested",
          "failed",
          "superseded"
        ],
        "title": "SourceStatus",
        "type": "string"
      },
      "SourcesPage": {
        "description": "Paged list of source records.\n\nReturned by ``GET /api/v1/sources``. The total reflects the\nfiltered set, not the page; callers paginate via\n``offset`` / ``limit`` against ``total``.",
        "properties": {
          "items": {
            "description": "Page of source records, newest first.",
            "items": {
              "$ref": "#/components/schemas/SourceRecord"
            },
            "title": "Items",
            "type": "array"
          },
          "limit": {
            "maximum": 500,
            "minimum": 1,
            "title": "Limit",
            "type": "integer"
          },
          "offset": {
            "minimum": 0,
            "title": "Offset",
            "type": "integer"
          },
          "total": {
            "description": "Total rows matching the filters.",
            "minimum": 0,
            "title": "Total",
            "type": "integer"
          }
        },
        "required": [
          "items",
          "total",
          "offset",
          "limit"
        ],
        "title": "SourcesPage",
        "type": "object"
      },
      "StaleItem": {
        "properties": {
          "computed_at": {
            "title": "Computed At",
            "type": "string"
          },
          "domain": {
            "title": "Domain",
            "type": "string"
          },
          "knowledge_item_id": {
            "title": "Knowledge Item Id",
            "type": "string"
          },
          "max_similarity": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Max Similarity"
          },
          "sample_size": {
            "minimum": 0,
            "title": "Sample Size",
            "type": "integer"
          },
          "score": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Score"
          },
          "title": {
            "title": "Title",
            "type": "string"
          }
        },
        "required": [
          "knowledge_item_id",
          "title",
          "domain",
          "sample_size",
          "computed_at"
        ],
        "title": "StaleItem",
        "type": "object"
      },
      "StaleReport": {
        "properties": {
          "items": {
            "items": {
              "$ref": "#/components/schemas/StaleItem"
            },
            "title": "Items",
            "type": "array"
          },
          "total": {
            "minimum": 0,
            "title": "Total",
            "type": "integer"
          }
        },
        "required": [
          "total"
        ],
        "title": "StaleReport",
        "type": "object"
      },
      "SubjectCostReport": {
        "description": "``GET /api/v1/billing/by-subject`` envelope.",
        "properties": {
          "rows": {
            "description": "One row per ``(subject_kind, subject_id)`` pair. Subjects without a populated pair are excluded.",
            "items": {
              "$ref": "#/components/schemas/SubjectCostRow"
            },
            "title": "Rows",
            "type": "array"
          }
        },
        "title": "SubjectCostReport",
        "type": "object"
      },
      "SubjectCostRow": {
        "description": "Cost attribution per ``(subject_kind, subject_id)``.",
        "properties": {
          "calls": {
            "description": "Number of calls attributed to this subject.",
            "minimum": 0,
            "title": "Calls",
            "type": "integer"
          },
          "cost_usd": {
            "description": "USD spent on this subject (decimal string).",
            "title": "Cost Usd",
            "type": "string"
          },
          "input_tokens": {
            "description": "Sum of input tokens attributed to this subject.",
            "minimum": 0,
            "title": "Input Tokens",
            "type": "integer"
          },
          "output_tokens": {
            "description": "Sum of output tokens attributed to this subject.",
            "minimum": 0,
            "title": "Output Tokens",
            "type": "integer"
          },
          "subject_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Id of the subject.",
            "title": "Subject Id"
          },
          "subject_kind": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Kind of the subject the call attributed to (``source`` / ``knowledge_item`` / ...).",
            "title": "Subject Kind"
          },
          "total_tokens": {
            "description": "``input_tokens + output_tokens``.",
            "minimum": 0,
            "title": "Total Tokens",
            "type": "integer"
          }
        },
        "required": [
          "input_tokens",
          "output_tokens",
          "total_tokens",
          "cost_usd",
          "calls"
        ],
        "title": "SubjectCostRow",
        "type": "object"
      },
      "SubmitSourceJsonPayload": {
        "description": "Wire payload for ``POST /api/v1/sources``.\n\nExtends :class:`SubmitSourceRequest` with the ``content_base64``\nfield that carries the canonical bytes. We deliberately ship a\nsingle JSON-only entry point (instead of multipart + JSON) so:\n\n* SDKs don't have to switch between content types per call.\n* Callers can run the bytes through their own normalisation\n  (e.g. signing, encryption) before submission without the\n  multipart boundary getting in the way.\n* The OpenAPI spec describes a single, simple shape.\n\nThe base64 string lands as raw bytes server-side; the binary\nnormaliser then sniffs the real media type, fans out archives /\nemails, and converts exotic image formats before the loader\npipeline sees the content.",
        "properties": {
          "content_base64": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Content Base64"
          },
          "content_type": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Content Type"
          },
          "filename": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Filename"
          },
          "kind": {
            "$ref": "#/components/schemas/SourceKind",
            "default": "unknown",
            "description": "Caller hint for the source format. When ``unknown`` (the default) the binary normaliser sniffs the actual type from magic bytes + the filename extension; the hint is a fast-path for callers that already know.",
            "examples": [
              "docx",
              "pdf",
              "xlsx",
              "html",
              "image",
              "archive",
              "email"
            ]
          },
          "metadata": {
            "$ref": "#/components/schemas/SourceMetadata",
            "description": "Caller-supplied metadata propagated to the source row."
          },
          "uri": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Origin URI when the caller is ingesting a fetch-by-URL source. Currently treated as a tracking field only -- URL fetching is on the roadmap; v1 callers must send the bytes via ``content_base64``.",
            "examples": [
              "https://example.com/policies/2026-procedure.pdf"
            ],
            "title": "Uri"
          }
        },
        "title": "SubmitSourceJsonPayload",
        "type": "object"
      },
      "SuggestRequest": {
        "description": "Generate suggested follow-up questions.\n\nUsed by chat UIs to render quick-reply chips. Off the same\nLLM that the answer endpoint uses.",
        "properties": {
          "answer": {
            "anyOf": [
              {
                "maxLength": 8000,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Optional prior answer for richer follow-ups.",
            "title": "Answer"
          },
          "n": {
            "default": 3,
            "maximum": 6,
            "minimum": 1,
            "title": "N",
            "type": "integer"
          },
          "question": {
            "maxLength": 4000,
            "minLength": 1,
            "title": "Question",
            "type": "string"
          }
        },
        "required": [
          "question"
        ],
        "title": "SuggestRequest",
        "type": "object"
      },
      "SuggestResponse": {
        "properties": {
          "suggestions": {
            "items": {
              "type": "string"
            },
            "title": "Suggestions",
            "type": "array"
          }
        },
        "title": "SuggestResponse",
        "type": "object"
      },
      "SupersedeKnowledgeRequest": {
        "description": "Mark a knowledge item as superseded by another.\n\nThe two items must share a domain (and ideally a jurisdiction);\nthe supersession is recorded on both sides of the relationship\nand emitted as a ``KnowledgeItemSuperseded`` event.",
        "properties": {
          "actor": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Actor"
          },
          "reason": {
            "anyOf": [
              {
                "maxLength": 2000,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Reason"
          },
          "superseded_by_item_id": {
            "title": "Superseded By Item Id",
            "type": "string"
          }
        },
        "required": [
          "superseded_by_item_id"
        ],
        "title": "SupersedeKnowledgeRequest",
        "type": "object"
      },
      "TaxonomyNode": {
        "description": "Single node in the taxonomy tree.",
        "properties": {
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "depth": {
            "minimum": 0,
            "title": "Depth",
            "type": "integer"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Description"
          },
          "domain": {
            "$ref": "#/components/schemas/Domain"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "label": {
            "title": "Label",
            "type": "string"
          },
          "parent_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Parent Id"
          },
          "slug": {
            "title": "Slug",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          }
        },
        "required": [
          "id",
          "parent_id",
          "slug",
          "label",
          "domain",
          "depth",
          "created_at",
          "updated_at"
        ],
        "title": "TaxonomyNode",
        "type": "object"
      },
      "TaxonomyTree": {
        "description": "Breadth-first view of the full taxonomy.",
        "properties": {
          "nodes": {
            "items": {
              "$ref": "#/components/schemas/TaxonomyNode"
            },
            "title": "Nodes",
            "type": "array"
          }
        },
        "required": [
          "nodes"
        ],
        "title": "TaxonomyTree",
        "type": "object"
      },
      "TopConsumerRow": {
        "description": "One entry in the top-N list keyed by the requested dimension.",
        "properties": {
          "calls": {
            "description": "Number of calls attributed to this consumer.",
            "minimum": 0,
            "title": "Calls",
            "type": "integer"
          },
          "cost_usd": {
            "description": "USD spent by this consumer (decimal string).",
            "title": "Cost Usd",
            "type": "string"
          },
          "dimension": {
            "description": "Column we grouped by (one of ``model`` / ``agent_name``).",
            "title": "Dimension",
            "type": "string"
          },
          "input_tokens": {
            "description": "Sum of input tokens for this consumer.",
            "minimum": 0,
            "title": "Input Tokens",
            "type": "integer"
          },
          "output_tokens": {
            "description": "Sum of output tokens for this consumer.",
            "minimum": 0,
            "title": "Output Tokens",
            "type": "integer"
          },
          "total_tokens": {
            "description": "``input_tokens + output_tokens``.",
            "minimum": 0,
            "title": "Total Tokens",
            "type": "integer"
          },
          "value": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The grouped value for this row (``null`` if the row had no value for ``dimension``).",
            "title": "Value"
          }
        },
        "required": [
          "dimension",
          "input_tokens",
          "output_tokens",
          "total_tokens",
          "cost_usd",
          "calls"
        ],
        "title": "TopConsumerRow",
        "type": "object"
      },
      "TopConsumersReport": {
        "description": "``GET /api/v1/billing/top`` envelope -- ranked consumers.",
        "properties": {
          "dimension": {
            "description": "Which column we ranked on (echoes the request param).",
            "title": "Dimension",
            "type": "string"
          },
          "rows": {
            "description": "Rows sorted by ``cost_usd`` descending. Length is bounded by the request ``limit``.",
            "items": {
              "$ref": "#/components/schemas/TopConsumerRow"
            },
            "title": "Rows",
            "type": "array"
          }
        },
        "required": [
          "dimension"
        ],
        "title": "TopConsumersReport",
        "type": "object"
      },
      "TurnResponse": {
        "description": "Synchronous response for the non-streaming turn endpoint.",
        "properties": {
          "conversation_id": {
            "title": "Conversation Id",
            "type": "string"
          },
          "turn": {
            "$ref": "#/components/schemas/ConversationTurn"
          }
        },
        "required": [
          "conversation_id",
          "turn"
        ],
        "title": "TurnResponse",
        "type": "object"
      },
      "UpdateKnowledgeRequest": {
        "description": "Materialise a new draft / published version of an existing item.\n\nEvery field is optional; whatever is sent overrides the\ncorresponding field on the current version. The new version is\nappended to the history; the previous one transitions to\n``superseded``.",
        "properties": {
          "actor": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Actor"
          },
          "body": {
            "anyOf": [
              {
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Body"
          },
          "citations": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/Citation"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Citations"
          },
          "domain": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Domain"
              },
              {
                "type": "null"
              }
            ],
            "default": null
          },
          "jurisdiction": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Jurisdiction"
              },
              {
                "type": "null"
              }
            ],
            "default": null
          },
          "metadata": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Metadata"
          },
          "publish": {
            "default": true,
            "title": "Publish",
            "type": "boolean"
          },
          "summary": {
            "anyOf": [
              {
                "maxLength": 4000,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Summary"
          },
          "tags": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Tags"
          },
          "title": {
            "anyOf": [
              {
                "maxLength": 512,
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Title"
          }
        },
        "title": "UpdateKnowledgeRequest",
        "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"
      },
      "VersionInfo": {
        "description": "Identity of the running service instance.",
        "properties": {
          "answer_fallback_model": {
            "description": "Secondary model used when the primary errors out. Empty disables the fallback.",
            "examples": [
              "openai:gpt-4o"
            ],
            "title": "Answer Fallback Model",
            "type": "string"
          },
          "answer_model": {
            "description": "Provider + model used by the RAG answerer.",
            "examples": [
              "anthropic:claude-sonnet-4-6"
            ],
            "title": "Answer Model",
            "type": "string"
          },
          "eda_adapter": {
            "description": "Event-driven adapter backing the lifecycle topics.",
            "examples": [
              "postgres",
              "redis",
              "kafka"
            ],
            "title": "Eda Adapter",
            "type": "string"
          },
          "embedding_model": {
            "description": "Provider + model used to embed every chunk.",
            "examples": [
              "openai:text-embedding-3-small"
            ],
            "title": "Embedding Model",
            "type": "string"
          },
          "service": {
            "description": "Service slug.",
            "examples": [
              "flycanon"
            ],
            "title": "Service",
            "type": "string"
          },
          "vector_store": {
            "description": "Backend used for vector search.",
            "examples": [
              "sqlite-vec",
              "pgvector"
            ],
            "title": "Vector Store",
            "type": "string"
          },
          "version": {
            "description": "CalVer (``YY.MM.PP``) baked into the wheel at build time. PEP 440 normalises ``26.05.01`` -> ``26.5.1`` so the value you see here uses the stripped form.",
            "examples": [
              "26.6.19"
            ],
            "title": "Version",
            "type": "string"
          }
        },
        "required": [
          "service",
          "version",
          "embedding_model",
          "answer_model",
          "answer_fallback_model",
          "vector_store",
          "eda_adapter"
        ],
        "title": "VersionInfo",
        "type": "object"
      },
      "WorkspaceCreate": {
        "description": "Request body for ``POST /api/v1/workspaces``.",
        "properties": {
          "id": {
            "maxLength": 64,
            "minLength": 1,
            "title": "Id",
            "type": "string"
          },
          "jurisdiction": {
            "anyOf": [
              {
                "maxLength": 64,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Jurisdiction"
          },
          "name": {
            "maxLength": 255,
            "minLength": 1,
            "title": "Name",
            "type": "string"
          },
          "retention_days": {
            "anyOf": [
              {
                "minimum": 1,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Retention Days"
          },
          "scope": {
            "anyOf": [
              {
                "items": {},
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Scope"
          },
          "sme_roster": {
            "anyOf": [
              {
                "items": {},
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sme Roster"
          },
          "status": {
            "$ref": "#/components/schemas/WorkspaceStatus",
            "default": "active"
          }
        },
        "required": [
          "id",
          "name"
        ],
        "title": "WorkspaceCreate",
        "type": "object"
      },
      "WorkspacePurgeResult": {
        "description": "Wire shape of ``POST /api/v1/workspaces/{workspace_id}:purge``.\n\nEvery counter is the number of rows (or objects) erased by THIS\ncall; a repeated purge reports zeros. ``originals_deleted`` counts\nobjects the removal actually found and deleted in the object\nstore, not rows that carried a key. ``closed`` is ``True`` only when\nTHIS call moved the ``canon_workspaces`` row to ``closed``; it is\n``False`` on a repeat (the row was already closed) and when no row\nexisted for the id -- an implicit workspace that only ever held\ndata -- in which case the data was still purged. A call that erased\nnothing and closed nothing publishes no event and writes no audit\nrow. Audit rows are never counted because they are never deleted.",
        "properties": {
          "candidates_removed": {
            "minimum": 0,
            "title": "Candidates Removed",
            "type": "integer"
          },
          "chunks_removed": {
            "minimum": 0,
            "title": "Chunks Removed",
            "type": "integer"
          },
          "citations_removed": {
            "minimum": 0,
            "title": "Citations Removed",
            "type": "integer"
          },
          "closed": {
            "description": "Whether THIS call moved the workspace row to ``closed`` (false on a repeat).",
            "title": "Closed",
            "type": "boolean"
          },
          "conversation_turns_removed": {
            "minimum": 0,
            "title": "Conversation Turns Removed",
            "type": "integer"
          },
          "conversations_removed": {
            "minimum": 0,
            "title": "Conversations Removed",
            "type": "integer"
          },
          "cost_events_removed": {
            "minimum": 0,
            "title": "Cost Events Removed",
            "type": "integer"
          },
          "ingest_job_events_removed": {
            "minimum": 0,
            "title": "Ingest Job Events Removed",
            "type": "integer"
          },
          "ingest_jobs_removed": {
            "minimum": 0,
            "title": "Ingest Jobs Removed",
            "type": "integer"
          },
          "knowledge_items_removed": {
            "minimum": 0,
            "title": "Knowledge Items Removed",
            "type": "integer"
          },
          "knowledge_relations_removed": {
            "minimum": 0,
            "title": "Knowledge Relations Removed",
            "type": "integer"
          },
          "knowledge_versions_removed": {
            "minimum": 0,
            "title": "Knowledge Versions Removed",
            "type": "integer"
          },
          "originals_deleted": {
            "description": "Stored originals actually found and removed from the object store by this call.",
            "minimum": 0,
            "title": "Originals Deleted",
            "type": "integer"
          },
          "sources_removed": {
            "minimum": 0,
            "title": "Sources Removed",
            "type": "integer"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          },
          "workspace_id": {
            "title": "Workspace Id",
            "type": "string"
          }
        },
        "required": [
          "tenant_id",
          "workspace_id",
          "sources_removed",
          "originals_deleted",
          "chunks_removed",
          "knowledge_items_removed",
          "knowledge_versions_removed",
          "citations_removed",
          "knowledge_relations_removed",
          "candidates_removed",
          "conversations_removed",
          "conversation_turns_removed",
          "ingest_jobs_removed",
          "ingest_job_events_removed",
          "cost_events_removed",
          "closed"
        ],
        "title": "WorkspacePurgeResult",
        "type": "object"
      },
      "WorkspaceSpec": {
        "description": "The canonical Workspace shape returned by GET / referenced by other DTOs.",
        "properties": {
          "closed_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Closed At"
          },
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "jurisdiction": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Jurisdiction"
          },
          "name": {
            "title": "Name",
            "type": "string"
          },
          "retention_days": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Retention Days"
          },
          "scope": {
            "anyOf": [
              {
                "items": {},
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Scope"
          },
          "sme_roster": {
            "anyOf": [
              {
                "items": {},
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sme Roster"
          },
          "status": {
            "$ref": "#/components/schemas/WorkspaceStatus"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "name",
          "status",
          "created_at",
          "updated_at"
        ],
        "title": "WorkspaceSpec",
        "type": "object"
      },
      "WorkspaceStatus": {
        "enum": [
          "draft",
          "active",
          "closed",
          "handed_off"
        ],
        "title": "WorkspaceStatus",
        "type": "string"
      },
      "WorkspaceSummary": {
        "description": "Compact list-row shape -- omits scope + sme_roster details.",
        "properties": {
          "closed_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Closed At"
          },
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "jurisdiction": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Jurisdiction"
          },
          "name": {
            "title": "Name",
            "type": "string"
          },
          "retention_days": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Retention Days"
          },
          "status": {
            "$ref": "#/components/schemas/WorkspaceStatus"
          },
          "tenant_id": {
            "title": "Tenant Id",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "name",
          "status",
          "created_at",
          "updated_at"
        ],
        "title": "WorkspaceSummary",
        "type": "object"
      },
      "WorkspaceUpdate": {
        "description": "Request body for ``PATCH /api/v1/workspaces/{id}``.\n\nEvery field is optional; only fields present in the payload are\napplied.",
        "properties": {
          "jurisdiction": {
            "anyOf": [
              {
                "maxLength": 64,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Jurisdiction"
          },
          "name": {
            "anyOf": [
              {
                "maxLength": 255,
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Name"
          },
          "retention_days": {
            "anyOf": [
              {
                "minimum": 1,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Retention Days"
          },
          "scope": {
            "anyOf": [
              {
                "items": {},
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Scope"
          },
          "sme_roster": {
            "anyOf": [
              {
                "items": {},
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sme Roster"
          },
          "status": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/WorkspaceStatus"
              },
              {
                "type": "null"
              }
            ],
            "default": null
          }
        },
        "title": "WorkspaceUpdate",
        "type": "object"
      }
    },
    "securitySchemes": {
      "AgentToken": {
        "description": "Tenant-scoped agent token (``agt_<8hex>_<32hex>``) minted by ``POST /api/v1/agent-tokens``. The credential of the ``/api/v1/agent/*`` tier: verified per request against the tenant in ``X-Tenant-Id``, the workspace allowlist and the route scope. It is the only credential that satisfies an agent-tier operation: the platform key is neither required nor accepted in its place (a platform-key-only call to ``/api/v1/agent/*`` fails with ``401 missing_agent_token``).",
        "in": "header",
        "name": "X-Agent-Token",
        "type": "apiKey"
      },
      "ApiKeyAuthorization": {
        "description": "The same platform key carried as ``Authorization: ApiKey <key>`` for clients that can only set the Authorization header. ``X-API-Key`` wins when both are present.",
        "scheme": "ApiKey",
        "type": "http"
      },
      "ApiKeyHeader": {
        "description": "Platform API key from ``FLYCANON_API_KEYS``. Required on every ``/api/v1/*`` route (except ``GET /api/v1/version``) and on the admin dashboard whenever at least one key is configured; when the setting is empty the user tier is open and the header is ignored. Missing -> ``401 missing_api_key``; unknown -> ``401 invalid_api_key``.",
        "in": "header",
        "name": "X-API-Key",
        "type": "apiKey"
      }
    }
  },
  "info": {
    "contact": {
      "name": "Firefly OperationOS",
      "url": "https://github.com/firefly-operationOS/flycanon"
    },
    "description": "Operational Knowledge Repository -- versioned, provenance-tracked canonical knowledge with hybrid retrieval (BM25 + vector + RRF) and retrieval-augmented answering, exposed as a standalone HTTP microservice over fireflyframework-pyfly and -agentic. Part of Firefly OperationOS, platform-agnostic by design.",
    "license": {
      "name": "Apache-2.0",
      "url": "https://github.com/firefly-operationOS/flycanon/blob/main/LICENSE"
    },
    "title": "flycanon",
    "version": "26.10.0"
  },
  "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/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/AgentTokenSummaryDto"
                  },
                  "type": "array"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "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/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "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": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "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/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "responses": {
          "204": {
            "description": "No Content"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Revoke a token. Idempotent -- already-revoked is a no-op (204).",
        "tags": [
          "AgentTokens"
        ]
      }
    },
    "/api/v1/agent/candidates:propose": {
      "post": {
        "description": "Scope: ``agent.candidates:propose``. Mandatory\n``Idempotency-Key`` header -- missing key returns\n``400 missing_idempotency_key``. Wire shape and 4xx\nmapping mirror the user-tier\n``POST /api/v1/candidates:propose`` byte-for-byte.\n\nA replayed POST (same ``Idempotency-Key`` + same tenant\nwithin the store TTL) returns the cached candidate list\nre-hydrated from the stored JSON body, without re-running\nthe consolidator. This is critical for the flyradar\nhandoff path: a retried discovery must not produce\nduplicate candidate rows in the canon.",
        "operationId": "propose",
        "parameters": [
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProposeCandidateRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/CandidateRecord"
                  },
                  "type": "array"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Propose candidates from an existing source (agent tier).",
        "tags": [
          "AgentCandidates"
        ]
      }
    },
    "/api/v1/agent/knowledge/{item_id}": {
      "get": {
        "description": "Scope: ``agent.knowledge:read``. Returns the pointer view\n(current version metadata), not the version body. Unknown\n``item_id`` (or any id outside the verified ctx's\nworkspace) returns ``404 resource_not_found``.",
        "operationId": "get_knowledge",
        "parameters": [
          {
            "in": "path",
            "name": "item_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KnowledgeItem"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Fetch a single knowledge item by id (agent tier).",
        "tags": [
          "AgentKnowledge"
        ]
      }
    },
    "/api/v1/agent/knowledge/{item_id}/provenance": {
      "get": {
        "description": "Scope: ``agent.knowledge:read``. ``version=0`` (or missing)\nresolves to the current version, matching the user-tier\nsurface. Unknown ``item_id`` returns\n``404 resource_not_found``; unknown ``version`` returns\n``404 knowledge_version_not_found``.",
        "operationId": "get_provenance",
        "parameters": [
          {
            "in": "path",
            "name": "item_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "version",
            "required": false,
            "schema": {
              "default": 0,
              "type": "integer"
            }
          },
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Provenance"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Resolve the citation graph for ``(item_id, version)``.",
        "tags": [
          "AgentKnowledge"
        ]
      }
    },
    "/api/v1/agent/query": {
      "post": {
        "description": "Scope: ``agent.query:run``. Mandatory ``Idempotency-Key``.\nIdentical wire shape to the user-tier\n``POST /api/v1/query`` -- the only differences are the\nauth gate and the required idempotency key.\n\nA replayed POST (same ``Idempotency-Key`` + same tenant\nwithin the store TTL) returns the cached\n:class:`AnswerResponse` re-hydrated from the stored JSON\nbody, without re-running retrieval + the LLM call.",
        "operationId": "answer",
        "parameters": [
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AnswerRequest"
              }
            }
          },
          "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": "Grounded RAG answer with explicit citations (agent tier).",
        "tags": [
          "AgentQuery"
        ]
      }
    },
    "/api/v1/agent/query/stream": {
      "post": {
        "description": "Scope: ``agent.query:run``. Mandatory ``Idempotency-Key``.\nWire format matches the user-tier\n``POST /api/v1/query/stream`` byte-for-byte and is routed\nthrough the same :class:`AnswerDispatcher`:\n\n* RAG mode -- ``event: hit`` per retrieved citation, then\n``event: final`` with the full answer.\n* RLM mode (default) -- one ``event: status`` (``reasoning``)\nframe per REPL turn, then ``event: final``.\n\nThe generator mirrors the user-tier\niterator. Token verification + idempotency-header check\nhappen synchronously before the streaming response is\nreturned, so authentication failures surface as a normal\n4xx response (not as an in-stream ``error`` frame).\n\nReplay dedup is **intentionally skipped** for the SSE\nendpoint -- streaming responses cannot be replayed\ndeterministically (frame ordering, hit ranking, and LLM\nnon-determinism would all need to be captured), and the\nclient is expected to handle a partial stream by reading\nthe terminal ``final`` / ``error`` frame. Only the\n``Idempotency-Key`` header *presence* is enforced; no\nstore interaction occurs.",
        "operationId": "stream_answer",
        "parameters": [
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AnswerRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "SSE answer stream (agent tier).",
        "tags": [
          "AgentQuery"
        ]
      }
    },
    "/api/v1/agent/search": {
      "post": {
        "description": "Scope: ``agent.query:run``. Mandatory ``Idempotency-Key``.\nIdentical wire shape to the user-tier\n``POST /api/v1/search`` -- no LLM call, just BM25 + dense\nretrieval fused via RRF.\n\nReplays under the same ``(tenant, scope, key)`` triple are\ncached for the store TTL -- the retrieval pipeline is not\nre-run. The replay-dedup ``scope`` is the route-specific\n``agent.search:run`` so a key reused on ``/query`` and\n``/search`` does **not** collide, even though both routes\nshare the same auth scope ``agent.query:run``.",
        "operationId": "search",
        "parameters": [
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Hybrid retrieval over the canon corpus (agent tier).",
        "tags": [
          "AgentQuery"
        ]
      }
    },
    "/api/v1/agent/sources": {
      "post": {
        "description": "Scope: ``agent.sources:ingest``. Mandatory\n``Idempotency-Key`` header -- missing key returns\n``400 missing_idempotency_key``. Always synchronous: the\nagent surface deliberately omits the user-tier\n``mode=async`` / ``callback_url`` toggles to keep the\ncontract minimal. Wire shape and 4xx mapping mirror the\nuser-tier ``POST /api/v1/sources`` byte-for-byte.\n\nA replayed POST (same ``Idempotency-Key`` + same tenant\nwithin the store TTL) short-circuits the command bus and\nreturns the cached :class:`SourceRecord` re-hydrated from\nthe stored JSON body. The wire response is identical to\nthe original ``201`` so flyradar's canon handoff can retry\nsafely without creating duplicate sources.",
        "operationId": "submit",
        "parameters": [
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubmitSourceJsonPayload"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SourceRecord"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Submit a source for intake (agent tier).",
        "tags": [
          "AgentSources"
        ]
      }
    },
    "/api/v1/agent/sources/{source_id}": {
      "delete": {
        "description": "Scope: ``agent.sources:ingest``. Mandatory\n``Idempotency-Key`` header -- missing key returns\n``400 missing_idempotency_key``. Dispatches\n:class:`RemoveSourceCommand` -> ``IntakeService.remove``:\nthe BM25 rows + dense vectors are purged, the chunk rows are\ndeleted, the stored original is removed from the object store\n(since 26.7.1 -- before that an \"erased\" document stayed\nreadable by the RLM corpus), and the source row is removed\nwithin the verified tenant/workspace scope. Unknown ids return\n``404 source_not_found``.\n\nReplays dedup under the route-specific\n``agent.sources:delete`` scope: a retried DELETE with the\nsame key returns the original ``204`` without re-dispatching\n(so a retry after a successful delete does not surface a\nspurious 404).",
        "operationId": "remove",
        "parameters": [
          {
            "in": "path",
            "name": "source_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "204": {
            "description": "No Content"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Remove a source and its indexed projections (agent tier).",
        "tags": [
          "AgentSources"
        ]
      },
      "get": {
        "description": "Scope: ``agent.sources:read``. Unknown ``source_id`` (or\nany id outside the verified ctx's workspace) returns\n``404 resource_not_found`` -- the agent gate validates the\ntoken can speak for ``(tenant, workspace)``, and the\nquery handler's scope filter completes the chain so a\ntoken with a multi-workspace allowlist cannot read sources\nfrom a workspace other than the one in the header.",
        "operationId": "get_source",
        "parameters": [
          {
            "in": "path",
            "name": "source_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SourceRecord"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Read a single source record (agent tier).",
        "tags": [
          "AgentSources"
        ]
      },
      "put": {
        "description": "Scope: ``agent.sources:ingest``. Mandatory\n``Idempotency-Key`` header -- missing key returns\n``400 missing_idempotency_key``. Delegates to the same\n:class:`ReplaceSourceCommand` -> ``IntakeService.replace``\npath as the user-tier ``PUT /api/v1/sources/{source_id}``:\nthe pipeline re-runs against the new bytes and the chunks +\nvectors are replaced under the same ``source_id``.\n``content_base64`` is required -- URL-fetched re-ingestion\nis not supported, mirroring the user-tier PUT. Unknown ids\n(or ids outside the verified tenant/workspace scope) return\n``404 source_not_found``.\n\nReplays dedup under the route-specific\n``agent.sources:replace`` scope so a key reused across the\nPOST and the PUT cannot collide; the cached ``200`` body is\nreturned without re-dispatching the command.",
        "operationId": "replace",
        "parameters": [
          {
            "in": "path",
            "name": "source_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubmitSourceJsonPayload"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SourceRecord"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "AgentToken": []
          }
        ],
        "summary": "Replace an existing source in place (agent tier).",
        "tags": [
          "AgentSources"
        ]
      }
    },
    "/api/v1/audit": {
      "get": {
        "description": "Scope is fixed to the (tenant, workspace) carried by the\nrequest headers; cross-scope audit views are out of v1.",
        "operationId": "list_audit",
        "parameters": [
          {
            "in": "query",
            "name": "subject_id",
            "required": false,
            "schema": {
              "default": "",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "subject_kind",
            "required": false,
            "schema": {
              "default": "",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "event_type",
            "required": false,
            "schema": {
              "default": "",
              "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/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditPage"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Paginated audit-log view -- filters compose with AND.",
        "tags": [
          "Audit"
        ]
      }
    },
    "/api/v1/billing": {
      "get": {
        "description": "Scope is fixed to the (tenant, workspace) carried by the\nrequest headers; cross-scope rollups are out of v1.\n\nQuery params:\n\n* ``group_by`` -- comma-separated columns. Allowed:\n``date`` / ``model`` / ``agent_name``.\n* ``since`` / ``until`` -- ISO-8601 timestamps to bound\nthe window.\n\nResponse: :class:`BillingReport` with per-group rows plus\nthe overall ``total_cost_usd`` + ``total_calls`` for the\nsame filter window.",
        "operationId": "report",
        "parameters": [
          {
            "in": "query",
            "name": "group_by",
            "required": false,
            "schema": {
              "default": "date,model",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "since",
            "required": false,
            "schema": {
              "default": "",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "until",
            "required": false,
            "schema": {
              "default": "",
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillingReport"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Aggregated cost report.",
        "tags": [
          "Billing"
        ]
      }
    },
    "/api/v1/billing/by-subject": {
      "get": {
        "description": "Useful for answering \"how much did indexing source X cost?\"\nCaller-side instrumentation must populate ``subject_kind`` /\n``subject_id`` when recording the cost event; rows without a\nsubject are excluded from this report.",
        "operationId": "by_subject",
        "parameters": [
          {
            "in": "query",
            "name": "subject_kind",
            "required": false,
            "schema": {
              "default": "",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "since",
            "required": false,
            "schema": {
              "default": "",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "until",
            "required": false,
            "schema": {
              "default": "",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 20,
              "type": "integer"
            }
          },
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubjectCostReport"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Cost attribution per ``(subject_kind, subject_id)``.",
        "tags": [
          "Billing"
        ]
      }
    },
    "/api/v1/billing/events": {
      "get": {
        "description": "The aggregator hides the call-level breadcrumbs (correlation\nid, subject id, latency, actor). This endpoint surfaces them\nso an on-call engineer triaging \"why did our spend spike at\n14:32?\" can pivot from the aggregate row into the underlying\ncall list. ``actor`` is retained as audit metadata on each\nrow, but is no longer a scope filter.",
        "operationId": "list_events",
        "parameters": [
          {
            "in": "query",
            "name": "agent_name",
            "required": false,
            "schema": {
              "default": "",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "since",
            "required": false,
            "schema": {
              "default": "",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "until",
            "required": false,
            "schema": {
              "default": "",
              "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/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CostEventsPage"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Per-call drill-down view.",
        "tags": [
          "Billing"
        ]
      }
    },
    "/api/v1/billing/latency": {
      "get": {
        "description": "Pulled from the same ``canon_cost_events`` stream: each row's\n``latency_ms`` is captured at record time alongside cost. The\ncomputation runs in Python so the SQL backend doesn't need\n``percentile_cont`` (kept dialect-agnostic for the SQLite\ntest path).",
        "operationId": "latency",
        "parameters": [
          {
            "in": "query",
            "name": "group_by",
            "required": false,
            "schema": {
              "default": "model",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "since",
            "required": false,
            "schema": {
              "default": "",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "until",
            "required": false,
            "schema": {
              "default": "",
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LatencyReport"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Latency percentiles -- p50 / p95 / p99 -- per group bucket.",
        "tags": [
          "Billing"
        ]
      }
    },
    "/api/v1/billing/summary": {
      "get": {
        "description": "Three windows -- ``last_24h``, ``last_7d``, ``last_30d`` --\nare always populated. The top model inside each window lands\nin the same envelope so a dashboard can render a single\nbanner without a follow-up query.",
        "operationId": "summary",
        "parameters": [
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillingSummary"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Rolling-window cost snapshot.",
        "tags": [
          "Billing"
        ]
      }
    },
    "/api/v1/billing/top": {
      "get": {
        "description": "``dimension`` is one of ``model`` / ``agent_name``. The\nhandler returns the highest-cost ``limit`` rows for the\nprovided window, scoped to the request headers.",
        "operationId": "top",
        "parameters": [
          {
            "in": "query",
            "name": "dimension",
            "required": false,
            "schema": {
              "default": "model",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "since",
            "required": false,
            "schema": {
              "default": "",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "until",
            "required": false,
            "schema": {
              "default": "",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 10,
              "type": "integer"
            }
          },
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TopConsumersReport"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Top-N consumers by cost on a single dimension.",
        "tags": [
          "Billing"
        ]
      }
    },
    "/api/v1/candidates": {
      "get": {
        "operationId": "list_candidates",
        "parameters": [
          {
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "default": "",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "source_id",
            "required": false,
            "schema": {
              "default": "",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "domain",
            "required": false,
            "schema": {
              "default": "",
              "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/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CandidatesPage"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "tags": [
          "Candidates"
        ]
      }
    },
    "/api/v1/candidates/{candidate_id}": {
      "get": {
        "operationId": "get_candidate",
        "parameters": [
          {
            "in": "path",
            "name": "candidate_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CandidateRecord"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "tags": [
          "Candidates"
        ]
      }
    },
    "/api/v1/candidates/{candidate_id}:accept": {
      "post": {
        "operationId": "accept",
        "parameters": [
          {
            "in": "path",
            "name": "candidate_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AcceptCandidateRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CandidateRecord"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Materialise the candidate as a knowledge version.",
        "tags": [
          "Candidates"
        ]
      }
    },
    "/api/v1/candidates/{candidate_id}:reject": {
      "post": {
        "operationId": "reject",
        "parameters": [
          {
            "in": "path",
            "name": "candidate_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RejectCandidateRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CandidateRecord"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "tags": [
          "Candidates"
        ]
      }
    },
    "/api/v1/candidates:propose": {
      "post": {
        "operationId": "propose",
        "parameters": [
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProposeCandidateRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/CandidateRecord"
                  },
                  "type": "array"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Run the consolidation stage against a source and persist",
        "tags": [
          "Candidates"
        ]
      }
    },
    "/api/v1/conversations": {
      "post": {
        "operationId": "create_conversation",
        "parameters": [
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateConversationRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Conversation"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Open a fresh conversation -- returns the empty session.",
        "tags": [
          "Conversations"
        ]
      }
    },
    "/api/v1/conversations/{conversation_id}": {
      "get": {
        "description": "The service-layer ``get`` requires ``(tenant_id,\nworkspace_id)``; a same-tenant cross-workspace lookup raises\n:class:`ConversationNotFound` (404) rather than returning the\nforeign row.",
        "operationId": "get_conversation",
        "parameters": [
          {
            "in": "path",
            "name": "conversation_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Conversation"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Return the full session + turn history.",
        "tags": [
          "Conversations"
        ]
      }
    },
    "/api/v1/conversations/{conversation_id}/turn": {
      "post": {
        "operationId": "append_turn",
        "parameters": [
          {
            "in": "path",
            "name": "conversation_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateTurnRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TurnResponse"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Run the next turn and return the answer + citations.",
        "tags": [
          "Conversations"
        ]
      }
    },
    "/api/v1/ingest-jobs": {
      "get": {
        "operationId": "list_jobs",
        "parameters": [
          {
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "default": "",
              "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/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IngestJobsPage"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Paginated listing of async ingest jobs.",
        "tags": [
          "Jobs"
        ]
      }
    },
    "/api/v1/ingest-jobs/{job_id}": {
      "get": {
        "operationId": "get_job",
        "parameters": [
          {
            "in": "path",
            "name": "job_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IngestJob"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Single-shot lookup. Polling target for callers that",
        "tags": [
          "Jobs"
        ]
      }
    },
    "/api/v1/ingest-jobs/{job_id}/stream": {
      "get": {
        "description": "Each ``event`` frame carries ``id:`` + ``data:``; ``status``\nframes carry ``data:`` only. The stream closes when the job\nreaches a terminal state. Implementation polls the\n``canon_ingest_job_events`` table (cursor = max event id\nseen) and the ``canon_ingest_jobs.status`` column at\n``poll_interval_ms`` cadence -- this avoids holding a\nlong-lived DB connection per stream and works under\npgbouncer transaction-mode pooling.\n\nResume: ``after_id`` (query) or ``Last-Event-ID`` (header)\nseeds the cursor so a reconnect replays only events with a\ngreater id. Without it the cursor started at ``None`` and every\nreconnect replayed the whole history, which is what\n``docs/api-reference.md`` promised ``after_id`` would prevent\nlong before the parameter existed (26.7.1 closes that gap). The\nquery parameter wins when both are present; a value of ``0``\n(the default) means \"from the beginning\".",
        "operationId": "stream_job",
        "parameters": [
          {
            "in": "path",
            "name": "job_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "poll_interval_ms",
            "required": false,
            "schema": {
              "default": 500,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "after_id",
            "required": false,
            "schema": {
              "default": 0,
              "type": "integer"
            }
          },
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "SSE stream of progress events.",
        "tags": [
          "Jobs"
        ]
      }
    },
    "/api/v1/knowledge": {
      "get": {
        "operationId": "list_knowledge",
        "parameters": [
          {
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "default": "",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "domain",
            "required": false,
            "schema": {
              "default": "",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "jurisdiction",
            "required": false,
            "schema": {
              "default": "",
              "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/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KnowledgeItemsPage"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Paginated, filterable list of knowledge items.",
        "tags": [
          "Knowledge"
        ]
      },
      "post": {
        "operationId": "create_knowledge",
        "parameters": [
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateKnowledgeRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KnowledgeVersion"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Create a fresh knowledge item + version=1.",
        "tags": [
          "Knowledge"
        ]
      }
    },
    "/api/v1/knowledge/{item_id}": {
      "get": {
        "operationId": "get_knowledge",
        "parameters": [
          {
            "in": "path",
            "name": "item_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KnowledgeItem"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Fetch a single knowledge item by id (returns the pointer",
        "tags": [
          "Knowledge"
        ]
      },
      "put": {
        "operationId": "update_knowledge",
        "parameters": [
          {
            "in": "path",
            "name": "item_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateKnowledgeRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KnowledgeVersion"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Append a new version to the item (the previous version",
        "tags": [
          "Knowledge"
        ]
      }
    },
    "/api/v1/knowledge/{item_id}/diff": {
      "get": {
        "description": "``from_version`` / ``to_version`` are 1-based and both\nrequired. Returns a structured diff: unified-diff body,\nscalar field changes (title / summary / domain /\njurisdiction / status / tags), and citation set deltas\n(added / removed).\n\nErrors:\n\n* ``400`` -- either query param is 0 / missing.\n* ``404 knowledge_item_not_found`` -- item id is unknown.\n* ``404 knowledge_version_not_found`` -- one of the\nrequested versions doesn't exist.",
        "operationId": "get_diff",
        "parameters": [
          {
            "in": "path",
            "name": "item_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "from_version",
            "required": false,
            "schema": {
              "default": 0,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "to_version",
            "required": false,
            "schema": {
              "default": 0,
              "type": "integer"
            }
          },
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KnowledgeVersionDiff"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Diff two versions of a knowledge item.",
        "tags": [
          "Knowledge"
        ]
      }
    },
    "/api/v1/knowledge/{item_id}/history": {
      "get": {
        "operationId": "get_history",
        "parameters": [
          {
            "in": "path",
            "name": "item_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/KnowledgeVersion"
                  },
                  "type": "array"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Full version history (oldest first).",
        "tags": [
          "Knowledge"
        ]
      }
    },
    "/api/v1/knowledge/{item_id}/provenance": {
      "get": {
        "operationId": "get_provenance",
        "parameters": [
          {
            "in": "path",
            "name": "item_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "version",
            "required": false,
            "schema": {
              "default": 0,
              "type": "integer"
            }
          },
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Provenance"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Resolve the citation graph for ``(item_id, version)``.",
        "tags": [
          "Knowledge"
        ]
      }
    },
    "/api/v1/knowledge/{item_id}/relations": {
      "get": {
        "description": "The response splits by direction so a UI can render\n``Depends on`` and ``Required by`` sections without\nfiltering client-side.",
        "operationId": "list_relations",
        "parameters": [
          {
            "in": "path",
            "name": "item_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KnowledgeRelations"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Outgoing + incoming relations for ``{item_id}``.",
        "tags": [
          "Knowledge"
        ]
      },
      "post": {
        "description": "``kind`` is one of ``related`` / ``depends_on`` /\n``conflicts_with`` / ``replaces``. ``(from, to, kind)`` is\nunique -- re-asserting the same edge returns ``409\nrelation_already_exists``.",
        "operationId": "add_relation",
        "parameters": [
          {
            "in": "path",
            "name": "item_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateRelationRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KnowledgeRelation"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Attach a typed relation rooted at ``{item_id}``.",
        "tags": [
          "Knowledge"
        ]
      }
    },
    "/api/v1/knowledge/{item_id}/relations/{relation_id}": {
      "delete": {
        "operationId": "remove_relation",
        "parameters": [
          {
            "in": "path",
            "name": "item_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "relation_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "responses": {
          "204": {
            "description": "No Content"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Drop one relation by id.",
        "tags": [
          "Knowledge"
        ]
      }
    },
    "/api/v1/knowledge/{item_id}:retire": {
      "post": {
        "operationId": "retire_knowledge",
        "parameters": [
          {
            "in": "path",
            "name": "item_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RetireKnowledgeRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KnowledgeItem"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Withdraw the item permanently.",
        "tags": [
          "Knowledge"
        ]
      }
    },
    "/api/v1/knowledge/{item_id}:supersede": {
      "post": {
        "operationId": "supersede_knowledge",
        "parameters": [
          {
            "in": "path",
            "name": "item_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SupersedeKnowledgeRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KnowledgeItem"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Point the whole item at another canonical item.",
        "tags": [
          "Knowledge"
        ]
      }
    },
    "/api/v1/knowledge:detect-conflicts": {
      "post": {
        "description": "Confirmed conflicts land as ``CandidateRow``s with\n``metadata.kind=conflict_detection`` so the inbox UI's\nexisting candidate queue surfaces them alongside ordinary\nproposals.",
        "operationId": "detect_conflicts",
        "parameters": [
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConflictScanRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConflictScanResponse"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Run the conflict-detection pass and queue any contradictions.",
        "tags": [
          "KnowledgeQuality"
        ]
      }
    },
    "/api/v1/knowledge:graph": {
      "get": {
        "description": "Query params:\n\n* ``format`` -- ``json`` (default) or ``mermaid``.\n* ``domain`` / ``jurisdiction`` / ``status`` -- comma-\nseparated filter lists narrowing the rendered set.\n* ``include_sources`` -- when true, ``canon_sources`` cited\nby at least one rendered item are added as nodes with\n``cites`` edges linking them to the citing item.\n* ``limit`` -- caps the number of knowledge items rendered\n(graph builds dominated by the citation join scale\nlinearly with this).\n\nReturns either:\n\n* :class:`KnowledgeGraph` with flat ``nodes`` + ``edges``\narrays consumable by D3 / Cytoscape / react-flow.\n* :class:`MermaidGraph` carrying a ``graph LR`` Mermaid\nblock ready to drop in a Markdown viewer.",
        "operationId": "get_graph",
        "parameters": [
          {
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "default": "json",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "domain",
            "required": false,
            "schema": {
              "default": "",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "jurisdiction",
            "required": false,
            "schema": {
              "default": "",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "default": "",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "include_sources",
            "required": false,
            "schema": {
              "default": "true",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 500,
              "type": "integer"
            }
          },
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Render the knowledge graph.",
        "tags": [
          "KnowledgeGraph"
        ]
      }
    },
    "/api/v1/knowledge:stale": {
      "get": {
        "description": "Score is on-demand + cached on\n``KnowledgeItemRow.metadata_json.staleness`` (6h TTL). First\ncall populates; subsequent calls within the TTL return the\ncached value.\n\n``score = 1 - max(cosine(version_body, recent_source))``.\nHigh = the canon disagrees with fresh sources.",
        "operationId": "stale_report",
        "parameters": [
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StaleReport"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Return staleness scores for every published knowledge item.",
        "tags": [
          "KnowledgeQuality"
        ]
      }
    },
    "/api/v1/query": {
      "post": {
        "description": "Pipeline:\n\n1. Hybrid retrieval (same as ``/search``) over the\nconfigured filters; pulls ``top_k`` candidates (default 8).\n\n2. Renders the ``answer.yaml`` prompt with the question +\nthe retrieved chunks + the optional ``instructions``\nsteering, and calls :class:`FireflyAgent` against the\nconfigured answer model (``FLYCANON_ANSWER_MODEL`` or the\nper-request ``model`` override).\n\n3. On primary-model failure the answerer falls through to\n``FLYCANON_ANSWER_FALLBACK_MODEL`` when configured. Both\nsteps are wrapped in a circuit breaker so transient\nfailures don't cascade.\n\n4. The model returns a structured :class:`AnswerOutput`\n(Pydantic) carrying the answer text + the chunk_ids it\nexplicitly relied on. The handler hydrates those ids\nback to full :class:`Hit` rows so the caller gets one\nround-trip.\n\nResponse semantics:\n\n* ``no_answer=true`` -- the retrieval did not contain\nenough evidence; the answer text explains what is\nmissing. Callers should NOT display the answer verbatim\nin a high-stakes UI; surface \"no canonical answer yet\"\ninstead.\n* ``no_answer=false`` -- the answer is grounded in the\n``citations`` list. The citations are a *subset* of the\nretrieval (only the chunks the model actually cited).\n\nScope is fixed to the (tenant, workspace) carried by the\nrequest headers; the :class:`RetrievalService` fails closed\non missing values.\n\nUse this surface when:\n\n* you want a final user-facing answer with citation badges,\n* you don't want to operate a separate LLM call from your\nbackend,\n* you're prototyping a chatbot or a copilot integration.",
        "operationId": "answer",
        "parameters": [
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AnswerRequest"
              }
            }
          },
          "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": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Grounded RAG answer with explicit citations.",
        "tags": [
          "Query"
        ]
      }
    },
    "/api/v1/query/stream": {
      "post": {
        "description": "Frames (RAG mode, ``FLYCANON_ANSWER_MODE=rag``):\n\n* ``event: hit`` -- one frame per retrieved citation\n(UI can render citation badges immediately).\n* ``event: final`` -- terminal frame with the full answer\n+ the cited subset + model + elapsed_ms + no_answer flag.\n\nFrames (RLM mode, the default):\n\n* ``event: status`` -- one ``reasoning`` frame per REPL turn\n(carrying the turn number + the latest document accessed);\nRLM has no pre-retrieval step so there are no ``hit`` frames.\n* ``event: final`` -- the same terminal frame shape.\n\nScope is fixed to the (tenant, workspace) carried by the\nrequest headers; the :class:`RetrievalService` fails closed\non missing values.",
        "operationId": "stream_answer",
        "parameters": [
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AnswerRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "SSE answer stream routed through the answer dispatcher.",
        "tags": [
          "QueryStream"
        ]
      }
    },
    "/api/v1/query/suggest": {
      "post": {
        "operationId": "suggest",
        "parameters": [
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SuggestRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuggestResponse"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Suggested follow-up questions for chat UI chips.",
        "tags": [
          "QueryStream"
        ]
      }
    },
    "/api/v1/search": {
      "post": {
        "description": "BM25 (Postgres ``tsvector`` + GIN on ``canon_chunks``) is fused\nwith dense-vector search (pgvector) via Reciprocal Rank\nFusion::\n\nscore(chunk) = sum_over_modalities( 1 / (k + rank) )\n\nwith ``k`` from ``FLYCANON_RETRIEVAL_RRF_K`` (default 60).\nThe vector half uses the embedding provider configured in\n``FLYCANON_EMBEDDING_MODEL``; the BM25 half uses the\n``tsvector``-indexed chunk content.\n\nFilters in the request body compose with ``AND`` and are\napplied *post-retrieval*; the retriever widens internally by\n3x (so ``top_k=10`` actually fetches 30 candidates) before\ntrimming, but heavy filtering may still starve the result\nset -- raise ``per_query_k`` if so.\n\nScope is fixed to the (tenant, workspace) carried by the\nrequest headers; the :class:`RetrievalService` fails closed\non missing values.\n\nUse this surface when:\n\n* you want to power your own answer / summarisation step,\n* you need the raw evidence (chunk content + citation\nmetadata) without the answer-stage cost,\n* you're building a \"show citations\" UI that lets the user\nread the source verbatim.\n\nReturns :class:`SearchResponse` (always 200). Empty result\nsets return ``hits=[]``.",
        "operationId": "search",
        "parameters": [
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Hybrid retrieval over the canon corpus.",
        "tags": [
          "Query"
        ]
      }
    },
    "/api/v1/sources": {
      "get": {
        "description": "Filters compose with ``AND``:\n\n* ``status`` -- comma-separated lifecycle states\n(``pending``, ``ingesting``, ``ingested``, ``failed``,\n``superseded``). Empty = any status.\n* ``kind`` -- comma-separated :class:`SourceKind` values.\nEmpty = any kind.\n\nOrdered ``created_at DESC`` (newest first). The compound\nindex ``ix_canon_sources_kind_status_created`` keeps the\nquery index-only.",
        "operationId": "list_sources",
        "parameters": [
          {
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "default": "",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "kind",
            "required": false,
            "schema": {
              "default": "",
              "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/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SourcesPage"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Paginated, filterable source list.",
        "tags": [
          "Sources"
        ]
      },
      "post": {
        "description": "The request body carries the canonical bytes encoded as\nbase64 (``content_base64``) plus the caller-supplied\nmetadata. The handler:\n\n1. Decodes the bytes and runs the binary normaliser. The\nnormaliser sniffs the media type from magic bytes, routes\nthrough the right adapter (image conversion, archive\nexpansion, email decomposition, optional Office -> PDF),\nand emits one or more loader-ready artifacts. Archive +\nemail intakes are concatenated into a single Markdown\ndocument with constituent section markers; the ancestry\nchain is preserved on ``metadata.artifacts`` so the audit\ntrail can reconstruct it.\n\n2. Hashes the canonical bytes (SHA-256) -- two uploads of\nthe same content share a :class:`SourceRecord`. The hash\nlands on ``content_sha256`` (also unique-indexed in\nPostgres).\n\n3. Loads through the per-format :class:`SourceLoader`\nregistered for the detected kind. Heading-aware loaders\npreserve the section path on every chunk.\n\n4. Chunks via :class:`ParagraphChunker` (paragraph-bounded,\ntoken-budgeted, soft overlap).\n\n5. Embeds every chunk through the configured provider\n(``FLYCANON_EMBEDDING_MODEL``).\n\n6. Indexes BM25 (Postgres ``tsvector`` + GIN on\n``canon_chunks``) + dense vectors (pgvector) keyed by\n``chunk_id``.\n\n7. Records an audit row and broadcasts ``SourceIngested`` on\n``flycanon.ingest``.\n\nReturns the populated :class:`SourceRecord` with ``201\nCreated`` on success. Failure modes (all RFC 7807):\n\n* ``415 unsupported_binary`` -- no normaliser route.\n* ``422 encrypted_pdf`` -- PDF is encrypted.\n* ``422 corrupt_pdf`` / ``corrupt_source`` -- parser failed.\n* ``422 empty_source`` -- loader produced no text.\n* ``413 binary_too_large`` -- exceeds ``FLYCANON_MAX_BYTES``.\n* ``422 binary_fanout_cap_exceeded`` -- archive / email\nexpansion exceeded ``FLYCANON_BINARY_MAX_EXPANDED_FILES``.\n\nEach failure persists a :class:`SourceRecord` with\n``status=failed`` and the typed ``error_code`` /\n``error_message`` so callers can inspect and re-submit.",
        "operationId": "submit_json",
        "parameters": [
          {
            "in": "query",
            "name": "mode",
            "required": false,
            "schema": {
              "default": "sync",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "callback_url",
            "required": false,
            "schema": {
              "default": "",
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubmitSourceJsonPayload"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Submit a source for intake.",
        "tags": [
          "Sources"
        ]
      }
    },
    "/api/v1/sources/{source_id}": {
      "delete": {
        "description": "The user-tier sibling of ``DELETE /api/v1/agent/sources/{id}``,\nadded in 26.7.1 because a control plane that provisions\nworkspaces and retention policies over the user tier had no way\nto delete a document without minting itself an agent token.\nDispatches the same :class:`RemoveSourceCommand`: BM25 rows and\ndense vectors are purged, chunk rows deleted, the original\nremoved from the object store (so an erased document is gone\nfrom the RLM corpus too, not only from search), the row\ndeleted, an audit row written and ``SourceRemoved`` published.\n\nUnknown ids -- including ids that exist in another workspace of\nthe same tenant -- return ``404 source_not_found``. The verb is\nnot idempotent on the wire (a second call is a 404); callers\nthat retry should treat 404 after a 204 as success.",
        "operationId": "remove_source",
        "parameters": [
          {
            "in": "path",
            "name": "source_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "responses": {
          "204": {
            "description": "No Content"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Remove a source, its indexed projections and its stored original.",
        "tags": [
          "Sources"
        ]
      },
      "get": {
        "description": "Returns the full :class:`SourceRecord`. The\n``content_sha256`` field doubles as the dedup anchor: two\n``SourceRecord`` rows with the same sha point at the same\ncanonical content.\n\nErrors:\n\n* ``404 source_not_found`` -- the id is unknown.",
        "operationId": "get_source",
        "parameters": [
          {
            "in": "path",
            "name": "source_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SourceRecord"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Fetch a single source by id.",
        "tags": [
          "Sources"
        ]
      },
      "put": {
        "description": "Use when the canonical file has been updated and you want\ndownstream citations to follow the new content rather than\norphan to a deleted row. The handler:\n\n1. Validates the existing ``SourceRow`` exists (returns\n404 ``source_not_found`` otherwise).\n2. Drops the existing chunks + vector projection for the\nrow (keeps the row id + audit history).\n3. Runs the same intake pipeline as :meth:`submit_json`\nagainst the new bytes.\n4. Emits a ``source.replaced`` audit event +\n``SourceReplaced`` EDA event so downstream projections\ncan re-sync.\n\nCitations pointing at chunks that disappear in the new\nemission raise a ``dangling_citation`` audit warning (per\ncitation) but do NOT block the replacement -- the audit\ntrail is the system of record for that case.",
        "operationId": "replace_source",
        "parameters": [
          {
            "in": "path",
            "name": "source_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubmitSourceJsonPayload"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SourceRecord"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Re-ingest an existing source under the same ``source_id``.",
        "tags": [
          "Sources"
        ]
      }
    },
    "/api/v1/sources:bulk": {
      "post": {
        "description": "Each entry runs through the same intake pipeline as\n:meth:`submit_json` (binary normaliser -> loader -> chunker\n-> embedder -> indexer -> audit + event). Entries are\nprocessed **sequentially** (we don't fan out internally so\nthe binary normaliser's caps remain meaningful per-entry),\nbut a failure on any entry never aborts the batch.\n\nReturns :class:`BulkSourcesResponse` with one\n:class:`BulkSourceResult` per input entry carrying the\noutcome:\n\n* ``status=succeeded`` -- ``source`` is populated.\n* ``status=failed`` -- ``error_code`` + ``error_message``\ncarry the typed failure reason (same codes as the\nsingle-source endpoint).\n\nThe HTTP status is **always 200** regardless of per-entry\noutcomes; clients inspect each result's ``status`` to\ndecide what to retry. The wire shape mirrors the AWS\nSQS / S3 batch-API convention so an SDK retry helper can\noperate on the result list directly.",
        "operationId": "submit_bulk",
        "parameters": [
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BulkSubmitSourcesPayload"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkSourcesResponse"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Submit up to 100 sources in one call.",
        "tags": [
          "Sources"
        ]
      }
    },
    "/api/v1/stats": {
      "get": {
        "operationId": "get",
        "parameters": [
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CorpusStats"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "tags": [
          "Stats"
        ]
      }
    },
    "/api/v1/taxonomy": {
      "get": {
        "operationId": "get_taxonomy",
        "parameters": [
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaxonomyTree"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Return the full taxonomy as a flat list ordered breadth-first.",
        "tags": [
          "Taxonomy"
        ]
      }
    },
    "/api/v1/taxonomy/nodes": {
      "post": {
        "operationId": "create_node",
        "parameters": [
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateTaxonomyNodeRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaxonomyNode"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Attach a new node to the tree.",
        "tags": [
          "Taxonomy"
        ]
      }
    },
    "/api/v1/version": {
      "get": {
        "description": "Response shape (:class:`VersionInfo`):\n\n* ``service`` -- always ``\"flycanon\"``.\n* ``version`` -- CalVer baked into the wheel (``YY.MM.PP``,\ne.g. ``\"26.5.1\"``).\n* ``embedding_model`` / ``answer_model`` /\n``answer_fallback_model`` -- ``<provider>:<model>``\nidentifiers read from :class:`CanonSettings`.\n* ``vector_store`` -- ``pgvector``.\n* ``eda_adapter`` -- one of ``postgres`` (default),\n``memory``, ``redis``, ``kafka``.",
        "operationId": "version",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VersionInfo"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "summary": "Return the service identity + provider selection.",
        "tags": [
          "Version"
        ]
      }
    },
    "/api/v1/workspaces": {
      "get": {
        "description": "Ordered ``created_at DESC`` (the repository's contract) so the\nmost-recently-opened workspaces surface first.",
        "operationId": "list_workspaces",
        "parameters": [
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/WorkspaceSummary"
                  },
                  "type": "array"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Return every workspace owned by the caller's tenant.",
        "tags": [
          "Workspaces"
        ]
      },
      "post": {
        "description": "The body carries the caller-chosen workspace id (slug,\n``<= 64`` chars). Tenant id comes from the ``X-Tenant-Id``\nheader -- the body intentionally does not accept it so a\ncaller cannot create workspaces under another tenant.\n\nReturns ``201 Created`` with the persisted :class:`WorkspaceSpec`.",
        "operationId": "create",
        "parameters": [
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WorkspaceCreate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkspaceSpec"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Create a workspace.",
        "tags": [
          "Workspaces"
        ]
      }
    },
    "/api/v1/workspaces/{workspace_id}": {
      "get": {
        "description": "Returns ``404 workspace_not_found`` when the\n``(tenant_id, workspace_id)`` pair does not exist -- the\nrepository's composite-key lookup guards against the\ncross-tenant leak where tenant A guesses tenant B's id.",
        "operationId": "get",
        "parameters": [
          {
            "in": "path",
            "name": "workspace_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkspaceSpec"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Fetch a single workspace by id within the caller's tenant.",
        "tags": [
          "Workspaces"
        ]
      },
      "patch": {
        "description": "Only fields present in the body (``exclude_unset=True``) are\napplied; everything else is preserved. The DTO field\n``scope`` writes to ``scope_json`` (and ditto for\n``sme_roster`` / ``sme_roster_json``) -- see\n:func:`_patch_to_columns`. ``updated_at`` is bumped by the\nrepository.\n\nReturns ``404 workspace_not_found`` when the row does not\nexist under the caller's tenant.",
        "operationId": "update",
        "parameters": [
          {
            "in": "path",
            "name": "workspace_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WorkspaceUpdate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkspaceSpec"
                }
              }
            },
            "description": "Successful response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Apply a sparse patch to a workspace row.",
        "tags": [
          "Workspaces"
        ]
      }
    },
    "/api/v1/workspaces/{workspace_id}:close": {
      "post": {
        "description": "Idempotent at the row level: closing an already-closed\nworkspace rewrites the same terminal state with a fresh\n``closed_at`` and returns the current row. Returns\n``404 workspace_not_found`` only when the row truly does\nnot exist.",
        "operationId": "close",
        "parameters": [
          {
            "in": "path",
            "name": "workspace_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkspaceSpec"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Close a workspace (status='closed' + closed_at=now()).",
        "tags": [
          "Workspaces"
        ]
      }
    },
    "/api/v1/workspaces/{workspace_id}:purge": {
      "post": {
        "description": "The destructive sibling of ``:close`` (which only flips the\nstatus). Every source is removed through the full pipeline --\ndense vectors, chunks, the stored original in the object store,\nthe row, an audit entry and a ``SourceRemoved`` event each --\nthen knowledge items with their versions, citations and\nrelations, candidates, conversations and turns, ingest jobs and\nevents, and cost events are deleted in one transaction, the\nworkspace row is moved to ``closed`` and a ``WorkspaceDeleted``\nevent is emitted. Audit rows are kept (the log is append-only)\nand a ``workspace.purged`` row records the counts.\n\n``X-Workspace-Id`` MUST equal the path id\n(``400 workspace_scope_mismatch`` otherwise): under the\nproduction RLS role the header is what scopes every row the\nrequest can see, so a purge aimed at a different path id would\nsilently do nothing -- or, on a BYPASSRLS dev role, hit the\nwrong workspace. Requiring agreement makes the verb mean the\nsame thing on both roles.\n\nIdempotent: a workspace with nothing left (or one that never had\na ``canon_workspaces`` row) returns ``200`` with zero counts and\n``closed=false``, so an off-boarding job can retry.",
        "operationId": "purge",
        "parameters": [
          {
            "in": "path",
            "name": "workspace_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/XTenantId"
          },
          {
            "$ref": "#/components/parameters/XWorkspaceId"
          },
          {
            "$ref": "#/components/parameters/XCorrelationId"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkspacePurgeResult"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "security": [
          {
            "ApiKeyHeader": []
          },
          {
            "ApiKeyAuthorization": []
          }
        ],
        "summary": "Erase everything the workspace holds, then close it.",
        "tags": [
          "Workspaces"
        ]
      }
    }
  },
  "servers": [
    {
      "description": "This service",
      "url": "/"
    }
  ],
  "tags": [
    {
      "name": "AgentCandidates"
    },
    {
      "name": "AgentKnowledge"
    },
    {
      "name": "AgentQuery"
    },
    {
      "name": "AgentSources"
    },
    {
      "name": "AgentTokens"
    },
    {
      "description": "Append-only audit log. Every mutation in flycanon (``source.ingested``, ``knowledge.published``, ``candidate.accepted``, ...) writes a row here with the actor, the correlation id from the originating request, and a free-form payload. The same payload is broadcast on the ``flycanon.audit`` topic for compliance projections.",
      "name": "Audit"
    },
    {
      "name": "Billing"
    },
    {
      "description": "Pre-canonical knowledge proposals. The consolidation stage feeds source chunks to an LLM (FireflyAgent over pydantic-ai) that emits structured CandidateProposals with chunk-anchored citations and a self-rated confidence score. Operators (or an automated policy) accept proposals to materialise a new knowledge version, reject them with a reason, or merge them into existing items. Every decision flows through the audit log.",
      "name": "Candidates"
    },
    {
      "name": "Conversations"
    },
    {
      "name": "Jobs"
    },
    {
      "description": "Canonical knowledge items. The validated, versioned units downstream consumers should treat as ground truth. Every create / update appends a new version row; supersession and retirement are final transitions. Every lifecycle event is audited and broadcast on the ``flycanon.knowledge`` topic, so projections (dashboards, copilots, compliance feeds) stay in lock-step without polling.",
      "name": "Knowledge"
    },
    {
      "name": "KnowledgeGraph"
    },
    {
      "name": "KnowledgeQuality"
    },
    {
      "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": "QueryStream"
    },
    {
      "description": "Source intake. The front door for binary content -- DOCX, XLSX, PPTX, PDF, RTF, ODT/ODS/ODP, HTML, Markdown, plain text, CSV, TSV, JSON, XML, EPUB, raster images (PNG, JPEG, GIF, WebP, HEIC, AVIF, TIFF, SVG, BMP) routed through Tesseract OCR, ZIP / 7Z / TAR / GZ archives expanded inline, EML / MSG emails decomposed into body + attachments, and WebVTT / SRT transcripts. The intake pipeline sniffs the actual media type from magic bytes, runs the binary normaliser, loads through the per-format SourceLoader, chunks, embeds, and indexes BM25 + dense vectors keyed by chunk_id. SHA-256 hashing makes ingestion idempotent on content.",
      "name": "Sources"
    },
    {
      "name": "Stats"
    },
    {
      "description": "Domain + jurisdiction taxonomy. Seed inserts one root per :class:`Domain` value at first boot; callers attach finer-grained children at runtime (sub-processes, jurisdiction sub-trees). The tree is read flat in breadth-first order via the ``depth`` column so the API round-trip is index-only.",
      "name": "Taxonomy"
    },
    {
      "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"
    }
  ]
}