> For the complete documentation index, see [llms.txt](https://docs.unitlab.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.unitlab.ai/api-sdk-cli/apis/ontologies-api.md).

# Ontologies API

{% hint style="info" %}
**Outcome:** List, retrieve, create, and save reusable Ontology schemas with explicit structures and revisions.
{% endhint %}

### 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

```bash
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. |

{% hint style="warning" %}
Do not infer undocumented private routes. After a timeout, inspect remote state before repeating a mutation.
{% endhint %}