Skip to content

Endpoint Reference

All Raw to Knowledge API routes are documented here. The interactive OpenAPI UI is available at http://localhost:8000/docs and provides live request execution, schema inspection, and response examples.

HTTP status codes used across the API

Status Meaning
200 OK Request completed synchronously. Response body contains the result.
202 Accepted Request accepted for asynchronous processing. A task has been enqueued. Poll the resource to check progress.
404 Not Found The specified ID does not exist, or the resource is not in a status that permits this operation.
409 Conflict Duplicate detected. A resource with the same unique key already exists.
422 Unprocessable Entity Pydantic validation failure, or a domain rule violation (invalid state transition, missing provenance, etc.).
500 Internal Server Error Service fault. Check structlog output and database connectivity.

Intake

Routes for ingesting source artifacts and extracting candidate questions and answers.

Method Path Description Key request fields Response
POST /v1/artifacts Ingest a source artifact (transcript, document, etc.) source_ref, source_system, source_type, legal_basis, customer_scope, raw_content 201 artifact record with artifact_id. 409 if source_ref already exists.
GET /v1/artifacts List all ingested artifacts — Array of artifact summaries.
GET /v1/artifacts/{artifact_id} Get a single artifact by ID — Full artifact record.
POST /v1/artifacts/{artifact_id}/extract Extract candidate questions and answers from an artifact — 202 Accepted. Extraction runs synchronously and results are queryable immediately.
GET /v1/artifacts/{artifact_id}/candidates List candidates extracted from an artifact — Array of CandidateQuestion and CandidateAnswer records.

Classification

Routes for classifying candidate answers into Horn information types.

Method Path Description Key request fields Response
POST /v1/classification/candidates/{candidate_id}/classify Run automated classification on a candidate answer — ClassificationRecord with horn_type, confidence, assertion_subtype, assertion_grammar, requires_review.
GET /v1/classification/candidates/{candidate_id}/classification Get the classification record for a candidate — ClassificationRecord. 404 if not yet classified.
GET /v1/classification/candidates List candidates awaiting or requiring classification review ?requires_review=true filter available Array of candidates with classification records.

Validation

Routes for the human validation workflow.

Method Path Description Key request fields Response
GET /v1/validation/queue Get the next candidate from the validation queue ?horn_type= to filter by type CandidateAnswer with its classification, or 204 No Content if the queue is empty.
POST /v1/validation/candidates/{candidate_id}/claim Claim a candidate for review (transitions to IN_REVIEW) actor Updated candidate state. 422 if transition is not permitted.
POST /v1/validation/candidates/{candidate_id}/approve Approve a candidate as-is actor, rationale ValidationRecord.
POST /v1/validation/candidates/{candidate_id}/revise Approve with revised text actor, rationale, revised_text ValidationRecord.
POST /v1/validation/candidates/{candidate_id}/reject Reject a candidate actor, rationale ValidationRecord.
POST /v1/validation/candidates/{candidate_id}/escalate Escalate a candidate for expert review actor, rationale, escalation_reason ValidationRecord. Creates a WorkItem.
GET /v1/validation/candidates/{candidate_id}/history Get the full validation decision history for a candidate — Array of ValidationRecord entries in decision order.

Registry

Routes for publishing approved answers and querying the knowledge registry.

Method Path Description Key request fields Response
POST /v1/registry/answers Publish an approved answer to the registry candidate_id, validation_record_id, owner_role, evidence_links, review_due, customer_scope ApprovedAnswer. 422 ProvenanceError if required provenance fields are missing.
GET /v1/registry/answers List approved answers ?status=, ?horn_type=, ?customer_scope= filters available Array of ApprovedAnswer summaries.
GET /v1/registry/answers/{answer_id} Get a single approved answer — Full ApprovedAnswer.
POST /v1/registry/answers/{answer_id}/supersede Supersede an answer with a newer version new_answer_id, actor, rationale Updated ApprovedAnswer with status = SUPERSEDED.
POST /v1/registry/answers/{answer_id}/dispute Mark an answer as disputed actor, rationale Updated ApprovedAnswer with status = DISPUTED.
POST /v1/registry/answers/{answer_id}/retire Retire an answer from active use actor, rationale Updated ApprovedAnswer with status = RETIRED.
GET /v1/registry/conflicts List active conflict flags — Array of RegistryConflictRecord entries.

Readout

Routes for exporting answers in structured formats.

Method Path Description Key request fields Response
GET /v1/readout/answers/{answer_id}/export Export an approved answer in structured format ?format=json\|dita\|markdown Formatted answer. 404 if the answer does not exist or is not in APPROVED status.
GET /v1/readout/answers Bulk export answers matching filters ?horn_type=, ?customer_scope=, ?format= Array of formatted answers.

Generation

Routes for the generated answer pipeline (work items and LLM-generated candidates).

Method Path Description Key request fields Response
POST /v1/generation/work-items Create a new generation work item from an escalated question question_text, source_segment_id, escalation_reason, customer_scope WorkItem with status = NEW.
GET /v1/generation/work-items List work items ?state= filter available Array of WorkItem summaries.
GET /v1/generation/work-items/{work_item_id} Get a single work item — Full WorkItem with latest GeneratedCandidate if available.
POST /v1/generation/work-items/{work_item_id}/generate Trigger answer generation for a work item — 202 Accepted. Enqueues generate_answer_task on raw_to_knowledge_generation queue.
GET /v1/generation/work-items/{work_item_id}/candidates List generated candidates for a work item — Array of GeneratedCandidate records.

Graph

Routes for Neo4j graph sync and contradiction detection.

Method Path Description Key request fields Response
POST /v1/graph/answers/{answer_id}/sync Sync an approved answer into the Neo4j graph — 202 Accepted. Enqueues sync_graph_task on raw_to_knowledge_graph queue.
POST /v1/graph/answers/{answer_id}/detect-contradictions Run contradiction detection for an answer — 202 Accepted. Enqueues detect_contradictions_task on raw_to_knowledge_graph queue.
GET /v1/graph/answers/{answer_id}/contradictions Get detected contradictions for an answer — Array of contradiction records.
GET /v1/graph/answers/{answer_id}/relationships Get graph relationships for an answer — Graph neighborhood: nodes and edges adjacent to this answer.

Retrieval

Routes for semantic search over the Weaviate vector index.

Method Path Description Key request fields Response
POST /v1/retrieval/search Semantic search for answers matching a query query_text, limit, customer_scope Array of answers ranked by similarity score.
POST /v1/retrieval/known-answer-check Check if a question already has a known answer (≥ 0.92 similarity) question_text { "matched": true/false, "answer": ApprovedAnswer \| null }

Dashboard

Routes for operational metrics and pipeline health.

Method Path Description Key request fields Response
GET /v1/dashboard/metrics Get pipeline health metrics (counts by state, queue depths, etc.) — JSON object with counts. Also updates Prometheus gauges.
GET /v1/dashboard/pipeline Get a summary of the full pipeline state — Counts per stage from ingest through approved.

Operations

Routes for health checks and observability.

Method Path Description Key request fields Response
GET /health Service health check — { "status": "ok", "version": "...", "db": "ok\|error" }
GET /metrics Prometheus metrics endpoint — Text exposition format (13 metrics). Gauges reflect values from the last /v1/dashboard/metrics call.