Skip to content

HTTP API

This page lists every route the OntoCast server exposes, with its parameters, responses and error codes. Start the server with ontocast serve; it listens on http://127.0.0.1:8999 by default (HOST, PORT).

The server has no authentication, and POST /flush deletes data. Keep it on the loopback interface unless a proxy that authenticates sits in front of it.

FastAPI serves interactive documentation at /docs and the OpenAPI schema at /openapi.json.

Routes

Route Purpose
GET /health Liveness probe
GET /info Version, accepted input types, cache statistics
GET /config Every setting the server runs with, credentials redacted
POST /process Extract an ontology and facts from each uploaded document
POST /process_unit Extract from short texts, each as a single content unit, without chunking
GET /ontologies List the catalog's ontologies with their head version(s)
GET /ontologies/{ontology_id}/versions The version history of one ontology
GET /ontologies/{ontology_id}/versions/{key} One version as Turtle
DELETE /ontologies/{ontology_id}/versions/{key} Tombstone one version
GET /ontologies/{ontology_id}/diff Content triples added and removed between two versions
POST /ontologies Add an ontology to the catalog
PUT /ontologies/{iri} Upload a new version of an ontology
DELETE /ontologies/{iri} Remove a catalog ontology
GET /shapes List stored SHACL shapes documents
POST /shapes Add a SHACL shapes document
DELETE /shapes/{graph_uri} Remove a SHACL shapes document
POST /flush Delete stored facts, ontologies and vectors
POST /match/entities Align entities across several graphs
POST /match/derive-matches Turn alignment clusters into one-to-one entity matches
POST /match/evaluate Score a predicted graph against a reference graph
GET /entities/cluster The stored entities that are one with an entity, across documents

Tenant and project

/process, /process_unit, /ontologies, /shapes, /flush and /entities work on one tenant and project partition. Pass tenant and project as query parameters to choose it; they are not read from a JSON body or form. With neither, a route uses the partition the server started with (ontocast serve --tenant ... --project ..., ontocast/test by default). With only one, the other takes its built-in default (ontocast or test), not the server's. Tenancy explains how partitions map to datasets and collections.

Health and info

GET /health

Reports that the server is up and its LLM client was built. It does not contact the LLM provider, the triple store or the vector store.

{"status": "healthy", "version": "...", "llm_provider": "openai"}

Returns 503 with {"status": "unhealthy", "error": "..."} when the LLM client is missing.

GET /info

Returns name, version, description, capabilities, input_types (the file extensions this install can convert), output_types, llm_cache (cache statistics) and max_concurrent_processes (MAX_CONCURRENT_PROCESSES).

GET /config

Returns the settings the server was started with, keyed by environment variable, and the mode the chunker runs in. It is the same record a batch run writes as effective_config in its run manifest. Credentials read <redacted> (null when unset), and a user:password@ in a URL is replaced the same way. Per-request parameters of /process and /process_unit override some settings for that request only; they are not reflected here.

{"version": "...", "chunking_mode": "semantic",
 "settings": {"AGG_ENABLED": true, "CHUNK_CHUNKING_MODE": "semantic", "LLM_API_KEY": "<redacted>"}}

chunking_mode is naive when CHUNK_CHUNKING_MODE asks for semantic but the semantic-chunking extra is not installed.

Extraction

POST /process

Runs the whole pipeline on each document: convert, chunk, extract the ontology, extract facts, merge. Documents run one after another, and the request returns when the last one is done.

Send the documents in one of two ways:

Content type Body
multipart/form-data One or more uploaded files, under any field name, plus any parameters as form fields. Each file's name selects its converter: .txt, .json, or a suffix in CONVERTER_SUPPORTED_EXTENSIONS such as .pdf, .docx or .md (/info lists what this install accepts)
application/json One document as a JSON object. Its text is the text field, or else its longest top-level string field. A url field is recorded as the document's source

These return 400: any other content type, a form with no file, a file with no name, or more files than MAX_FILES_PER_REQUEST. The parameters apply to every document in the request.

Parameters

Each parameter is read from the query string, the JSON body or a form field. The body or form field wins over the query string, and either wins over the server's setting. A present but unrecognised value returns 400; it is never replaced by the default.

