openapi.json

{
  "components": {
    "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": {
          "embedded": {
            "minimum": 0,
            "title": "Embedded",
            "type": "integer"
          },
          "embedded_pct": {
            "description": "Percentage of chunks with a non-NULL embedding vector.",
            "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"
      },
      "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"
      }
    }
  },
  "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.6.19"
  },
  "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",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/AgentTokenSummaryDto"
                  },
                  "type": "array"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "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",
        "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"
          }
        },
        "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"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "No Content"
          }
        },
        "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",
        "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"
          }
        },
        "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"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KnowledgeItem"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "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"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Provenance"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "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",
        "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"
          }
        },
        "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",
        "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"
          }
        },
        "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",
        "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"
          }
        },
        "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",
        "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"
          }
        },
        "summary": "Submit a source for intake (agent tier).",
        "tags": [
          "AgentSources"
        ]
      }
    },
    "/api/v1/agent/sources/{source_id}": {
      "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"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SourceRecord"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "summary": "Read a single source record (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"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditPage"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "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"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillingReport"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "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"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubjectCostReport"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "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"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CostEventsPage"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "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"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LatencyReport"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "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",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillingSummary"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "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"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TopConsumersReport"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "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"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CandidatesPage"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "tags": [
          "Candidates"
        ]
      }
    },
    "/api/v1/candidates/{candidate_id}": {
      "get": {
        "operationId": "get_candidate",
        "parameters": [
          {
            "in": "path",
            "name": "candidate_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CandidateRecord"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "tags": [
          "Candidates"
        ]
      }
    },
    "/api/v1/candidates/{candidate_id}:accept": {
      "post": {
        "operationId": "accept",
        "parameters": [
          {
            "in": "path",
            "name": "candidate_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "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"
          }
        },
        "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"
            }
          }
        ],
        "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"
          }
        },
        "tags": [
          "Candidates"
        ]
      }
    },
    "/api/v1/candidates:propose": {
      "post": {
        "operationId": "propose",
        "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"
          }
        },
        "summary": "Run the consolidation stage against a source and persist",
        "tags": [
          "Candidates"
        ]
      }
    },
    "/api/v1/conversations": {
      "post": {
        "operationId": "create_conversation",
        "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"
          }
        },
        "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"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Conversation"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "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"
            }
          }
        ],
        "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"
          }
        },
        "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"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IngestJobsPage"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "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"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IngestJob"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "summary": "Single-shot lookup. Polling target for callers that",
        "tags": [
          "Jobs"
        ]
      }
    },
    "/api/v1/ingest-jobs/{job_id}/stream": {
      "get": {
        "description": "Each ``data:`` frame is a JSON blob. The stream closes when\nthe job reaches 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.",
        "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"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response"
          }
        },
        "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"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KnowledgeItemsPage"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "summary": "Paginated, filterable list of knowledge items.",
        "tags": [
          "Knowledge"
        ]
      },
      "post": {
        "operationId": "create_knowledge",
        "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"
          }
        },
        "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"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KnowledgeItem"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "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"
            }
          }
        ],
        "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"
          }
        },
        "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"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KnowledgeVersionDiff"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "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"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/KnowledgeVersion"
                  },
                  "type": "array"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "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"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Provenance"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "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"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KnowledgeRelations"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "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"
            }
          }
        ],
        "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"
          }
        },
        "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"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "No Content"
          }
        },
        "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"
            }
          }
        ],
        "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"
          }
        },
        "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"
            }
          }
        ],
        "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"
          }
        },
        "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",
        "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"
          }
        },
        "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"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response"
          }
        },
        "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",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StaleReport"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "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",
        "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"
          }
        },
        "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",
        "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"
          }
        },
        "summary": "SSE answer stream routed through the answer dispatcher.",
        "tags": [
          "QueryStream"
        ]
      }
    },
    "/api/v1/query/suggest": {
      "post": {
        "operationId": "suggest",
        "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"
          }
        },
        "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",
        "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"
          }
        },
        "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"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SourcesPage"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "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"
            }
          }
        ],
        "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"
          }
        },
        "summary": "Submit a source for intake.",
        "tags": [
          "Sources"
        ]
      }
    },
    "/api/v1/sources/{source_id}": {
      "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"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SourceRecord"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "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"
            }
          }
        ],
        "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"
          }
        },
        "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",
        "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"
          }
        },
        "summary": "Submit up to 100 sources in one call.",
        "tags": [
          "Sources"
        ]
      }
    },
    "/api/v1/stats": {
      "get": {
        "operationId": "get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CorpusStats"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "tags": [
          "Stats"
        ]
      }
    },
    "/api/v1/taxonomy": {
      "get": {
        "operationId": "get_taxonomy",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaxonomyTree"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "summary": "Return the full taxonomy as a flat list ordered breadth-first.",
        "tags": [
          "Taxonomy"
        ]
      }
    },
    "/api/v1/taxonomy/nodes": {
      "post": {
        "operationId": "create_node",
        "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"
          }
        },
        "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",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/WorkspaceSummary"
                  },
                  "type": "array"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "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",
        "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"
          }
        },
        "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"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkspaceSpec"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "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"
            }
          }
        ],
        "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"
          }
        },
        "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"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkspaceSpec"
                }
              }
            },
            "description": "Successful response"
          }
        },
        "summary": "Close a workspace (status='closed' + closed_at=now()).",
        "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"
    }
  ]
}