---
title: "Ontologies"
section: "API Reference"
route: /apiontology
account: {accountId}
bruce_api: https://{accountId}.api.nextspace.host
guardian_api: https://guardian.nextspace.host
---
# Ontologies

An Ontology is a named group of Entity Types. It describes one domain of your data: the Entity Types in it, the relations between them, where their records come from, and documents that explain them.

Ontologies are managed in Operator, in the Entity Types area, where the Entity Type tree is grouped by Ontology and each Ontology has a diagram and a list of documents. In Navigator, Ask Nextspace scopes a conversation to one Ontology.

This article will cover how to manage Ontology records, how Entity Types belong to one, how to read the diagram of an Ontology in one request, and how to attach documents to it.

## Data model

Below is the core data model for an Ontology. The record itself holds no list of Entity Types; each Entity Type names its Ontology instead.

```typescript
interface IOntology {
    // Unique ID for the Ontology.
    // Exclude this value for new records.
    ID?: number;
    // Human readable name. Required. Limited to 120 characters, longer values are cut.
    Name: string;
    // Description of the Ontology and its purpose.
    Description?: string;
    // Saved layout of the Ontology diagram in Operator.
    // See the Diagram layout section below for the structure.
    Diagram?: IOntologyDiagram;
    // Free JSON object stored with the record.
    // Nothing in Operator, Navigator or Ask Nextspace reads or writes it today.
    Settings?: any;
    // What the requesting user can do with Ontologies.
    // A combination of "C" (create), "R" (read), "U" (update) and "D" (delete). Eg: "RU".
    // This is returned by the API and ignored when saving.
    Permission?: string;
    // ISO 8601 date time strings, set by the API.
    Created?: string;
    Updated?: string;
}
```

## Entity Types in an Ontology

An Entity Type joins an Ontology through its "Ontology.ID" value. An Entity Type belongs to at most one Ontology. Entity Types with no "Ontology.ID" are shown in Operator under "Default Ontology", which is not a record and has no ID.

```typescript
// Only the Ontology fields of an Entity Type are shown here.
interface IEntityType {
    // ID of the Ontology this Entity Type belongs to.
    // Send null or 0 to remove it from its Ontology.
    "Ontology.ID"?: number;
    // Saved layout of the diagram on this Entity Type's own Ontology tab in Operator.
    // Same structure as the Ontology's Diagram. Only returned when requested with Expand.
    OntologyDiagramSettings?: IOntologyDiagram;
}
```

Child Entity Types follow their parent. An Entity Type whose own "Ontology.ID" is empty counts as part of its parent's Ontology when we work out an Ontology's members for its diagram, up to 10 levels down. A child that names a different Ontology belongs to that one instead. When you change an Entity Type's Ontology in Operator, Operator also writes the same "Ontology.ID" to each of its descendants.

You can list the Entity Types tagged with an Ontology through the Entity Types request with "Ontology.ID={ontology_id}". That filter matches the "Ontology.ID" value only, and like the other filters it also returns the parents of each match. To get the full membership with inherited children, use the connections request below. You can read about Entity Types in [Entity Types](/apientitytype).

Deleting an Ontology does not delete its Entity Types. Their "Ontology.ID" is cleared, so they move to the Default Ontology.

## Requesting records

You can request a list of all Ontologies, ordered by name, or a single Ontology by ID. Each request checks the account's Ontology permissions.

### Get a list of Ontologies

