Ontologies API

List, retrieve, create, and save reusable Ontology schemas with explicit structures and revisions.

Outcome: List, retrieve, create, and save reusable Ontology schemas with explicit structures and revisions.

Endpoints

Method	Endpoint	Purpose
GET	/api/sdk/ontologies/	List current non-archived Workspace Ontologies
POST	/api/sdk/ontologies/	Create a reusable Ontology
GET	/api/sdk/ontologies/{ontology_hash}/	Retrieve one Ontology and structure
PUT	/api/sdk/ontologies/{ontology_hash}/	Save complete mutable fields and create a revision

List filters include title_eq, title_like, desc_eq, desc_like, created_before, created_after, edited_before, and edited_after.

Create an Ontology

curl --fail-with-body --silent --show-error \
  -X POST "$UNITLAB_API_URL/api/sdk/ontologies/" \
  -H "Authorization: Api-Key $UNITLAB_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "title":"Road ontology",
    "description":"Production road-scene policy",
    "data_type":"image",
    "structure":{"objects":[],"classifications":[]}
  }'

The response identifier is ontology_hash. Project creation can reference it. Creation makes a Workspace Ontology available immediately.

Save a revision

Read the current Ontology, change the complete intended document, then send PUT with title, description, data type, and the complete structure. Do not treat PUT as a partial patch.

Validate object and classification classes, properties, relations, item properties, conditional logic, required fields, and dynamic temporal properties before saving. Test the new revision in a controlled Project before using it in production work.

Request operating contract

Concern	Required behavior
Execution surface	TLS-verified client using the reviewed current public /api/sdk/... route contract.
Identity	Least-privilege workspace service identity; secrets remain outside code and logs.
Request boundary	URL-encoded stable IDs, explicit deadlines, structured errors, and complete pagination.
Success evidence	Response identifiers, read-after-write verification, and separate processing status for Batch Queues.

Do not infer undocumented private routes. After a timeout, inspect remote state before repeating a mutation.

---

Related Unitlab capability guides: Unitlab’s data annotation platform