{"openapi":"3.1.0","info":{"title":"SciPot Core API","description":"**SciPot** (Scientia Potentia Est) is a Memory-as-a-Service platform for AI agents. It provides specialized knowledge containers called **POTs** (Knowledge Pots) with certainty scoring (**POT Score** — Proof of Truth), typed relationships (**Edges**), and intelligent retrieval (CAG / RAG / GraphRAG).\n\n## Authentication\n\nAll endpoints (except `/health`, `/ready`, and the `/auth/*` signup flow) require an integrator API key via the `X-API-Key` header and (for workspace-scoped operations) a workspace ID via `X-Workspace-ID`.\n\n## Getting Started\n\n**Interactive Tutorial:** Follow our step-by-step [Google Colab notebook](https://colab.research.google.com/gist/smtx/b0dceb963d3efabfa8fdd9fbf1772729) to sign up, create your first Knowledge POT, ingest documents, detect contradictions, and query your knowledge base — all in minutes.\n\n**Full docs:** [docs.scipot.ai](https://docs.scipot.ai)\n\n### Quick Reference\n\n1. Sign up via `POST /auth/signup` and verify your email\n2. Create a POT via `POST /pots`\n3. Ingest content via `POST /pots/{pot_id}/ingest`\n4. Query knowledge via `POST /pots/{pot_id}/query` or `POST /pots/{pot_id}/synthesize`\n","version":"0.2.0"},"paths":{"/health":{"get":{"tags":["health"],"summary":"Liveness probe","description":"Liveness probe.\n\nReturns 200 OK if the server is running.\nThis is a simple endpoint with no dependencies to verify\nthat the application process is alive.","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/ready":{"get":{"tags":["health"],"summary":"Readiness probe","description":"Readiness probe.\n\nReturns 200 OK if the service is ready to process requests.\nReturns 503 Service Unavailable if storage is not available.\n\nThis endpoint verifies that:\n- PotService is initialized\n- Storage adapter is accessible","operationId":"ready_ready_get","responses":{"200":{"description":"Service is ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadinessResponse"}}}},"503":{"description":"Service is not ready"}}}},"/integrator/workspaces":{"get":{"tags":["integrator-workspaces"],"summary":"List workspaces","description":"List all active workspaces for the authenticated integrator.","operationId":"list_workspaces_integrator_workspaces_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceListResponse"}}}}}},"post":{"tags":["integrator-workspaces"],"summary":"Create workspace for tenant","description":"Create a new workspace for the authenticated integrator.\n\nEach workspace represents a tenant in KB2B.","operationId":"create_workspace_integrator_workspaces_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWorkspaceRequest"}}},"required":true},"responses":{"201":{"description":"Workspace created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceInfo"}}}},"409":{"description":"Workspace slug already exists"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/integrator/workspaces/{workspace_id}":{"get":{"tags":["integrator-workspaces"],"summary":"Get workspace details","description":"Get details of a specific workspace.","operationId":"get_workspace_integrator_workspaces__workspace_id__get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceInfo"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["integrator-workspaces"],"summary":"Deactivate workspace","description":"Deactivate (soft delete) a workspace.","operationId":"deactivate_workspace_integrator_workspaces__workspace_id__delete","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/integrator/workspaces/{workspace_id}/token-topup":{"post":{"tags":["integrator-workspaces"],"summary":"Add bonus tokens to a workspace","description":"Add bonus tokens to a workspace's monthly quota. These tokens are added\non top of the base `max_monthly_tokens` limit. Use this when a user\npurchases additional token packs.\n\nThe bonus tokens persist until explicitly reset (e.g., on billing cycle renewal).","operationId":"token_topup_integrator_workspaces__workspace_id__token_topup_post","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenTopUpRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenTopUpResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/integrator/workspaces/{workspace_id}/token-reset":{"post":{"tags":["integrator-workspaces"],"summary":"Reset bonus tokens to zero","description":"Reset a workspace's bonus tokens to zero. Use this on billing cycle renewal\nto clear previously purchased top-ups.","operationId":"token_reset_integrator_workspaces__workspace_id__token_reset_post","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResetResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/integrator/workspaces/{workspace_id}/quotas":{"patch":{"tags":["integrator-workspaces"],"summary":"Update workspace token quota","description":"Update the monthly token limit for a workspace. Set to null to remove the limit\n(unlimited), or a positive integer to enforce a cap. Existing bonus_tokens are\npreserved.","operationId":"update_workspace_quotas_integrator_workspaces__workspace_id__quotas_patch","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWorkspaceQuotasRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWorkspaceQuotasResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/integrator/workspaces/{workspace_id}/contributors":{"post":{"tags":["contributors"],"summary":"Register or update contributor","description":"Register a new contributor or update an existing one (upsert by external_id).\n\nIf a contributor with the same external_id exists in this workspace:\n- Updates display_name\n- If the role differs from the current active role, closes the old role and opens a new one\n\nIf not found, creates a new contributor with initial role.","operationId":"create_or_update_contributor_integrator_workspaces__workspace_id__contributors_post","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateContributorRequest"}}}},"responses":{"201":{"description":"Contributor created or updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContributorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["contributors"],"summary":"List contributors","description":"List contributors in a workspace, optionally filtering by active status.","operationId":"list_contributors_integrator_workspaces__workspace_id__contributors_get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"is_active","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Active"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContributorListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/integrator/workspaces/{workspace_id}/contributors/by-external/{external_id}":{"get":{"tags":["contributors"],"summary":"Get contributor by external ID","description":"Look up a contributor by their external ID (integrator's user ID).","operationId":"get_contributor_by_external_id_integrator_workspaces__workspace_id__contributors_by_external__external_id__get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"external_id","in":"path","required":true,"schema":{"type":"string","title":"External Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContributorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/integrator/workspaces/{workspace_id}/contributors/{contributor_id}":{"get":{"tags":["contributors"],"summary":"Get contributor details","description":"Get a contributor with current role and full role history.","operationId":"get_contributor_integrator_workspaces__workspace_id__contributors__contributor_id__get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"contributor_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Contributor Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContributorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["contributors"],"summary":"Update contributor","description":"Update contributor fields. Deactivation (is_active=false) closes the active role.","operationId":"update_contributor_integrator_workspaces__workspace_id__contributors__contributor_id__patch","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"contributor_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Contributor Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateContributorRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContributorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/integrator/workspaces/{workspace_id}/contributors/{contributor_id}/roles":{"post":{"tags":["contributors"],"summary":"Add new role","description":"Add a new role, automatically closing the previous active role.","operationId":"add_role_integrator_workspaces__workspace_id__contributors__contributor_id__roles_post","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"contributor_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Contributor Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddRoleRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContributorRoleResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["contributors"],"summary":"Get role history","description":"Get complete role history for a contributor, sorted by started_at descending.","operationId":"list_roles_integrator_workspaces__workspace_id__contributors__contributor_id__roles_get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"contributor_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Contributor Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pots":{"post":{"tags":["pots"],"summary":"Create a POT","description":"Create a new Knowledge Pot (POT) with a Constitution — 3–10 foundational axioms that define what's true in the POT's domain. Returns the POT with assigned UUID and the Constitution materialised as facts at POT Score 1.0.\n\nThe workspace this POT belongs to is taken from the `X-Workspace-ID` header.\n\n**Renamed from `POST /pots/from-json` (deprecated, removed).** Legacy callers should update to this route. The YAML-directory variant is now an internal-only endpoint (`POST /pots/from-directory`) and is not exposed in the public API surface.","operationId":"create_pot_pots_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePOTFromJSONRequest"}}}},"responses":{"201":{"description":"POT created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/POTResponse"}}}},"400":{"description":"POT already exists in workspace"},"422":{"description":"Invalid constitution or configuration"},"429":{"description":"POT quota exceeded for workspace"}}},"get":{"tags":["pots"],"summary":"List all POTs","description":"List all POTs, optionally filtered by workspace.\n\nArgs:\n    workspace_id: Optional workspace UUID filter\n    pot_service: Injected PotService instance\n\nReturns:\n    List of POTs and total count","operationId":"list_pots_pots_get","parameters":[{"name":"workspace_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Filter POTs by workspace ID","title":"Workspace Id"},"description":"Filter POTs by workspace ID"}],"responses":{"200":{"description":"POTs retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/POTListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pots/{pot_id}":{"get":{"tags":["pots"],"summary":"Get a POT by UUID","description":"Get a POT by its UUID.\n\nArgs:\n    pot_id: POT unique identifier\n    pot_service: Injected PotService instance\n\nReturns:\n    POT data\n\nRaises:\n    404: POT not found","operationId":"get_pot_pots__pot_id__get","parameters":[{"name":"pot_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Pot Id"}}],"responses":{"200":{"description":"POT retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/POTResponse"}}}},"404":{"description":"POT not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["pots"],"summary":"Delete a POT","description":"Delete a POT by its UUID.\n\nDeletes POT data and associated vectors from the vector store.","operationId":"delete_pot_pots__pot_id__delete","parameters":[{"name":"pot_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Pot Id"}}],"responses":{"204":{"description":"POT deleted successfully"},"404":{"description":"POT not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pots/by-slug/{slug}":{"get":{"tags":["pots"],"summary":"Get a POT by slug","description":"Look up a POT by its human-readable slug within the workspace identified by the `X-Workspace-ID` header. Returns the same shape as `GET /pots/{pot_id}`.\n\n**Renamed from `/pots/by-slug/{workspace_id}/{slug}`** — the workspace path segment was redundant with the required header and has been removed.","operationId":"get_pot_by_slug_pots_by_slug__slug__get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}}],"responses":{"200":{"description":"POT retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/POTResponse"}}}},"404":{"description":"POT not found in this workspace"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pots/{pot_id}/constitution/with-edges":{"get":{"tags":["pots"],"summary":"Get constitution axioms with their edges and connected facts","description":"Get constitution axioms enriched with edges and connected facts.\n\nM18: Uses single-query + in-memory filter strategy (3 DynamoDB ops).\n\nStrategy:\n1. get_constitution() — 1 query\n2. get_all_edges() — 1 query\n3. get_facts(batch) — 1 query for connected facts","operationId":"get_constitution_with_edges_pots__pot_id__constitution_with_edges_get","parameters":[{"name":"pot_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Pot Id"}}],"responses":{"200":{"description":"Constitution with edges retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConstitutionWithEdgesResponse"}}}},"404":{"description":"POT not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pots/{pot_id}/constitution/facts":{"post":{"tags":["pots"],"summary":"Add a new constitution axiom to an existing POT","description":"Add a new constitution axiom to an existing POT.\n\nThe axiom is automatically assigned pot_score=1.0 and level=CONSTITUTION.\nMaximum 10 axioms per POT.","operationId":"add_constitution_fact_pots__pot_id__constitution_facts_post","parameters":[{"name":"pot_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Pot Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConstitutionFactInput"}}}},"responses":{"201":{"description":"Axiom added successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddAxiomResponse"}}}},"400":{"description":"Axiom limit reached (max 10)"},"404":{"description":"POT not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pots/{pot_id}/graph":{"get":{"tags":["pots"],"summary":"Get full POT knowledge graph for visualization","description":"Get the complete knowledge graph of a POT for visualization.\n\nReturns all facts (as nodes), edges, and documents in a single response.\nOptimized for graph rendering in KB2B Knowledge Graph.\n\nM19: KB2B v1.0 Enablers.","operationId":"get_pot_graph_pots__pot_id__graph_get","parameters":[{"name":"pot_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Pot Id"}},{"name":"max_nodes","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Max nodes to return","default":200,"title":"Max Nodes"},"description":"Max nodes to return"},{"name":"include_content","in":"query","required":false,"schema":{"type":"boolean","description":"Include full fact content (increases payload)","default":false,"title":"Include Content"},"description":"Include full fact content (increases payload)"}],"responses":{"200":{"description":"Graph retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PotGraphResponse"}}}},"404":{"description":"POT not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pots/{pot_id}/propagate":{"post":{"tags":["pots"],"summary":"Manually trigger POT Score propagation","description":"Manually trigger edge-based POT Score propagation.\n\nApplies 3 propagation rules (M19 MVP):\n1. CONTRADICTS penalty against constitution facts\n2. SUPPORTS boost from constitution facts\n3. DERIVES_FROM ceiling constraint\n\nIdempotent: can be re-run safely (uses original_pot_score as base).","operationId":"propagate_scores_pots__pot_id__propagate_post","parameters":[{"name":"pot_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Pot Id"}}],"responses":{"200":{"description":"Propagation completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PropagationResponse"}}}},"404":{"description":"POT not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pots/{pot_id}/facts":{"get":{"tags":["facts","facts"],"summary":"List facts in a POT","description":"List facts within a POT, with filtering (POT Score range, domain, tags, source document, status), sorting (created_at, updated_at, pot_score), and offset-based pagination. Returns each fact with its current POT Score, level (e.g., `VERIFIED`, `SUPPORTED`), provenance, and an `edge_summary` block counting incoming/outgoing edges by type.\n\n**Common use cases:**\n- Browsing facts by certainty (`min_pot_score=0.8` for VERIFIED+).\n- Auditing a single source document's extracted facts (`document_id=...`).\n- Building a Curator review queue (filter by `status=pending`).\n- Powering an internal knowledge browser.\n\n**Pagination:** offset-based with `limit` (max 500) and `offset`. The response includes `has_more` and `total` so you can render proper paging.","operationId":"list_facts_pots__pot_id__facts_get","parameters":[{"name":"pot_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Pot Id"}},{"name":"min_pot_score","in":"query","required":false,"schema":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Min Pot Score"}},{"name":"max_pot_score","in":"query","required":false,"schema":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Max Pot Score"}},{"name":"document_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Filter by source document UUID","title":"Document Id"},"description":"Filter by source document UUID"},{"name":"domain","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}},{"name":"tags","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"title":"Tags"}},{"name":"sort_by","in":"query","required":false,"schema":{"enum":["created_at","updated_at","pot_score"],"type":"string","default":"created_at","title":"Sort By"}},{"name":"sort_order","in":"query","required":false,"schema":{"enum":["asc","desc"],"type":"string","default":"desc","title":"Sort Order"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Facts retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FactListResponse"}}}},"404":{"description":"POT not found in this workspace"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pots/{pot_id}/stats":{"get":{"tags":["facts","facts"],"summary":"Get aggregated statistics for a POT","description":"Get aggregated statistics for a POT.\n\nComputes per-level fact counts via Select=\"COUNT\" + FilterExpression\nqueries — no fact rows materialized. Used by KB2B's dashboard to render\nthe score distribution chart and total fact count without sampling.","operationId":"get_pot_stats_pots__pot_id__stats_get","parameters":[{"name":"pot_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Pot Id"}}],"responses":{"200":{"description":"Stats retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/POTStatsResponse"}}}},"404":{"description":"POT not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pots/{pot_id}/facts/{fact_id}":{"get":{"tags":["facts","facts"],"summary":"Get a single fact by ID","description":"Get a single fact by ID.","operationId":"get_fact_pots__pot_id__facts__fact_id__get","parameters":[{"name":"pot_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Pot Id"}},{"name":"fact_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Fact Id"}}],"responses":{"200":{"description":"Fact retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FactExtended"}}}},"404":{"description":"POT or fact not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["facts","facts"],"summary":"Delete a fact from a POT","description":"Delete a fact from a POT.\n\nAlso deletes all edges connected to this fact (cascade delete).\n\n- **pot_id**: UUID of the POT\n- **fact_id**: UUID of the fact to delete","operationId":"delete_fact_pots__pot_id__facts__fact_id__delete","parameters":[{"name":"pot_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Pot Id"}},{"name":"fact_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Fact Id"}}],"responses":{"204":{"description":"Fact deleted successfully"},"404":{"description":"POT or Fact not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pots/{pot_id}/facts/{fact_id}/with-edges":{"get":{"tags":["facts","facts"],"summary":"Get a fact with all its edges and related facts","description":"Get a fact with all its edges and a paginated slice of related facts.\n\nM18: Exposes StorageBackend.get_fact_with_relations() as API endpoint.\nEdges (edges_out, edges_in) are returned in full so the UI knows the\nreal degree of the fact. Related facts are paginated via\nrelated_limit/related_offset to keep payloads bounded for high-degree\nfacts (e.g. CONSTITUTION axioms with hundreds of supporting edges).","operationId":"get_fact_with_edges_pots__pot_id__facts__fact_id__with_edges_get","parameters":[{"name":"pot_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Pot Id"}},{"name":"fact_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Fact Id"}},{"name":"related_limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"Page size for related facts","default":50,"title":"Related Limit"},"description":"Page size for related facts"},{"name":"related_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Pagination offset for related facts","default":0,"title":"Related Offset"},"description":"Pagination offset for related facts"}],"responses":{"200":{"description":"Fact with relations retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FactWithRelationsResponse"}}}},"404":{"description":"POT or fact not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pots/{pot_id}/edges":{"get":{"tags":["edges","edges"],"summary":"List edges in a POT, optionally filtered by type","description":"List all edges in a POT, optionally filtered by edge type.\n\n- **pot_id**: UUID of the POT\n- **type**: Optional edge type filter (e.g., contradicts, supports)\n\nExamples:\n    GET /pots/{id}/edges — all edges\n    GET /pots/{id}/edges?type=contradicts — only contradictions","operationId":"list_edges_pots__pot_id__edges_get","parameters":[{"name":"pot_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Pot Id"}},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/EdgeType"},{"type":"null"}],"title":"Type"}}],"responses":{"200":{"description":"Edges retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeListResponse"}}}},"404":{"description":"POT not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["edges","edges"],"summary":"Create edges between facts","description":"Create one or more edges between facts in a POT.\n\nAfter creating edges, runs POT Score propagation to update\naffected fact scores based on the new relationships.\n\n- **pot_id**: UUID of the POT\n- **edges_data**: List of edge definitions (from_id, to_id, type, weight, rationale)\n\nReturns the created edges and triggers POT Score propagation.","operationId":"create_edges_pots__pot_id__edges_post","parameters":[{"name":"pot_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Pot Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/EdgeCreate"},"title":"Edges Data"}}}},"responses":{"201":{"description":"Edges created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeListResponse"}}}},"404":{"description":"POT or referenced facts not found"},"422":{"description":"Validation error"}}}},"/pots/{pot_id}/edges/detect":{"post":{"tags":["edges","edges"],"summary":"Detect edges between facts and the Constitution using LLM","description":"Analyse the supplied facts against the POT's Constitutional axioms to detect **typed epistemic edges** — `SUPPORTS`, `CONTRADICTS`, `REFINES`, `DERIVES_FROM`, `IS_PART_OF` — using an LLM with structured output. Each edge carries a confidence-weighted relationship that drives downstream POT Score propagation.\n\n**Scope of this endpoint:** detection runs across `facts_to_analyze × constitution_facts` (the workhorse mode that catches contradictions against canonical truths). It does NOT currently run fact↔fact detection among the supplied facts themselves — that's a separate, on-demand operation (see roadmap M16 for batch intra-fact detection).\n\n**Request shape:**\n- `fact_ids` — facts to evaluate against the Constitution (required).\n- `include_constitution=true` (default) — load and pair against the POT's axioms. Setting `false` results in zero pairs analysed.\n- `auto_save=true` — persist detected edges (deduplicated by `(pot_id, from_id, to_id, type)`) and trigger POT Score propagation.\n- `min_weight` (default `0.2`) — filter low-confidence detections.\n\n**Cost model:** roughly `len(fact_ids) × len(constitution_facts)` LLM pair-evaluations (linear in the number of axioms — Constitutions are typically 3–10 facts, so this is cheap).\n\n**Contradictions are flagged, never auto-resolved.** Detected `CONTRADICTS` edges land in the curator review queue with priority based on what was contradicted (Constitution = critical; high-score fact = high; standard = normal).","operationId":"detect_edges_pots__pot_id__edges_detect_post","parameters":[{"name":"pot_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Pot Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeDetectRequest"}}}},"responses":{"200":{"description":"Edges detected; included in the response with metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeDetectResponse"}}}},"404":{"description":"POT or one of the supplied facts not found"},"422":{"description":"Validation error"},"502":{"description":"LLM error (timeout, rate limit, invalid response)"}}}},"/pots/{pot_id}/edges/from/{from_id}":{"get":{"tags":["edges","edges"],"summary":"Get outgoing edges from a fact","description":"Get all outgoing edges from a fact (A → ?).\n\nReturns edges where the specified fact is the source.\n\n- **pot_id**: UUID of the POT\n- **from_id**: UUID of the source fact","operationId":"get_edges_from_pots__pot_id__edges_from__from_id__get","parameters":[{"name":"pot_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Pot Id"}},{"name":"from_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"From Id"}}],"responses":{"200":{"description":"Outgoing edges retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeListResponse"}}}},"404":{"description":"POT or fact not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pots/{pot_id}/edges/to/{to_id}":{"get":{"tags":["edges","edges"],"summary":"Get incoming edges to a fact","description":"Get all incoming edges to a fact (? → B).\n\nReturns edges where the specified fact is the target.\n\n- **pot_id**: UUID of the POT\n- **to_id**: UUID of the target fact","operationId":"get_edges_to_pots__pot_id__edges_to__to_id__get","parameters":[{"name":"pot_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Pot Id"}},{"name":"to_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"To Id"}}],"responses":{"200":{"description":"Incoming edges retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeListResponse"}}}},"404":{"description":"POT or fact not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pots/{pot_id}/edges/{from_id}/{to_id}/{edge_id}":{"delete":{"tags":["edges","edges"],"summary":"Delete an edge between two facts","description":"Delete an edge between two facts.\n\nThe from_id and to_id are used for validation and efficient lookup.\n\n- **pot_id**: UUID of the POT\n- **from_id**: UUID of the source fact\n- **to_id**: UUID of the target fact (used for validation)\n- **edge_id**: ID of the edge to delete","operationId":"delete_edge_pots__pot_id__edges__from_id___to_id___edge_id__delete","parameters":[{"name":"pot_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Pot Id"}},{"name":"from_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"From Id"}},{"name":"to_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"To Id"}},{"name":"edge_id","in":"path","required":true,"schema":{"type":"string","title":"Edge Id"}}],"responses":{"204":{"description":"Edge deleted successfully"},"404":{"description":"POT or edge not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pots/{pot_id}/ingest":{"post":{"tags":["ingestion"],"summary":"Ingest inline text into a POT","description":"Submit raw text content for ingestion into a POT. The request returns immediately with a `job_id` (HTTP 202); the actual work — chunking, fact extraction, scoring, edge detection vs. the Constitution, score propagation — happens asynchronously.\n\n**Poll** `GET /jobs/{job_id}` for progress and the final result. Typical small documents (< 5 KB) complete in 5–15 seconds; larger ones scale with chunk count.\n\n**Use this endpoint for:** programmatic ingestion of text already in memory — snippets, structured exports, conversation summaries, ADR bodies, etc.\n\n**This endpoint's text limit is 100 KB (102,400 chars).** It's enforced at the request schema level: an oversize `content` field returns `422` with a Pydantic validation error. The 100 KB ceiling is specific to this inline-text route — it is NOT a per-document limit on SciPot as a whole.\n\n**For documents larger than 100 KB**, or for file formats SciPot needs to convert (PDF, DOCX, PPTX, XLSX, HTML), use the upload pipeline instead:\n1. `POST /documents/upload` (multipart/form-data, default 50 MB cap, auto-conversion via MarkItDown).\n2. `POST /pots/{pot_id}/extract-from-document` to extract facts from the stored document into one or more POTs.\n\n**Provenance:** every fact extracted will carry the `source` block you provide here. Be specific (`path`, `author`, `tags`) — provenance is the audit trail your agents will rely on later.","operationId":"ingest_document_pots__pot_id__ingest_post","parameters":[{"name":"pot_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Pot Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestionRequest"}}}},"responses":{"202":{"description":"Document ingestion queued; poll /jobs/{job_id} for progress","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestionAccepted"}}}},"404":{"description":"POT not found in this workspace"},"409":{"description":"Document with same content hash already ingested"},"422":{"description":"Validation error — including `content` exceeding the 100 KB inline-text limit (use /documents/upload for larger inputs)."},"429":{"description":"Workspace quota exceeded (storage, documents-per-POT, or tokens)"},"503":{"description":"Job queue unavailable"}}}},"/pots/{pot_id}/extract-from-document":{"post":{"tags":["ingestion"],"summary":"Extract facts from a stored document","description":"Re-extract facts from an already-stored document into a POT.\n\nThis allows extracting the same document into multiple POTs\nwithout re-uploading the content.","operationId":"extract_from_document_pots__pot_id__extract_from_document_post","parameters":[{"name":"pot_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Pot Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractFromDocumentRequest"}}}},"responses":{"202":{"description":"Re-extraction queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestionAccepted"}}}},"404":{"description":"POT or document not found"},"422":{"description":"Validation error"},"503":{"description":"Job queue unavailable"}}}},"/jobs/{job_id}":{"get":{"tags":["jobs"],"summary":"Get job status","description":"Get status of an ingestion job.\n\nPoll this endpoint to track progress of async ingestion.\n\n**Job Lifecycle:**\n- `pending`: Job queued, not started\n- `processing`: Job in progress (check `progress` field)\n- `completed`: Job finished successfully (check `result` field)\n- `failed`: Job failed (check `error` field)\n\n**M17 Phase Progress:**\nWhen processing, the `progress` field includes:\n- `phase`: Current pipeline phase (extracting, indexing, detecting_edges, propagating_scores)\n- `phase_index`/`phases_total`: Phase position (e.g., 2/4)\n- `phase_detail`: Sub-step detail within the phase\n- `overall_percent`: Overall progress estimate (0-100)\n\nThe `poll_interval_ms` field suggests an appropriate polling interval.","operationId":"get_job_status_jobs__job_id__get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Job Id"}}],"responses":{"200":{"description":"Job status retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResponse"}}}},"404":{"description":"Job not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/jobs":{"get":{"tags":["jobs"],"summary":"List jobs for workspace","description":"List jobs for the authenticated workspace.\n\nOptionally filter by status (pending, processing, completed, failed).\nUseful for building a global job status badge/dashboard.","operationId":"list_jobs_jobs_get","parameters":[{"name":"status_filter","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status Filter"}}],"responses":{"200":{"description":"Jobs listed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pots/{pot_id}/search":{"post":{"tags":["search","search"],"summary":"Semantic search over facts","description":"Execute semantic search using RAG retrieval strategy.\n\n**Ranking formula:** `combined_score = (similarity × 0.7) + (pot_score × 0.3)`\n\nResults are ordered by combined score descending.\n\n**Filtering:**\n- `min_pot_score`: Pre-filter by minimum certainty score\n- `filters.domain`: Post-filter by exact domain match\n- `filters.level`: Post-filter by POT Index level(s) (OR logic)\n- `filters.tags`: Post-filter by tags (AND logic - must have ALL)","operationId":"search_pots__pot_id__search_post","parameters":[{"name":"pot_id","in":"path","required":true,"schema":{"type":"string","description":"POT identifier (UUID or slug)","title":"Pot Id"},"description":"POT identifier (UUID or slug)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}}},"responses":{"200":{"description":"Successful search","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Search Pots  Pot Id  Search Post"},"example":{"data":{"results":[{"fact_id":"fact_abc123","content":"POT Index propagates certainty...","score":0.87,"pot_score":0.85,"level":"VERIFIED","domain":"architecture","tags":["pot-index"],"metadata":{"similarity_score":0.89}}]},"metadata":{"pot_id":"scipot-core","query":"POT Index propagation","retrieval_strategy":"RAG","latency_ms":234,"total_candidates":15,"results_returned":5,"filters_applied":{}}}}}},"400":{"description":"Invalid query (too short, invalid parameters)"},"404":{"description":"POT not found"},"500":{"description":"Search failed (vector store error, embedding error)"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pots/{pot_id}/vector-debug":{"get":{"tags":["search","search","debug"],"summary":"Debug vector store state for a POT","description":"Returns diagnostic info about vectors stored in the vector store for this POT.","operationId":"vector_debug_pots__pot_id__vector_debug_get","parameters":[{"name":"pot_id","in":"path","required":true,"schema":{"type":"string","description":"POT identifier (UUID or slug)","title":"Pot Id"},"description":"POT identifier (UUID or slug)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Vector Debug Pots  Pot Id  Vector Debug Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pots/{pot_id}/vectors/reindex":{"post":{"tags":["search","search","debug"],"summary":"Re-index all facts for a POT in the vector store","description":"Re-embeds and upserts all facts for a POT into the vector store. Use after changing embedding model or fixing indexing failures.","operationId":"reindex_vectors_pots__pot_id__vectors_reindex_post","parameters":[{"name":"pot_id","in":"path","required":true,"schema":{"type":"string","description":"POT identifier (UUID or slug)","title":"Pot Id"},"description":"POT identifier (UUID or slug)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Reindex Vectors Pots  Pot Id  Vectors Reindex Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pots/vectors/reset":{"delete":{"tags":["search","search","debug"],"summary":"Reset all vectors in the vector store","description":"Deletes ALL vectors. Use only in dev/staging. Not for production.","operationId":"reset_vectors_pots_vectors_reset_delete","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Reset Vectors Pots Vectors Reset Delete"}}}}}}},"/pots/{pot_id}/cag/search":{"post":{"tags":["cag","cag"],"summary":"CAG keyword/entity search","description":"Execute CAG (Cached Augmented Generation) search over cached facts.\n\n**How it works:**\n1. Tokenizes query into keywords and entities\n2. Looks up matching facts in cache (Constitution + High-Certainty)\n3. Scores by keyword overlap, entity overlap, and POT Score\n4. Returns results with confidence metadata\n\n**Scoring formula:**\n`score = (keyword_score * 0.5) + (entity_score * 0.3) + (pot_score * 0.2)`\n\n**Confidence suggestions:**\n- `sufficient`: Good matches found, likely complete answer\n- `consider_rag`: Partial matches, client may want to also query RAG\n- `no_match`: No meaningful matches, definitely query RAG\n\n**Note:** Client decides whether to follow up with RAG based on suggestion.","operationId":"cag_search_pots__pot_id__cag_search_post","parameters":[{"name":"pot_id","in":"path","required":true,"schema":{"type":"string","description":"POT identifier (UUID or slug)","title":"Pot Id"},"description":"POT identifier (UUID or slug)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CAGSearchRequest"}}}},"responses":{"200":{"description":"Successful search","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CAGSearchResponse"}}}},"404":{"description":"POT not found"},"500":{"description":"Cache initialization failed"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pots/{pot_id}/cag/warm":{"post":{"tags":["cag","cag"],"summary":"Pre-load CAG cache","description":"Explicitly warm up the CAG cache for a POT.\n\nThis loads:\n- All Constitution facts (Layer 1)\n- Facts with POT Score >= threshold (Layer 2)\n\nUseful for:\n- Pre-loading cache before expected queries\n- Ensuring cache is ready for low-latency responses\n- Verifying cache initialization works correctly","operationId":"cag_warm_pots__pot_id__cag_warm_post","parameters":[{"name":"pot_id","in":"path","required":true,"schema":{"type":"string","description":"POT identifier (UUID or slug)","title":"Pot Id"},"description":"POT identifier (UUID or slug)"}],"responses":{"200":{"description":"Cache warmed (or already warm)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CAGWarmResponse"}}}},"404":{"description":"POT not found"},"500":{"description":"Cache initialization failed"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pots/{pot_id}/cag/stats":{"get":{"tags":["cag","cag"],"summary":"Get CAG cache statistics","description":"Get statistics for the CAG cache of a POT.\n\nReturns:\n- Cache size (constitution, high-certainty, total)\n- Hit/miss rates\n- Timing information (initialization, last refresh)\n\nUseful for monitoring cache performance and debugging.","operationId":"cag_stats_pots__pot_id__cag_stats_get","parameters":[{"name":"pot_id","in":"path","required":true,"schema":{"type":"string","description":"POT identifier (UUID or slug)","title":"Pot Id"},"description":"POT identifier (UUID or slug)"}],"responses":{"200":{"description":"Cache statistics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CAGStatsResponse"}}}},"404":{"description":"POT not found or cache not initialized"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pots/{pot_id}/query":{"post":{"tags":["query","query"],"summary":"Unified query with automatic routing","description":"Execute a unified query against a POT with automatic strategy selection.\n\n**How it works:**\n1. Classifies query (factual → CAG, semantic → RAG, relational → GraphRAG)\n2. Executes optimal strategy first\n3. Automatically falls back to RAG if CAG insufficient\n4. Returns results with routing metadata\n\n**Strategies:**\n- `auto` (default): Automatic selection based on query classification\n- `cag`: Force CAG-only (fast, keyword-based)\n- `rag`: Force RAG-only (semantic search with embeddings)\n- `graph_rag`: Force GraphRAG (graph traversal for relational queries)\n\n**Fallback Logic:**\nWhen `enable_fallback=true` and `strategy=auto`:\n- If CAG returns `suggestion != \"sufficient\"`, executes RAG\n- If classification confidence is low, prefers RAG\n- Metadata shows which strategy was actually used\n\n**Latency:**\n- CAG-only: ~50ms\n- RAG: ~500ms\n- CAG with fallback: ~550ms\n- GraphRAG: ~200-800ms (depends on graph density)","operationId":"query_pot_pots__pot_id__query_post","parameters":[{"name":"pot_id","in":"path","required":true,"schema":{"type":"string","description":"POT identifier (UUID or slug)","title":"Pot Id"},"description":"POT identifier (UUID or slug)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryRequest"}}}},"responses":{"200":{"description":"Successful query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryResponse"}}}},"400":{"description":"Invalid query parameters"},"403":{"description":"Access denied to POT"},"404":{"description":"POT not found"},"501":{"description":"Strategy not available (e.g., graph_rag)"},"500":{"description":"Internal error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pots/{pot_id}/synthesize":{"post":{"tags":["synthesis","synthesis"],"summary":"Answer a question with receipts (facts + scores + provenance)","description":"Retrieve relevant facts from a POT and produce a synthesized natural-language answer **with receipts**: cited facts, POT Scores, source provenance, detected contradictions, and an optional epistemic briefing summarizing the system's confidence and coverage gaps.\n\n**Flow under the hood:**\n1. The Hybrid Router classifies the query and selects an optimal retrieval strategy — `CAG` (cached, <5ms), `RAG` (semantic vector), `GraphRAG` (graph traversal following edges), or a combination.\n2. Top facts are retrieved and ranked using `combined = (similarity × 0.7) + (pot_score × 0.3)`.\n3. Full provenance is fetched for each fact.\n4. Contradictions are detected among the retrieved set (flag-only, never auto-resolved).\n5. The LLM composes an answer with calibrated certainty (high-score facts spoken plainly; lower-score facts hedged or omitted).\n6. The response includes the answer, the facts used, contradictions, and an `epistemic_briefing` block describing what the system is confident about and where coverage is thin.\n\n**Production guidance:** for any consequential agent, set `include_epistemic_briefing=true` and treat unresolved contradictions (`contradictions_found`) as a signal that may justify deferring to a human.","operationId":"synthesize_pots__pot_id__synthesize_post","parameters":[{"name":"pot_id","in":"path","required":true,"schema":{"type":"string","description":"POT identifier (UUID or slug)","title":"Pot Id"},"description":"POT identifier (UUID or slug)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SynthesisRequest"}}}},"responses":{"200":{"description":"Synthesized answer with epistemic metadata + receipts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SynthesisResponse"}}}},"404":{"description":"POT not found in this workspace"},"429":{"description":"Token quota exceeded for workspace"},"500":{"description":"Retrieval or synthesis error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/documents/upload":{"post":{"tags":["documents"],"summary":"Upload a document file","description":"Upload a document file.\n\nAccepts any supported format (PDF, DOCX, PPTX, XLSX, Markdown, text, HTML, images).\nBinary formats are automatically converted to Markdown during upload.\nOnce uploaded, the document is ready for fact extraction.","operationId":"upload_document_documents_upload_post","parameters":[{"name":"author","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author"}},{"name":"tags","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tags"}},{"name":"source_url","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url"}},{"name":"description","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"}},{"name":"original_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Original Date"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_upload_document_documents_upload_post"}}}},"responses":{"201":{"description":"Document uploaded, converted (if needed), and stored","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentUploadResponse"}}}},"409":{"description":"Duplicate document (same content hash)"},"413":{"description":"File too large"},"422":{"description":"Conversion failed or empty file"}}}},"/documents":{"get":{"tags":["documents"],"summary":"List documents in workspace","description":"List documents in the authenticated workspace.\n\nReturns metadata only (no content). Use GET /documents/{id} for full content.","operationId":"list_documents_documents_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}}],"responses":{"200":{"description":"List of documents in the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/documents/{document_id}":{"get":{"tags":["documents"],"summary":"Get a document by ID","description":"Get a document by ID, including presigned download URLs.","operationId":"get_document_documents__document_id__get","parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Document Id"}}],"responses":{"200":{"description":"Document with full content and download URLs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentDetailResponse"}}}},"404":{"description":"Document not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["documents"],"summary":"Update document metadata","description":"Update document metadata (source_url, description, author, tags).","operationId":"update_document_documents__document_id__patch","parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Document Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentUpdateRequest"}}}},"responses":{"200":{"description":"Document updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentUpdateResponse"}}}},"404":{"description":"Document not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["documents"],"summary":"Delete a document and its files","description":"Delete a document and its files from storage.\n\nWith cascade=true, also deletes all facts extracted from this document\nacross all POTs in the workspace, removes their edges and embeddings,\nand recalculates POT scores on affected neighbor facts.","operationId":"delete_document_documents__document_id__delete","parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Document Id"}},{"name":"cascade","in":"query","required":false,"schema":{"type":"boolean","description":"Cascade delete facts, edges, embeddings and recalculate scores","default":false,"title":"Cascade"},"description":"Cascade delete facts, edges, embeddings and recalculate scores"}],"responses":{"200":{"description":"Document deleted with cascade (returns DeletionResult)","content":{"application/json":{"schema":{}}}},"204":{"description":"Document deleted (no cascade)"},"404":{"description":"Document not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pots/{pot_id}/facts/contribute":{"post":{"tags":["contribution","contribution"],"summary":"Contribute expert knowledge","description":"Contribute knowledge with a contributor profile.\n\nThe contributed content is extracted into facts. Each fact receives a POT Score\nbased on the contributor's expertise relevance to the fact's domain:\n- Score formula: 0.55 + (expertise_relevance × 0.30)\n- Range: 0.55 (no expertise match) to 0.85 (perfect expert)\n\nOptionally runs post-ingestion (edge detection + score propagation).","operationId":"contribute_knowledge_pots__pot_id__facts_contribute_post","parameters":[{"name":"pot_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Pot Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContributeRequest"}}}},"responses":{"201":{"description":"Facts created from contribution","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContributeResponse"}}}},"404":{"description":"POT not found"},"422":{"description":"Validation error"},"502":{"description":"LLM service error"}}}},"/pots/{pot_id}/facts/{fact_id}/curate":{"post":{"tags":["contribution","contribution"],"summary":"Curate a fact (approve/disapprove)","description":"Approve or disapprove a fact with expertise-weighted impact.\n\nThe curation impact depends on the curator's expertise:\n- Approve: +0.05 to +0.15 (based on expertise)\n- Disapprove: -0.03 to -0.15 (based on expertise)\n- Diminishing returns: delta × 0.8^n for repeated same-type curations\n- Score clamped to [0.01, 0.95]","operationId":"curate_fact_pots__pot_id__facts__fact_id__curate_post","parameters":[{"name":"pot_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Pot Id"}},{"name":"fact_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Fact Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurateRequest"}}}},"responses":{"200":{"description":"Curation applied successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurateResponse"}}}},"404":{"description":"POT or fact not found"},"400":{"description":"Cannot curate constitution facts"},"422":{"description":"Validation error"}}}},"/pots/{pot_id}/facts/{fact_id}/curations":{"get":{"tags":["contribution","contribution"],"summary":"Get curation history for a fact","description":"Get the full curation audit trail for a specific fact.\n\nOptionally filter by contributor_id.","operationId":"get_curations_pots__pot_id__facts__fact_id__curations_get","parameters":[{"name":"pot_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Pot Id"}},{"name":"fact_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Fact Id"}},{"name":"contributor_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Contributor Id"}}],"responses":{"200":{"description":"Curation history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurationListResponse"}}}},"404":{"description":"POT not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pots/{pot_id}/facts/{fact_id}/curations/{curation_id}":{"delete":{"tags":["contribution","contribution"],"summary":"Revoke a curation","description":"Revoke a curation, reverting the score delta it applied.\n\nOnly the original contributor can revoke their own curation.\nThe curation record is kept for audit trail (soft-delete with revoked_at).","operationId":"revoke_curation_pots__pot_id__facts__fact_id__curations__curation_id__delete","parameters":[{"name":"pot_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Pot Id"}},{"name":"fact_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Fact Id"}},{"name":"curation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Curation Id"}},{"name":"contributor_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","title":"Contributor Id"}}],"responses":{"200":{"description":"Curation revoked successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeCurationResponse"}}}},"400":{"description":"Curation already revoked"},"403":{"description":"Contributor does not own this curation"},"404":{"description":"POT, fact, or curation not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pots/{pot_id}/edges/{edge_id}/stances":{"post":{"tags":["contradiction","contradiction"],"summary":"Submit a stance on a contradiction","description":"Submit a stance on a contradiction edge.\n\nA stance records a contributor's opinion about which fact in a contradiction\nis correct. Stances accumulate as evidence and apply small score impacts\nweighted by the contributor's expertise.\n\nStance types:\n- **confirm_a**: Believes from_id (fact A) is correct\n- **confirm_b**: Believes to_id (fact B) is correct\n- **dismiss**: Believes the contradiction is not real/relevant","operationId":"add_stance_pots__pot_id__edges__edge_id__stances_post","parameters":[{"name":"pot_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Pot Id"}},{"name":"edge_id","in":"path","required":true,"schema":{"type":"string","title":"Edge Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StanceRequest"}}}},"responses":{"201":{"description":"Stance recorded successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StanceResponse"}}}},"404":{"description":"POT or edge not found"},"400":{"description":"Edge is not a contradiction"},"422":{"description":"Validation error"}}},"get":{"tags":["contradiction","contradiction"],"summary":"Get stances for a contradiction edge","description":"Get all stances submitted for a contradiction edge.\n\nReturns stances sorted by creation date (newest first) with counts\nper stance type. Optionally filter by contributor_id.","operationId":"get_stances_pots__pot_id__edges__edge_id__stances_get","parameters":[{"name":"pot_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Pot Id"}},{"name":"edge_id","in":"path","required":true,"schema":{"type":"string","title":"Edge Id"}},{"name":"contributor_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Contributor Id"}}],"responses":{"200":{"description":"Stances retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StanceListResponse"}}}},"404":{"description":"POT not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pots/{pot_id}/edges/{edge_id}/resolve":{"post":{"tags":["contradiction","contradiction"],"summary":"Resolve a contradiction","description":"Resolve a contradiction by mutating the edge type.\n\nThe edge type changes from 'contradicts' to 'resolved_contradiction'.\nThis means:\n- GET /edges?type=contradicts will no longer return this edge\n- GET /edges?type=resolved_contradiction will include it\n- Query results will no longer show this as an active contradiction\n\nResolution types:\n- **confirmed_a**: from_id is correct (+0.08), to_id is incorrect (-0.10)\n- **confirmed_b**: to_id is correct (+0.08), from_id is incorrect (-0.10)\n- **both_valid**: Both facts are valid in different contexts (no score change)\n- **needs_update**: Source documents need updating (flags both for review)\n- **dismissed**: False positive (reduces edge weight)","operationId":"resolve_contradiction_pots__pot_id__edges__edge_id__resolve_post","parameters":[{"name":"pot_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Pot Id"}},{"name":"edge_id","in":"path","required":true,"schema":{"type":"string","title":"Edge Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveRequest"}}}},"responses":{"200":{"description":"Contradiction resolved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveResponse"}}}},"404":{"description":"POT or edge not found"},"400":{"description":"Edge is not a contradiction"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["contradiction","contradiction"],"summary":"Revert a contradiction resolution","description":"Revert a resolved contradiction back to active.\n\nThe edge type changes from 'resolved_contradiction' back to 'contradicts'.\nScore impacts from the resolution are reversed.\nStances are preserved (they remain as evidence).","operationId":"revert_resolution_pots__pot_id__edges__edge_id__resolve_delete","parameters":[{"name":"pot_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Pot Id"}},{"name":"edge_id","in":"path","required":true,"schema":{"type":"string","title":"Edge Id"}}],"responses":{"200":{"description":"Resolution reverted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveResponse"}}}},"404":{"description":"POT or edge not found"},"400":{"description":"Edge is not a resolved contradiction"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/pots/{pot_id}/contributors/{contributor_id}/actions":{"get":{"tags":["contributor-actions","contributor-actions"],"summary":"Get all actions by a contributor in a POT","description":"Get all actions a contributor has performed in a POT.\n\nReturns stances, curations, and resolutions filtered by contributor_id.\nKB2B uses this at POT load time to know what the user has already done.\n\nQuery params:\n- action_types: comma-separated filter (stances,curations,resolutions). Default: all.\n- since: only return actions after this datetime.","operationId":"get_contributor_actions_pots__pot_id__contributors__contributor_id__actions_get","parameters":[{"name":"pot_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Pot Id"}},{"name":"contributor_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Contributor Id"}},{"name":"action_types","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Action Types"}},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Since"}}],"responses":{"200":{"description":"Contributor actions retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContributorActionsResponse"}}}},"404":{"description":"POT not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/integrator/usage/events":{"post":{"tags":["usage"],"summary":"Record usage events","description":"Record a batch of integrator usage events.\n\nIntegrators push their own LLM token consumption.\nNo model or cost fields — only tokens and operation metadata.","operationId":"record_usage_events_integrator_usage_events_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordUsageEventsRequest"}}},"required":true},"responses":{"201":{"description":"Events recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordUsageEventsResponse"}}}},"400":{"description":"Invalid request"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/integrator/usage/summary":{"get":{"tags":["usage"],"summary":"Get workspace usage summary","description":"Get usage summary for a workspace.\n\nReturns token counts and event counts by operation and source.\nDoes NOT include model or cost information.","operationId":"get_usage_summary_integrator_usage_summary_get","parameters":[{"name":"workspace_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","description":"Workspace ID to query","title":"Workspace Id"},"description":"Workspace ID to query"},{"name":"period","in":"query","required":true,"schema":{"type":"string","minLength":6,"maxLength":8,"description":"Period: YYYYMM for monthly","title":"Period"},"description":"Period: YYYYMM for monthly"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageSummaryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/integrator/usage/workspace/{workspace_id}":{"delete":{"tags":["usage"],"summary":"Reset workspace usage","description":"Delete all usage rollups for a workspace.\n\nUsed by demo reset. Clears token consumption history for the workspace\nacross all periods. Requires the workspace to belong to the authenticated integrator.","operationId":"reset_workspace_usage_integrator_usage_workspace__workspace_id__delete","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/integrator/usage/workspaces":{"get":{"tags":["usage"],"summary":"Get cross-workspace usage","description":"Get usage summary across all workspaces for this integrator.\n\nReturns token counts per workspace. No cost information.","operationId":"get_workspaces_usage_integrator_usage_workspaces_get","parameters":[{"name":"period","in":"query","required":true,"schema":{"type":"string","minLength":6,"maxLength":6,"description":"Period: YYYYMM for monthly","title":"Period"},"description":"Period: YYYYMM for monthly"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspacesUsageResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/integrator/usage/token-quota":{"get":{"tags":["usage"],"summary":"Get token quota status for a workspace","description":"Returns the current month's token usage vs. limit for a workspace.\n\nUse this to check remaining quota before LLM operations or to display\na usage bar in the frontend. When `is_limited` is false, the workspace\nhas no token limit (unlimited).","operationId":"get_token_quota_integrator_usage_token_quota_get","parameters":[{"name":"workspace_id","in":"query","required":true,"schema":{"type":"string","format":"uuid","description":"Workspace ID to check","title":"Workspace Id"},"description":"Workspace ID to check"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenQuotaStatus"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/integrator/dashboard":{"get":{"tags":["dashboard"],"summary":"Get integrator consumption dashboard","description":"Returns an aggregated view of the integrator's consumption:\n- Total tokens used / limit / remaining for the current billing period\n- Usage percentage and days remaining\n- Top 10 workspaces by token consumption\n- Plan information (if applicable)\n\nUse this endpoint to build consumption dashboards in your frontend.","operationId":"get_dashboard_integrator_dashboard_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DashboardResponse"}}}}}}},"/auth/signup":{"post":{"tags":["auth"],"summary":"Register a new integrator","description":"Register a new integrator account via self-service.\n\nA verification email will be sent to the provided address.\nClick the link in the email to verify and receive your API key.","operationId":"signup_auth_signup_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/auth/verify":{"get":{"tags":["auth"],"summary":"Verify email and get API key","description":"Verify your email using the token from the magic link.\n\n**The API key is returned only once.** Store it securely.","operationId":"verify_email_auth_verify_get","parameters":[{"name":"token","in":"query","required":true,"schema":{"type":"string","description":"Verification token from email","title":"Token"},"description":"Verification token from email"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyEmailResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/auth/resend-verification":{"post":{"tags":["auth"],"summary":"Resend verification email","description":"Resend verification email for a pending account.","operationId":"resend_verification_auth_resend_verification_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResendVerificationRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Resend Verification Auth Resend Verification Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/integrator/billing/checkout":{"post":{"tags":["billing"],"summary":"Create Stripe checkout session or upgrade existing subscription","description":"If the integrator already has an active subscription, upgrades in-place. Otherwise creates a Stripe Checkout session.","operationId":"create_checkout_integrator_billing_checkout_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/integrator/billing/portal":{"post":{"tags":["billing"],"summary":"Create Stripe billing portal session","description":"Access the Stripe billing portal to manage subscription and payment methods.","operationId":"create_portal_integrator_billing_portal_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingPortalRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingPortalResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/integrator/billing/token-topup":{"post":{"tags":["billing"],"summary":"Purchase additional tokens","description":"Create a one-time payment checkout to add bonus tokens to your account.","operationId":"create_token_topup_integrator_billing_token_topup_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenTopupRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenTopupResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/billing/webhook":{"post":{"tags":["billing"],"summary":"Stripe webhook handler","description":"Receives Stripe webhook events. Authenticated via Stripe signature.","operationId":"stripe_webhook_billing_webhook_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"AddAxiomResponse":{"properties":{"fact_id":{"type":"string","title":"Fact Id"},"content":{"type":"string","title":"Content"},"pot_score":{"type":"number","title":"Pot Score","default":1.0},"level":{"type":"string","title":"Level","default":"CONSTITUTION"},"rationale":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rationale"},"keywords":{"items":{"type":"string"},"type":"array","title":"Keywords"},"fact_count":{"type":"integer","title":"Fact Count","description":"Total axiom count after addition"}},"type":"object","required":["fact_id","content","fact_count"],"title":"AddAxiomResponse","description":"Response after adding a new constitution axiom."},"AddRoleRequest":{"properties":{"role_title":{"type":"string","maxLength":200,"minLength":1,"title":"Role Title","description":"Job title"},"department":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Department","description":"Department or team"},"seniority":{"$ref":"#/components/schemas/SeniorityLevel","description":"Seniority level","default":"mid"},"expertise_areas":{"items":{"type":"string"},"type":"array","maxItems":20,"title":"Expertise Areas","description":"Areas of expertise"}},"type":"object","required":["role_title"],"title":"AddRoleRequest","description":"Request body for POST .../contributors/{contributor_id}/roles."},"AxiomWithEdges":{"properties":{"axiom":{"$ref":"#/components/schemas/ConstitutionAxiom"},"edges_out":{"items":{"$ref":"#/components/schemas/Edge"},"type":"array","title":"Edges Out"},"edges_in":{"items":{"$ref":"#/components/schemas/Edge"},"type":"array","title":"Edges In"},"connected_facts":{"items":{"$ref":"#/components/schemas/FactExtended"},"type":"array","title":"Connected Facts"},"total_edges":{"type":"integer","title":"Total Edges","default":0}},"type":"object","required":["axiom"],"title":"AxiomWithEdges","description":"Constitution axiom with its edges and connected facts (M18)."},"BillingPortalRequest":{"properties":{"return_url":{"type":"string","title":"Return Url","description":"URL to redirect after portal session"}},"type":"object","required":["return_url"],"title":"BillingPortalRequest","description":"Request to create a Stripe billing portal session."},"BillingPortalResponse":{"properties":{"portal_url":{"type":"string","title":"Portal Url"}},"type":"object","required":["portal_url"],"title":"BillingPortalResponse","description":"Response with Stripe billing portal URL."},"Body_upload_document_documents_upload_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"}},"type":"object","required":["file"],"title":"Body_upload_document_documents_upload_post"},"CAGSearchData":{"properties":{"results":{"items":{"$ref":"#/components/schemas/CAGSearchResultItem"},"type":"array","title":"Results","description":"Ranked search results"},"total_results":{"type":"integer","minimum":0.0,"title":"Total Results","description":"Total matching results found"}},"type":"object","required":["total_results"],"title":"CAGSearchData","description":"Data payload for CAG search response."},"CAGSearchMetadata":{"properties":{"pot_id":{"type":"string","title":"Pot Id","description":"POT identifier"},"query":{"type":"string","title":"Query","description":"Original query text"},"retrieval_strategy":{"type":"string","const":"CAG","title":"Retrieval Strategy","description":"Retrieval strategy used","default":"CAG"},"latency_ms":{"type":"integer","minimum":0.0,"title":"Latency Ms","description":"Response latency in milliseconds"},"cache_status":{"type":"string","enum":["hit","miss","initialized"],"title":"Cache Status","description":"Cache status for this request"}},"type":"object","required":["pot_id","query","latency_ms","cache_status"],"title":"CAGSearchMetadata","description":"Metadata for CAG search response."},"CAGSearchRequest":{"properties":{"query":{"type":"string","maxLength":500,"minLength":1,"title":"Query","description":"Query text for keyword/entity matching","examples":["What is POT Index?","How does Constitution work?"]},"top_k":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Top K","description":"Maximum results to return","default":10},"include_constitution":{"type":"boolean","title":"Include Constitution","description":"Include Constitution facts in search","default":true},"min_pot_score":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Min Pot Score","description":"Minimum POT Index threshold","default":0.0}},"type":"object","required":["query"],"title":"CAGSearchRequest","description":"Request body for CAG search endpoint.","example":{"include_constitution":true,"min_pot_score":0.0,"query":"What is POT Index?","top_k":10}},"CAGSearchResponse":{"properties":{"data":{"$ref":"#/components/schemas/CAGSearchData","description":"Search results data"},"confidence":{"$ref":"#/components/schemas/SearchConfidence","description":"Confidence metadata"},"metadata":{"$ref":"#/components/schemas/CAGSearchMetadata","description":"Request metadata"}},"type":"object","required":["data","confidence","metadata"],"title":"CAGSearchResponse","description":"Full CAG search response.","example":{"confidence":{"match_quality":0.92,"results_count":1,"suggestion":"sufficient","top_score":0.92},"data":{"results":[{"content":"POT Index assigns certainty scores 0-1","domain":"core","fact_id":"const_001","level":"CONSTITUTION","match_details":{"entity_score":1.0,"keyword_score":0.8,"matched_entities":["POT Index"],"matched_keywords":["pot","index"]},"pot_score":1.0,"score":0.92,"tags":["pot-index"]}],"total_results":1},"metadata":{"cache_status":"hit","latency_ms":12,"pot_id":"scipot-core","query":"What is POT Index?","retrieval_strategy":"CAG"}}},"CAGSearchResultItem":{"properties":{"fact_id":{"type":"string","title":"Fact Id","description":"Unique identifier of the fact"},"content":{"type":"string","title":"Content","description":"Full fact content"},"score":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Score","description":"Combined match score [0-1]"},"pot_score":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Pot Score","description":"POT Index certainty score [0-1]"},"level":{"type":"string","title":"Level","description":"POT Index level (CONSTITUTION, VERIFIED, SUPPORTED, etc.)"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain","description":"Fact domain classification"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Classification tags"},"match_details":{"$ref":"#/components/schemas/MatchDetails","description":"Score breakdown for transparency"}},"type":"object","required":["fact_id","content","score","pot_score","level","match_details"],"title":"CAGSearchResultItem","description":"Single CAG search result.","example":{"content":"POT Index assigns certainty scores 0-1 to facts","domain":"core","fact_id":"const_001","level":"CONSTITUTION","match_details":{"entity_score":1.0,"keyword_score":0.8,"matched_entities":["POT Index"],"matched_keywords":["pot","index"]},"pot_score":1.0,"score":0.92,"tags":["pot-index","scoring"]}},"CAGStatsResponse":{"properties":{"pot_id":{"type":"string","title":"Pot Id","description":"POT identifier"},"cache_stats":{"$ref":"#/components/schemas/CacheStatsData","description":"Cache size stats"},"hit_stats":{"$ref":"#/components/schemas/HitStatsData","description":"Hit/miss stats"},"timing":{"$ref":"#/components/schemas/TimingData","description":"Timing information"}},"type":"object","required":["pot_id","cache_stats","hit_stats","timing"],"title":"CAGStatsResponse","description":"Response for GET /cag/stats endpoint.","example":{"cache_stats":{"certainty_size":47,"constitution_size":5,"max_certainty_size":500,"threshold":0.85,"total_size":52},"hit_stats":{"cache_hits":142,"cache_misses":8,"hit_rate":0.947,"total_searches":150},"pot_id":"scipot-core","timing":{"initialized_at":"2026-01-20T10:25:00Z","last_refresh":"2026-01-20T11:00:00Z"}}},"CAGWarmResponse":{"properties":{"status":{"type":"string","enum":["warmed","already_warm"],"title":"Status","description":"Warm operation result"},"cache_stats":{"$ref":"#/components/schemas/WarmCacheStats","description":"Cache stats after warm"}},"type":"object","required":["status","cache_stats"],"title":"CAGWarmResponse","description":"Response for POST /cag/warm endpoint.","example":{"cache_stats":{"certainty_size":47,"constitution_size":5,"initialized_at":"2026-01-20T10:30:00Z","total_size":52},"status":"warmed"}},"CacheStatsData":{"properties":{"constitution_size":{"type":"integer","minimum":0.0,"title":"Constitution Size","description":"Number of Constitution facts in cache"},"certainty_size":{"type":"integer","minimum":0.0,"title":"Certainty Size","description":"Number of high-certainty facts in cache"},"total_size":{"type":"integer","minimum":0.0,"title":"Total Size","description":"Total cached facts"},"threshold":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Threshold","description":"POT Index threshold for high-certainty cache"},"max_certainty_size":{"type":"integer","minimum":0.0,"title":"Max Certainty Size","description":"Maximum facts in high-certainty cache"}},"type":"object","required":["constitution_size","certainty_size","total_size","threshold","max_certainty_size"],"title":"CacheStatsData","description":"Cache statistics."},"CertaintySummary":{"properties":{"total_facts":{"type":"integer","title":"Total Facts"},"constitution":{"type":"integer","title":"Constitution","default":0},"verified":{"type":"integer","title":"Verified","default":0},"extracted":{"type":"integer","title":"Extracted","default":0},"inferred":{"type":"integer","title":"Inferred","default":0},"pending":{"type":"integer","title":"Pending","default":0},"average_score":{"type":"number","title":"Average Score","default":0.0}},"type":"object","required":["total_facts"],"title":"CertaintySummary","description":"Distribution of facts by certainty level."},"CheckoutRequest":{"properties":{"plan":{"$ref":"#/components/schemas/IntegratorPlan","description":"Target plan to subscribe to"},"success_url":{"type":"string","title":"Success Url","description":"URL to redirect after successful checkout"},"cancel_url":{"type":"string","title":"Cancel Url","description":"URL to redirect on checkout cancellation"}},"type":"object","required":["plan","success_url","cancel_url"],"title":"CheckoutRequest","description":"Request to create a Stripe Checkout session."},"CheckoutResponse":{"properties":{"checkout_url":{"type":"string","title":"Checkout Url","description":"Checkout URL, or 'upgraded' if subscription was modified in-place"},"upgraded":{"type":"boolean","title":"Upgraded","description":"True when subscription was upgraded in-place (no checkout needed)","default":false}},"type":"object","required":["checkout_url"],"title":"CheckoutResponse","description":"Response with Stripe Checkout session URL or upgrade confirmation."},"Classification":{"properties":{"domain":{"type":"string","title":"Domain","description":"Domain category","default":"unknown"},"subdomain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subdomain","description":"Subdomain category"},"tags":{"items":{"type":"string"},"type":"array","maxItems":20,"title":"Tags","description":"Tags for search (max 20). Inherited from SourceMetadata.tags during ingestion."},"entity_mentions":{"items":{"type":"string"},"type":"array","title":"Entity Mentions","description":"Entities mentioned"}},"type":"object","title":"Classification","description":"Classification metadata for a fact."},"ClassificationResponse":{"properties":{"category":{"type":"string","title":"Category","description":"Query category (factual, semantic, relational, unknown)"},"confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Confidence","description":"Classification confidence [0-1]"},"suggested_strategy":{"type":"string","title":"Suggested Strategy","description":"Strategy suggested by classifier"},"reasoning":{"items":{"type":"string"},"type":"array","title":"Reasoning","description":"Explanation of classification decision"}},"type":"object","required":["category","confidence","suggested_strategy"],"title":"ClassificationResponse","description":"Query classification details."},"ConstitutionAxiom":{"properties":{"id":{"type":"string","title":"Id","description":"Unique axiom identifier (e.g., CONST#001)"},"pot_id":{"type":"string","format":"uuid","title":"Pot Id","description":"POT this axiom belongs to"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id","description":"Multi-tenant isolation"},"content":{"type":"string","minLength":1,"title":"Content","description":"The axiom statement"},"pot_score":{"type":"number","title":"Pot Score","description":"Always 1.0 for constitution","default":1.0},"level":{"$ref":"#/components/schemas/PotScoreLevel","description":"Always CONSTITUTION","default":"CONSTITUTION"},"created_by":{"type":"string","title":"Created By","description":"User who created this axiom"},"approved_by":{"type":"string","title":"Approved By","description":"User who approved this axiom"},"rationale":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rationale","description":"Why this axiom is foundational"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain","description":"Domain category"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Tags for search"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When axiom was created"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"When axiom was last updated"}},"additionalProperties":true,"type":"object","required":["id","pot_id","workspace_id","content","created_by","approved_by"],"title":"ConstitutionAxiom","description":"Constitution axiom - foundational truth in a POT.\n\nM7: Added for DynamoDB persistence.\nConstitution axioms are immutable facts with pot_score=1.0."},"ConstitutionFactInput":{"properties":{"content":{"type":"string","minLength":1,"title":"Content","description":"The axiom statement"},"title":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Title","description":"Short title (max 50 chars, hard limit 80). Auto-generated from content if not provided."},"rationale":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rationale","description":"Why this is foundational"},"keywords":{"items":{"type":"string"},"type":"array","title":"Keywords","description":"Tags for search"}},"type":"object","required":["content"],"title":"ConstitutionFactInput","description":"A constitution fact for API-driven POT creation.\n\nIDs are auto-assigned by SciPot — integrators only provide content."},"ConstitutionFactResponse":{"properties":{"id":{"type":"string","title":"Id"},"content":{"type":"string","title":"Content"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"pot_score":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Pot Score"},"level":{"type":"string","title":"Level"},"rationale":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rationale"},"keywords":{"items":{"type":"string"},"type":"array","title":"Keywords"}},"type":"object","required":["id","content","pot_score","level"],"title":"ConstitutionFactResponse","description":"Constitution fact for API responses.","examples":[{"content":"SciPot builds memory infrastructure for AI agents","id":"const_001","keywords":["infrastructure","memory","agents"],"level":"CONSTITUTION","pot_score":1.0,"rationale":"Core mission statement"}]},"ConstitutionResponse":{"properties":{"facts":{"items":{"$ref":"#/components/schemas/ConstitutionFactResponse"},"type":"array","title":"Facts"},"version":{"type":"string","title":"Version","default":"1.0"},"last_updated":{"type":"string","title":"Last Updated"},"approved_by":{"type":"string","title":"Approved By"},"fact_count":{"type":"integer","title":"Fact Count"}},"type":"object","required":["facts","last_updated","approved_by","fact_count"],"title":"ConstitutionResponse","description":"Constitution for API responses.","examples":[{"approved_by":"system","fact_count":3,"facts":[{"content":"SciPot builds memory infrastructure for AI agents","id":"const_001","level":"CONSTITUTION","pot_score":1.0}],"last_updated":"2026-01-06T10:30:45Z","version":"1.0"}]},"ConstitutionWithEdgesResponse":{"properties":{"pot_id":{"type":"string","format":"uuid","title":"Pot Id"},"axioms":{"items":{"$ref":"#/components/schemas/AxiomWithEdges"},"type":"array","title":"Axioms"},"total_axioms":{"type":"integer","title":"Total Axioms"},"total_edges":{"type":"integer","title":"Total Edges"},"total_edges_in_pot":{"type":"integer","title":"Total Edges In Pot","description":"Total edges in the POT (before axiom filtering). If > 0 but total_edges == 0, edges exist but don't reference axioms.","default":0}},"type":"object","required":["pot_id","axioms","total_axioms","total_edges"],"title":"ConstitutionWithEdgesResponse","description":"Response for constitution with edges endpoint (M18)."},"ContradictionItem":{"properties":{"fact_id_a":{"type":"string","title":"Fact Id A"},"fact_id_b":{"type":"string","title":"Fact Id B"},"content_a":{"type":"string","title":"Content A"},"content_b":{"type":"string","title":"Content B"},"weight":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Weight","description":"Contradiction edge weight"},"rationale":{"type":"string","title":"Rationale","description":"Explanation of the contradiction","default":""}},"type":"object","required":["fact_id_a","fact_id_b","content_a","content_b","weight"],"title":"ContradictionItem","description":"A contradiction between two facts."},"ContradictionPair":{"properties":{"fact_a_id":{"type":"string","title":"Fact A Id","description":"First fact ID"},"fact_a_content_snippet":{"type":"string","title":"Fact A Content Snippet","description":"First ~150 chars of fact A"},"fact_a_pot_score":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Fact A Pot Score"},"fact_b_id":{"type":"string","title":"Fact B Id","description":"Second fact ID"},"fact_b_content_snippet":{"type":"string","title":"Fact B Content Snippet","description":"First ~150 chars of fact B"},"fact_b_pot_score":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Fact B Pot Score"},"weight":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Weight","description":"Contradiction strength"},"rationale":{"type":"string","title":"Rationale","description":"Why these facts contradict","default":""},"edge_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Edge Id","description":"Edge ID for stance/resolution operations"},"stances_summary":{"anyOf":[{"$ref":"#/components/schemas/StancesSummary"},{"type":"null"}],"description":"Stance summary (only when include_stances=True)"},"resolution_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resolution Type","description":"Resolution type (confirmed_a, confirmed_b, both_valid, needs_update, dismissed)"},"resolution_notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resolution Notes","description":"Notes explaining the resolution"},"winner_fact_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Winner Fact Id","description":"The fact confirmed correct (convenience field derived from resolution_type)"}},"type":"object","required":["fact_a_id","fact_a_content_snippet","fact_a_pot_score","fact_b_id","fact_b_content_snippet","fact_b_pot_score","weight"],"title":"ContradictionPair","description":"A pair of facts that contradict each other, with POT scores for trust weighting."},"ContradictionStance":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique stance record ID"},"edge_id":{"type":"string","title":"Edge Id","description":"Edge this stance is about"},"pot_id":{"type":"string","format":"uuid","title":"Pot Id","description":"POT the edge belongs to"},"stance":{"$ref":"#/components/schemas/StanceType","description":"Which fact is confirmed or dismissed"},"contributor":{"$ref":"#/components/schemas/ContributorProfile","description":"Who submitted the stance"},"contributor_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Contributor Id","description":"Contributor registry ID (if registered)"},"expertise_evaluation":{"$ref":"#/components/schemas/ExpertiseEvaluation","description":"Expertise evaluation result"},"notes":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Notes","description":"Reasoning for the stance"},"score_delta":{"type":"number","title":"Score Delta","description":"Score change applied to affected fact","default":0.0},"score_before":{"type":"number","title":"Score Before","description":"POT Score before stance","default":0.0},"score_after":{"type":"number","title":"Score After","description":"POT Score after stance","default":0.0},"affected_fact_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Affected Fact Id","description":"Fact whose score was affected (None for dismiss)"},"opposing_score_delta":{"type":"number","title":"Opposing Score Delta","description":"Score change applied to opposing fact","default":0.0},"opposing_fact_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Opposing Fact Id","description":"Opposing fact whose score was penalized"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When stance was submitted"}},"type":"object","required":["edge_id","pot_id","stance","contributor","expertise_evaluation"],"title":"ContradictionStance","description":"Record of a stance taken on a contradiction edge.\n\nStored in DynamoDB for evidence accumulation and audit trail.\nEach stance represents one user's opinion about which fact is correct."},"ContributeRequest":{"properties":{"content":{"type":"string","maxLength":10000,"minLength":10,"title":"Content","description":"Knowledge content to contribute (will be extracted into facts)"},"contributor_id":{"type":"string","format":"uuid","title":"Contributor Id","description":"Contributor registry ID (must be a registered, active contributor)"},"run_post_ingestion":{"type":"boolean","title":"Run Post Ingestion","description":"Whether to run edge detection and score propagation after contribution","default":true},"influence_factor":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Influence Factor","description":"Integrator-defined seniority influence factor (0.0-1.0). Scales the contribution score range."}},"type":"object","required":["content","contributor_id"],"title":"ContributeRequest","description":"Request body for POST /pots/{pot_id}/facts/contribute."},"ContributeResponse":{"properties":{"pot_id":{"type":"string","format":"uuid","title":"Pot Id"},"facts_created":{"type":"integer","title":"Facts Created","description":"Number of facts extracted and saved"},"fact_ids":{"items":{"type":"string"},"type":"array","title":"Fact Ids","description":"IDs of created facts"},"avg_pot_score":{"type":"number","title":"Avg Pot Score","description":"Average POT Score of created facts"},"expertise_evaluation":{"$ref":"#/components/schemas/ExpertiseEvaluation","description":"How the contributor's expertise was evaluated"},"edges_created":{"type":"integer","title":"Edges Created","description":"Edges created by post-ingestion","default":0},"scores_updated":{"type":"integer","title":"Scores Updated","description":"Scores updated by propagation","default":0}},"type":"object","required":["pot_id","facts_created","avg_pot_score","expertise_evaluation"],"title":"ContributeResponse","description":"Response for POST /pots/{pot_id}/facts/contribute."},"ContributorActionsResponse":{"properties":{"stances":{"items":{"$ref":"#/components/schemas/StanceActionItem"},"type":"array","title":"Stances"},"curations":{"items":{"$ref":"#/components/schemas/CurationActionItem"},"type":"array","title":"Curations"},"resolutions":{"items":{"$ref":"#/components/schemas/ResolutionActionItem"},"type":"array","title":"Resolutions"}},"type":"object","title":"ContributorActionsResponse","description":"Response for GET /pots/{pot_id}/contributors/{contributor_id}/actions."},"ContributorListResponse":{"properties":{"contributors":{"items":{"$ref":"#/components/schemas/ContributorResponse"},"type":"array","title":"Contributors"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["contributors","total"],"title":"ContributorListResponse","description":"Response for GET /integrator/workspaces/{workspace_id}/contributors."},"ContributorProfile":{"properties":{"name":{"type":"string","maxLength":200,"minLength":1,"title":"Name","description":"Contributor display name"},"role":{"type":"string","maxLength":200,"minLength":1,"title":"Role","description":"Job title or role"},"seniority_level":{"$ref":"#/components/schemas/SeniorityLevel","description":"Seniority level for expertise weighting"},"department":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Department","description":"Department or team"},"expertise_areas":{"items":{"type":"string"},"type":"array","maxItems":20,"title":"Expertise Areas","description":"Areas of expertise (e.g., 'machine learning', 'oncology')"},"bio":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Bio","description":"Brief professional bio for LLM context"}},"type":"object","required":["name","role","seniority_level"],"title":"ContributorProfile","description":"Profile of a knowledge contributor or curator.\n\nSent by the integrator (KB2B) alongside contributions and curations.\nSciPot does NOT store user profiles — it evaluates expertise per-request."},"ContributorResponse":{"properties":{"contributor_id":{"type":"string","format":"uuid","title":"Contributor Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"external_id":{"type":"string","title":"External Id"},"display_name":{"type":"string","title":"Display Name"},"is_active":{"type":"boolean","title":"Is Active"},"current_role":{"anyOf":[{"$ref":"#/components/schemas/ContributorRoleResponse"},{"type":"null"}]},"role_history":{"anyOf":[{"items":{"$ref":"#/components/schemas/ContributorRoleResponse"},"type":"array"},{"type":"null"}],"title":"Role History"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["contributor_id","workspace_id","external_id","display_name","is_active","created_at","updated_at"],"title":"ContributorResponse","description":"Response for contributor endpoints."},"ContributorRoleResponse":{"properties":{"role_id":{"type":"string","format":"uuid","title":"Role Id"},"role_title":{"type":"string","title":"Role Title"},"department":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Department"},"seniority":{"$ref":"#/components/schemas/SeniorityLevel"},"expertise_areas":{"items":{"type":"string"},"type":"array","title":"Expertise Areas"},"started_at":{"type":"string","format":"date-time","title":"Started At"},"ended_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Ended At"}},"type":"object","required":["role_id","role_title","department","seniority","expertise_areas","started_at"],"title":"ContributorRoleResponse","description":"Role information in API responses."},"CreateContributorRequest":{"properties":{"external_id":{"type":"string","maxLength":200,"minLength":1,"title":"External Id","description":"External user ID from integrator"},"display_name":{"type":"string","maxLength":200,"minLength":1,"title":"Display Name","description":"Display name"},"role":{"$ref":"#/components/schemas/RoleFields","description":"Current role information"}},"type":"object","required":["external_id","display_name","role"],"title":"CreateContributorRequest","description":"Request body for POST /integrator/workspaces/{workspace_id}/contributors.\n\nUpsert semantics: if external_id already exists, updates display_name and\ncreates a new role if the role differs from the current one."},"CreatePOTFromJSONRequest":{"properties":{"name":{"type":"string","maxLength":200,"minLength":1,"title":"Name","description":"POT display name"},"slug":{"type":"string","maxLength":100,"minLength":1,"pattern":"^[a-z0-9-]+$","title":"Slug","description":"URL-friendly identifier"},"description":{"type":"string","title":"Description","description":"POT description","default":""},"domain":{"type":"string","title":"Domain","description":"Knowledge domain","default":"general"},"constitution":{"items":{"$ref":"#/components/schemas/ConstitutionFactInput"},"type":"array","maxItems":10,"minItems":3,"title":"Constitution","description":"Foundational axioms (3-10 facts)"}},"type":"object","required":["name","slug","constitution"],"title":"CreatePOTFromJSONRequest","description":"Request body for creating a POT from JSON payload (for remote integrators).","examples":[{"constitution":[{"content":"Acme Corp was founded in 2020","keywords":["founding","history"],"rationale":"Founding date is foundational"},{"content":"Acme Corp's mission is to build great products","rationale":"Mission statement"},{"content":"Acme Corp headquarters are in San Francisco","rationale":"Location is foundational"}],"description":"Internal knowledge for Acme Corp","domain":"business","name":"Company Knowledge Base","slug":"company-kb"}]},"CreateWorkspaceRequest":{"properties":{"name":{"type":"string","maxLength":200,"minLength":1,"title":"Name","description":"Workspace name"},"slug":{"type":"string","maxLength":100,"minLength":1,"pattern":"^[a-z0-9-]+$","title":"Slug","description":"URL-friendly slug"}},"type":"object","required":["name","slug"],"title":"CreateWorkspaceRequest","description":"Request to create a workspace for a tenant."},"CurateRequest":{"properties":{"action":{"$ref":"#/components/schemas/CurationAction","description":"Approve or disapprove the fact"},"contributor_id":{"type":"string","format":"uuid","title":"Contributor Id","description":"Contributor registry ID (must be a registered, active contributor)"},"rationale":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Rationale","description":"Reason for the curation action"},"influence_factor":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Influence Factor","description":"Integrator-defined seniority influence factor (0.0-1.0). Scales the curation delta directly."}},"type":"object","required":["action","contributor_id"],"title":"CurateRequest","description":"Request body for POST /pots/{pot_id}/facts/{fact_id}/curate."},"CurateResponse":{"properties":{"fact_id":{"type":"string","format":"uuid","title":"Fact Id"},"action":{"$ref":"#/components/schemas/CurationAction"},"contributor_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Contributor Id","description":"Contributor registry ID"},"score_before":{"type":"number","title":"Score Before"},"score_after":{"type":"number","title":"Score After"},"score_delta":{"type":"number","title":"Score Delta"},"expertise_evaluation":{"$ref":"#/components/schemas/ExpertiseEvaluation"},"influence_factor":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Influence Factor","description":"Integrator influence factor applied (if any)"},"validation_status":{"type":"string","title":"Validation Status","description":"Updated validation status"},"curation_id":{"type":"string","format":"uuid","title":"Curation Id","description":"ID of the curation record"}},"type":"object","required":["fact_id","action","score_before","score_after","score_delta","expertise_evaluation","validation_status","curation_id"],"title":"CurateResponse","description":"Response for POST /pots/{pot_id}/facts/{fact_id}/curate."},"CurationAction":{"type":"string","enum":["approve","disapprove"],"title":"CurationAction","description":"Actions a curator can take on a fact."},"CurationActionItem":{"properties":{"fact_id":{"type":"string","title":"Fact Id"},"action":{"type":"string","title":"Action"},"rationale":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rationale"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["fact_id","action","created_at"],"title":"CurationActionItem","description":"Curation action summary for bulk response."},"CurationListResponse":{"properties":{"fact_id":{"type":"string","format":"uuid","title":"Fact Id"},"curations":{"items":{"$ref":"#/components/schemas/CurationRecord"},"type":"array","title":"Curations"},"total":{"type":"integer","title":"Total"},"approve_count":{"type":"integer","title":"Approve Count","description":"Number of active approve curations","default":0},"disapprove_count":{"type":"integer","title":"Disapprove Count","description":"Number of active disapprove curations","default":0}},"type":"object","required":["fact_id","curations","total"],"title":"CurationListResponse","description":"Response for GET /pots/{pot_id}/facts/{fact_id}/curations."},"CurationRecord":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique curation record ID"},"pot_id":{"type":"string","format":"uuid","title":"Pot Id","description":"POT the fact belongs to"},"fact_id":{"type":"string","format":"uuid","title":"Fact Id","description":"Fact being curated"},"action":{"$ref":"#/components/schemas/CurationAction","description":"Approve or disapprove"},"contributor":{"$ref":"#/components/schemas/ContributorProfile","description":"Who performed the curation"},"contributor_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Contributor Id","description":"Contributor registry ID (if registered)"},"expertise_evaluation":{"$ref":"#/components/schemas/ExpertiseEvaluation","description":"Expertise evaluation result"},"rationale":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Rationale","description":"Why this action"},"score_delta":{"type":"number","title":"Score Delta","description":"Actual score change applied"},"score_before":{"type":"number","title":"Score Before","description":"POT Score before curation"},"score_after":{"type":"number","title":"Score After","description":"POT Score after curation"},"influence_factor":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Influence Factor","description":"Integrator influence factor applied (if any)"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When curated"},"revoked_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Revoked At","description":"When revoked, None if active"}},"type":"object","required":["pot_id","fact_id","action","contributor","expertise_evaluation","score_delta","score_before","score_after"],"title":"CurationRecord","description":"Record of a curation action on a fact.\n\nStored in DynamoDB for audit trail and diminishing returns calculation."},"DashboardResponse":{"properties":{"integrator_id":{"type":"string","format":"uuid","title":"Integrator Id"},"integrator_name":{"type":"string","title":"Integrator Name","default":""},"plan":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Plan","description":"Current plan (free/startup/growth/scale)"},"period":{"type":"string","title":"Period","description":"Current billing period (YYYYMM)"},"total_tokens_used":{"type":"integer","minimum":0.0,"title":"Total Tokens Used","default":0},"total_tokens_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Tokens Limit","description":"Monthly token limit. None if unlimited."},"tokens_remaining":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Tokens Remaining","description":"Tokens remaining. None if unlimited."},"usage_percentage":{"anyOf":[{"type":"number","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Usage Percentage","description":"Usage as percentage (0-100). None if unlimited."},"bonus_tokens":{"type":"integer","minimum":0.0,"title":"Bonus Tokens","default":0},"days_remaining_in_period":{"type":"integer","minimum":0.0,"title":"Days Remaining In Period"},"total_events":{"type":"integer","minimum":0.0,"title":"Total Events","default":0},"top_workspaces":{"items":{"$ref":"#/components/schemas/WorkspaceDashboardSummary"},"type":"array","title":"Top Workspaces","description":"Workspaces sorted by token consumption (top 10)"}},"type":"object","required":["integrator_id","period","days_remaining_in_period"],"title":"DashboardResponse","description":"Aggregated consumption dashboard for an integrator.\n\nComposes data from usage tracking, token quota, and workspace management\ninto a single convenient response."},"DetectedEdgeResponse":{"properties":{"from_id":{"type":"string","format":"uuid","title":"From Id"},"to_id":{"type":"string","format":"uuid","title":"To Id"},"type":{"$ref":"#/components/schemas/EdgeType"},"weight":{"type":"number","title":"Weight"},"rationale":{"type":"string","title":"Rationale"},"direction":{"type":"string","title":"Direction"}},"type":"object","required":["from_id","to_id","type","weight","rationale","direction"],"title":"DetectedEdgeResponse","description":"Single detected edge in response.\n\nUses from_id/to_id for consistency with Edge model."},"Document":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Document ID (UUID v7)"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id","description":"Workspace that owns this document"},"filename":{"type":"string","maxLength":500,"minLength":1,"title":"Filename","description":"Original filename or path"},"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content","description":"Inline text content (legacy/small docs)"},"content_hash":{"type":"string","title":"Content Hash","description":"SHA-256 hash for dedup"},"size_bytes":{"type":"integer","minimum":0.0,"title":"Size Bytes","description":"Content size in bytes"},"type":{"type":"string","enum":["markdown","text","pdf","html","docx","pptx","xlsx","image"],"title":"Type","description":"Document type","default":"markdown"},"mime_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mime Type","description":"MIME type of the original file"},"original_s3_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Original S3 Key","description":"S3 key for original file"},"markdown_s3_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Markdown S3 Key","description":"S3 key for converted markdown"},"original_size_bytes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Original Size Bytes","description":"Original file size in bytes"},"conversion_status":{"type":"string","enum":["not_required","pending","completed","failed"],"title":"Conversion Status","description":"Status of format conversion","default":"not_required"},"conversion_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Conversion Error","description":"Error message if conversion failed"},"converted_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Converted At","description":"When conversion completed"},"uploaded_by_contributor_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Uploaded By Contributor Id","description":"Contributor who uploaded this document (for ownership tracking)"},"author":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author","description":"Document author"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Tags for organization"},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url","description":"URL of the original source (e.g. Confluence, SharePoint, Google Drive)"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"User-provided description of the document"},"original_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Original Date","description":"Original creation date of the document (may differ from upload date)"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When document was first stored"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"Last update timestamp"},"extraction_history":{"items":{"$ref":"#/components/schemas/ExtractionRecord"},"type":"array","title":"Extraction History","description":"History of extractions performed"}},"type":"object","required":["id","workspace_id","filename","content_hash","size_bytes","created_at","updated_at"],"title":"Document","description":"Workspace-scoped document.\n\nDocuments are persisted after ingestion so they can be re-extracted\nto different POTs without re-uploading."},"DocumentContext":{"properties":{"title":{"type":"string","title":"Title","description":"Main topic or title of the document"},"key_entities":{"items":{"type":"string"},"type":"array","title":"Key Entities","description":"5-10 key entities mentioned in document"},"main_themes":{"items":{"type":"string"},"type":"array","title":"Main Themes","description":"3-5 main themes or topics discussed"},"document_type":{"type":"string","enum":["technical","conceptual","reference","guide","other"],"title":"Document Type","description":"Document type classification"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"ISO 639-1 language code of the document (e.g. 'es', 'en'). None if mixed-language or undetermined."}},"type":"object","required":["title","key_entities","main_themes","document_type"],"title":"DocumentContext","description":"Global context extracted from a document.","examples":[{"document_type":"technical","key_entities":["POT Index","SciPot","certainty scores","facts","provenance"],"language":"en","main_themes":["scoring system","knowledge validation","certainty measurement"],"title":"POT Index Specification"}]},"DocumentDetailResponse":{"properties":{"document":{"$ref":"#/components/schemas/Document"},"download_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Download Url","description":"Presigned URL for original file download"},"markdown_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Markdown Url","description":"Presigned URL for markdown download"}},"type":"object","required":["document"],"title":"DocumentDetailResponse","description":"Response for getting a single document."},"DocumentListItem":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"filename":{"type":"string","title":"Filename"},"content_hash":{"type":"string","title":"Content Hash"},"size_bytes":{"type":"integer","title":"Size Bytes"},"type":{"type":"string","enum":["markdown","text","pdf","html","docx","pptx","xlsx","image"],"title":"Type"},"mime_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mime Type"},"conversion_status":{"type":"string","enum":["not_required","pending","completed","failed"],"title":"Conversion Status","default":"not_required"},"uploaded_by_contributor_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Uploaded By Contributor Id"},"author":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","default":[]},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"original_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Original Date"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"extraction_count":{"type":"integer","title":"Extraction Count","description":"Number of extractions performed","default":0}},"type":"object","required":["id","workspace_id","filename","content_hash","size_bytes","type","created_at","updated_at"],"title":"DocumentListItem","description":"Document metadata without content (for list endpoints)."},"DocumentListResponse":{"properties":{"documents":{"items":{"$ref":"#/components/schemas/DocumentListItem"},"type":"array","title":"Documents"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","required":["documents"],"title":"DocumentListResponse","description":"Response for listing documents."},"DocumentLocation":{"properties":{"page_number":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Page Number","description":"Page number (1-indexed). PDF: page. PPTX: slide number."},"section_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Section Path","description":"Heading breadcrumb, e.g. '## Resultados > ### Q3 2024'."},"source_text":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Source Text","description":"Verbatim text excerpt from the document this fact was derived from."},"sheet_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sheet Name","description":"XLSX sheet (tab) name where the fact was found."},"row_number":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Row Number","description":"XLSX row number (1-indexed)."},"cell_ref":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cell Ref","description":"XLSX cell reference, e.g. 'B7' or 'B7:D7'."}},"type":"object","title":"DocumentLocation","description":"Location metadata tracing a fact back to its source in the document.\n\nPopulated during ingestion when document_index_enabled=True.\nAvailable fields depend on document format:\n- PDF: page_number, section_path, source_text\n- DOCX: section_path, source_text (no page_number without LibreOffice)\n- PPTX: page_number (slide), section_path, source_text\n- XLSX: sheet_name, row_number, cell_ref, source_text\n- MD/TXT: section_path, source_text"},"DocumentUpdateRequest":{"properties":{"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"author":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author"},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tags"},"original_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Original Date"}},"type":"object","title":"DocumentUpdateRequest","description":"Request for partial document update."},"DocumentUpdateResponse":{"properties":{"document":{"$ref":"#/components/schemas/Document"}},"type":"object","required":["document"],"title":"DocumentUpdateResponse","description":"Response for document update."},"DocumentUploadResponse":{"properties":{"document_id":{"type":"string","format":"uuid","title":"Document Id"},"filename":{"type":"string","title":"Filename"},"size_bytes":{"type":"integer","title":"Size Bytes"},"type":{"type":"string","title":"Type"},"conversion_status":{"type":"string","title":"Conversion Status"},"message":{"type":"string","title":"Message","default":"Document uploaded successfully"}},"type":"object","required":["document_id","filename","size_bytes","type","conversion_status"],"title":"DocumentUploadResponse","description":"Response for document upload."},"Edge":{"properties":{"id":{"type":"string","title":"Id","description":"Unique edge identifier"},"pot_id":{"type":"string","format":"uuid","title":"Pot Id","description":"POT this edge belongs to"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id","description":"Workspace this edge belongs to"},"from_id":{"type":"string","format":"uuid","title":"From Id","description":"Source fact ID (A in A → B)"},"to_id":{"type":"string","format":"uuid","title":"To Id","description":"Target fact ID (B in A → B)"},"type":{"$ref":"#/components/schemas/EdgeType","description":"Type of semantic relationship"},"weight":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Weight","description":"Confidence in relationship (0.0-1.0)"},"rationale":{"type":"string","title":"Rationale","description":"Brief explanation of why this relationship exists","default":""},"detected_by":{"type":"string","title":"Detected By","description":"Detector/model that identified this edge","default":"edge-detector-v1"},"confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Confidence","description":"Detection confidence (0.0-1.0)","default":0.0},"validation_status":{"type":"string","title":"Validation Status","description":"Validation status (auto-approved, pending, validated, rejected)","default":"auto-approved"},"resolution_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resolution Type","description":"Resolution type (confirmed_a, confirmed_b, both_valid, needs_update, dismissed)"},"resolved_by_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resolved By Name","description":"Name of the person who resolved the contradiction"},"resolved_by_role":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resolved By Role","description":"Role of the person who resolved the contradiction"},"resolved_by_contributor_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Resolved By Contributor Id","description":"Contributor registry ID of the person who resolved the contradiction"},"resolved_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Resolved At","description":"When the contradiction was resolved"},"resolution_notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resolution Notes","description":"Notes about the resolution"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"}},"additionalProperties":true,"type":"object","required":["id","pot_id","workspace_id","from_id","to_id","type","weight"],"title":"Edge","description":"Semantic relationship between two facts.\n\nDirectionality: from_id → to_id\nExample: \"Fact A supports Fact B\" → Edge(from_id=A, to_id=B, type=SUPPORTS)\n\nThis model is used for persistence and API responses. The workbench uses\nits own Edge model which will be unified in M8+."},"EdgeCreate":{"properties":{"from_id":{"type":"string","format":"uuid","title":"From Id"},"to_id":{"type":"string","format":"uuid","title":"To Id"},"type":{"$ref":"#/components/schemas/EdgeType"},"weight":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Weight"},"rationale":{"type":"string","title":"Rationale","default":""},"detected_by":{"type":"string","title":"Detected By","default":"manual"},"confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Confidence","default":0.0}},"type":"object","required":["from_id","to_id","type","weight"],"title":"EdgeCreate","description":"Edge creation request schema."},"EdgeDetectMetadata":{"properties":{"pairs_analyzed":{"type":"integer","title":"Pairs Analyzed"},"edges_found":{"type":"integer","title":"Edges Found"},"edges_saved":{"type":"integer","title":"Edges Saved","default":0},"edges_updated":{"type":"integer","title":"Edges Updated","default":0},"duration_ms":{"type":"integer","title":"Duration Ms"},"model":{"type":"string","title":"Model"}},"type":"object","required":["pairs_analyzed","edges_found","duration_ms","model"],"title":"EdgeDetectMetadata","description":"Metadata about edge detection run."},"EdgeDetectRequest":{"properties":{"fact_ids":{"items":{"type":"string","format":"uuid"},"type":"array","maxItems":100,"minItems":1,"title":"Fact Ids","description":"Fact IDs to analyze for relationships"},"include_constitution":{"type":"boolean","title":"Include Constitution","description":"Include constitution axioms in analysis","default":true},"auto_save":{"type":"boolean","title":"Auto Save","description":"Persist detected edges automatically","default":false},"min_weight":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Min Weight","description":"Minimum weight threshold for edges","default":0.2},"batch_size":{"type":"integer","maximum":20.0,"minimum":1.0,"title":"Batch Size","description":"Facts per batch LLM call for edge detection. Overrides server default (edge_detection_batch_size setting).","default":8}},"type":"object","required":["fact_ids"],"title":"EdgeDetectRequest","description":"Request for edge detection endpoint.\n\nMSP Context: M9 - Edge Detection Backend Migration"},"EdgeDetectResponse":{"properties":{"edges":{"items":{"$ref":"#/components/schemas/DetectedEdgeResponse"},"type":"array","title":"Edges"},"metadata":{"$ref":"#/components/schemas/EdgeDetectMetadata"}},"type":"object","required":["edges","metadata"],"title":"EdgeDetectResponse","description":"Response from edge detection endpoint."},"EdgeListResponse":{"properties":{"edges":{"items":{"$ref":"#/components/schemas/Edge"},"type":"array","title":"Edges"},"total":{"type":"integer","title":"Total"},"pot_id":{"type":"string","format":"uuid","title":"Pot Id"}},"type":"object","required":["edges","total","pot_id"],"title":"EdgeListResponse","description":"Response for list edges endpoint."},"EdgeSummary":{"properties":{"total_in":{"type":"integer","minimum":0.0,"title":"Total In","description":"Total incoming edges","default":0},"total_out":{"type":"integer","minimum":0.0,"title":"Total Out","description":"Total outgoing edges","default":0},"by_type":{"additionalProperties":{"$ref":"#/components/schemas/EdgeTypeCounts"},"type":"object","title":"By Type","description":"Edge counts broken down by type (e.g. supports, contradicts)"}},"type":"object","title":"EdgeSummary","description":"Denormalized edge count summary stored on each fact.\n\nEnables KB2B to display edge counts per fact without extra API calls.\nUpdated atomically when edges are created or deleted."},"EdgeType":{"type":"string","enum":["supports","contradicts","resolved_contradiction","refines","derives_from","is_part_of","extends","cites","related_to"],"title":"EdgeType","description":"Types of semantic relationships between facts.\n\nM7 uses a simplified subset. Full taxonomy in edge-types.md will be\nimplemented in M8+ when GraphRAG is introduced."},"EdgeTypeCounts":{"properties":{"in":{"type":"integer","minimum":0.0,"title":"In","default":0},"out":{"type":"integer","minimum":0.0,"title":"Out","default":0}},"type":"object","title":"EdgeTypeCounts","description":"In/out edge counts for a single edge type."},"EpistemicBriefingResponse":{"properties":{"certainty_summary":{"$ref":"#/components/schemas/CertaintySummary"},"high_confidence_facts":{"items":{"type":"string"},"type":"array","title":"High Confidence Facts","description":"Fact references that can be stated boldly"},"hedged_facts":{"items":{"type":"string"},"type":"array","title":"Hedged Facts","description":"Fact references needing qualification"},"contradictions":{"items":{"type":"string"},"type":"array","title":"Contradictions","description":"Descriptions of contradictions found"},"knowledge_gaps":{"items":{"type":"string"},"type":"array","title":"Knowledge Gaps","description":"Identified gaps in available knowledge"},"provenance_notes":{"items":{"type":"string"},"type":"array","title":"Provenance Notes","description":"Notes about source quality and types"}},"type":"object","required":["certainty_summary"],"title":"EpistemicBriefingResponse","description":"Epistemic briefing included in synthesis response."},"ExpertiseEvaluation":{"properties":{"relevance_score":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Relevance Score","description":"How relevant the contributor's expertise is (0.0-1.0)"},"method":{"type":"string","title":"Method","description":"Evaluation method used: 'heuristic' or 'llm'"},"matched_areas":{"items":{"type":"string"},"type":"array","title":"Matched Areas","description":"Expertise areas that matched the fact domain"},"reasoning":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reasoning","description":"LLM reasoning for the evaluation (if method=llm)"}},"type":"object","required":["relevance_score","method"],"title":"ExpertiseEvaluation","description":"Result of evaluating a contributor's expertise relative to a fact's domain."},"ExtractFromDocumentRequest":{"properties":{"document_id":{"type":"string","format":"uuid","title":"Document Id","description":"ID of the stored document to extract from"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"ISO 639-1 override for extraction language. Falls back to POT default and then auto-detect when omitted."}},"type":"object","required":["document_id"],"title":"ExtractFromDocumentRequest","description":"Request to re-extract facts from an already-stored document."},"ExtractionRecord":{"properties":{"pot_id":{"type":"string","format":"uuid","title":"Pot Id","description":"POT where facts were extracted to"},"job_id":{"type":"string","format":"uuid","title":"Job Id","description":"Ingestion job ID"},"facts_created":{"type":"integer","minimum":0.0,"title":"Facts Created","description":"Number of facts created"},"extracted_at":{"type":"string","format":"date-time","title":"Extracted At","description":"When extraction was performed"}},"type":"object","required":["pot_id","job_id","facts_created","extracted_at"],"title":"ExtractionRecord","description":"Record of a fact extraction performed on a document."},"FactExtended":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique identifier (UUID)"},"pot_id":{"type":"string","format":"uuid","title":"Pot Id","description":"POT this fact belongs to"},"workspace_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Workspace Id","description":"Multi-tenant isolation. Defaults to DEV_WORKSPACE_ID if None."},"content":{"type":"string","minLength":1,"title":"Content","description":"The actual claim or statement"},"title":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Title","description":"Short title (max 50 chars, hard limit 80) for graph node labels. Generated by LLM during extraction. None for legacy facts."},"content_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content Hash","description":"SHA-256 hash of content for deduplication"},"pot_score":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Pot Score","description":"Certainty score (0.0-1.0, where 1.0 = CONSTITUTION)"},"original_pot_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Original Pot Score","description":"Pre-propagation POT Score. None if propagation hasn't run."},"level":{"$ref":"#/components/schemas/PotScoreLevel","description":"Category based on pot_score range"},"embedding_model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Embedding Model","description":"Embedding model used, e.g. text-embedding-3-small"},"provenance":{"$ref":"#/components/schemas/Provenance","description":"Source and origin information"},"classification":{"$ref":"#/components/schemas/Classification","description":"Domain and entity classification"},"status":{"type":"string","title":"Status","description":"Processing status (processing, ready, error)","default":"processing"},"validation_status":{"type":"string","title":"Validation Status","description":"Validation status (pending, validated, disputed, rejected)","default":"pending"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When fact was created"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"When fact was last updated"},"valid_from":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Valid From","description":"When the fact started being true"},"valid_until":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Valid Until","description":"When the fact stopped being true"},"decay_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Decay Rate","description":"Temporal decay rate per day (null if no decay)"},"document_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Document Id","description":"Document UUID this fact was extracted from. None for constitution facts and inline ingestion."},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"ISO 639-1 language code of the fact content (e.g. 'es', 'en'). Inherited from document language detection during extraction."},"location":{"anyOf":[{"$ref":"#/components/schemas/DocumentLocation"},{"type":"null"}],"description":"Page, section and source text evidence. None when document_index_enabled=False."},"version":{"type":"integer","title":"Version","description":"Version number (increments on update)","default":1},"flags":{"items":{"type":"string"},"type":"array","title":"Flags","description":"Special flags (needs_review, deprecated, etc.)"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes","description":"Internal notes"},"edge_summary":{"$ref":"#/components/schemas/EdgeSummary","description":"Denormalized edge count summary. Updated atomically on edge mutations."}},"additionalProperties":true,"type":"object","required":["id","pot_id","content","pot_score","level","provenance"],"title":"FactExtended","description":"Extended fact representation with full metadata for ingestion pipeline.\n\nThis model includes provenance, classification, and temporal fields\nneeded during document ingestion and fact processing.\n\nM7 Update: Added embedding support for semantic search.\nNote: embedding field is TRANSIENT (not persisted to DynamoDB).\n      Only populated during embedding generation workflows.\n      Embeddings stored in vector store only.\n      Only embedding_model is persisted as metadata reference."},"FactListResponse":{"properties":{"pot_id":{"type":"string","format":"uuid","title":"Pot Id"},"facts":{"items":{"$ref":"#/components/schemas/FactExtended"},"type":"array","title":"Facts"},"total":{"type":"integer","title":"Total","description":"Total facts matching filters (ignoring pagination)"},"limit":{"type":"integer","title":"Limit","description":"Page size requested"},"offset":{"type":"integer","title":"Offset","description":"Pagination offset"},"has_more":{"type":"boolean","title":"Has More","description":"Whether more results exist beyond this page"}},"type":"object","required":["pot_id","facts","total","limit","offset","has_more"],"title":"FactListResponse","description":"Response for list facts endpoint."},"FactProvenance":{"properties":{"type":{"type":"string","title":"Type","description":"Source type: extracted, manual, inferred, imported"},"sources":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Sources","description":"Source documents with id, type, reference, path"}},"type":"object","required":["type"],"title":"FactProvenance","description":"Provenance information for a synthesized fact."},"FactWithRelationsResponse":{"properties":{"fact":{"$ref":"#/components/schemas/FactExtended"},"edges_out":{"items":{},"type":"array","title":"Edges Out","description":"Outgoing edges"},"edges_in":{"items":{},"type":"array","title":"Edges In","description":"Incoming edges"},"connected_facts":{"items":{"$ref":"#/components/schemas/FactExtended"},"type":"array","title":"Connected Facts","description":"Paginated slice of related facts (1-hop neighbors)"},"total_edges_out":{"type":"integer","title":"Total Edges Out","description":"Count of outgoing edges","default":0},"total_edges_in":{"type":"integer","title":"Total Edges In","description":"Count of incoming edges","default":0},"total_related_facts":{"type":"integer","title":"Total Related Facts","description":"Total distinct related facts (uncapped) — for pagination UI","default":0}},"type":"object","required":["fact"],"title":"FactWithRelationsResponse","description":"Response for fact with all its relations (M18).\n\n`connected_facts` is the paginated slice of 1-hop neighbors. `total_*`\nfields reflect uncapped totals so consumers can render \"Show N more\"\naffordances."},"GraphDocument":{"properties":{"id":{"type":"string","title":"Id"},"filename":{"type":"string","title":"Filename"},"type":{"type":"string","title":"Type"},"facts_count":{"type":"integer","title":"Facts Count","default":0},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"}},"type":"object","required":["id","filename","type"],"title":"GraphDocument","description":"A document reference in the POT graph."},"GraphEdge":{"properties":{"id":{"type":"string","title":"Id"},"from_id":{"type":"string","title":"From Id"},"to_id":{"type":"string","title":"To Id"},"type":{"type":"string","title":"Type"},"weight":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Weight"},"confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Confidence","default":0.0},"rationale":{"type":"string","title":"Rationale","default":""},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"}},"type":"object","required":["id","from_id","to_id","type","weight"],"title":"GraphEdge","description":"An edge in the POT knowledge graph."},"GraphNode":{"properties":{"id":{"type":"string","title":"Id","description":"Fact UUID"},"title":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Title","description":"Short label for graph node (max 80 chars)"},"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content","description":"Full fact content (only if include_content=true)"},"pot_score":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Pot Score"},"original_pot_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Original Pot Score","description":"Pre-propagation score (null if not propagated)"},"level":{"type":"string","title":"Level"},"node_type":{"type":"string","title":"Node Type","description":"constitution | extracted | inferred | manual"},"document_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Id","description":"Source document UUID (null for constitution/manual)"},"provenance_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provenance Type","description":"extracted | inferred | manual | imported"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"}},"type":"object","required":["id","pot_score","level","node_type"],"title":"GraphNode","description":"A node in the POT knowledge graph."},"GraphStats":{"properties":{"total_nodes":{"type":"integer","title":"Total Nodes","default":0},"total_edges":{"type":"integer","title":"Total Edges","default":0},"by_level":{"additionalProperties":{"type":"integer"},"type":"object","title":"By Level"},"by_edge_type":{"additionalProperties":{"type":"integer"},"type":"object","title":"By Edge Type"},"contradictions_count":{"type":"integer","title":"Contradictions Count","default":0},"avg_pot_score":{"type":"number","title":"Avg Pot Score","default":0.0},"propagation_applied":{"type":"boolean","title":"Propagation Applied","default":false}},"type":"object","title":"GraphStats","description":"Aggregate stats for the POT graph."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HealthResponse":{"properties":{"status":{"type":"string","const":"healthy","title":"Status"},"timestamp":{"type":"string","format":"date-time","title":"Timestamp"},"version":{"type":"string","title":"Version","default":"0.1.0"}},"type":"object","required":["status","timestamp"],"title":"HealthResponse","description":"Health check response."},"HitStatsData":{"properties":{"total_searches":{"type":"integer","minimum":0.0,"title":"Total Searches","description":"Total search operations"},"cache_hits":{"type":"integer","minimum":0.0,"title":"Cache Hits","description":"Searches that found results"},"cache_misses":{"type":"integer","minimum":0.0,"title":"Cache Misses","description":"Searches with no results"},"hit_rate":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Hit Rate","description":"Cache hit rate [0-1]"}},"type":"object","required":["total_searches","cache_hits","cache_misses","hit_rate"],"title":"HitStatsData","description":"Cache hit/miss statistics."},"IngestionAccepted":{"properties":{"job_id":{"type":"string","format":"uuid","title":"Job Id","description":"Unique identifier for this ingestion job"},"pot_id":{"type":"string","format":"uuid","title":"Pot Id","description":"Target POT ID"},"status":{"type":"string","const":"pending","title":"Status","description":"Job status (always 'pending' for initial response)","default":"pending"},"message":{"type":"string","title":"Message","description":"Human-readable status message","default":"Document ingestion queued"}},"type":"object","required":["job_id","pot_id"],"title":"IngestionAccepted","description":"Response for POST /ingest (202 Accepted).","examples":[{"job_id":"01JH8KQMW3PG0HXNZV2QRST9YZ","message":"Document ingestion queued","pot_id":"01JH8KQMW3PG0HXNZV2QRST9YX","status":"pending"}]},"IngestionPhase":{"type":"string","enum":["extracting","indexing","detecting_edges","propagating_scores"],"title":"IngestionPhase","description":"Phases of the ingestion pipeline (M17)."},"IngestionRequest":{"properties":{"content":{"type":"string","maxLength":102400,"minLength":1,"title":"Content","description":"Document content (max 100KB)"},"source":{"$ref":"#/components/schemas/SourceMetadata","description":"Metadata about the document source"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"ISO 639-1 override for extraction language. When provided, skips auto-detection and forces facts + edge rationales into this language. Falls back to POT default and then auto-detect when omitted."}},"type":"object","required":["content","source"],"title":"IngestionRequest","description":"Request to ingest a document into a POT.","examples":[{"content":"# Document Title\n\nContent here...","source":{"author":"sebas","created_at":"2026-01-07T10:00:00Z","path":"docs/architecture.md","type":"markdown"}}]},"IntegratorPlan":{"type":"string","enum":["free","startup","growth","scale"],"title":"IntegratorPlan","description":"Available integrator plans."},"JobError":{"properties":{"code":{"type":"string","title":"Code","description":"Error code (LLM_RATE_LIMIT, LLM_TIMEOUT, etc.)"},"message":{"type":"string","title":"Message","description":"Human-readable error message"},"step":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Step","description":"Step where failure occurred"},"retryable":{"type":"boolean","title":"Retryable","description":"Whether job can be retried","default":false}},"type":"object","required":["code","message"],"title":"JobError","description":"Error info when job fails."},"JobListResponse":{"properties":{"jobs":{"items":{"$ref":"#/components/schemas/JobResponse"},"type":"array","title":"Jobs"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["jobs","total"],"title":"JobListResponse","description":"Response for listing jobs."},"JobProgress":{"properties":{"current_step":{"type":"string","title":"Current Step","description":"Current processing step"},"chunks_total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Chunks Total","description":"Total chunks to process"},"chunks_done":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Chunks Done","description":"Chunks processed so far"},"facts_extracted":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Facts Extracted","description":"Facts extracted so far"},"phase":{"anyOf":[{"$ref":"#/components/schemas/IngestionPhase"},{"type":"null"}],"description":"Current pipeline phase"},"phase_index":{"anyOf":[{"type":"integer","maximum":4.0,"minimum":1.0},{"type":"null"}],"title":"Phase Index","description":"Phase index (1-based: 1=extracting, 2=indexing, ...)"},"phases_total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Phases Total","description":"Total phases (always 4 for ingestion)"},"phase_detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phase Detail","description":"Sub-step detail within current phase"},"overall_percent":{"anyOf":[{"type":"integer","maximum":100.0,"minimum":0.0},{"type":"null"}],"title":"Overall Percent","description":"Overall progress estimate 0-100"}},"type":"object","required":["current_step"],"title":"JobProgress","description":"Progress info for long-running jobs."},"JobResponse":{"properties":{"job_id":{"type":"string","format":"uuid","title":"Job Id"},"pot_id":{"type":"string","format":"uuid","title":"Pot Id"},"status":{"$ref":"#/components/schemas/JobStatus"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"progress":{"anyOf":[{"$ref":"#/components/schemas/JobProgress"},{"type":"null"}]},"result":{"anyOf":[{"$ref":"#/components/schemas/JobResult"},{"type":"null"}]},"error":{"anyOf":[{"$ref":"#/components/schemas/JobError"},{"type":"null"}]},"poll_interval_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Poll Interval Ms","description":"Suggested polling interval in milliseconds"}},"type":"object","required":["job_id","pot_id","status","created_at","updated_at"],"title":"JobResponse","description":"Full job status response."},"JobResult":{"properties":{"chunks_processed":{"type":"integer","minimum":0.0,"title":"Chunks Processed"},"facts_created":{"type":"integer","minimum":0.0,"title":"Facts Created"},"fact_ids":{"items":{"type":"string"},"type":"array","title":"Fact Ids","description":"IDs of created facts"},"facts_duplicated":{"type":"integer","minimum":0.0,"title":"Facts Duplicated"},"document_context":{"$ref":"#/components/schemas/DocumentContext"},"processing_time_ms":{"type":"integer","minimum":0.0,"title":"Processing Time Ms"},"extraction_audit":{"anyOf":[{},{"type":"null"}],"title":"Extraction Audit","description":"Audit data for extraction and deduplication (ExtractionAudit type)"},"edges_created":{"type":"integer","minimum":0.0,"title":"Edges Created","description":"Constitution edges created","default":0},"scores_updated":{"type":"integer","minimum":0.0,"title":"Scores Updated","description":"Facts with updated POT Scores","default":0}},"type":"object","required":["chunks_processed","facts_created","facts_duplicated","document_context","processing_time_ms"],"title":"JobResult","description":"Result when job completes successfully."},"JobStatus":{"type":"string","enum":["pending","processing","completed","failed"],"title":"JobStatus","description":"Job lifecycle states."},"MatchDetails":{"properties":{"keyword_score":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Keyword Score","description":"Normalized keyword match score [0-1]"},"entity_score":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Entity Score","description":"Normalized entity match score [0-1]"},"matched_keywords":{"items":{"type":"string"},"type":"array","title":"Matched Keywords","description":"Keywords that matched from the query"},"matched_entities":{"items":{"type":"string"},"type":"array","title":"Matched Entities","description":"Entities that matched from the query"}},"type":"object","required":["keyword_score","entity_score"],"title":"MatchDetails","description":"Score breakdown for a CAG match result."},"OperationSummary":{"properties":{"prompt_tokens":{"type":"integer","title":"Prompt Tokens","default":0},"completion_tokens":{"type":"integer","title":"Completion Tokens","default":0},"events":{"type":"integer","title":"Events","default":0}},"type":"object","title":"OperationSummary","description":"Operation breakdown visible to integrators (no cost)."},"POTListResponse":{"properties":{"pots":{"items":{"$ref":"#/components/schemas/POTResponse"},"type":"array","title":"Pots"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["pots","total"],"title":"POTListResponse","description":"Response for listing POTs.","examples":[{"pots":[{"created_at":"2026-01-06T10:30:45.123456Z","description":"A POT about SciPot itself","id":"018d1e8c-7b29-7a3e-8c1d-5e9a1c2d3e4f","name":"SciPot Meta-POT","slug":"scipot-pot","updated_at":"2026-01-06T10:30:45.123456Z","workspace_id":"550e8400-e29b-41d4-a716-446655440000"}],"total":1}]},"POTResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"slug":{"type":"string","title":"Slug"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"constitution":{"$ref":"#/components/schemas/ConstitutionResponse"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","slug","workspace_id","name","description","constitution","created_at","updated_at"],"title":"POTResponse","description":"POT for API responses.","examples":[{"constitution":{"approved_by":"system","fact_count":3,"facts":[{"content":"SciPot builds memory infrastructure for AI agents","id":"const_001","level":"CONSTITUTION","pot_score":1.0}],"last_updated":"2026-01-06T10:30:45Z","version":"1.0"},"created_at":"2026-01-06T10:30:45.123456Z","description":"A POT about SciPot itself","id":"018d1e8c-7b29-7a3e-8c1d-5e9a1c2d3e4f","name":"SciPot Meta-POT","slug":"scipot-pot","updated_at":"2026-01-06T10:30:45.123456Z","workspace_id":"550e8400-e29b-41d4-a716-446655440000"}]},"POTStatsResponse":{"properties":{"total_facts":{"type":"integer","title":"Total Facts","description":"Total facts in the POT (uncapped)","default":0},"constitution_count":{"type":"integer","title":"Constitution Count","description":"Number of constitution axioms","default":0},"score_distribution":{"$ref":"#/components/schemas/ScoreDistribution","description":"Count of facts per POT score level"},"average_score":{"type":"number","title":"Average Score","description":"Approximate average POT score, computed from level midpoints. Exact within ~0.1 for typical distributions; this avoids loading all fact rows.","default":0.0}},"type":"object","title":"POTStatsResponse","description":"Aggregated statistics for a POT (M22)."},"PotGraphResponse":{"properties":{"pot_id":{"type":"string","format":"uuid","title":"Pot Id"},"pot_name":{"type":"string","title":"Pot Name"},"nodes":{"items":{"$ref":"#/components/schemas/GraphNode"},"type":"array","title":"Nodes"},"edges":{"items":{"$ref":"#/components/schemas/GraphEdge"},"type":"array","title":"Edges"},"documents":{"items":{"$ref":"#/components/schemas/GraphDocument"},"type":"array","title":"Documents"},"stats":{"$ref":"#/components/schemas/GraphStats"}},"type":"object","required":["pot_id","pot_name","nodes","edges","documents","stats"],"title":"PotGraphResponse","description":"Full graph response for GET /pots/{pot_id}/graph."},"PotScoreLevel":{"type":"string","enum":["CONSTITUTION","VERIFIED","SUPPORTED","INFERRED","HYPOTHESIS","SPECULATION"],"title":"PotScoreLevel","description":"POT Index levels matching score ranges."},"PropagationDetailResponse":{"properties":{"fact_id":{"type":"string","title":"Fact Id"},"original_score":{"type":"number","title":"Original Score"},"adjusted_score":{"type":"number","title":"Adjusted Score"},"reason":{"type":"string","title":"Reason"},"edge_id":{"type":"string","title":"Edge Id"}},"type":"object","required":["fact_id","original_score","adjusted_score","reason","edge_id"],"title":"PropagationDetailResponse","description":"Detail of a single fact's score adjustment."},"PropagationResponse":{"properties":{"facts_adjusted":{"type":"integer","title":"Facts Adjusted","default":0},"contradictions_applied":{"type":"integer","title":"Contradictions Applied","default":0},"supports_applied":{"type":"integer","title":"Supports Applied","default":0},"derives_constraints_applied":{"type":"integer","title":"Derives Constraints Applied","default":0},"details":{"items":{"$ref":"#/components/schemas/PropagationDetailResponse"},"type":"array","title":"Details"}},"type":"object","title":"PropagationResponse","description":"Response for POST /pots/{pot_id}/propagate."},"Provenance":{"properties":{"type":{"type":"string","title":"Type","description":"Type of provenance (extracted, manual, inferred, imported)"},"sources":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Sources","description":"Source documents or references"},"derivation":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Derivation","description":"Derivation info for inferred facts"}},"type":"object","required":["type"],"title":"Provenance","description":"Provenance information for a fact."},"QueryDataResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/QueryResultItem"},"type":"array","title":"Results","description":"Ranked query results"},"total_results":{"type":"integer","minimum":0.0,"title":"Total Results","description":"Total results returned"},"edges_context":{"anyOf":[{"$ref":"#/components/schemas/QueryEdgesContext"},{"type":"null"}],"description":"Edge context for returned facts (null if include_edges=false)"}},"type":"object","required":["total_results"],"title":"QueryDataResponse","description":"Results data wrapper."},"QueryEdgeItem":{"properties":{"from_fact_id":{"type":"string","title":"From Fact Id","description":"Source fact ID"},"to_fact_id":{"type":"string","title":"To Fact Id","description":"Target fact ID"},"type":{"type":"string","title":"Type","description":"Edge type (supports, contradicts, etc.)"},"weight":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Weight","description":"Relationship strength"},"rationale":{"type":"string","title":"Rationale","description":"Why this relationship exists","default":""},"peer_fact_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Peer Fact Id","description":"The other fact's ID (the one NOT in this result item)"},"peer_content_snippet":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Peer Content Snippet","description":"Snippet of the peer fact content (~150 chars) for context"},"peer_pot_score":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Peer Pot Score","description":"POT Score of the peer fact, for trust weighting"},"resolution_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resolution Type","description":"Resolution type if edge is resolved (confirmed_a, confirmed_b, both_valid, etc.)"},"resolution_notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resolution Notes","description":"Notes about the resolution"}},"type":"object","required":["from_fact_id","to_fact_id","type","weight"],"title":"QueryEdgeItem","description":"Lightweight edge for query responses."},"QueryEdgesContext":{"properties":{"total_edges":{"type":"integer","title":"Total Edges","description":"Total relevant edges found","default":0},"edges":{"items":{"$ref":"#/components/schemas/QueryEdgeItem"},"type":"array","title":"Edges","description":"All edges connecting returned facts"},"contradictions":{"items":{"$ref":"#/components/schemas/ContradictionPair"},"type":"array","title":"Contradictions","description":"Contradiction pairs with POT scores for trust weighting"},"contradiction_count":{"type":"integer","title":"Contradiction Count","description":"Number of active contradictions","default":0},"resolved_contradictions":{"items":{"$ref":"#/components/schemas/ContradictionPair"},"type":"array","title":"Resolved Contradictions","description":"Resolved contradiction pairs with resolution metadata"},"resolved_contradiction_count":{"type":"integer","title":"Resolved Contradiction Count","description":"Number of resolved contradictions","default":0},"edges_by_type":{"additionalProperties":{"type":"integer"},"type":"object","title":"Edges By Type","description":"Edge count by type (e.g. {'supports': 3, 'contradicts': 1})"}},"type":"object","title":"QueryEdgesContext","description":"Edge context for returned facts — contradictions, relationships, and type counts."},"QueryMetadataResponse":{"properties":{"strategy_used":{"type":"string","enum":["cag","rag","cag_with_rag_fallback","graph_rag"],"title":"Strategy Used","description":"Final strategy used"},"classification":{"anyOf":[{"$ref":"#/components/schemas/ClassificationResponse"},{"additionalProperties":true,"type":"object"}],"title":"Classification","description":"Query classification details"},"cag_attempted":{"type":"boolean","title":"Cag Attempted","description":"Whether CAG was attempted"},"cag_suggestion":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cag Suggestion","description":"CAG confidence suggestion (sufficient, consider_rag, no_match)"},"cag_results_count":{"type":"integer","minimum":0.0,"title":"Cag Results Count","description":"Number of CAG results (before fallback)"},"fallback_triggered":{"type":"boolean","title":"Fallback Triggered","description":"Whether fallback to RAG was triggered"},"fallback_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fallback Reason","description":"Reason for fallback (if triggered)"},"total_duration_ms":{"type":"integer","minimum":0.0,"title":"Total Duration Ms","description":"Total request duration in milliseconds"},"cag_duration_ms":{"type":"integer","minimum":0.0,"title":"Cag Duration Ms","description":"CAG retrieval duration in milliseconds"},"rag_duration_ms":{"type":"integer","minimum":0.0,"title":"Rag Duration Ms","description":"RAG retrieval duration in milliseconds"},"graphrag_duration_ms":{"type":"integer","minimum":0.0,"title":"Graphrag Duration Ms","description":"GraphRAG retrieval duration in milliseconds","default":0},"traversal_metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Traversal Metadata","description":"GraphRAG traversal statistics (seeds, nodes, edges)"}},"type":"object","required":["strategy_used","classification","cag_attempted","cag_results_count","fallback_triggered","total_duration_ms","cag_duration_ms","rag_duration_ms"],"title":"QueryMetadataResponse","description":"Routing metadata - aligned with RoutingMetadata from router spec.\n\nProvides transparency into routing decisions for debugging/monitoring."},"QueryRequest":{"properties":{"query":{"type":"string","maxLength":500,"minLength":1,"title":"Query","description":"Query text for retrieval","examples":["What is POT Index?","How does Constitution work?"]},"top_k":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Top K","description":"Maximum results to return","default":5},"strategy":{"type":"string","enum":["auto","cag","rag","graph_rag"],"title":"Strategy","description":"Force strategy or auto-select based on query classification","default":"auto"},"enable_fallback":{"type":"boolean","title":"Enable Fallback","description":"Allow automatic fallback from CAG to RAG when results insufficient","default":true},"filters":{"anyOf":[{"$ref":"#/components/schemas/scipot__api__schemas__query__SearchFiltersRequest"},{"type":"null"}],"description":"Optional post-retrieval filters"},"include_edges":{"type":"boolean","title":"Include Edges","description":"Include edge context (contradictions, relationships) in response","default":true},"include_stances":{"type":"boolean","title":"Include Stances","description":"Include stance summaries for contradiction edges (requires include_edges=True)","default":false}},"type":"object","required":["query"],"title":"QueryRequest","description":"Request body for unified query endpoint.","example":{"enable_fallback":true,"filters":{"domain":"architecture","levels":["CONSTITUTION","VERIFIED"],"tags":["core"]},"query":"What is POT Index?","strategy":"auto","top_k":5}},"QueryResponse":{"properties":{"data":{"$ref":"#/components/schemas/QueryDataResponse","description":"Query results data"},"metadata":{"$ref":"#/components/schemas/QueryMetadataResponse","description":"Routing and timing metadata"}},"type":"object","required":["data","metadata"],"title":"QueryResponse","description":"Full query response.","example":{"data":{"results":[{"content":"POT Index es el sistema de scoring...","domain":"architecture","fact_id":"01234567-89ab-cdef-0123-456789abcdef","level":"VERIFIED","match_details":{"keyword_score":0.95,"matched_keywords":["POT","Index"]},"pot_score":0.85,"score":0.92,"source":"cag","tags":["core","scoring"]}],"total_results":1},"metadata":{"cag_attempted":true,"cag_duration_ms":42,"cag_results_count":1,"cag_suggestion":"sufficient","classification":{"category":"factual","confidence":0.9,"reasoning":["What-question pattern detected"],"suggested_strategy":"cag"},"fallback_triggered":false,"rag_duration_ms":0,"strategy_used":"cag","total_duration_ms":45}}},"QueryResultItem":{"properties":{"fact_id":{"type":"string","title":"Fact Id","description":"Unique identifier of the fact"},"content":{"type":"string","title":"Content","description":"Full fact content"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Short title for display (M19)"},"score":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Score","description":"Combined match score [0-1]"},"pot_score":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Pot Score","description":"POT Index certainty score [0-1]"},"original_pot_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Original Pot Score","description":"Pre-propagation POT Score (M19). None if not propagated."},"level":{"$ref":"#/components/schemas/PotScoreLevel","description":"POT Index level"},"source":{"type":"string","enum":["cag","rag","graph_rag"],"title":"Source","description":"Which retrieval strategy produced this result"},"match_details":{"additionalProperties":true,"type":"object","title":"Match Details","description":"Strategy-specific match details"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain","description":"Fact domain classification"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Classification tags"},"document_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Id","description":"Source document UUID (M19)"},"edges":{"items":{"$ref":"#/components/schemas/QueryEdgeItem"},"type":"array","title":"Edges","description":"Edges connecting this fact to other returned facts"}},"type":"object","required":["fact_id","content","score","pot_score","level","source","match_details"],"title":"QueryResultItem","description":"Single result from query.","example":{"content":"POT Index es el sistema de scoring...","domain":"architecture","fact_id":"01234567-89ab-cdef-0123-456789abcdef","level":"VERIFIED","match_details":{"keyword_score":0.95,"matched_keywords":["POT","Index"]},"pot_score":0.85,"score":0.92,"source":"cag","tags":["core","scoring"]}},"ReadinessResponse":{"properties":{"status":{"type":"string","enum":["ready","not_ready"],"title":"Status"},"timestamp":{"type":"string","format":"date-time","title":"Timestamp"},"checks":{"additionalProperties":{"type":"string"},"type":"object","title":"Checks"},"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail"}},"type":"object","required":["status","timestamp","checks"],"title":"ReadinessResponse","description":"Readiness check response."},"RecordUsageEventRequest":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"pot_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Pot Id"},"operation":{"type":"string","maxLength":100,"minLength":1,"title":"Operation"},"prompt_tokens":{"type":"integer","minimum":0.0,"title":"Prompt Tokens"},"completion_tokens":{"type":"integer","minimum":0.0,"title":"Completion Tokens"},"latency_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Latency Ms"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"}},"type":"object","required":["workspace_id","operation","prompt_tokens","completion_tokens"],"title":"RecordUsageEventRequest","description":"Single event in a batch from an integrator. No model or cost fields."},"RecordUsageEventsRequest":{"properties":{"events":{"items":{"$ref":"#/components/schemas/RecordUsageEventRequest"},"type":"array","maxItems":50,"minItems":1,"title":"Events"}},"type":"object","required":["events"],"title":"RecordUsageEventsRequest","description":"Batch of usage events from an integrator."},"RecordUsageEventsResponse":{"properties":{"recorded":{"type":"integer","title":"Recorded","description":"Number of events recorded"}},"type":"object","required":["recorded"],"title":"RecordUsageEventsResponse","description":"Response after recording usage events."},"ResendVerificationRequest":{"properties":{"email":{"type":"string","maxLength":255,"minLength":5,"title":"Email"}},"type":"object","required":["email"],"title":"ResendVerificationRequest","description":"Request to resend verification email."},"ResolutionActionItem":{"properties":{"edge_id":{"type":"string","title":"Edge Id"},"resolution_type":{"type":"string","title":"Resolution Type"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["edge_id","resolution_type","created_at"],"title":"ResolutionActionItem","description":"Resolution action summary for bulk response."},"ResolutionType":{"type":"string","enum":["confirmed_a","confirmed_b","both_valid","needs_update","dismissed"],"title":"ResolutionType","description":"Types of resolution for a contradiction edge."},"ResolveRequest":{"properties":{"resolution_type":{"$ref":"#/components/schemas/ResolutionType","description":"How the contradiction is resolved"},"contributor_id":{"type":"string","format":"uuid","title":"Contributor Id","description":"Contributor registry ID (must be a registered, active contributor)"},"notes":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Notes","description":"Notes about the resolution"}},"type":"object","required":["resolution_type","contributor_id"],"title":"ResolveRequest","description":"Request body for POST /pots/{pot_id}/edges/{edge_id}/resolve."},"ResolveResponse":{"properties":{"edge_id":{"type":"string","title":"Edge Id"},"previous_type":{"type":"string","title":"Previous Type","description":"Edge type before mutation"},"new_type":{"type":"string","title":"New Type","description":"Edge type after mutation"},"resolution_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resolution Type","description":"Resolution type (None on revert)"},"resolved_by_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resolved By Name","description":"Who resolved"},"resolved_by_contributor_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Resolved By Contributor Id","description":"Contributor registry ID of resolver"},"resolved_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Resolved At","description":"When resolved"},"score_impact":{"items":{"$ref":"#/components/schemas/ScoreImpact"},"type":"array","title":"Score Impact","description":"Score changes applied to facts"}},"type":"object","required":["edge_id","previous_type","new_type"],"title":"ResolveResponse","description":"Response for POST /pots/{pot_id}/edges/{edge_id}/resolve and DELETE."},"RevokeCurationResponse":{"properties":{"curation_id":{"type":"string","format":"uuid","title":"Curation Id"},"fact_id":{"type":"string","format":"uuid","title":"Fact Id"},"score_before":{"type":"number","title":"Score Before"},"score_after":{"type":"number","title":"Score After"},"score_delta":{"type":"number","title":"Score Delta","description":"Revert delta applied (negated original)"},"validation_status":{"type":"string","title":"Validation Status","description":"Updated validation status after revocation"}},"type":"object","required":["curation_id","fact_id","score_before","score_after","score_delta","validation_status"],"title":"RevokeCurationResponse","description":"Response for DELETE /pots/{pot_id}/facts/{fact_id}/curations/{curation_id}."},"RoleFields":{"properties":{"role_title":{"type":"string","maxLength":200,"minLength":1,"title":"Role Title","description":"Job title"},"department":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Department","description":"Department or team"},"seniority":{"$ref":"#/components/schemas/SeniorityLevel","description":"Seniority level for expertise weighting","default":"mid"},"expertise_areas":{"items":{"type":"string"},"type":"array","maxItems":20,"title":"Expertise Areas","description":"Areas of expertise"}},"type":"object","required":["role_title"],"title":"RoleFields","description":"Role fields for contributor registration."},"RoleListResponse":{"properties":{"roles":{"items":{"$ref":"#/components/schemas/ContributorRoleResponse"},"type":"array","title":"Roles"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["roles","total"],"title":"RoleListResponse","description":"Response for GET .../contributors/{contributor_id}/roles."},"ScoreDistribution":{"properties":{"constitution":{"type":"integer","title":"Constitution","description":"POT score == 1.0","default":0},"verified":{"type":"integer","title":"Verified","description":"0.8 <= POT score < 1.0","default":0},"supported":{"type":"integer","title":"Supported","description":"0.6 <= POT score < 0.8","default":0},"inferred":{"type":"integer","title":"Inferred","description":"0.4 <= POT score < 0.6","default":0},"hypothesis":{"type":"integer","title":"Hypothesis","description":"0.2 <= POT score < 0.4","default":0},"speculation":{"type":"integer","title":"Speculation","description":"POT score < 0.2","default":0}},"type":"object","title":"ScoreDistribution","description":"Per-level fact counts for a POT.\n\nCutoffs mirror PotScoreLevel.from_score so distribution counts agree\nwith the level enum used everywhere else in SciPot."},"ScoreImpact":{"properties":{"fact_id":{"type":"string","title":"Fact Id"},"score_before":{"type":"number","title":"Score Before"},"score_after":{"type":"number","title":"Score After"},"delta":{"type":"number","title":"Delta"}},"type":"object","required":["fact_id","score_before","score_after","delta"],"title":"ScoreImpact","description":"Score change for a single fact during resolution or stance."},"SearchConfidence":{"properties":{"match_quality":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Match Quality","description":"Average score of top results [0-1]"},"top_score":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Top Score","description":"Score of best result [0-1]"},"results_count":{"type":"integer","minimum":0.0,"title":"Results Count","description":"Number of results found"},"suggestion":{"type":"string","enum":["sufficient","consider_rag","no_match"],"title":"Suggestion","description":"Guidance for client on result quality"}},"type":"object","required":["match_quality","top_score","results_count","suggestion"],"title":"SearchConfidence","description":"Confidence metadata for CAG search results.\n\nHelps clients decide if they should also query RAG for better coverage.","example":{"match_quality":0.85,"results_count":3,"suggestion":"sufficient","top_score":0.92}},"SearchRequest":{"properties":{"query":{"type":"string","maxLength":500,"minLength":3,"title":"Query","description":"Natural language search query","examples":["How does POT Index propagate through edges?"]},"top_k":{"type":"integer","maximum":50.0,"minimum":1.0,"title":"Top K","description":"Maximum number of results to return","default":10},"min_pot_score":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Min Pot Score","description":"Minimum POT Index threshold for results","default":0.0},"filters":{"anyOf":[{"$ref":"#/components/schemas/scipot__api__schemas__search__SearchFiltersRequest"},{"type":"null"}],"description":"Optional post-retrieval filters"},"include_content":{"type":"boolean","title":"Include Content","description":"Include full fact content in results (set false for compact response)","default":true}},"type":"object","required":["query"],"title":"SearchRequest","description":"Semantic search request.\n\nUses RAG retrieval with hybrid ranking:\ncombined_score = (similarity × 0.7) + (pot_score × 0.3)","example":{"filters":{"domain":"architecture"},"min_pot_score":0.4,"query":"How does POT Index propagate through edges?","top_k":10}},"SeniorityLevel":{"type":"string","enum":["junior","mid","senior","lead","principal","executive"],"title":"SeniorityLevel","description":"Seniority level for contributor expertise weighting."},"SignupRequest":{"properties":{"email":{"type":"string","maxLength":255,"minLength":5,"title":"Email","description":"Contact email"},"name":{"type":"string","maxLength":200,"minLength":1,"title":"Name","description":"Organization name"}},"type":"object","required":["email","name"],"title":"SignupRequest","description":"Request to register a new integrator via self-service."},"SignupResponse":{"properties":{"message":{"type":"string","title":"Message","default":"Verification email sent. Check your inbox."},"integrator_id":{"type":"string","format":"uuid","title":"Integrator Id"}},"type":"object","required":["integrator_id"],"title":"SignupResponse","description":"Response after signup initiation."},"SourceMetadata":{"properties":{"path":{"type":"string","title":"Path","description":"Path or URL of the source document"},"type":{"type":"string","enum":["markdown","text","pdf","html","docx","pptx","xlsx","image"],"title":"Type","description":"Document type","default":"markdown"},"author":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author","description":"Document author or creator"},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"When the document was created"},"tags":{"items":{"type":"string"},"type":"array","maxItems":20,"title":"Tags","description":"Tags associated with this source (max 20)"},"authoritative":{"type":"boolean","title":"Authoritative","description":"Whether this is an authoritative source (affects POT Index boost)","default":false}},"type":"object","required":["path"],"title":"SourceMetadata","description":"Metadata about a document source.","examples":[{"author":"sebas","authoritative":true,"created_at":"2026-01-07T10:00:00Z","path":"docs/architecture.md","tags":["architecture","core"],"type":"markdown"}]},"SourceSummary":{"properties":{"prompt_tokens":{"type":"integer","title":"Prompt Tokens","default":0},"completion_tokens":{"type":"integer","title":"Completion Tokens","default":0},"events":{"type":"integer","title":"Events","default":0}},"type":"object","title":"SourceSummary","description":"Source breakdown visible to integrators (no cost)."},"StanceActionItem":{"properties":{"edge_id":{"type":"string","title":"Edge Id"},"stance":{"$ref":"#/components/schemas/StanceType"},"score_delta":{"type":"number","title":"Score Delta"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["edge_id","stance","score_delta","created_at"],"title":"StanceActionItem","description":"Stance action summary for bulk response."},"StanceListResponse":{"properties":{"edge_id":{"type":"string","title":"Edge Id"},"stances":{"items":{"$ref":"#/components/schemas/ContradictionStance"},"type":"array","title":"Stances"},"total":{"type":"integer","title":"Total"},"confirm_a_count":{"type":"integer","title":"Confirm A Count","description":"Stances confirming fact A","default":0},"confirm_b_count":{"type":"integer","title":"Confirm B Count","description":"Stances confirming fact B","default":0},"dismiss_count":{"type":"integer","title":"Dismiss Count","description":"Stances dismissing the contradiction","default":0}},"type":"object","required":["edge_id","stances","total"],"title":"StanceListResponse","description":"Response for GET /pots/{pot_id}/edges/{edge_id}/stances."},"StanceRequest":{"properties":{"stance":{"$ref":"#/components/schemas/StanceType","description":"Which fact to confirm or dismiss"},"contributor_id":{"type":"string","format":"uuid","title":"Contributor Id","description":"Contributor registry ID (must be a registered, active contributor)"},"notes":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Notes","description":"Reasoning for the stance"}},"type":"object","required":["stance","contributor_id"],"title":"StanceRequest","description":"Request body for POST /pots/{pot_id}/edges/{edge_id}/stances."},"StanceResponse":{"properties":{"stance_id":{"type":"string","format":"uuid","title":"Stance Id","description":"ID of the created stance record"},"edge_id":{"type":"string","title":"Edge Id","description":"Edge the stance was submitted for"},"stance":{"$ref":"#/components/schemas/StanceType","description":"Stance type submitted"},"contributor_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Contributor Id","description":"Contributor registry ID"},"expertise_evaluation":{"$ref":"#/components/schemas/ExpertiseEvaluation","description":"How the contributor's expertise was evaluated"},"score_impact":{"items":{"$ref":"#/components/schemas/ScoreImpact"},"type":"array","title":"Score Impact","description":"Score changes applied to facts (confirmed + opposing)"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When stance was submitted"}},"type":"object","required":["stance_id","edge_id","stance","expertise_evaluation","created_at"],"title":"StanceResponse","description":"Response for POST /pots/{pot_id}/edges/{edge_id}/stances."},"StanceType":{"type":"string","enum":["confirm_a","confirm_b","dismiss"],"title":"StanceType","description":"Types of stances a user can take on a contradiction edge."},"StancesSummary":{"properties":{"confirm_a_count":{"type":"integer","title":"Confirm A Count","description":"Stances confirming fact A (from_id)","default":0},"confirm_b_count":{"type":"integer","title":"Confirm B Count","description":"Stances confirming fact B (to_id)","default":0},"dismiss_count":{"type":"integer","title":"Dismiss Count","description":"Stances dismissing the contradiction","default":0},"total":{"type":"integer","title":"Total","description":"Total stances","default":0},"latest_stances":{"items":{"$ref":"#/components/schemas/ContradictionStance"},"type":"array","title":"Latest Stances","description":"Most recent stances (up to 10)"}},"type":"object","title":"StancesSummary","description":"Summary of stances on a contradiction edge."},"SynthesisFactItem":{"properties":{"fact_id":{"type":"string","title":"Fact Id"},"content":{"type":"string","title":"Content"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Short title for display (M19)"},"pot_score":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Pot Score"},"original_pot_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Original Pot Score","description":"Pre-propagation POT Score (M19)"},"level":{"$ref":"#/components/schemas/PotScoreLevel"},"source":{"type":"string","title":"Source","description":"Retrieval strategy that found this fact"},"document_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Id","description":"Source document UUID (M19)"},"provenance":{"anyOf":[{"$ref":"#/components/schemas/FactProvenance"},{"type":"null"}],"description":"Source document information for citations"}},"type":"object","required":["fact_id","content","pot_score","level","source"],"title":"SynthesisFactItem","description":"A fact used in synthesis with full provenance."},"SynthesisRequest":{"properties":{"query":{"type":"string","maxLength":500,"minLength":1,"title":"Query","description":"Question to answer from the knowledge base"},"max_facts":{"type":"integer","maximum":50.0,"minimum":1.0,"title":"Max Facts","description":"Maximum facts to retrieve for synthesis","default":10},"include_epistemic_briefing":{"type":"boolean","title":"Include Epistemic Briefing","description":"Include epistemic briefing in response (certainty guidance)","default":true}},"type":"object","required":["query"],"title":"SynthesisRequest","description":"Request body for synthesis endpoint.","example":{"include_epistemic_briefing":true,"max_facts":10,"query":"What is the POT Score system?"}},"SynthesisResponse":{"properties":{"answer":{"type":"string","title":"Answer","description":"Synthesized answer from LLM"},"facts_used":{"items":{"$ref":"#/components/schemas/SynthesisFactItem"},"type":"array","title":"Facts Used","description":"Facts used for synthesis"},"strategy_used":{"type":"string","title":"Strategy Used","description":"Retrieval strategy used"},"total_facts_retrieved":{"type":"integer","minimum":0.0,"title":"Total Facts Retrieved"},"llm_model":{"type":"string","title":"Llm Model","description":"LLM model used for synthesis"},"llm_cost_usd":{"type":"number","minimum":0.0,"title":"Llm Cost Usd","description":"Cost of LLM call"},"latency_ms":{"type":"number","minimum":0.0,"title":"Latency Ms","description":"Total latency including retrieval + synthesis"},"epistemic_briefing":{"anyOf":[{"$ref":"#/components/schemas/EpistemicBriefingResponse"},{"type":"null"}],"description":"Structured certainty guidance (6 dimensions)"},"contradictions_found":{"items":{"$ref":"#/components/schemas/ContradictionItem"},"type":"array","title":"Contradictions Found","description":"Contradictions detected among retrieved facts"}},"type":"object","required":["answer","facts_used","strategy_used","total_facts_retrieved","llm_model","llm_cost_usd","latency_ms"],"title":"SynthesisResponse","description":"Response from synthesis endpoint."},"TimingData":{"properties":{"initialized_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Initialized At","description":"When cache was initialized (ISO 8601)"},"last_refresh":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Refresh","description":"Last cache refresh (ISO 8601)"}},"type":"object","title":"TimingData","description":"Cache timing information."},"TokenQuotaStatus":{"properties":{"is_allowed":{"type":"boolean","title":"Is Allowed"},"tokens_used":{"type":"integer","minimum":0.0,"title":"Tokens Used"},"tokens_limit":{"type":"integer","minimum":0.0,"title":"Tokens Limit","description":"Effective limit (base + bonus)"},"tokens_remaining":{"type":"integer","title":"Tokens Remaining"},"bonus_tokens":{"type":"integer","minimum":0.0,"title":"Bonus Tokens","default":0},"period":{"type":"string","title":"Period","description":"Period key YYYYMM"},"is_limited":{"type":"boolean","title":"Is Limited","description":"False when workspace has no token limit (unlimited)"}},"type":"object","required":["is_allowed","tokens_used","tokens_limit","tokens_remaining","period","is_limited"],"title":"TokenQuotaStatus","description":"Result of a token quota check."},"TokenResetResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"bonus_tokens_before":{"type":"integer","title":"Bonus Tokens Before"},"bonus_tokens_after":{"type":"integer","title":"Bonus Tokens After","default":0},"effective_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Effective Limit","description":"Effective monthly limit after reset. None if unlimited."}},"type":"object","required":["workspace_id","bonus_tokens_before","effective_limit"],"title":"TokenResetResponse","description":"Response after resetting bonus tokens."},"TokenTopUpRequest":{"properties":{"tokens":{"type":"integer","exclusiveMinimum":0.0,"title":"Tokens","description":"Number of tokens to add"}},"type":"object","required":["tokens"],"title":"TokenTopUpRequest","description":"Request to add bonus tokens to a workspace."},"TokenTopUpResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"bonus_tokens_before":{"type":"integer","title":"Bonus Tokens Before"},"bonus_tokens_after":{"type":"integer","title":"Bonus Tokens After"},"effective_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Effective Limit","description":"Effective monthly limit (base + bonus). None if unlimited."}},"type":"object","required":["workspace_id","bonus_tokens_before","bonus_tokens_after","effective_limit"],"title":"TokenTopUpResponse","description":"Response after adding bonus tokens."},"TokenTopupRequest":{"properties":{"token_amount":{"type":"integer","minimum":100000.0,"title":"Token Amount","description":"Number of tokens to purchase"},"success_url":{"type":"string","title":"Success Url"},"cancel_url":{"type":"string","title":"Cancel Url"}},"type":"object","required":["token_amount","success_url","cancel_url"],"title":"TokenTopupRequest","description":"Request to purchase additional tokens."},"TokenTopupResponse":{"properties":{"checkout_url":{"type":"string","title":"Checkout Url"},"tokens":{"type":"integer","title":"Tokens"},"price_cents":{"type":"integer","title":"Price Cents"}},"type":"object","required":["checkout_url","tokens","price_cents"],"title":"TokenTopupResponse","description":"Response with token top-up checkout URL."},"UpdateContributorRequest":{"properties":{"display_name":{"anyOf":[{"type":"string","maxLength":200,"minLength":1},{"type":"null"}],"title":"Display Name"},"is_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Active"}},"type":"object","title":"UpdateContributorRequest","description":"Request body for PATCH /integrator/workspaces/{workspace_id}/contributors/{contributor_id}."},"UpdateWorkspaceQuotasRequest":{"properties":{"max_monthly_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Monthly Tokens","description":"Monthly token limit. None removes the limit (unlimited). 0 blocks all usage."}},"type":"object","required":["max_monthly_tokens"],"title":"UpdateWorkspaceQuotasRequest","description":"Request to update workspace token quota settings."},"UpdateWorkspaceQuotasResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"max_monthly_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Monthly Tokens"},"bonus_tokens":{"type":"integer","title":"Bonus Tokens"},"effective_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Effective Limit"}},"type":"object","required":["workspace_id","max_monthly_tokens","bonus_tokens","effective_limit"],"title":"UpdateWorkspaceQuotasResponse","description":"Response after updating workspace quotas."},"UsageSummaryResponse":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"period":{"type":"string","title":"Period"},"total_prompt_tokens":{"type":"integer","title":"Total Prompt Tokens","default":0},"total_completion_tokens":{"type":"integer","title":"Total Completion Tokens","default":0},"total_events":{"type":"integer","title":"Total Events","default":0},"by_operation":{"additionalProperties":{"$ref":"#/components/schemas/OperationSummary"},"type":"object","title":"By Operation"},"by_source":{"additionalProperties":{"$ref":"#/components/schemas/SourceSummary"},"type":"object","title":"By Source"}},"type":"object","required":["workspace_id","period"],"title":"UsageSummaryResponse","description":"Usage summary visible to integrators — no model, no cost."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"VerifyEmailResponse":{"properties":{"api_key":{"type":"string","title":"Api Key","description":"Full API key (shown only once)"},"integrator_id":{"type":"string","format":"uuid","title":"Integrator Id"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"message":{"type":"string","title":"Message","default":"Email verified. Store your API key securely."}},"type":"object","required":["api_key","integrator_id","workspace_id"],"title":"VerifyEmailResponse","description":"Response after email verification (API key shown only once)."},"WarmCacheStats":{"properties":{"constitution_size":{"type":"integer","minimum":0.0,"title":"Constitution Size"},"certainty_size":{"type":"integer","minimum":0.0,"title":"Certainty Size"},"total_size":{"type":"integer","minimum":0.0,"title":"Total Size"},"initialized_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Initialized At"}},"type":"object","required":["constitution_size","certainty_size","total_size"],"title":"WarmCacheStats","description":"Cache stats for warm response."},"WorkspaceDashboardSummary":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"workspace_name":{"type":"string","title":"Workspace Name","default":""},"total_tokens":{"type":"integer","minimum":0.0,"title":"Total Tokens","description":"Total tokens consumed this period","default":0},"total_events":{"type":"integer","minimum":0.0,"title":"Total Events","description":"Number of usage events","default":0},"pots_count":{"type":"integer","minimum":0.0,"title":"Pots Count","description":"Number of POTs in this workspace","default":0}},"type":"object","required":["workspace_id"],"title":"WorkspaceDashboardSummary","description":"Usage summary for a single workspace within the dashboard."},"WorkspaceInfo":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"slug":{"type":"string","title":"Slug"},"integrator_id":{"type":"string","format":"uuid","title":"Integrator Id"},"is_active":{"type":"boolean","title":"Is Active"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"quotas":{"$ref":"#/components/schemas/WorkspaceQuotas"},"usage":{"$ref":"#/components/schemas/WorkspaceUsage"}},"type":"object","required":["id","name","slug","integrator_id","is_active","created_at"],"title":"WorkspaceInfo","description":"Workspace information."},"WorkspaceListResponse":{"properties":{"workspaces":{"items":{"$ref":"#/components/schemas/WorkspaceInfo"},"type":"array","title":"Workspaces"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["workspaces","total"],"title":"WorkspaceListResponse","description":"Response listing workspaces."},"WorkspaceQuotas":{"properties":{"max_pots":{"type":"integer","minimum":1.0,"title":"Max Pots","description":"Max POTs per workspace","default":5},"max_documents_per_pot":{"type":"integer","minimum":1.0,"title":"Max Documents Per Pot","description":"Max documents per POT","default":50},"max_storage_bytes":{"type":"integer","minimum":1.0,"title":"Max Storage Bytes","description":"Max cumulative storage in bytes (default 50MB)","default":52428800},"max_monthly_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Monthly Tokens","description":"Monthly token limit (prompt + completion). None = unlimited."},"bonus_tokens":{"type":"integer","minimum":0.0,"title":"Bonus Tokens","description":"Add-on tokens for current billing period (top-ups).","default":0}},"type":"object","title":"WorkspaceQuotas","description":"Quota limits for a workspace."},"WorkspaceUsage":{"properties":{"pots_count":{"type":"integer","minimum":0.0,"title":"Pots Count","default":0},"documents_count":{"type":"integer","minimum":0.0,"title":"Documents Count","default":0},"storage_bytes":{"type":"integer","minimum":0.0,"title":"Storage Bytes","default":0}},"type":"object","title":"WorkspaceUsage","description":"Current usage counters for a workspace."},"WorkspaceUsageSummary":{"properties":{"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"workspace_name":{"type":"string","title":"Workspace Name","default":""},"total_prompt_tokens":{"type":"integer","title":"Total Prompt Tokens","default":0},"total_completion_tokens":{"type":"integer","title":"Total Completion Tokens","default":0},"total_events":{"type":"integer","title":"Total Events","default":0}},"type":"object","required":["workspace_id"],"title":"WorkspaceUsageSummary","description":"Per-workspace summary in the cross-workspace listing."},"WorkspacesUsageResponse":{"properties":{"period":{"type":"string","title":"Period"},"workspaces":{"items":{"$ref":"#/components/schemas/WorkspaceUsageSummary"},"type":"array","title":"Workspaces"},"total_prompt_tokens":{"type":"integer","title":"Total Prompt Tokens","default":0},"total_completion_tokens":{"type":"integer","title":"Total Completion Tokens","default":0},"total_events":{"type":"integer","title":"Total Events","default":0}},"type":"object","required":["period","workspaces"],"title":"WorkspacesUsageResponse","description":"Cross-workspace usage for an integrator."},"scipot__api__schemas__query__SearchFiltersRequest":{"properties":{"domain":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Domain","description":"Filter by domain (exact match)"},"levels":{"anyOf":[{"items":{"$ref":"#/components/schemas/PotScoreLevel"},"type":"array","maxItems":6},{"type":"null"}],"title":"Levels","description":"Filter by POT Index levels (any match)"},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":20},{"type":"null"}],"title":"Tags","description":"Must have ALL tags (AND logic)"}},"type":"object","title":"SearchFiltersRequest","description":"Optional post-retrieval filters."},"scipot__api__schemas__search__SearchFiltersRequest":{"properties":{"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain","description":"Filter by domain (exact match)","examples":["architecture","business"]},"level":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Level","description":"Filter by POT Index levels (OR logic)","examples":[["VERIFIED","SUPPORTED"]]},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tags","description":"Filter by tags (AND logic - must have ALL)","examples":[["pot-index","propagation"]]}},"type":"object","title":"SearchFiltersRequest","description":"Optional post-retrieval filters.\n\nFilters are applied after vector search for flexibility:\n- domain: Exact match on domain\n- level: Any of these levels (OR logic)\n- tags: Must have ALL tags (AND logic)","example":{"domain":"architecture","level":["VERIFIED","SUPPORTED"]}}}},"tags":[{"name":"health","description":"Liveness and readiness probes"},{"name":"pots","description":"Knowledge POT lifecycle — create, read, list, delete"},{"name":"ingestion","description":"Document ingestion and fact extraction pipeline"},{"name":"jobs","description":"Async job status polling for ingestion and extraction"},{"name":"facts","description":"Fact CRUD — list, get, delete extracted facts with POT Score filtering"},{"name":"edges","description":"Edge detection, creation, and management between facts"},{"name":"documents","description":"Document upload with automatic format conversion (PDF/DOCX/PPTX/XLSX)"},{"name":"query","description":"Unified query endpoint with auto-routing (CAG/RAG/GraphRAG)"},{"name":"search","description":"Direct RAG semantic search using embeddings"},{"name":"cag","description":"Cached Augmented Generation — fast keyword/entity search (<5ms)"},{"name":"synthesis","description":"LLM synthesis with epistemic calibration over retrieved facts"},{"name":"integrator-workspaces","description":"Multi-tenant workspace provisioning and management (advanced — for integrators with multiple tenants)"},{"name":"contribution","description":"Expert knowledge contribution and fact curation with expertise-weighted scoring"}]}