```http
GET https://{accountId}.api.nextspace.host/ontologies
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |

**Response**

```typescript
interface IResponse {
    // Array of Ontology records.
    // See the data model above for the record structure.
    Items: IOntology[];
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/ontologies";
const method = "get";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

### Get Ontology by ID

```http
GET https://{accountId}.api.nextspace.host/ontology/{ontology_id}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{ontology_id}` | path | yes | The ID of the Ontology to get. |

**Response**

```typescript
// The response is the Ontology record directly.
// See the data model above for the record structure.
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/ontology/{ontology_id}";
const method = "get";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

## Create and update records

You can create a record by performing a POST request to the same URL as the GET. If you specify the ID as "0" then it'll create a new record and return it. If you specify an existing ID then it'll update the record and return it. An ID that does not exist returns a 404.

When updating, only the properties you include are changed. "Diagram" and "Settings" are replaced as a whole.

### Create or update Ontology

```http
POST https://{accountId}.api.nextspace.host/ontology/{ontology_id}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{ontology_id}` | path | yes | The ID of the Ontology to update. Set as 0 to create a new record. |

**Request body**

```typescript
// Body should be the Ontology JSON as specified at the top of the article.
```

**Example request body**

```json
{
    "Name": "My new Ontology",
    "Description": "Entity Types for the water network."
}
```

**Response**

```typescript
// The response is the Ontology record directly.
// See the data model above for the record structure.
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/ontology/{ontology_id}";
const method = "post";
const token = "your-token";
const body = {
    "Name": "My new Ontology",
    "Description": "Entity Types for the water network."
};

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

## Delete a record

We don't provide any bulk deletion but you can delete by record ID. Deleting an ID that does not exist still succeeds. Deleting an Ontology also deletes its document links, but not the files they point at.

### Delete Ontology

```http
DELETE https://{accountId}.api.nextspace.host/ontology/{ontology_id}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{ontology_id}` | path | yes | The ID of the Ontology to delete. |

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/ontology/{ontology_id}";
const method = "delete";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

## Ontology connections

The connections request returns every record an Ontology diagram draws, in one response. Operator's diagram is built from it. The Entity Types in scope are the Ontology's members as described above, and only those the user may view.

An Ontology is a closed set: the response holds the relations, sources and dependencies between its members, and an edge to an Entity Type outside it is left out.

### Get Ontology connections

```http
GET https://{accountId}.api.nextspace.host/ontology/{ontology_id}/connections?IncludeImports={true/false}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{ontology_id}` | path | yes | The ID of the Ontology to get the connections of. |
| `IncludeImports={true/false}` | query | no | Also return the file imports recorded against the Entity Types in scope. Default is false. |

**Response**

```typescript
interface IResponse {
    // The Entity Types in scope, without their Data Schemas.
    "EntityType": IEntityType[];
    // Entity Type relations where both Entity Types are in scope.
    "EntityType.Relation": IEntityTypeRelation[];
    // Where Entity Types get their records from: another Entity Type in scope, or a registered Source.
    // Returned without "DataMapping" and "FilterMapping".
    "EntityType.Source": any[];
    // One row per attribute whose Data Schema dictionary reads values from another Entity Type in scope.
    "EntityType.DictionaryDependency": IDictionaryDependency[];
    // The registered Sources the "EntityType.Source" rows point at.
    "Source": any[];
    // Every Entity Relation Type in the account, to name the relations.
    "EntityRelationType": any[];
    // File imports against the Entity Types in scope. Empty unless IncludeImports is true.
    "FileImport": any[];
}

interface IEntityTypeRelation {
    ID: number;
    "A.EntityType.ID": string;
    "B.EntityType.ID": string;
    // The Entity Relation Type this relation registers.
    "EntityRelationType.ID": string;
    // Attribute paths used as the foreign key on each side.
    "A.ForeignKey.AttributePath"?: string;
    "B.ForeignKey.AttributePath"?: string;
    // How many Entities may sit on side A for one Entity on side B, and the reverse.
    // A maximum of -1 means no limit.
    "A.Cardinality.Min": number;
    "A.Cardinality.Max": number;
    "B.Cardinality.Min": number;
    "B.Cardinality.Max": number;
}

interface IDictionaryDependency {
    // The Entity Type whose attribute uses the dictionary.
    "EntityType.ID": string;
    // The Entity Type the dictionary values come from.
    "Dictionary.EntityType.ID": string;
    // Key of the attribute in the Data Schema.
    "Attribute.Key": string;
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/ontology/{ontology_id}/connections";
const method = "get";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

A second form reads the same response for views that have no Ontology record: the Default Ontology, or a walk out from chosen Entity Types. You must give at least one of "Ontology.ID", "Unassigned" or "EntityType.ID". A walk from "EntityType.ID" follows relations, sources and child Entity Types for "Depth" steps. Children of the file container types "IFC", "BRZ", "ASSEMBLY", "DWG", "DXF", "PLANT3DZ" and "NWD" are only followed when you name that Entity Type yourself. "Ontology.ID" and "Unassigned" return their members only and are not walked out from.

### Get connections by query

```http
GET https://{accountId}.api.nextspace.host/ontologyConnections?Ontology.ID={ontology_id}&Unassigned={true/false}&EntityType.ID={type_id}&Depth={3}&IncludeParents={true/false}&IncludeImports={true/false}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `Ontology.ID={ontology_id}` | query | no | Include the members of this Ontology. |
| `Unassigned={true/false}` | query | no | Include the Entity Types that belong to no Ontology (the Default Ontology). |
| `EntityType.ID={type_id}` | query | no | Walk out from these Entity Types. Repeat the parameter or separate IDs with commas. |
| `Depth={3}` | query | no | How many steps to walk out from the given Entity Types. Default is 3, the maximum is 10. |
| `IncludeParents={true/false}` | query | no | Also walk up to parent Entity Types. Default is false. |
| `IncludeImports={true/false}` | query | no | Also return the file imports recorded against the Entity Types in scope. Default is false. |

**Response**

```typescript
// The response has the same structure as the Ontology connections request above.
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/ontologyConnections";
const method = "get";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

## Diagram layout

Operator saves the layout of an Ontology diagram in the Ontology's "Diagram" value, and the layout of an Entity Type's own diagram in that Entity Type's "OntologyDiagramSettings". Both hold the same structure. Nodes without a saved position are laid out automatically.

```typescript
interface IOntologyDiagram {
    // Operator writes 1.
    version: 1;
    // Position of each node on the diagram, keyed by node ID.
    nodePositions: Record<string, { x: number; y: number; }>;
    // IDs of the nodes the user has hidden, sorted.
    hiddenNodeIds: string[];
}

// Node IDs are one of:
// An Entity Type ID. Eg: "pipe".
// "external-source:" plus a Source ID, for a live Source.
// "file-source:" plus a Source ID, for a file Source such as CSV, KML or XLSX.
// "imported-file:" plus a file import ID, for an import shown with IncludeImports.
```

To save an Entity Type's diagram layout without saving the rest of the Entity Type, use the request below. It needs permission to edit the Entity Type. To read it back, request the Entity Type with "Expand=OntologyDiagramSettings".

### Save Entity Type diagram layout

```http
POST https://{accountId}.api.nextspace.host/entityType/{type_id}/ontologyDiagramSettings
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{type_id}` | path | yes | The ID of the Entity Type to save the diagram layout of. |

**Request body**

```typescript
interface IBody {
    OntologyDiagramSettings: IOntologyDiagram;
}
```

**Example request body**

```json
{
    "OntologyDiagramSettings": {
        "version": 1,
        "nodePositions": {
            "pipe": {
                "x": 0,
                "y": 0
            }
        },
        "hiddenNodeIds": []
    }
}
```

**Response**

```typescript
interface IResponse {
    "EntityType.ID": string;
    OntologyDiagramSettings: IOntologyDiagram;
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/entityType/{type_id}/ontologyDiagramSettings";
const method = "post";
const token = "your-token";
const body = {
    "OntologyDiagramSettings": {
        "version": 1,
        "nodePositions": {
            "pipe": {
                "x": 0,
                "y": 0
            }
        },
        "hiddenNodeIds": []
    }
};

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

## Documents

A document link attaches a Client File to an Ontology, usually a PDF or a Markdown file that explains the domain. A PDF can also link a Markdown summary of itself. Ask Nextspace reads the documents whose "Purpose" is "AI", and Operator uses "AI" unless you enter another Purpose. You can read about Client Files in [Client and temp files](/apiclientfile).

```typescript
interface IOntologyDocument {
    // Unique ID for the document link.
    // Exclude this value for new records.
    ID?: number;
    // ID of the Ontology the document belongs to. Required.
    // It cannot be changed on an existing link.
    "Ontology.ID": number;
    // ID of the document's Client File. Required.
    "ClientFile.ID": string;
    // Label that groups documents by who reads them.
    // Ask Nextspace reads documents with the Purpose "AI".
    Purpose?: string;
    // ID of a Markdown Client File holding a summary of the PDF.
    // Only a PDF document can have one. Send null to unlink it, which keeps the Markdown file.
    "SummaryClientFile.ID"?: string | null;
    // The "Version" of the PDF Client File the summary was made from.
    // When linking a summary it must equal the PDF's current Version.
    // The summary is current only while this matches the PDF's Version.
    SummarySourceVersion?: number | null;
    // Page count of the PDF, counted by the API. Ignored when saving.
    // Missing when the count is unknown or the document is not a PDF.
    SourcePageCount?: number;
    // Returned by the API and ignored when saving.
    ClientFile?: ClientFile.IFile;
    SummaryClientFile?: ClientFile.IFile;
    Ontology?: IOntology;
    // ISO 8601 date time strings, set by the API.
    Created?: string;
    Updated?: string;
}
```

A summary is outdated once the PDF is replaced with a new version. Replacing the PDF and linking a new summary are two separate saves: save the new PDF first, then link a summary made from it.

## Documents: Requests

You can list the document links of an Ontology, or find the links that use a Client File as the document or as the summary. Give exactly one of the query parameters.

### Get a list of Ontology documents

```http
GET https://{accountId}.api.nextspace.host/ontology/documents?ontology_id={ontology_id}&client_file_id={file_id}&summary_client_file_id={file_id}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `ontology_id={ontology_id}` | query | no | List the documents of this Ontology. |
| `client_file_id={file_id}` | query | no | List the links that use this Client File as the document. |
| `summary_client_file_id={file_id}` | query | no | List the links that use this Client File as the summary. Links to Ontologies or PDFs you cannot view are left out. |

**Response**

```typescript
interface IResponse {
    // Array of document links.
    // See the documents data model above for the record structure.
    Items: IOntologyDocument[];
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/ontology/documents";
const method = "get";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

Saving a link needs permission to edit the Ontology and to view the Client Files. Without an "ID", a link with the same "Ontology.ID", "ClientFile.ID" and "Purpose" is updated rather than duplicated. Keys you leave out of the body are left unchanged.

### Create or update Ontology document

```http
POST https://{accountId}.api.nextspace.host/ontology/document
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |

**Request body**

```typescript
// Body should be the document JSON as specified in the documents section.
```

**Example request body**

```json
{
    "Ontology.ID": 1,
    "ClientFile.ID": "your_client_file_id",
    "Purpose": "AI"
}
```

**Response**

```typescript
// The response is the document link directly.
// See the documents data model above for the record structure.
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/ontology/document";
const method = "post";
const token = "your-token";
const body = {
    "Ontology.ID": 1,
    "ClientFile.ID": "your_client_file_id",
    "Purpose": "AI"
};

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

Deleting a link does not delete its Client Files. Deleting an ID that does not exist still succeeds.

### Delete Ontology document

```http
DELETE https://{accountId}.api.nextspace.host/ontology/document/{document_id}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{document_id}` | path | yes | The ID of the document link to delete. |

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/ontology/document/{document_id}";
const method = "delete";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

Before generating a summary, Operator checks the source with the request below. It needs permission to edit the Ontology, and fails if the document is not a PDF.

### Get document summary source

```http
GET https://{accountId}.api.nextspace.host/ontology/document/{document_id}/summary-source
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{document_id}` | path | yes | The ID of the document link to check. |

**Response**

```typescript
interface IResponse {
    ID: number;
    "Ontology.ID": number;
    "ClientFile.ID": string;
    // The PDF Client File, including its current Version.
    ClientFile: ClientFile.IFile;
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/ontology/document/{document_id}/summary-source";
const method = "get";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

## Describe with AI

The describe request asks the account's AI provider to write a Markdown description of an Ontology. We send it the Ontology's tagged Entity Types, every Entity Type reachable from them through Entity Type relations, and their sources. The response is the Markdown text itself, not JSON. Operator's "Suggest ontology document" uses it to draft a new document. If the account has no AI key configured, it returns a 503 with "AINotConfigured".

### Describe Ontology

```http
POST https://{accountId}.api.nextspace.host/ontology/{ontology_id}/describe
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{ontology_id}` | path | yes | The ID of the Ontology to describe. |

**Example request body**

```json
{}
```

**Response**

```typescript
// The response is Markdown text with the content type "text/markdown".
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/ontology/{ontology_id}/describe";
const method = "post";
const token = "your-token";
const body = {};

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

## Ask Nextspace

Navigator's Ask Nextspace scopes each conversation to one Ontology, or to none. The user can pick one from the chat menu. Otherwise the Project View's default applies, set in its "llms.ontologyId" setting. You can read about that setting in [Project Views](/apiprojectview#apiprojectviewdefaults).

With an Ontology in scope, the assistant is given that Ontology's Entity Type hierarchy and a list of its "AI" documents, which it reads when a question needs them. A current PDF summary is offered alongside its PDF. When neither the user nor the Project View sets an Ontology, the assistant may pick one for that message only, and nothing is saved.

## AI tools in Operator

Operator offers these AI tools around Ontologies. Each produces a draft for you to review, and nothing is saved until you choose to save it.

- Suggest ontology document: drafts a Markdown document from the describe request above.
- Generate AI summary: drafts a Markdown summary of a PDF document through Operator's chat service. Saving it uploads the Markdown as a Client File and links it as "SummaryClientFile.ID".
- Convert ontology: on a diagram, suggests how the shown Entity Types map onto another Entity Type hierarchy, through "entityType/ontology/aiSuggestOptimisation".
- Unify ontology sources: on a diagram, suggests one Data Schema and mapping for the shown Entity Types, through "v1/entityType/DataSchema/SuggestUnification".

---

Urls on this page are resolved for account `{accountId}`.
Site index: https://docs.nextspace.host/llms.txt · whole site in one file: https://docs.nextspace.host/llms-full.txt
Human-readable version of this page: https://docs.nextspace.host/apiontology
