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

# Auto-ontology (Premium Ontology)

> Let Cognee build an ontology from your own data, refine it in plain language, and give your agents more precise retrieval

Auto-ontology replaces Cognee's generic entity types with a taxonomy of entity types that comes from your own data, and lets you refine it by describing changes in plain language. It is part of **Premium Ontology**, a **\$99 / month** add-on. The base knowledge graph stays free.

## What an ontology is in Cognee

An ontology is the structure your memory is sorted into. It has three parts:

| Part | What it is | Example |
| - | - | - |
| **Entity types** | The categories of things in your data, each with a one-sentence definition | *Customer*, *Incident record*, *Credit approval* |
| **Hierarchy** | Which entity types are specializations of others (`is_a`) | *Enterprise customer* is a *Customer* |
| **Relations** | How entity types connect: who performs what, what it produces, requires, permits, or blocks | *Approver* performs *Credit approval* |

Every **entity** Cognee extracts (a person, a ticket, an invoice) gets the most specific entity type that fits it.

## Default ontology vs. auto-generated ontology

**Default (free).** Cognee extracts entities with generic types such as *Person*, *Organization*, *Location*, or *Concept*. That works for any dataset, but it does not know that, in your company, a customer and an employee are different kinds of person, or that incidents and incident records are the same thing.

