Skip to main content
Version: v5.3

AI assistance

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​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology IDRequired

Query​

ParameterTypeDescriptionRequired
nsfilterStringNamespace filter to apply. It must name only namespaces that the ontology belongs to.Required

Body​

ParameterTypeDescriptionRequired
_promptStringWhat to generate, up to 500 charactersRequired
_teamIdStringThe ID of an AI Service team to reuseOptional
_currentModelObjectThe application model you're working on. If you omit it, the AI treats the application model as empty.Optional
_conversationHistoryArray of ObjectUp to 20 earlier messages. Each is { "_role": "user" or "assistant", "_content": "..." }.Optional
_attachmentsArray of ObjectUp 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​

CodeDescription
200Success
400Bad 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.
401Unauthorized
403Forbidden. You don't have READ on the ontology.
404Not 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.
502Bad Gateway. The AI Service call failed.
504Gateway 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​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology IDRequired

Query​

ParameterTypeDescriptionRequired
nsfilterStringNamespace filter to apply. It must name only namespaces that the ontology belongs to.Required
ParameterTypeDescriptionRequired
X-Ontology-DraftNumberThe ontology version to read class names from, in any status. If the version doesn't exist, the call returns 404.Optional

Body​

ParameterTypeDescriptionRequired
dataJsonStringThe sample data, as a JSON-encoded stringRequired
_typeNameStringThe item type name to produceOptional
_teamIdStringThe ID of an AI Service team to reuseOptional

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​

CodeDescription
200Success
400Bad Request. nsfilter or dataJson is missing, or X-Ontology-Draft is malformed.
401Unauthorized
403Forbidden. You don't have READ on the ontology.
404Not 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.
502Bad Gateway. The AI Service call failed.
504Gateway 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​

ParameterTypeDescriptionRequired
ontologyIdStringThe ontology IDRequired

Query​

ParameterTypeDescriptionRequired
nsfilterStringNamespace filter to apply. It must name only namespaces that the ontology belongs to.Required

Body​

ParameterTypeDescriptionRequired
promptStringWhat to check in the datasetRequired
datasetJsonStringThe dataset, as a JSON-encoded stringRequired
modelJsonStringThe model to check against, as a JSON-encoded stringRequired
teamIdStringThe ID of an AI Service team to reuseOptional

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​

CodeDescription
200Success
400Bad Request. nsfilter is missing, or prompt, datasetJson, or modelJson is missing or blank.
401Unauthorized
403Forbidden. You don't have READ on the ontology.
404Not 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.
502Bad Gateway. The AI Service call failed.
504Gateway 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​

ParameterTypeDescriptionRequired
classIdStringThe class IDRequired

Query​

ParameterTypeDescriptionRequired
nsfilterStringNamespace filter to apply. It must name only namespaces that the owning ontology belongs to.Required

Header​

ParameterTypeDescriptionRequired
X-Ontology-DraftNumberThe draft version number to readOptional

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​

CodeDescription
200Success
400Bad Request. nsfilter is missing, or X-Ontology-Draft is malformed.
401Unauthorized
403Forbidden. You don't have READ on the owning ontology.
404Not 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​

ParameterTypeDescriptionRequired
classIdStringThe class IDRequired

Query​

ParameterTypeDescriptionRequired
nsfilterStringNamespace filter to apply. It must name only namespaces that the owning ontology belongs to.Required

Header​

ParameterTypeDescriptionRequired
X-Ontology-DraftNumberThe number of an editable draft versionRequired

Body​

ParameterTypeDescriptionRequired
_toolNameStringThe tool name. Use 1 to 64 letters, digits, underscores, or hyphens.Required
_criteriaJsonStringThe query criteria, as a JSON-encoded stringOptional

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​

CodeDescription
200Success
400Bad 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.
401Unauthorized
403Forbidden. You don't have EDIT on the owning ontology.
404Not Found. The class or draft doesn't exist, or nsfilter names a namespace that the owning ontology doesn't belong to.
409Conflict. 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​

ParameterTypeDescriptionRequired
classIdStringThe class IDRequired

Query​

ParameterTypeDescriptionRequired
nsfilterStringNamespace filter to apply. It must name only namespaces that the owning ontology belongs to.Required

Header​

ParameterTypeDescriptionRequired
X-Ontology-DraftNumberThe 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​

CodeDescription
200Success
400Bad Request. nsfilter is missing, X-Ontology-Draft is malformed, or the class is a platform lifecycle class or one of its subclasses.
401Unauthorized
403Forbidden. You don't have EDIT on the owning ontology.
404Not Found. The class, draft, or declaration doesn't exist, or nsfilter names a namespace that the owning ontology doesn't belong to.
409Conflict. X-Ontology-Draft doesn't name an editable draft, or you omit it and the ontology has no live version yet.
502Bad 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​

ParameterTypeDescriptionRequired
classIdStringThe class IDRequired

Query​

ParameterTypeDescriptionRequired
nsfilterStringNamespace filter to apply. It must name only namespaces that the owning ontology belongs to.Required

Header​

ParameterTypeDescriptionRequired
X-Ontology-DraftNumberThe number of an editable draft versionRequired

Request example​

DELETE /aosvc/api/v1/classes/c1d2e3f4-0000-0000-0000-aaaaaaaaaaaa/mcp-config?nsfilter=myapp

Response​

The response has no body.

{}

Codes​

CodeDescription
204No Content. The declaration was removed, or didn't exist.
400Bad Request. nsfilter is missing, X-Ontology-Draft is malformed, or the class is a platform lifecycle class or one of its subclasses.
401Unauthorized
403Forbidden. You don't have EDIT on the owning ontology.
404Not Found. The class or draft doesn't exist, or nsfilter names a namespace that the owning ontology doesn't belong to.
409Conflict. 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​

ParameterTypeDescriptionRequired
nsfilterStringNamespace 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

Header​

ParameterTypeDescriptionRequired
X-Ontology-DraftNumberThe ontology version to read class names from, in any status. Use it only with _ontologyId.Optional

Body​

ParameterTypeDescriptionRequired
_attachmentsArray of ObjectThe file versions to read. Each is { "_fileId": "...", "_fileVersionId": "..." }, and both IDs are required. The array can't be empty.Required
_teamIdStringThe ID of an AI Service team to reuseOptional
_ontologyIdStringThe ontology whose class names to add to the promptOptional

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​

CodeDescription
200Success
400Bad 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.
401Unauthorized
404Not Found. _ontologyId names an ontology that doesn't exist, or X-Ontology-Draft names a version that doesn't exist.
502Bad Gateway. The AI Service call failed or returned no valid instance map.
504Gateway 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:

typeFields
progressphase, path, status, detail, index, total
resultdataset, log
errorstatus, 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​

CodeDescription
200Success. 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.
400Bad 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.
401Unauthorized