Parameter Value Default
render_mode ontology, facts or ontology_and_facts RENDER_MODE
ontology_context_mode selected_single_ontology, selected_vector_search_ontology or fixed_single_ontology ONTOLOGY_CONTEXT_MODE
ontology_context_fixed_ontology_id IRI, ontology_id or prefix of a catalog ontology. A non-empty value selects fixed_single_ontology whatever ontology_context_mode says In fixed mode, ONTOLOGY_CONTEXT_FIXED_ONTOLOGY_ID
llm_graph_format jsonld or turtle: the format the model writes graphs in LLM_GRAPH_FORMAT
max_visits Integer of at least 1: render attempts per content unit when a render fails outright MAX_VISITS_PER_NODE
strip_provenance true to leave the provenance OntoCast adds (statement reifiers, chunk nodes, an ontology header's prov:wasDerivedFrom) out of the returned Turtle; domain triples stay, PROV-O ones included false
ontology_user_instruction Text added to the ontology prompt none
ontology_selection_user_instruction Text added to the prompt that picks a catalog ontology none
facts_user_instruction Text added to the facts prompt none
target_sections Section labels to keep, comma-separated or a JSON array all sections
exclude_sections Section labels to drop; a unit is dropped only when its label is strong. Any value replaces the section schema's default exclusions, so an empty value turns them off the section schema's default exclusions (its boilerplate labels)
summarize_sections Section labels whose content units get a summary; * or an empty value summarizes every unit. It does not select what is extracted no summaries
summary_max_sentences Positive integer: sentences per summary 5
section_schema_id Section label schema: academic, clinical, fiction, financial, general, legal, manual, news, patent or standard resolved from the document
document_type_hint Free text describing the document, used to pick a section schema when section_schema_id is not given none
document_metadata JSON object (or a string holding one) of identity facts you assert about the document; see Document identity none

Section labels in a list are matched loosely: case is ignored, spaces and hyphens read as underscores, and a heading such as Materials and Methods maps to its label. Unknown labels are dropped with a warning, and a list in which no label is known returns 400. User instructions covers the three instruction fields.

To cap the number of content units each request processes, start the server with ontocast serve --head-chunks N.

Examples

# Text in a JSON body
curl -X POST http://127.0.0.1:8999/process \
  -H "Content-Type: application/json" \
  -d '{"text": "Your document text here", "render_mode": "facts"}'

# File upload into a tenant partition, provenance stripped
curl -X POST "http://127.0.0.1:8999/process?tenant=acme&project=reports&strip_provenance=true" \
  -F "file=@document.pdf"

# Document identity metadata
curl -X POST http://127.0.0.1:8999/process \
  -F "file=@document.pdf" \
  -F 'document_metadata={"doi": "10.1234/example", "title": "Example Report", "author": ["Jane Doe"], "project": {"name": "Example Project", "identifier": "PRJ-1"}, "identifiers": [{"scheme": "example:doc", "value": "DOC-1"}]}'

# Keep only the methods and results sections
curl -X POST http://127.0.0.1:8999/process \
  -F "file=@paper.pdf" -F "target_sections=methods,results"

Response

A request that passes the checks above returns 200 with one result per document, in upload order:

{
  "results": [
    {
      "filename": "paper.pdf",
      "status_code": 200,
      "outcome": {
        "status": "success",
        "data": {
          "facts": "@prefix cd: <...> . ...",
          "ontology": null,
          "ontology_artifacts": [
            {"iri": "https://...", "ontology_id": "...", "title": "...", "version": "1.0.1", "version_iri": "https://...#...", "triples": 42, "ttl": "..."}
          ]
        },
        "metadata": {"status": "...", "chunks_processed": 7, "chunks_remaining": 0, "budget": {}, "...": "..."}
      }
    }
  ]
}

Check every result: status_code is 200 when the document was extracted, 422 when it could not be (it could not be converted, its section selection matched nothing, it reached its token cap, or no content unit produced output), and 500 on an unexpected error. A failed outcome has "status": "error" with error, error_type, error_code and error_details; one document's failure does not stop the others.

In a successful outcome, data.facts is the merged facts graph in Turtle; it is empty in ontology mode. data.ontology_artifacts holds one entry per ontology the run created or changed (iri, ontology_id, title, version, version_iri, triples, ttl); version and version_iri are null when the run changed nothing for that ontology, so no version was written. data.ontology is always null.

metadata field Content
status Final status of the run
chunks_processed, chunks_remaining Content units processed and left unprocessed
budget LLM calls, cache hits, characters, triple counts and per-node timings; see Reading run telemetry
retrieval_metrics Retrieval, extraction and validation counters; see Telemetry counters
unit_context_sources The ontology IRIs each unit's prompt context was drawn from, by block (ontology, facts) and unit index
facts_repairs Rule-based rewrites applied to each content unit's facts, keyed by unit index
failed_units Content units that produced no output, with stage and reason; empty on a clean run
improvement_suggestions Advisory notes from the structural check and the consistency critic; nothing acts on them
facts_conformance Validation summary of the returned facts: whether SHACL ran and the graph conforms, counts by finding kind, constraint and shape, repairs applied; see Validation
facts_validation_findings The findings behind that summary, after every repair
facts_gate_repairs LLM-free repairs applied to the merged graph
ontology_versions The ontology versions the run wrote (role created or updated, with iri, version_iri, ontology_id, version, prior_version_iris) and read without changing (role read, with iri and version_iri)

A document in which no content unit produced output is a 422 result (error_code no_units_extracted), not an empty success.

POST /process_unit

Treats each document as one content unit: no chunking, section tagging, summarization or normalization. Use it for single passages, or to debug prompts. It takes the same body and parameters as /process; the section parameters have no effect.

curl -X POST http://127.0.0.1:8999/process_unit \
  -H "Content-Type: application/json" \
  -d '{"text": "Single paragraph to process."}'

The response has the shape of /process. Each ontology_artifacts holds at most one entry, the triples the unit added. The facts go through the same validation gate as in /process, except the repair that splits wrongly merged entities, which needs more than one unit. A failed unit is a 422 result.

Ontology catalog

These routes manage the catalog of the selected tenant and project. Uploads are Turtle files in a file form field. The path IRI is URL-encoded.

Route Behavior
GET /ontologies Lists every ontology: iri, ontology_id, title, description, versions (how many are stored), heads and diverged (true when it has more than one head; runs cannot extend it until a PUT merges it). Each head is a version summary: version_iri, version, prior_version_iris, created_at, modified_at, removed
GET /ontologies/{ontology_id}/versions The version history of the ontology the id (or IRI, or prefix) names, newest first: iri, ontology_id and one summary per version, as above. 404 for an unknown ontology
GET /ontologies/{ontology_id}/versions/{key} The named graph of that version as Turtle. {key} is the fragment of version_iri (<iri>#<key>). A tombstone returns its header only. 404 when the version is unknown
DELETE /ontologies/{ontology_id}/versions/{key} Tombstones the version: content dropped, header kept, typed oc:RemovedVersion. Returns version_iri and the ontology's new heads (nearest live ancestors become heads when a head is removed). 404 when the version is unknown
GET /ontologies/{ontology_id}/diff?from=<key>&to=<key> Content triples added and removed between two versions, header excluded: from_iri, to_iri, added and removed as sorted N-Triples lines, plus their counts. 404 when either version is unknown
POST /ontologies Adds the ontology as the root version of a new ontology. Returns iri, ontology_id, version and version_iri. 409 when an ontology with that IRI already exists: delete it first, or use PUT
PUT /ontologies/{iri} Uploads a new version derived from every current head, so it also merges a diverged ontology. Content equal to a single head's writes nothing and returns the head. An ontology with no live head is adopted as a new root. The file must declare the same ontology IRI as the path (400 otherwise)
DELETE /ontologies/{iri} Removes the ontology, every version included. Returns its iri
curl "http://127.0.0.1:8999/ontologies?tenant=acme&project=reports"

curl "http://127.0.0.1:8999/ontologies/obs/versions"

curl "http://127.0.0.1:8999/ontologies/obs/versions/<key>"

curl "http://127.0.0.1:8999/ontologies/obs/diff?from=<key>&to=<key>"

curl -X POST "http://127.0.0.1:8999/ontologies?tenant=acme&project=reports" \
  -F "file=@my-ontology.ttl"

curl -X PUT "http://127.0.0.1:8999/ontologies/https%3A%2F%2Fexample.org%2Fonto" \
  -F "file=@my-ontology-v2.ttl"

curl -X DELETE "http://127.0.0.1:8999/ontologies/https%3A%2F%2Fexample.org%2Fonto"

Shapes

These routes manage the SHACL shapes that extracted facts are validated against. Shapes are stored in their own partition, apart from the catalog; see Validation.

Route Behavior
GET /shapes Returns graph_uris, the stored documents, and triples, the size of all shapes merged
POST /shapes Adds a Turtle shapes document from the file form field. A document that declares <iri> a owl:Ontology is stored under that IRI, so uploading it again replaces it; otherwise it is named after the file. Returns graph_uri and triples, the size of all shapes merged
DELETE /shapes/{graph_uri} Removes the document. Documents loaded from FACTS_SHAPES_DIR come back at the next start
curl -X POST "http://127.0.0.1:8999/shapes?tenant=acme&project=reports" \
  -F "file=@my-shapes.ttl"

Flush

POST /flush

Deletes stored data. It cannot be undone.

Query parameters What is deleted
none Facts and ontologies in the triple store partition the server started with
tenant and/or project Facts and ontologies in that partition's triple store, and its vector-store collection. Returns 400 if the triple store has no partitions
include_shapes=true Also the shapes partition. Off by default: without shapes the SHACL gate stops running, and later runs report shacl_evaluated: null instead of failing
curl -X POST "http://127.0.0.1:8999/flush?tenant=acme&project=reports"

Graph matching

These routes compare graphs, for example an extracted graph against a reference. The match-graphs command runs the same matching locally; see Entity disambiguation. Graphs are Turtle strings in the JSON body.

Route Body Returns in data
POST /match/entities graphs (a list of {id, graph}), regime (ontology_loose (default) or ontology_strict), similarity_threshold (0 to 1; default AGG_SIMILARITY_THRESHOLD), embedding_model (default AGG_EMBEDDING_MODEL) Entity clusters across the graphs
POST /match/derive-matches clusters (from /match/entities), predicted_graph_id, gt_graph_id, similarity_threshold (default 0) entity_matches: one-to-one predicted-to-reference matches
POST /match/evaluate predicted_graph, gt_graph, entity_matches Triple, fact and entity precision, recall and F1. rdfs:label triples are not counted; entities are the subjects and objects that are not vocabulary. A ratio with a zero denominator (nothing predicted, or no reference) is null
{
  "graphs": [
    {"id": "gt:doc1.ttl", "graph": "@prefix ex: <https://gt.example/> . ..."},
    {"id": "predicted:doc1.ttl", "graph": "@prefix ex: <https://pred.example/> . ..."}
  ],
  "regime": "ontology_loose",
  "similarity_threshold": 0.8
}

Cross-document identity

GET /entities/cluster?iri=<entity IRI> reads the stored identity links (see Cross-document identity) and returns the entity's cluster:

Field Meaning
members The entities that are one with iri: each with its document graph, labels, types, the reason it joined (self, key, ifp, identifier or label) and the match nodes it shares (via)
kept_apart Candidates that share a match node but are not in the cluster, each with its veto
truncated true when more candidates were linked than one read collects

Returns 404 when no stored document holds the entity, and 501 when the triple store cannot answer SPARQL.

curl "http://127.0.0.1:8999/entities/cluster?iri=https://example.org/doc/a1b2/echr&tenant=acme&project=reports"

Errors

Error responses share one shape:

{"status": "error", "error": "...", "error_type": "...", "error_code": "..."}

/process and /process_unit add error_details where they have a failing stage or per-unit failures. A body that does not match a /match/* model, or an upload route called without file, gets FastAPI's standard 422 with a detail list instead.

Status Cause error_code
400 Unsupported content type, a form with no file, or a file with no name none
400 More files than MAX_FILES_PER_REQUEST too_many_files
400 Unrecognised render_mode, ontology_context_mode, llm_graph_format or strip_provenance value invalid_param:<name>
400 A tenant or project of only whitespace invalid_param:<name> on /process, /process_unit and /flush
400 max_visits or summary_max_sentences not a positive integer; document_metadata not a JSON object; a section list that is malformed JSON or names no known label invalid_param:<name>
400 fixed_single_ontology mode with no ontology id in the request or in ONTOLOGY_CONTEXT_FIXED_ONTOLOGY_ID none
400 No store configured on /flush; a Turtle file that does not parse, or whose ontology IRI does not match the path, on /ontologies or /shapes none
404 An unknown ontology or version on the /ontologies/{ontology_id}/... routes none
409 selected_vector_search_ontology requested but no vector store is configured and ready VECTOR_STORE_UNAVAILABLE
409 POST /ontologies with an IRI the catalog already holds none
422 No content unit produced output, including when the document could not be converted (/process) no_units_extracted
422 The uploaded file could not be converted (/process_unit) conversion_failed:<stage>
422 The single unit failed (/process_unit) none
422 A section selection (target_sections, or exclude_sections including the schema's default exclusions) removed every part of the document, with CHUNK_SECTION_FILTER_ON_EMPTY=error; with the default warn, the run continues with nothing to extract (/process) empty_section_selection:<name>
422 The document reached MAX_INPUT_TOKENS_PER_DOCUMENT or MAX_OUTPUT_TOKENS_PER_DOCUMENT; error_details.run_meter holds the usage budget_exceeded
500 Any other failure during processing or in a store none
503 /health only: the LLM client is missing none