**Auto-generated (Premium).** Cognee reads your dataset and works out the entity types your company actually talks about, with definitions, a hierarchy, and the relations between them. Your entities are then sorted into these sharper types. On the [Graph](https://docs.cognee.ai/cognee-cloud/ui/knowledge-graph.md) page the result appears as extra domains and sub-domains, and the entity types and entities that are new or changed are highlighted.

> [!TIP]
>
> Think of it as your company's taxonomy of entity types. The more precise it is, the easier it is for an agent to retrieve the right context: a question about "open incidents for enterprise customers" can be answered from the right entity types instead of a pile of generic *Concept* nodes.

## Generate an ontology

> [!NOTE]
>
> The Premium ontology view on the Graph page, with its generate action and the ontology chat editor, is rolling out with the November 2026 launch, so exact labels may differ slightly from this page. Until it reaches your workspace, the editor is available through the [API](#api).

**1. Add data first**

Auto-ontology works from what is already in a dataset, so [add data](https://docs.cognee.ai/cognee-cloud/functionality/data-ingestion.md) and let it finish processing. The richer the dataset, the better the taxonomy.

**2. Open the Graph page**

Open [Graph](https://docs.cognee.ai/cognee-cloud/ui/knowledge-graph.md) in the sidebar and choose the dataset.

**3. Start the generation**

Switch to the Premium ontology view and start the generation. You need an active Premium Ontology plan; see [Who can use it](#who-can-use-it).

**4. Keep working while it runs**

Generation runs in the background. It takes several times longer than a normal ingestion (roughly four times as long), so you do not need to wait on the page. When it finishes, the Premium ontology view shows the new domains, entity types, and the entities that moved into them.

Generation calls the language model, so its tokens are billed from your workspace credits at the normal rate (\$0.10 per 1M tokens), on top of the subscription. If the workspace has no credit left, generation is refused until you [add credits](https://docs.cognee.ai/cognee-cloud/functionality/account-and-billing.md).

As your data grows, the Graph page keeps placing new entity types into domains and sub-domains. A type that has been placed keeps its place. Placing new types is a small language-model call, billed from workspace credits on every plan.

## Refine it with the ontology chat editor

The ontology chat editor lets you change the ontology by describing what you want, instead of editing a schema file. Open it from the Premium ontology view, or from the card of an entity type to make a change about that type.

**1. Describe the change**

Write the change in your own words. A request can hold several changes, up to 4,000 characters.

**2. Review the proposal**

Cognee reads your request and turns it into concrete changes, each with its impact (for example, how many entities it affects). Nothing changes yet. A change Cognee could not understand, or one that cannot be applied, is marked as such.

**3. Apply**

Confirm to apply the proposal. All changes in it are applied together, or none of them are.

Example requests:

* *Merge incidents into incident records.*
* *Rename Client to Customer.*
* *Split Event into Customer meeting and Internal meeting.*
* *Move Invoice into Finance.*
* *Add a new type Approver: the person who signs off a credit request.*
* *Customers own contracts.* (adds a relation)
* *Employees do not report to customers.* (removes a relation)

| Change | What it does |
| - | - |
| Rename | Shows an entity type under a new name |
| Merge | Folds one or more entity types into another; their entities follow |
| Split | Sorts the entities of one type into new, more specific types (runs as a background job) |
| Move | Places an entity type in another domain or sub-domain |
| New type | Adds an entity type with a definition and, optionally, a domain |
| Add / remove relation | Adds a relation between two entity types, or removes one that is wrong |

Renames, merges, moves, new types and relation changes are stored as decisions on top of the graph, not written into it, so they survive rebuilds: when the graph is built again, the same decisions apply. A split is the exception: it re-types the entities in the graph itself. A dataset can hold up to 200 added entity types and 1,000 relation changes.

Reading a request and splitting a type call the language model, so they use workspace credits like generation does.

## How it improves retrieval

Agents and search read the graph through its entity types. With an ontology built from your data:

* Questions land on the right category (customers vs. employees, incidents vs. incident records), so fewer irrelevant entities reach the agent's context.
* Entities that were scattered across generic types are grouped, so "how do credit approvals usually work" can be answered from one entity type and its relations instead of dozens of loose chunks.
* Relations carry meaning (*performs*, *requires*, *blocks*) instead of a vague "related to", so multi-step questions follow the right path.

## Who can use it

| | Free workspace | Premium workspace |
| - | - | - |
| Base knowledge graph on the Graph page | Yes | Yes |
| Domain map of your entity types | Yes | Yes |
| Auto-generated ontology | Locked; you can see that more structure is available | Yes |
| Ontology chat editor | Locked | Yes |

A Premium Ontology subscription belongs to a **workspace owner** and makes every workspace that person owns Premium; members of those workspaces get it at no cost. Only an owner can subscribe; members see *"Only a workspace owner can subscribe."* Subscribe from **Premium** in the top bar or on the Billing page; see [Premium Ontology billing](https://docs.cognee.ai/cognee-cloud/functionality/account-and-billing.md#premium-ontology).

## When Premium ends

If you cancel, Premium stays active until the end of the paid period. After that, your workspaces lose:

* **Automatically generated ontologies**: new data is no longer modelled into ontologies for you.
* **The ontology chat editor**: you can no longer refine ontologies by chatting with the editor.
* **Extra domains and sharper types**: your knowledge graph goes back to the standard ontology.

Your data and your base graph are not deleted. Changes you already made with the editor stay on your map; you cannot make new ones until you subscribe again.

If a renewal payment fails, Premium is paused until Stripe collects it: *"Your last Premium payment did not go through, so Premium is paused. Stripe retries it with the card on file."*

## API

The ontology chat editor is also available on the tenant API, under `/api/v1/datasets/{dataset_id}/knowledge-map/edits`. Making a change needs an active Premium Ontology plan and write permission on the dataset; reading the changes in force needs only read permission and works on any plan.

| Endpoint | What it does |
| - | - |
| `POST .../knowledge-map/edits/propose` | Turns `{"text": "...", "about": "<entity type>"}` into proposed operations with their impact. Writes nothing |
| `POST .../knowledge-map/edits` | Applies `{"operations": [...]}` (1 to 50), all or none. Answers `202` with a `jobId` |
| `GET .../knowledge-map/edits/jobs/{jobId}` | The job's status: `queued`, `running`, `done`, or `failed` |
| `GET .../knowledge-map/edits` | The changes in force for the dataset |

| Status code | Meaning |
| - | - |
| `403` | `premium_required`: the workspace is not on Premium Ontology |
| `402` / `429` | The workspace has no credit left for the language-model call |
| `404` | The dataset does not exist, or you lack the needed permission on it |
| `409` | The dataset's domain map is not built yet; reading it (`GET /api/v1/datasets/{dataset_id}/knowledge-map`, or opening the Graph page) builds it |
| `422` | An operation was refused (for example an unknown entity type or a name already taken), or the request reads as more than 50 changes |
| `503` | `premium_unavailable` (the plan could not be checked), or the map was busy; send the request again |

## Uploading your own ontology

If you already maintain a formal ontology (OWL, Turtle, JSON-LD), you can upload it and use it during extraction instead. That is free and works on any plan; see [Configuration & Ontologies](https://docs.cognee.ai/cognee-cloud/functionality/configuration-and-ontologies.md#ontologies).


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