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.
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 |
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 |
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:
/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 |
What to read next¶
- Configuring OntoCast: the server settings behind each default.
- User instructions: steering extraction per request.
- How OntoCast works: what happens inside
/process.