Skip to main content
Version: v5.3

Actions

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:

_actionTypeRequired _params keysOptional _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​

ParameterTypeDescriptionRequired
ontologyIdStringThe ID of the ontologyRequired

Query​

ParameterTypeDescriptionRequired
nsfilterStringNamespace filter to applyRequired
ParameterTypeDescriptionRequired
X-Ontology-DraftIntegerThe 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​

CodeDescription
200Success
401Unauthorized
403Forbidden
404The 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​

ParameterTypeDescriptionRequired
ontologyIdStringThe ID of the ontologyRequired

Query​

ParameterTypeDescriptionRequired
nsfilterStringNamespace filter to applyRequired

Header​

ParameterTypeDescriptionRequired
X-Ontology-DraftIntegerThe number of the draft version to editRequired
If-MatchStringThe ontology revision you expect, for example "3". A stale revision returns 412.Optional

Body​

ParameterTypeDescriptionRequired
_nameStringThe action name. It must be unique in the ontology version.Required
_actionTypeStringOne of the action typesRequired
_descriptionStringA description of the actionOptional
_paramsObjectThe 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​

CodeDescription
200Success
400Bad Request. _name is blank, _actionType is missing or unknown, or a required _params key is missing.
401Unauthorized
403Forbidden
404The ontology or the named draft is not found
409Conflict. 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.
412The If-Match revision is stale
423The 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​

ParameterTypeDescriptionRequired
ontologyIdStringThe ID of the ontologyRequired
actionIdStringThe ID of the actionRequired

Query​

ParameterTypeDescriptionRequired
nsfilterStringNamespace filter to applyRequired

Header​

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

CodeDescription
200Success
401Unauthorized
403Forbidden
404The 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​

ParameterTypeDescriptionRequired
ontologyIdStringThe ID of the ontologyRequired
actionIdStringThe ID of the actionRequired

Query​

ParameterTypeDescriptionRequired
nsfilterStringNamespace filter to applyRequired

Header​

ParameterTypeDescriptionRequired
X-Ontology-DraftIntegerThe number of the draft version to editRequired
If-MatchStringThe ontology revision you expect, for example "3". A stale revision returns 412.Optional

Body​

ParameterTypeDescriptionRequired
_nameStringThe new action name. The service doesn't check it for uniqueness.Optional
_actionTypeStringOne of the action typesOptional
_descriptionStringA description of the actionOptional
_paramsObjectKeys to add or changeOptional

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​

CodeDescription
200Success
400Bad Request. _actionType is unknown or a required _params key is missing.
401Unauthorized
403Forbidden
404The ontology, the named draft, or the action is not found
409Conflict. X-Ontology-Draft is missing or does not name an editable draft, or another user holds the ontology edit lock.
412The If-Match revision is stale
423The 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​

ParameterTypeDescriptionRequired
ontologyIdStringThe ID of the ontologyRequired
actionIdStringThe ID of the actionRequired

Query​

ParameterTypeDescriptionRequired
nsfilterStringNamespace filter to applyRequired

Header​

ParameterTypeDescriptionRequired
X-Ontology-DraftIntegerThe number of the draft version to editRequired
If-MatchStringThe ontology revision you expect, for example "3". A stale revision returns 412.Optional

Response​

The response has no body.

Codes​

CodeDescription
204No Content
401Unauthorized
403Forbidden
404The ontology, the named draft, or the action is not found
409Conflict. 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.
412The If-Match revision is stale
423The ontology uses edit locking and you don't hold the lock