The AI assistance API uses the AI Service to help you build an ontology and prepare data for it. It also lets you declare a class as an MCP tool that AI agents can call. You don't need any of these calls to build or use an ontology.
The AI calls return proposals. They don't change your ontology. To apply a proposal, use the classes, relationships, and rules APIs. When you omit a team ID, the platform sets up an AI Service team for the call and returns its ID, so you can reuse it.
If the AI Service refuses a request, the call returns the AI Service's status code and message unchanged. Other AI Service failures return 502, or 504 on a timeout.
Every call needs an Authorization: Bearer <token> header. For more information, see AI and reasoning and Application Ontology Service.
This section contains the following API calls:
Generate a model
Proposes classes, relationships, and rules from a natural-language prompt. You need READ on the ontology. The response returns the AI Service output as is, so validate it before you use it.
The proposal covers the ontology's schema only: classes, properties, relationships, rules, and validators. It doesn't propose individuals or the relationships between them. If your prompt names individuals, the response lists them in a warning instead. To load individuals, use Import individuals or the Individuals API.
Endpoints
POST /aosvc/api/v1/ontologies/{ontologyId}/ai/generate-model
Parameters
Path
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ontology ID | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | Namespace filter to apply. It must name only namespaces that the ontology belongs to. | Required |
Body
| Parameter | Type | Description | Required |
|---|
_prompt | String | What to generate, up to 500 characters | Required |
_teamId | String | The ID of an AI Service team to reuse | Optional |
_currentModel | Object | The application model you're working on. If you omit it, the AI treats the application model as empty. | Optional |
_conversationHistory | Array of Object | Up to 20 earlier messages. Each is { "_role": "user" or "assistant", "_content": "..." }. | Optional |
_attachments | Array of Object | Up to 10 file versions from the File Service. Each is { "_fileId": "...", "_fileVersionId": "..." }. | Optional |
Example:
{
"_prompt": "Add pumps and the rooms they sit in, with a locatedAt relationship",
"_currentModel": {
"classes": []
}
}
Response
{
"_output": {
"contractVersion": "ontology-studio-ai/v2",
"mode": "extend",
"upserts": {
"extensions": [
{ "className": "Pump", "parentClass": "Equipment" },
{ "className": "Room", "parentClass": "Space" }
],
"relationshipEdges": [
{ "propertyName": "locatedAt", "sourceClassName": "Pump", "targetClassName": "Room" }
],
"objectPropertyDefinitions": [],
"rules": [
{ "type": "relationship_rule", "property": "locatedAt" }
],
"validators": {}
},
"deletes": [],
"warnings": []
},
"_teamId": "f73d1653-bf1d-4f00-ad58-543ac48f80a3",
"_conversationId": "b9a0c53e-22f6-4e9d-9a14-f832367b41cc"
}
Codes
| Code | Description |
|---|
200 | Success |
400 | Bad Request. nsfilter or _prompt is missing, _prompt is longer than 500 characters, there are more than 20 history messages or 10 attachments, or an attachment doesn't have both IDs. |
401 | Unauthorized |
403 | Forbidden. You don't have READ on the ontology. |
404 | Not Found. The ontology doesn't exist, or nsfilter names a namespace that the ontology doesn't belong to. The platform checks this before it calls the AI Service. |
502 | Bad Gateway. The AI Service call failed. |
504 | Gateway Timeout. The AI Service call timed out. |
Infer an item type schema
Infers an item type schema from sample JSON data. You need READ on the ontology. The platform adds the ontology's class names to the prompt. It reads them from the version that X-Ontology-Draft names, in any status, or from the live version.
Endpoints
POST /aosvc/api/v1/ontologies/{ontologyId}/ai/infer-schema
Parameters
Path
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ontology ID | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | Namespace filter to apply. It must name only namespaces that the ontology belongs to. | Required |
| Parameter | Type | Description | Required |
|---|
X-Ontology-Draft | Number | The ontology version to read class names from, in any status. If the version doesn't exist, the call returns 404. | Optional |
Body
| Parameter | Type | Description | Required |
|---|
dataJson | String | The sample data, as a JSON-encoded string | Required |
_typeName | String | The item type name to produce | Optional |
_teamId | String | The ID of an AI Service team to reuse | Optional |
Example:
{
"dataJson": "[{\"name\":\"Boiler-1\",\"pressureKpa\":210,\"installed\":\"2021-06-01\"}]",
"_typeName": "Boiler"
}
Response
{
"_output": {
"_typeName": "Boiler",
"_properties": {
"name": { "_type": "string" },
"pressureKpa": { "_type": "number" },
"installed": { "_type": "isodate" }
}
},
"_teamId": "f73d1653-bf1d-4f00-ad58-543ac48f80a3"
}
Codes
| Code | Description |
|---|
200 | Success |
400 | Bad Request. nsfilter or dataJson is missing, or X-Ontology-Draft is malformed. |
401 | Unauthorized |
403 | Forbidden. You don't have READ on the ontology. |
404 | Not Found. The ontology or the X-Ontology-Draft version doesn't exist, or nsfilter names a namespace that the ontology doesn't belong to. The platform checks this before it calls the AI Service. |
502 | Bad Gateway. The AI Service call failed. |
504 | Gateway Timeout. The AI Service call timed out. |
Review a dataset
Reviews an import dataset against a model. You need READ on the ontology. Nothing is saved. The request fields have no _ prefix.
Endpoints
POST /aosvc/api/v1/ontologies/{ontologyId}/ai/review-dataset
Parameters
Path
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ontology ID | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | Namespace filter to apply. It must name only namespaces that the ontology belongs to. | Required |
Body
| Parameter | Type | Description | Required |
|---|
prompt | String | What to check in the dataset | Required |
datasetJson | String | The dataset, as a JSON-encoded string | Required |
modelJson | String | The model to check against, as a JSON-encoded string | Required |
teamId | String | The ID of an AI Service team to reuse | Optional |
Example:
{
"prompt": "Check that every pump has a room",
"datasetJson": "{\"pump-1\":{\"@type\":\"Pump\",\"name\":\"Pump 1\"}}",
"modelJson": "{\"classes\":[{\"name\":\"Pump\"},{\"name\":\"Room\"}]}"
}
Response
_output is the AI Service output as is. _mcpToolName is the AI Service tool that ran.
{
"_output": {
"protocol": "ontology-studio-review/v1",
"summary": "Pump 1 has no room. No changes were applied.",
"operations": [],
"warnings": ["pump-1 has no locatedAt relationship"],
"appliedDataset": {
"pump-1": { "@type": "Pump", "name": "Pump 1" }
},
"appliedCount": 0,
"skipped": [],
"removedInstanceIds": []
},
"_teamId": "f73d1653-bf1d-4f00-ad58-543ac48f80a3",
"_mcpToolName": "ReviewImportDatasetTool"
}
Codes
| Code | Description |
|---|
200 | Success |
400 | Bad Request. nsfilter is missing, or prompt, datasetJson, or modelJson is missing or blank. |
401 | Unauthorized |
403 | Forbidden. You don't have READ on the ontology. |
404 | Not Found. The ontology doesn't exist, or nsfilter names a namespace that the ontology doesn't belong to. The platform checks this before it calls the AI Service. |
502 | Bad Gateway. The AI Service call failed. |
504 | Gateway Timeout. The AI Service call timed out. |
Get a class MCP config
Gets the MCP tool declaration of a class. You need READ on the ontology that owns the class. The call reads the live ontology version unless X-Ontology-Draft names a draft.
Endpoints
GET /aosvc/api/v1/classes/{classId}/mcp-config
Parameters
Path
| Parameter | Type | Description | Required |
|---|
classId | String | The class ID | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | Namespace filter to apply. It must name only namespaces that the owning ontology belongs to. | Required |
| Parameter | Type | Description | Required |
|---|
X-Ontology-Draft | Number | The draft version number to read | Optional |
Request example
GET /aosvc/api/v1/classes/c1d2e3f4-0000-0000-0000-aaaaaaaaaaaa/mcp-config?nsfilter=myapp
Response
_provisioningStatus is PENDING, PROVISIONED, or FAILED. _provisionedAt is the time of the last successful provisioning.
{
"_id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
"_classId": "c1d2e3f4-0000-0000-0000-aaaaaaaaaaaa",
"_toolName": "list_pumps",
"_criteriaJson": "{\"status\":\"active\"}",
"_provisioningStatus": "PROVISIONED",
"_provisionedAt": "2026-10-13T09:12:44.512Z",
"_createdAt": "2026-10-12T15:02:10.003Z",
"_updatedAt": "2026-10-13T09:12:44.512Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
Codes
| Code | Description |
|---|
200 | Success |
400 | Bad Request. nsfilter is missing, or X-Ontology-Draft is malformed. |
401 | Unauthorized |
403 | Forbidden. You don't have READ on the owning ontology. |
404 | Not Found. The class or declaration doesn't exist, the draft doesn't exist, or nsfilter names a namespace that the owning ontology doesn't belong to. |
Declare a class MCP config
Declares or replaces the MCP tool for a class in a draft. You need EDIT on the ontology that owns the class. The response has _provisioningStatus set to PENDING. The platform creates the tool in the AI Service when you promote the draft. The class must be mapped to a collection by then, or provisioning fails. If the promoted version drops or renames a tool that the live version had, the platform deletes the old tool.
Endpoints
PUT /aosvc/api/v1/classes/{classId}/mcp-config
Parameters
Path
| Parameter | Type | Description | Required |
|---|
classId | String | The class ID | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | Namespace filter to apply. It must name only namespaces that the owning ontology belongs to. | Required |
| Parameter | Type | Description | Required |
|---|
X-Ontology-Draft | Number | The number of an editable draft version | Required |
Body
| Parameter | Type | Description | Required |
|---|
_toolName | String | The tool name. Use 1 to 64 letters, digits, underscores, or hyphens. | Required |
_criteriaJson | String | The query criteria, as a JSON-encoded string | Optional |
Example:
{
"_toolName": "list_pumps",
"_criteriaJson": "{\"status\":\"active\"}"
}
Response
{
"_id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
"_classId": "c1d2e3f4-0000-0000-0000-aaaaaaaaaaaa",
"_toolName": "list_pumps",
"_criteriaJson": "{\"status\":\"active\"}",
"_provisioningStatus": "PENDING",
"_provisionedAt": null,
"_createdAt": "2026-10-12T15:02:10.003Z",
"_updatedAt": "2026-10-12T15:02:10.003Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
Codes
| Code | Description |
|---|
200 | Success |
400 | Bad Request. nsfilter is missing, X-Ontology-Draft is malformed, _toolName is invalid, _criteriaJson isn't valid JSON, or the class is a platform lifecycle class (State, StateTransition, Event, or Action) or one of its subclasses. |
401 | Unauthorized |
403 | Forbidden. You don't have EDIT on the owning ontology. |
404 | Not Found. The class or draft doesn't exist, or nsfilter names a namespace that the owning ontology doesn't belong to. |
409 | Conflict. X-Ontology-Draft is missing or doesn't name an editable draft. |
Provision a class MCP config
Provisions the MCP tool of a class. You need EDIT on the ontology that owns the class. The call behaves differently depending on X-Ontology-Draft:
- If
X-Ontology-Draft names a draft, the call sets the draft declaration to PENDING. The platform creates the tool in the AI Service when you promote the draft.
- If you omit
X-Ontology-Draft, the call provisions the live declaration in the AI Service again. Use this to retry a declaration whose status is FAILED.
Endpoints
POST /aosvc/api/v1/classes/{classId}/mcp-config/provision
Parameters
Path
| Parameter | Type | Description | Required |
|---|
classId | String | The class ID | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | Namespace filter to apply. It must name only namespaces that the owning ontology belongs to. | Required |
| Parameter | Type | Description | Required |
|---|
X-Ontology-Draft | Number | The number of an editable draft version. Omit it to provision the live declaration again. | Optional |
Request example
POST /aosvc/api/v1/classes/c1d2e3f4-0000-0000-0000-aaaaaaaaaaaa/mcp-config/provision?nsfilter=myapp
Response
{
"_id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
"_classId": "c1d2e3f4-0000-0000-0000-aaaaaaaaaaaa",
"_toolName": "list_pumps",
"_criteriaJson": "{\"status\":\"active\"}",
"_provisioningStatus": "PENDING",
"_provisionedAt": null,
"_createdAt": "2026-10-12T15:02:10.003Z",
"_updatedAt": "2026-10-12T15:20:31.778Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
Codes
| Code | Description |
|---|
200 | Success |
400 | Bad Request. nsfilter is missing, X-Ontology-Draft is malformed, or the class is a platform lifecycle class or one of its subclasses. |
401 | Unauthorized |
403 | Forbidden. You don't have EDIT on the owning ontology. |
404 | Not Found. The class, draft, or declaration doesn't exist, or nsfilter names a namespace that the owning ontology doesn't belong to. |
409 | Conflict. X-Ontology-Draft doesn't name an editable draft, or you omit it and the ontology has no live version yet. |
502 | Bad Gateway. Provisioning the live declaration failed again. The declaration status is FAILED. |
Delete a class MCP config
Removes the MCP tool declaration of a class from a draft. You need EDIT on the ontology that owns the class. If no declaration exists, the call still returns 204.
Endpoints
DELETE /aosvc/api/v1/classes/{classId}/mcp-config
Parameters
Path
| Parameter | Type | Description | Required |
|---|
classId | String | The class ID | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | Namespace filter to apply. It must name only namespaces that the owning ontology belongs to. | Required |
| Parameter | Type | Description | Required |
|---|
X-Ontology-Draft | Number | The number of an editable draft version | Required |
Request example
DELETE /aosvc/api/v1/classes/c1d2e3f4-0000-0000-0000-aaaaaaaaaaaa/mcp-config?nsfilter=myapp
Response
The response has no body.
Codes
| Code | Description |
|---|
204 | No Content. The declaration was removed, or didn't exist. |
400 | Bad Request. nsfilter is missing, X-Ontology-Draft is malformed, or the class is a platform lifecycle class or one of its subclasses. |
401 | Unauthorized |
403 | Forbidden. You don't have EDIT on the owning ontology. |
404 | Not Found. The class or draft doesn't exist, or nsfilter names a namespace that the owning ontology doesn't belong to. |
409 | Conflict. X-Ontology-Draft is missing or doesn't name an editable draft. |
Prepare a source dataset
Infers an import dataset from files in the File Service. The AI Service reads the files. The call doesn't check ontology permissions, and your nsfilter must resolve to exactly one namespace.
If you send _ontologyId, the platform adds the ontology's class names to the prompt. It reads them from the version that X-Ontology-Draft names, or from the live version. If the ontology or the named version doesn't exist, the call returns 404.
Endpoints
POST /aosvc/api/v1/source/prepare
Parameters
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | Namespace filter to apply. It must resolve to exactly one namespace. Two namespaces are refused, whether you send them comma-separated or as repeated nsfilter parameters. | Required |
| Parameter | Type | Description | Required |
|---|
X-Ontology-Draft | Number | The ontology version to read class names from, in any status. Use it only with _ontologyId. | Optional |
Body
| Parameter | Type | Description | Required |
|---|
_attachments | Array of Object | The file versions to read. Each is { "_fileId": "...", "_fileVersionId": "..." }, and both IDs are required. The array can't be empty. | Required |
_teamId | String | The ID of an AI Service team to reuse | Optional |
_ontologyId | String | The ontology whose class names to add to the prompt | Optional |
Example:
{
"_attachments": [
{
"_fileId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d",
"_fileVersionId": "7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b"
}
],
"_ontologyId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
Response
dataset is an instance map of ID to record. Each record names its class in @type.
{
"dataset": {
"pump-1": {
"@type": "Pump",
"name": "Pump 1",
"locatedAt": "room-101"
},
"room-101": {
"@type": "Room",
"name": "Room 101"
}
},
"log": "aosvc Infer Data pass-through\nattachments=1\ninstances=2\nteam=f73d1653-bf1d-4f00-ad58-543ac48f80a3\npreprocessing=none"
}
Codes
| Code | Description |
|---|
200 | Success |
400 | Bad Request. nsfilter is missing or doesn't resolve to exactly one namespace, X-Ontology-Draft is malformed, _attachments is empty, or an attachment doesn't have both IDs. |
401 | Unauthorized |
404 | Not Found. _ontologyId names an ontology that doesn't exist, or X-Ontology-Draft names a version that doesn't exist. |
502 | Bad Gateway. The AI Service call failed or returned no valid instance map. |
504 | Gateway Timeout. The AI Service call timed out. |
Prepare a source dataset with progress
Does the same as Prepare a source dataset, but streams progress as newline-delimited JSON (application/x-ndjson). Each line is one object with a type:
type | Fields |
|---|
progress | phase, path, status, detail, index, total |
result | dataset, log |
error | status, such as 400, 404, 502, or 504, and message |
After streaming starts, the HTTP status is 200, and a failure arrives as an error line. Body and namespace errors still return a normal error status before streaming starts.
Endpoints
POST /aosvc/api/v1/source/prepare/stream
Parameters
The parameters are the same as for Prepare a source dataset.
Response
{"type":"progress","phase":"aisvc","path":null,"status":"running","detail":"Sending attachments to AISvc","index":0,"total":1}
{"type":"progress","phase":"done","path":null,"status":"done","detail":"AISvc returned 1 instance(s)","index":1,"total":1}
{"type":"result","dataset":{"pump-1":{"@type":"Pump","name":"Pump 1"}},"log":"aosvc Infer Data pass-through\nattachments=1\ninstances=1\nteam=f73d1653-bf1d-4f00-ad58-543ac48f80a3\npreprocessing=none"}
Codes
| Code | Description |
|---|
200 | Success. The stream started. Check the last line for a result or an error. A missing ontology or version arrives as an error line with status 404. |
400 | Bad Request. nsfilter is missing or doesn't resolve to exactly one namespace, X-Ontology-Draft is malformed, _attachments is empty, or an attachment doesn't have both IDs. |
401 | Unauthorized |