Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.


Related Unitlab capability guides: Unitlab’s data annotation platform