An action is a named side effect in an ontology, such as running a script, starting a workflow, or sending a notification. An action runs only when a state machine transition that references it fires. Actions you define inline in a state machine's transitions also appear in these lists. To see what an action did when it ran, see List action executions. For more information, see Actions.
Note: Every request needs an Authorization: Bearer <token> header and the nsfilter query parameter. Reads need READ on the ontology, and writes need EDIT. For more information, see Permissions.
This section contains the following API calls:
Action types
Set _actionType to one of the following values, and send the matching keys in _params:
_actionType | Required _params keys | Optional _params keys |
|---|
SCRIPT | _userType, _scriptName | |
WORKFLOW | _workflowDefId | _workflowInput, a string that contains a JSON object |
AI_TEAM | _aiTeamId, _systemPrompt | |
NOTIFICATION | _notificationTriggerId | |
EVENT | _stateMachineId, _eventId or _eventName, _targetFromStateValue, _targetToStateValue | _targets |
List actions
Lists the actions of an ontology.
Endpoints
GET /aosvc/api/v1/ontologies/{ontologyId}/actions
Parameters
Path
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ID of the ontology | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | Namespace filter to apply | Required |
| Parameter | Type | Description | Required |
|---|
X-Ontology-Draft | Integer | The version number to read. Omit it to read the live version. | Optional |
Response
Returns an array of actions. An ontology with no live version returns an empty array.
[
{
"_id": "6f1c2a4e-8b7d-4c3a-9e21-0d5b7a9c4f12",
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_name": "notifyMaintenance",
"_actionType": "NOTIFICATION",
"_description": "Tell the maintenance group a pump went out of service",
"_params": {
"_notificationTriggerId": "trg-7f3a"
},
"_createdAt": "2026-10-01T10:29:00Z",
"_updatedAt": "2026-10-01T10:29:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
]
Codes
| Code | Description |
|---|
200 | Success |
401 | Unauthorized |
403 | Forbidden |
404 | The ontology or the named draft is not found |
Create an action
Creates one action in a draft version of the ontology.
Endpoints
POST /aosvc/api/v1/ontologies/{ontologyId}/actions
Parameters
Path
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ID of the ontology | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | Namespace filter to apply | Required |
| Parameter | Type | Description | Required |
|---|
X-Ontology-Draft | Integer | The number of the draft version to edit | Required |
If-Match | String | The ontology revision you expect, for example "3". A stale revision returns 412. | Optional |
Body
| Parameter | Type | Description | Required |
|---|
_name | String | The action name. It must be unique in the ontology version. | Required |
_actionType | String | One of the action types | Required |
_description | String | A description of the action | Optional |
_params | Object | The keys for the action type. For the keys each type needs, see Action types. | Optional |
Example:
{
"_name": "notifyMaintenance",
"_actionType": "NOTIFICATION",
"_description": "Tell the maintenance group a pump went out of service",
"_params": {
"_notificationTriggerId": "trg-7f3a"
}
}
Response
Returns the stored action. The response ETag header holds the new ontology revision.
{
"_id": "6f1c2a4e-8b7d-4c3a-9e21-0d5b7a9c4f12",
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_name": "notifyMaintenance",
"_actionType": "NOTIFICATION",
"_description": "Tell the maintenance group a pump went out of service",
"_params": {
"_notificationTriggerId": "trg-7f3a"
},
"_createdAt": "2026-10-01T10:29:00Z",
"_updatedAt": "2026-10-01T10:29:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
Codes
| Code | Description |
|---|
200 | Success |
400 | Bad Request. _name is blank, _actionType is missing or unknown, or a required _params key is missing. |
401 | Unauthorized |
403 | Forbidden |
404 | The ontology or the named draft is not found |
409 | Conflict. X-Ontology-Draft is missing or does not name an editable draft, another user holds the ontology edit lock, or the _name is already used. |
412 | The If-Match revision is stale |
423 | The ontology uses edit locking and you don't hold the lock |
Get an action
Gets one action of the ontology.
Endpoints
GET /aosvc/api/v1/ontologies/{ontologyId}/actions/{actionId}
Parameters
Path
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ID of the ontology | Required |
actionId | String | The ID of the action | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | Namespace filter to apply | Required |
| Parameter | Type | Description | Required |
|---|
X-Ontology-Draft | Integer | The version number to read. Omit it to read the live version. | Optional |
Response
{
"_id": "6f1c2a4e-8b7d-4c3a-9e21-0d5b7a9c4f12",
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_name": "notifyMaintenance",
"_actionType": "NOTIFICATION",
"_description": "Tell the maintenance group a pump went out of service",
"_params": {
"_notificationTriggerId": "trg-7f3a"
},
"_createdAt": "2026-10-01T10:29:00Z",
"_updatedAt": "2026-10-01T10:29:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
Codes
| Code | Description |
|---|
200 | Success |
401 | Unauthorized |
403 | Forbidden |
404 | The ontology, the named draft, or the action is not found |
Update an action
Updates an action in a draft version of the ontology. Fields you omit stay unchanged.
The service merges _params into the stored keys. You can't remove a _params key: delete the action and create it again instead. If you change _actionType, the service clears the stored _params first, so send the new type's required keys in the same request.
Endpoints
PUT /aosvc/api/v1/ontologies/{ontologyId}/actions/{actionId}
Parameters
Path
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ID of the ontology | Required |
actionId | String | The ID of the action | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | Namespace filter to apply | Required |
| Parameter | Type | Description | Required |
|---|
X-Ontology-Draft | Integer | The number of the draft version to edit | Required |
If-Match | String | The ontology revision you expect, for example "3". A stale revision returns 412. | Optional |
Body
| Parameter | Type | Description | Required |
|---|
_name | String | The new action name. The service doesn't check it for uniqueness. | Optional |
_actionType | String | One of the action types | Optional |
_description | String | A description of the action | Optional |
_params | Object | Keys to add or change | Optional |
Example:
{
"_actionType": "WORKFLOW",
"_params": {
"_workflowDefId": "37a5d99e-c20d-45f7-8a2f-8d5af5ea6535"
}
}
Response
Returns the updated action. The response ETag header holds the new ontology revision.
{
"_id": "6f1c2a4e-8b7d-4c3a-9e21-0d5b7a9c4f12",
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_name": "notifyMaintenance",
"_actionType": "WORKFLOW",
"_description": "Tell the maintenance group a pump went out of service",
"_params": {
"_workflowDefId": "37a5d99e-c20d-45f7-8a2f-8d5af5ea6535"
},
"_createdAt": "2026-10-01T10:29:00Z",
"_updatedAt": "2026-10-02T08:12:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
Codes
| Code | Description |
|---|
200 | Success |
400 | Bad Request. _actionType is unknown or a required _params key is missing. |
401 | Unauthorized |
403 | Forbidden |
404 | The ontology, the named draft, or the action is not found |
409 | Conflict. X-Ontology-Draft is missing or does not name an editable draft, or another user holds the ontology edit lock. |
412 | The If-Match revision is stale |
423 | The ontology uses edit locking and you don't hold the lock |
Delete an action
Deletes an action from a draft version of the ontology. You can't delete an action that a state machine transition references.
Endpoints
DELETE /aosvc/api/v1/ontologies/{ontologyId}/actions/{actionId}
Parameters
Path
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ID of the ontology | Required |
actionId | String | The ID of the action | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | Namespace filter to apply | Required |
| Parameter | Type | Description | Required |
|---|
X-Ontology-Draft | Integer | The number of the draft version to edit | Required |
If-Match | String | The ontology revision you expect, for example "3". A stale revision returns 412. | Optional |
Response
The response has no body.
Codes
| Code | Description |
|---|
204 | No Content |
401 | Unauthorized |
403 | Forbidden |
404 | The ontology, the named draft, or the action is not found |
409 | Conflict. X-Ontology-Draft is missing or does not name an editable draft, another user holds the ontology edit lock, or a state machine transition references the action. |
412 | The If-Match revision is stale |
423 | The ontology uses edit locking and you don't hold the lock |