> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open-metadata.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Ontology API Reference | OpenMetadata

> REST endpoints for ontologies, concepts, properties, constraints, releases, imports, library packs, relationship types, and AI proposals.

# Ontology API Reference

Ontologies are managed through ordinary OpenMetadata REST APIs. The visual authoring workspace, Ontology Studio, is available only in Collate; these endpoints are part of OpenMetadata. The relational model is authoritative, so creating, editing, publishing, importing, and exporting an ontology don't need the RDF triple store. Where an endpoint needs RDF or an LLM provider, the table says so.

```bash theme={null}
export OM_HOST=http://localhost:8585
export TOKEN=<your-personal-access-token>
```

Paths in the Ontologies table are relative to `/api`. Paths in the other tables are relative to the base path shown above each table. Every entity group below also supports the standard entity operations, so each table lists them once.

## Ontologies

`/api/v1/ontologies`

| Method | Path | Purpose |
| - | - | - |
| `GET` | `/v1/ontologies` | List ontologies. |
| `GET` | `/v1/ontologies/{id}`, `/v1/ontologies/name/{fqn}` | Fetch one. |
| `POST` | `/v1/ontologies` | Create an ontology. |
| `PUT` | `/v1/ontologies` | Create or update. |
| `PATCH` | `/v1/ontologies/{id}` | JSON Patch. |
| `DELETE` | `/v1/ontologies/{id}`, `/v1/ontologies/name/{fqn}` | Delete. |
| `PUT` | `/v1/ontologies/restore` | Restore a deleted ontology. |
| `GET` | `/v1/ontologies/{id}/versions`, `/v1/ontologies/{id}/versions/{version}` | Version history. |
| `GET` | `/v1/ontologies/{id}/state` | Working and activation revision numbers, and the active release. |
| `GET` | `/v1/ontologies/{id}/working/diff` | Unpublished changes compared with the active release. Takes `limit` (1–1,000, default 25) and `after`. Add `groupBy=concept` to group the changes by concept. |
| `POST` | `/v1/ontologies/{id}/releases` | Capture a release. For more information, see [Capture a Release](#capture-a-release). |
| `GET` | `/v1/ontologies/{id}/releases` | List the sealed releases of the ontology, newest first. |
| `PUT` | `/v1/ontologies/{id}/activation` | Activate an approved release, or roll back to an older approved one. |
| `POST` | `/v1/ontologies/{id}/sparql` | Read-only SPARQL over one version of the ontology. Takes `scope=release` (default, the active release) or `scope=draft`. The draft includes unpublished edits and needs `EditAll` on the ontology. |
| `POST` | `/v1/ontologies/{id}/imports/preview` | Turn a local RDF or native CSV file into a list of proposed changes. Saves nothing. |
| `POST` | `/v1/ontologies/imports/preview` | Count what a file would import into a new ontology. |
| `POST` | `/v1/ontologies/imports/detect` | Name the format of a local ontology file. |
| `GET` | `/v1/ontologies/{id}/export` | Export the current draft. Takes `format`. Needs edit permission. |
| `GET` | `/v1/ontologies/{id}/working/validation` | Validate the working draft. Needs edit permission. |
| `POST` | `/v1/ontologies/{id}/library/{packId}/summary` | Summarize the selected library pack modules for the ontology. |
| `POST` | `/v1/ontologies/{id}/library/{packId}/preview` | Preview library pack modules as draft changes. |
| `POST` | `/v1/ontologies/{id}/library/{packId}/review` | List the changes an install would make. |
| `POST` | `/v1/ontologies/{id}/library/{packId}/install` | Start a pack install as a background job. |
| `GET` | `/v1/ontologies/{id}/library/jobs/{jobId}` | Read the progress of an install job. |
| `PUT` | `/v1/ontologies/{id}/library/jobs/{jobId}/cancel` | Cancel an install job. |
| `GET` | `/v1/ontologies/{id}/references` | Find working definitions that reference an IRI. Takes `iri`. |
| `GET` | `/v1/ontologies/{id}/dataGraph` | Data graph of the ontology for the **Data** layer. |
| `POST` | `/v1/ontologies/{id}/dataGraph/pages` | Read a page of the data graph. |
| `GET` | `/v1/ontologies/reviews` | List release reviews. Takes `view` (`assigned`, `created`, or `pending`) and `ontologyId`. |

### Notable Fields

The ontology and release entities carry the review state of a release. These fields are read-only outputs of the release flow.

| Entity | Fields |
| - | - |
| Ontology | `approvalRule` (the rule that decides when reviewers approve), `installedPacks`, and the working and activation revisions. |
| Release | `publicationStatus`, `lifecycleStatus`, `approvalBasis` (`REVIEWED` or `NO_REVIEWERS_CONFIGURED`), and `changeSummary`. |
| Concept | `abstract`, `definitionSource`, `deprecated`, and `replacedBy`. |
| Property | `superProperties`. |

## Concepts

`/api/v1/ontologyConcepts`

| Method | Path | Purpose |
| - | - | - |
| `GET` | `/` | List concepts. Takes `ontology` (the ontology name), `fields`, `limit`, `before`, `after`, and `include`. |
| `GET` | `/{id}`, `/name/{fqn}` | Fetch one. |
| `POST` | `/` | Create. |
| `PUT` | `/` | Create or update. |
| `PATCH` | `/{id}` | JSON Patch. |
| `DELETE` | `/{id}`, `/name/{fqn}` | Delete. |
| `PUT` | `/restore` | Restore. |
| `GET` | `/{id}/versions`, `/{id}/versions/{version}` | Version history. |
| `GET` | `/{id}/bindings` | One page of the catalog assets bound to the concept. `limit` 1 to 100, default 100. |
| `PUT` | `/{id}/bindings` | Replace one binding. |
| `DELETE` | `/{id}/bindings/{assetType}/{assetId}` | Remove one binding. Takes `expectedRevision`. |
| `POST` | `/{id}/query` | Generate SQL over the concept's bound tables. |
| `GET` | `/{id}/deleteImpact` | Count what deleting the concept would affect, such as child concepts, relationships, rules, and bindings, and list the definitions that block the deletion. |
| `GET` | `/boundTo/{assetType}/{assetId}` | List the concepts bound to a catalog asset. |

Concept bindings are catalog links. They apply right away and aren't part of a release.

## Properties

`/api/v1/ontologyProperties`

Same operations as concepts, without the bindings and `query` routes: list, fetch by `{id}` or `/name/{fqn}`, create, `PUT`, `PATCH`, delete, `/restore`, and version history. `GET` takes `ontology` to list the properties of one ontology.

## Constraints

Constraints are stored as axioms. `/api/v1/ontologyAxioms`

| Method | Path | Purpose |
| - | - | - |
| `GET` | `/` | List. Takes `ontologyId`. |
| `GET` | `/{id}`, `/name/{fqn}` | Fetch one. |
| `POST` | `/` | Create. |
| `POST` | `/validate` | Validate an axiom without saving it. |
| `PUT` | `/` | Create or update. |
| `PATCH` | `/{id}` | JSON Patch. |
| `DELETE` | `/{id}` | Delete. |
| `PUT` | `/restore` | Restore. |
| `GET` | `/{id}/versions`, `/{id}/versions/{version}` | Version history. |

Axiom types: `SUBCLASS_OF`, `EQUIVALENT_CLASS`, `DISJOINT_WITH`, `CLASS_ASSERTION`, `OBJECT_PROPERTY_ASSERTION`, `DATA_PROPERTY_ASSERTION`.

## Releases

A release is an immutable snapshot of an ontology. `/api/v1/ontologyReleases`

| Method | Path | Purpose |
| - | - | - |
| `GET` | `/` | List sealed releases. Takes `ontologyId`, `limit` (1–1,000, default 50), and `after`. |
| `GET` | `/{id}` | Fetch one release. |
| `GET` | `/{id}/versions/{version}` | The release header version submitted to an approval workflow. |
| `GET` | `/{id}/diff` | Compare the release with another. Takes `baseReleaseId`, `limit`, and `after`. |
| `GET` | `/{id}/structure` | Check property declarations and axiom structure. |
| `GET` | `/{id}/validation` | Validate the release. |
| `GET` | `/{id}/export` | Export the release. For more information, see [Export a Release](#export-a-release). |
| `GET` | `/{id}/review` | Read the review of the release as the calling user sees it. |
| `GET` | `/{id}/events` | Captured, review requested, review withdrawn, approved, rejected, and activated events. Takes `limit` and `after`. |
| `GET` | `/{id}/members/{kind}` | Page through the immutable members of the release. |
| `GET` | `/{id}/members/{kind}/{memberId}` | Read one member. |

### Capture a Release

`POST /api/v1/ontologies/{id}/releases` takes this body:

| Field | Required | Notes |
| - | - | - |
| `expectedWorkingRevision` | Yes | The working revision you saw in `GET /v1/ontologies/{id}/state` or the working diff. |
| `expectedActivationRevision` | No | The activation revision you saw with the working diff. |
| `versionBump` | No | `major`, `minor`, or `patch`. Allocates the next semantic version. |
| `expectedLatestReleaseRevision` | When `versionBump` is set | The latest release revision you saw. |
| `releaseNotes` | No | Notes kept with the release. |

`PUT /api/v1/ontologies/{id}/activation` takes `releaseId` and `expectedActivationRevision`, both required.

### Export a Release

`GET /api/v1/ontologyReleases/{id}/export` exports the captured definitions, independent of working edits and of RDF availability.

| Parameter | Notes |
| - | - |
| `format` | `turtle` (default), `rdfxml`, `ntriples`, `jsonld`, `skos`, `skos-xl`, or `csv`. |
| `includeInverses` | Also write the inverse of each relationship. |
| `includeBoundAssets` | Also write the data assets bound to concepts. |
| `shaclGate` | Refuse the export with status `422` if the release has SHACL violations. |

```bash theme={null}
curl "$OM_HOST/api/v1/ontologyReleases/{id}/export?format=turtle&includeInverses=true" \
  -H "Authorization: Bearer $TOKEN"
```

### Preview an Import

`POST /api/v1/ontologies/{id}/imports/preview`, `POST /api/v1/ontologies/imports/preview`, and `POST /api/v1/ontologies/imports/detect` take a JSON body:

| Field | Required | Notes |
| - | - | - |
| `data` | Yes | The file content as a string. |
| `fileName` | No | The file name. Format detection uses its extension only when the content has no recognizable signature. |
| `format` | No | `turtle`, `rdfxml`, `ntriples`, `jsonld`, or `csv`. When omitted, the server detects it from the content first and the file name second. |

The preview with an ontology id compares the file with that ontology's working revision. It returns the detected format, counts of what the file would add, update, or repeat, and the change set request that applies it. The preview without an id parses the file against an empty ontology, and needs permission to create ontologies. `imports/detect` reads at most the first 65,536 characters. None of them save anything.

```bash theme={null}
curl -X POST "$OM_HOST/api/v1/ontologies/{id}/imports/preview" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile data domain.ttl '{fileName: "domain.ttl", data: $data}')"
```

## Change Sets

Durable authoring sessions with typed operations. A change set is created and applied for you when you import a file. `/api/v1/ontologyChangeSets`

| Method | Path | Purpose |
| - | - | - |
| `GET` | `/` | List. |
| `GET` | `/{id}` | Fetch one. |
| `POST` | `/` | Create a change set. |
| `PUT` | `/{id}/operations` | Replace draft operations. |
| `POST` | `/{id}/undo`, `/{id}/redo` | Move the draft cursor. |
| `POST` | `/{id}/submit` | Submit for review. |
| `POST` | `/{id}/apply` | Apply the active operations. |
| `POST` | `/{id}/discard` | Discard. |
| `DELETE` | `/{id}` | Delete. |
| `PUT` | `/restore` | Restore. |
| `GET` | `/{id}/versions`, `/{id}/versions/{version}` | Version history. |

## Library Packs

`/api/v1/ontologyPacks`

| Method | Path | Purpose |
| - | - | - |
| `GET` | `/` | List library packs. |
| `GET` | `/{packId}` | Manifest: modules, dependencies, counts, SHA-256 checksums, and license. |
| `GET` | `/{packId}/sample` | Preview selected concepts. Takes `moduleIds`. |
| `POST` | `/{packId}/install` | Install a pack into a new ontology. |

To install a pack into an existing ontology, review it with `POST /v1/ontologies/{id}/library/{packId}/review`, start it with `POST /v1/ontologies/{id}/library/{packId}/install`, and read the job with `GET /v1/ontologies/{id}/library/jobs/{jobId}`.

## Relationship Types

Governed OWL object properties. `/api/v1/relationshipTypes`

| Method | Path | Purpose |
| - | - | - |
| `GET` | `/` | List. |
| `GET` | `/{id}`, `/name/{fqn}` | Fetch one. |
| `POST` | `/` | Create. |
| `PUT` | `/` | Create or update. |
| `PATCH` | `/{id}` | JSON Patch. |
| `DELETE` | `/{id}` | Delete a custom type. |
| `PUT` | `/restore` | Restore a deleted type. |
| `GET` | `/{id}/versions`, `/{id}/versions/{version}` | Version history. |

Related: `GET /api/v1/glossaryTerms/relationTypes/usage` returns usage counts per type.

## Reasoning and AI

The following endpoints explain inferences and propose changes with AI.

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/api/v1/ontology/reasoning/explanations` | Explain an asserted or materialized RDF statement in a glossary. It takes a `glossaryId`, needs `ViewBasic` on that glossary, and needs the RDF store enabled. Without it the call fails with `503`. |
| `POST` | `/api/v1/ontology/ai/relationships/suggestions` | Propose reviewable relationships. |
| `POST` | `/api/v1/ontology/ai/mappings/suggestions` | Propose reviewable external concept mappings. |
| `POST` | `/api/v1/ontology/ai/sparql` | Generate a visible read-only SPARQL query from a question. |
| `POST` | `/api/v1/ontology/ai/drafts` | Generate a reviewable change set draft. |

The `/api/v1/ontology/ai` routes need `RDF_AI_ENABLED=true` and a configured LLM provider.

## Create a Custom Relationship Type

This request creates a custom relationship type.

```bash theme={null}
curl -X POST "$OM_HOST/api/v1/relationshipTypes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "regulatedBy",
    "displayName": "Regulated By",
    "description": "The concept is subject to this regulation.",
    "category": "CUSTOM",
    "rdfPredicate": "https://example.com/ontology/regulatedBy",
    "characteristics": [],
    "crossGlossaryAllowed": true,
    "paletteKey": "AMBER"
  }'
```

## Read the Unpublished Changes of an Ontology

This request reads the unpublished changes of an ontology.

```bash theme={null}
curl "$OM_HOST/api/v1/ontologies/{id}/working/diff?limit=25" \
  -H "Authorization: Bearer $TOKEN"
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.