UI, assistant, HTTP API and MCP
Use only the public interface supported by each ontology action
The platform UI, a natural-language assistant request, HTTP resource API and MCP tool call are different input methods. A prompt describes intent; the assistant must use an available tool and real resources to perform it. Internal session routes are not workspace API-key interfaces.
Available actions
All HTTP paths below follow /api/v1/projects/<PROJECT_UUID>/. Bearer keys need the named scope and applicable read access. Mutation permissions do not create membership, credentials or missing source records. Account-linked actor requirements apply to definition authoring.
| Action | HTTP API | MCP | Permission |
|---|---|---|---|
| List/create definition | GET/POST ontology/definitions | ontology_list / ontology_create | ontologies:read/write |
| Inspect definition | GET ontology/definitions/<ID> | ontology_get | ontologies:read |
| Validate proposed model | Use supported UI validation; no standalone public route listed here | ontology_validate | ontologies:read |
| Commit definition version | POST ontology/definitions/<ID>/versions | ontology_update | ontologies:write |
| List/inspect definition history | GET versions, optional versionId selector | ontology_version_list / ontology_version_get | ontologies:read |
| Activate definition version | POST ontology/definitions/<ID>/versions/<VERSION_ID>/activate | No dedicated activation tool | ontologies:write |
| Compile/inspect project package | POST ontology/compile; GET ontology | Inspect through available ontology tools | ontologies:write/read |
| List/create bindings | GET/POST ontology/read-bindings | ontology_read_binding_list / ontology_read_binding_create | bindings:read/write |
| Inspect/update binding | GET/PUT ontology/read-bindings/<ID> | ontology_read_binding_get / ontology_read_binding_update | bindings:read/write |
| List/create queries | GET/POST ontology/queries | query_list / query_create | queries:read/write |
| Inspect/update query | GET/PUT ontology/queries/<ID> | query_get / query_update | queries:read/write |
| Publish reviewed query | POST ontology/queries/<ID>/releases | query_publish | queries:publish |
| List/retire releases | GET/PATCH same releases path | query_release_list / query_release_retire | queries:read/publish |
| Execute/poll/page query | POST ontology/queries/<ID>/execute | query_execute | queries:execute |
| Cancel active result job | DELETE queries/<ID>/jobs/<JOB_ID> | query_cancel | queries:execute |
| Read SPARQL | GET/POST ontology/sparql | sparql_query | sparql:query |
| Controlled SPARQL update | POST ontology/sparql with update content type | Not exposed over MCP | sparql:update |
| Inspect claim/capture | No generic public route documented | claim_list / claim_get / capture_get | queries:read |
| Create/review human assertion | Project Assertions UI; no generic public key endpoint | No generic mutation tool | Supported project reviewer workflow |
Definition/binding/query creation and relevant version mutations use HTTP Idempotency-Key or MCP idempotencyKey where the action contract requires it. Publication uses an expected saved version; MCP publication also has its operation key. Use the discovered tool contract rather than assuming every mutation shares one payload shape.
Complete definition creation
The downloadable definition body contains the full model and manifest. Replace resource placeholders and use a unique operation key.
Create the definition through Ontology → Definitions, review its model/files and manifest, validate and save.
Create the operations-demo ontology definition using the complete model and manifest provided here. Select this project, show validation and proposed files before saving, and report its definition and active version IDs.curl --request POST "https://platform.semogram.com/api/v1/projects/<PROJECT_UUID>/ontology/definitions" \
--header "Authorization: Bearer ${SEMOGRAM_API_KEY}" \
--header "Idempotency-Key: <UNIQUE_CREATE_KEY>" \
--header "Content-Type: application/json" \
--data-binary @definition.json{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "ontology_create",
"arguments": {
"projectId": "<PROJECT_UUID>",
"manifest": {
"name": "operations-demo",
"description": "Orders, customers and delivery evidence",
"defaultNamespace": "https://example.com/operations#",
"modelEntrypoints": [
"model.ttl"
],
"shapeEntrypoints": [],
"imports": []
},
"files": [
{
"path": "model.ttl",
"content": "@prefix ex: <https://example.com/operations#> .\n@prefix owl: <http://www.w3.org/2002/07/owl#> .\n@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .\n@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .\n\nex:Order a owl:Class ; rdfs:label \"Order\" .\nex:Customer a owl:Class ; rdfs:label \"Customer\" .\nex:orderId a owl:DatatypeProperty ; rdfs:domain ex:Order ; rdfs:range xsd:string .\nex:status a owl:DatatypeProperty ; rdfs:domain ex:Order ; rdfs:range xsd:string .\nex:total a owl:DatatypeProperty ; rdfs:domain ex:Order ; rdfs:range xsd:decimal .\nex:delivered a owl:DatatypeProperty ; rdfs:domain ex:Order ; rdfs:range xsd:boolean .\nex:isOpen a owl:DatatypeProperty ; rdfs:domain ex:Order ; rdfs:range xsd:boolean .\nex:customerName a owl:DatatypeProperty ; rdfs:domain ex:Customer ; rdfs:range xsd:string .\nex:placedBy a owl:ObjectProperty ; rdfs:domain ex:Order ; rdfs:range ex:Customer .",
"contentType": "text/turtle"
}
],
"commitMessage": "Define the operations demo model",
"idempotencyKey": "<UNIQUE_CREATE_KEY>"
}
}
}Binding creation differs
HTTP accepts a binding body. MCP ontology_read_binding_create accepts {binding: {...}, idempotencyKey: ...}. The read binding page shows both exactly. Query-create content is a YAML string; query-execute takes only declared inputs/options and identifies an existing published query.
Project scoping and assistants
The examples include projectId for a workspace MCP connection. A project-bound connection already supplies project context; follow its discovered schema and omit additional scoping fields where required. A connected assistant should discover capabilities, inspect resource IDs and preview proposed mutations. Asking it to approve a claim or enable Consumer SPARQL does not invent a missing review tool or authorize an access change.
For full tool schemas use the MCP section. Plugin-backed materialization and endpoint reads retain their installed capability's contract and permissions.