A state machine defines the states, events, and transitions of the individuals of one or more classes in an ontology. Each individual records its current state for each machine in its _aostates field. To change that state, fire an event against the individual. For more information, see State machines.
Note: Every request needs an Authorization: Bearer <token> header and the nsfilter query parameter. The nsfilter value must name only namespaces the ontology belongs to. Otherwise, the service returns 404. Reading a machine needs READ on the ontology, and changing one needs EDIT. For more information, see Permissions.
This section contains the following API calls:
List state machines
Lists the complete state machines of an ontology, sorted by _name.
Endpoints
GET /aosvc/api/v1/ontologies/{ontologyId}/state-machines
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 |
classId | String | Returns only the machines bound to this class | Optional |
| 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 state machines. For the fields of each machine, see Get a state machine.
[
{
"_id": "4926c6f5-ec5e-44ca-a793-11b0e86fa46e",
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_name": "Approval",
"_classIds": ["f5f565dc-4169-4664-909f-b2c6f11e1a27"],
"_states": [
{ "_id": "12198858-9325-4e3b-93a0-d4f8d36db6ed", "_name": "Draft", "_value": "draft", "_initial": true },
{ "_id": "fd57358f-5686-4f65-9c2c-10eb026f86c7", "_name": "Approved", "_value": "approved" }
],
"_events": [
{ "_id": "11b700ba-c9bb-4776-a0f1-36202f24a6b3", "_name": "Approve" }
],
"_transitions": [
{
"_id": "820ec042-810b-470b-be7c-55c6dae882d6",
"_name": "approve",
"_fromStateId": "12198858-9325-4e3b-93a0-d4f8d36db6ed",
"_toStateId": "fd57358f-5686-4f65-9c2c-10eb026f86c7",
"_executionOrder": 0,
"_eventIds": ["11b700ba-c9bb-4776-a0f1-36202f24a6b3"],
"_actions": []
}
],
"_createdAt": "2026-09-24T09:00:00Z",
"_updatedAt": "2026-09-24T09:00:00Z",
"_createdBy": "b0a30681-e719-486c-8f03-56091e590940",
"_updatedBy": "b0a30681-e719-486c-8f03-56091e590940"
}
]
Codes
| Code | Description |
|---|
200 | Success |
400 | Bad Request. nsfilter is missing. |
401 | Unauthorized |
403 | Forbidden |
404 | The ontology or the named draft is not found |
Create a state machine
Creates a complete state machine in a draft version of the ontology. Transitions refer to states and events by _id, so send the IDs of the states and events you reference.
The service grants you CREATE on each event of the machine, so you can fire it. Other users need their own grant to fire an event.
Endpoints
POST /aosvc/api/v1/ontologies/{ontologyId}/state-machines
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 |
|---|
_id | String | A UUID for the machine. The service creates one if you omit it. | Optional |
_name | String | The machine name, up to 500 characters. It must be unique among machines bound to the same classes. | Required |
_description | String | A description of the machine | Optional |
_classIds | Array of String | The IDs of the classes the machine tracks. Each class must be in this ontology. You can't bind the platform classes State, Event, Action, or StateTransition. | Required |
_states | Array of Object | The states of the machine. Exactly one state must have _initial set to true. | Required |
_states[n]._id | String | A UUID for the state. The service creates one if you omit it. | Optional |
_states[n]._name | String | The state name, up to 500 characters. It must be unique in the machine. | Required |
_states[n]._value | String, Number, or Boolean | The value stored for the state. It must be unique in the machine. A string value can't be blank and can have up to 500 characters. | Required |
_states[n]._initial | Boolean | Whether new individuals start in this state | Optional |
_events | Array of Object | The events of the machine | Required |
_events[n]._id | String | A UUID for the event. The service creates one if you omit it. | Optional |
_events[n]._name | String | The event name, up to 500 characters. It must be unique in the machine. | Required |
_events[n]._description | String | A description of the event | Optional |
_transitions | Array of Object | The transitions of the machine | Required |
_transitions[n]._id | String | A UUID for the transition. The service creates one if you omit it. | Optional |
_transitions[n]._name | String | The transition name, up to 500 characters. It must be unique in the machine. | Required |
_transitions[n]._fromStateId | String | The ID of the state the transition starts from | Required |
_transitions[n]._toStateId | String | The ID of the state the transition ends in | Required |
_transitions[n]._executionOrder | Integer | The order of the transition. Orders must run from 0 without gaps. When several transitions share an event, the lowest order wins. | Required |
_transitions[n]._eventIds | Array of String | The IDs of the events that fire the transition | Required |
_transitions[n]._actions | Array of Object | The actions that run when the transition fires. Each action takes the fields of an action, plus _id and _executionOrder. For the action fields, see Create an action. In a state machine, _workflowDefId, _aiTeamId, and _stateMachineId must be UUIDs, and _workflowInput must be a string that holds a JSON object. | Required |
_transitions[n]._actions[n]._executionOrder | Integer | The order the action runs in. It must be unique in the transition. | Required |
Example:
{
"_name": "Approval",
"_classIds": ["f5f565dc-4169-4664-909f-b2c6f11e1a27"],
"_states": [
{ "_id": "12198858-9325-4e3b-93a0-d4f8d36db6ed", "_name": "Draft", "_value": "draft", "_initial": true },
{ "_id": "fd57358f-5686-4f65-9c2c-10eb026f86c7", "_name": "Approved", "_value": "approved" }
],
"_events": [
{ "_id": "11b700ba-c9bb-4776-a0f1-36202f24a6b3", "_name": "Approve" }
],
"_transitions": [
{
"_name": "approve",
"_fromStateId": "12198858-9325-4e3b-93a0-d4f8d36db6ed",
"_toStateId": "fd57358f-5686-4f65-9c2c-10eb026f86c7",
"_executionOrder": 0,
"_eventIds": ["11b700ba-c9bb-4776-a0f1-36202f24a6b3"],
"_actions": [
{
"_name": "Start approval workflow",
"_actionType": "WORKFLOW",
"_executionOrder": 0,
"_params": {
"_workflowDefId": "37a5d99e-c20d-45f7-8a2f-8d5af5ea6535"
}
}
]
}
]
}
Response
Returns the complete state machine, with the IDs the service created. The response ETag header holds the new ontology revision.
{
"_id": "4926c6f5-ec5e-44ca-a793-11b0e86fa46e",
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_name": "Approval",
"_classIds": ["f5f565dc-4169-4664-909f-b2c6f11e1a27"],
"_states": [
{ "_id": "12198858-9325-4e3b-93a0-d4f8d36db6ed", "_name": "Draft", "_value": "draft", "_initial": true },
{ "_id": "fd57358f-5686-4f65-9c2c-10eb026f86c7", "_name": "Approved", "_value": "approved" }
],
"_events": [
{ "_id": "11b700ba-c9bb-4776-a0f1-36202f24a6b3", "_name": "Approve" }
],
"_transitions": [
{
"_id": "820ec042-810b-470b-be7c-55c6dae882d6",
"_name": "approve",
"_fromStateId": "12198858-9325-4e3b-93a0-d4f8d36db6ed",
"_toStateId": "fd57358f-5686-4f65-9c2c-10eb026f86c7",
"_executionOrder": 0,
"_eventIds": ["11b700ba-c9bb-4776-a0f1-36202f24a6b3"],
"_actions": [
{
"_id": "5b2d9e71-3c4a-4f8b-a6d2-7e1f0c9b8a35",
"_name": "Start approval workflow",
"_actionType": "WORKFLOW",
"_executionOrder": 0,
"_params": {
"_workflowDefId": "37a5d99e-c20d-45f7-8a2f-8d5af5ea6535"
}
}
]
}
],
"_createdAt": "2026-09-24T09:00:00Z",
"_updatedAt": "2026-09-24T09:00:00Z",
"_createdBy": "b0a30681-e719-486c-8f03-56091e590940",
"_updatedBy": "b0a30681-e719-486c-8f03-56091e590940"
}
Codes
| Code | Description |
|---|
201 | Created |
400 | Bad Request. A required field is missing or blank, a name or string state value is longer than 500 characters, the body is malformed, or _classIds names a platform lifecycle class. |
401 | Unauthorized |
403 | Forbidden |
404 | The ontology, the named draft, or a class in _classIds is not found |
409 | Conflict. X-Ontology-Draft is missing or does not name an editable draft, another user holds the ontology edit lock, the machine _id already exists, the machine name is already used on an overlapping class, or an action name is already used in the ontology. |
412 | The If-Match revision is stale |
422 | The definition is invalid. For example, an ID is not a UUID, one ID is used for two items, a name or state value is repeated, there isn't exactly one initial state, a transition refers to an unknown state or event, the execution orders have gaps or repeats, or an action parameter is invalid. |
423 | The ontology uses edit locking and you don't hold the lock |
502 | An event permission could not be granted. The service doesn't keep the machine. |
Get a state machine
Gets one complete state machine.
Endpoints
GET /aosvc/api/v1/ontologies/{ontologyId}/state-machines/{machineId}
Parameters
Path
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ID of the ontology | Required |
machineId | String | The ID of the state machine | 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
The response holds the fields you sent when you created the machine, plus _ontologyId, _createdAt, _updatedAt, _createdBy, and _updatedBy.
{
"_id": "4926c6f5-ec5e-44ca-a793-11b0e86fa46e",
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_name": "Approval",
"_classIds": ["f5f565dc-4169-4664-909f-b2c6f11e1a27"],
"_states": [
{ "_id": "12198858-9325-4e3b-93a0-d4f8d36db6ed", "_name": "Draft", "_value": "draft", "_initial": true },
{ "_id": "fd57358f-5686-4f65-9c2c-10eb026f86c7", "_name": "Approved", "_value": "approved" }
],
"_events": [
{ "_id": "11b700ba-c9bb-4776-a0f1-36202f24a6b3", "_name": "Approve" }
],
"_transitions": [
{
"_id": "820ec042-810b-470b-be7c-55c6dae882d6",
"_name": "approve",
"_fromStateId": "12198858-9325-4e3b-93a0-d4f8d36db6ed",
"_toStateId": "fd57358f-5686-4f65-9c2c-10eb026f86c7",
"_executionOrder": 0,
"_eventIds": ["11b700ba-c9bb-4776-a0f1-36202f24a6b3"],
"_actions": []
}
],
"_createdAt": "2026-09-24T09:00:00Z",
"_updatedAt": "2026-09-24T09:00:00Z",
"_createdBy": "b0a30681-e719-486c-8f03-56091e590940",
"_updatedBy": "b0a30681-e719-486c-8f03-56091e590940"
}
Codes
| Code | Description |
|---|
200 | Success |
401 | Unauthorized |
403 | Forbidden |
404 | The ontology, the named draft, or the machine is not found |
Replace a state machine
Replaces the whole definition of a state machine in a draft version of the ontology. The body takes the same fields as Create a state machine.
- To keep a state, event, transition, or action, send it with the
_id the service returned. The service deletes any child you omit.
- To add a child, omit its
_id or send a new UUID. An ID that belongs to another machine returns 422.
- If you send a machine
_id, it must match machineId.
- The service grants you
CREATE on each new event. For each event you remove, it removes the grants on that event. Wildcard grants that also cover the event stay.
Endpoints
PUT /aosvc/api/v1/ontologies/{ontologyId}/state-machines/{machineId}
Parameters
Path
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ID of the ontology | Required |
machineId | String | The ID of the state machine | 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
The same fields as Create a state machine.
Example:
{
"_id": "4926c6f5-ec5e-44ca-a793-11b0e86fa46e",
"_name": "Approval",
"_classIds": ["f5f565dc-4169-4664-909f-b2c6f11e1a27"],
"_states": [
{ "_id": "12198858-9325-4e3b-93a0-d4f8d36db6ed", "_name": "Draft", "_value": "draft", "_initial": true },
{ "_id": "fd57358f-5686-4f65-9c2c-10eb026f86c7", "_name": "Approved", "_value": "approved" },
{ "_id": "0c6a1f3e-92b4-4d7e-8a15-6f3b2c9d1e07", "_name": "Rejected", "_value": "rejected" }
],
"_events": [
{ "_id": "11b700ba-c9bb-4776-a0f1-36202f24a6b3", "_name": "Approve" },
{ "_id": "7d2e4b9a-1c3f-4e8d-b5a6-2f9c0e7d3b14", "_name": "Reject" }
],
"_transitions": [
{
"_id": "820ec042-810b-470b-be7c-55c6dae882d6",
"_name": "approve",
"_fromStateId": "12198858-9325-4e3b-93a0-d4f8d36db6ed",
"_toStateId": "fd57358f-5686-4f65-9c2c-10eb026f86c7",
"_executionOrder": 0,
"_eventIds": ["11b700ba-c9bb-4776-a0f1-36202f24a6b3"],
"_actions": []
},
{
"_name": "reject",
"_fromStateId": "12198858-9325-4e3b-93a0-d4f8d36db6ed",
"_toStateId": "0c6a1f3e-92b4-4d7e-8a15-6f3b2c9d1e07",
"_executionOrder": 1,
"_eventIds": ["7d2e4b9a-1c3f-4e8d-b5a6-2f9c0e7d3b14"],
"_actions": []
}
]
}
Response
Returns the complete state machine. The response ETag header holds the new ontology revision.
{
"_id": "4926c6f5-ec5e-44ca-a793-11b0e86fa46e",
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_name": "Approval",
"_classIds": ["f5f565dc-4169-4664-909f-b2c6f11e1a27"],
"_states": [
{ "_id": "12198858-9325-4e3b-93a0-d4f8d36db6ed", "_name": "Draft", "_value": "draft", "_initial": true },
{ "_id": "fd57358f-5686-4f65-9c2c-10eb026f86c7", "_name": "Approved", "_value": "approved" },
{ "_id": "0c6a1f3e-92b4-4d7e-8a15-6f3b2c9d1e07", "_name": "Rejected", "_value": "rejected" }
],
"_events": [
{ "_id": "11b700ba-c9bb-4776-a0f1-36202f24a6b3", "_name": "Approve" },
{ "_id": "7d2e4b9a-1c3f-4e8d-b5a6-2f9c0e7d3b14", "_name": "Reject" }
],
"_transitions": [
{
"_id": "820ec042-810b-470b-be7c-55c6dae882d6",
"_name": "approve",
"_fromStateId": "12198858-9325-4e3b-93a0-d4f8d36db6ed",
"_toStateId": "fd57358f-5686-4f65-9c2c-10eb026f86c7",
"_executionOrder": 0,
"_eventIds": ["11b700ba-c9bb-4776-a0f1-36202f24a6b3"],
"_actions": []
},
{
"_id": "3e8f1a2b-6c4d-4b9e-a7f0-5d2c1b8e9a46",
"_name": "reject",
"_fromStateId": "12198858-9325-4e3b-93a0-d4f8d36db6ed",
"_toStateId": "0c6a1f3e-92b4-4d7e-8a15-6f3b2c9d1e07",
"_executionOrder": 1,
"_eventIds": ["7d2e4b9a-1c3f-4e8d-b5a6-2f9c0e7d3b14"],
"_actions": []
}
],
"_createdAt": "2026-09-24T09:00:00Z",
"_updatedAt": "2026-09-25T14:30:00Z",
"_createdBy": "b0a30681-e719-486c-8f03-56091e590940",
"_updatedBy": "b0a30681-e719-486c-8f03-56091e590940"
}
Codes
| Code | Description |
|---|
200 | Success |
400 | Bad Request. A required field is missing or blank, a name or string state value is longer than 500 characters, the body is malformed, or _classIds names a platform lifecycle class. |
401 | Unauthorized |
403 | Forbidden |
404 | The ontology, the named draft, the machine, or a class in _classIds is not found |
409 | Conflict. X-Ontology-Draft is missing or does not name an editable draft, another user holds the ontology edit lock, the body _id differs from machineId, the machine name is already used on an overlapping class, or an action name is already used in the ontology. |
412 | The If-Match revision is stale |
422 | The definition is invalid. For example, a child ID belongs to another machine, one ID is used for two items, a name or state value is repeated, there isn't exactly one initial state, or an action parameter is invalid. |
423 | The ontology uses edit locking and you don't hold the lock |
502 | An event permission could not be granted |
Delete a state machine
Deletes a state machine and its inline actions from a draft version of the ontology. The service then removes the grants on each of the machine's events. Wildcard grants that also cover the events stay. You need only EDIT on the ontology.
Endpoints
DELETE /aosvc/api/v1/ontologies/{ontologyId}/state-machines/{machineId}
Parameters
Path
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ID of the ontology | Required |
machineId | String | The ID of the state machine | 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 machine 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 |
Bind classes to a state machine
Adds classes to a state machine's _classIds in a draft version of the ontology.
Endpoints
POST /aosvc/api/v1/ontologies/{ontologyId}/state-machines/{machineId}/classes
Parameters
Path
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ID of the ontology | Required |
machineId | String | The ID of the state machine | 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 |
|---|
_classIds | Array of String | The IDs of the classes to bind. Each class must be in this ontology. | Required |
Example:
{
"_classIds": ["9a3c5e7f-2b4d-4f6a-8c1e-3d5f7a9b1c2e"]
}
Response
Returns the complete state machine with the classes added.
{
"_id": "4926c6f5-ec5e-44ca-a793-11b0e86fa46e",
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_name": "Approval",
"_classIds": [
"f5f565dc-4169-4664-909f-b2c6f11e1a27",
"9a3c5e7f-2b4d-4f6a-8c1e-3d5f7a9b1c2e"
],
"_states": [
{ "_id": "12198858-9325-4e3b-93a0-d4f8d36db6ed", "_name": "Draft", "_value": "draft", "_initial": true },
{ "_id": "fd57358f-5686-4f65-9c2c-10eb026f86c7", "_name": "Approved", "_value": "approved" }
],
"_events": [
{ "_id": "11b700ba-c9bb-4776-a0f1-36202f24a6b3", "_name": "Approve" }
],
"_transitions": [
{
"_id": "820ec042-810b-470b-be7c-55c6dae882d6",
"_name": "approve",
"_fromStateId": "12198858-9325-4e3b-93a0-d4f8d36db6ed",
"_toStateId": "fd57358f-5686-4f65-9c2c-10eb026f86c7",
"_executionOrder": 0,
"_eventIds": ["11b700ba-c9bb-4776-a0f1-36202f24a6b3"],
"_actions": []
}
],
"_createdAt": "2026-09-24T09:00:00Z",
"_updatedAt": "2026-09-26T11:05:00Z",
"_createdBy": "b0a30681-e719-486c-8f03-56091e590940",
"_updatedBy": "b0a30681-e719-486c-8f03-56091e590940"
}
Codes
| Code | Description |
|---|
200 | Success |
400 | Bad Request. _classIds is empty or names a platform lifecycle class. |
401 | Unauthorized |
403 | Forbidden |
404 | The ontology, the named draft, the machine, or a class 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 |
Unbind classes from a state machine
Removes classes from a state machine's _classIds in a draft version of the ontology. At least one class must stay bound.
Endpoints
DELETE /aosvc/api/v1/ontologies/{ontologyId}/state-machines/{machineId}/classes
Parameters
Path
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ID of the ontology | Required |
machineId | String | The ID of the state machine | 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 |
|---|
_classIds | Array of String | The IDs of the classes to unbind | Required |
Example:
{
"_classIds": ["9a3c5e7f-2b4d-4f6a-8c1e-3d5f7a9b1c2e"]
}
Response
Returns the complete state machine with the classes removed.
{
"_id": "4926c6f5-ec5e-44ca-a793-11b0e86fa46e",
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_name": "Approval",
"_classIds": ["f5f565dc-4169-4664-909f-b2c6f11e1a27"],
"_states": [
{ "_id": "12198858-9325-4e3b-93a0-d4f8d36db6ed", "_name": "Draft", "_value": "draft", "_initial": true },
{ "_id": "fd57358f-5686-4f65-9c2c-10eb026f86c7", "_name": "Approved", "_value": "approved" }
],
"_events": [
{ "_id": "11b700ba-c9bb-4776-a0f1-36202f24a6b3", "_name": "Approve" }
],
"_transitions": [
{
"_id": "820ec042-810b-470b-be7c-55c6dae882d6",
"_name": "approve",
"_fromStateId": "12198858-9325-4e3b-93a0-d4f8d36db6ed",
"_toStateId": "fd57358f-5686-4f65-9c2c-10eb026f86c7",
"_executionOrder": 0,
"_eventIds": ["11b700ba-c9bb-4776-a0f1-36202f24a6b3"],
"_actions": []
}
],
"_createdAt": "2026-09-24T09:00:00Z",
"_updatedAt": "2026-09-26T11:20:00Z",
"_createdBy": "b0a30681-e719-486c-8f03-56091e590940",
"_updatedBy": "b0a30681-e719-486c-8f03-56091e590940"
}
Codes
| Code | Description |
|---|
200 | Success |
400 | Bad Request. _classIds is empty. |
401 | Unauthorized |
403 | Forbidden |
404 | The ontology, the named draft, or the machine 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 |
422 | The request would leave no class bound |
423 | The ontology uses edit locking and you don't hold the lock |
List states
Lists the states of the ontology's state machines, grouped by machine. The response has one entry for each machine that has at least one state, sorted by _stateMachineId. States are sorted by _id.
Endpoints
GET /aosvc/api/v1/ontologies/{ontologyId}/state-machines/states
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 |
machineId | String | Returns only the states of this machine | Optional |
| Parameter | Type | Description | Required |
|---|
X-Ontology-Draft | Integer | The version number to read. Omit it to read the live version. | Optional |
Response
[
{
"_stateMachineId": "4926c6f5-ec5e-44ca-a793-11b0e86fa46e",
"_states": [
{ "_id": "12198858-9325-4e3b-93a0-d4f8d36db6ed", "_name": "Draft", "_value": "draft", "_initial": true },
{ "_id": "fd57358f-5686-4f65-9c2c-10eb026f86c7", "_name": "Approved", "_value": "approved" }
]
}
]
Codes
| Code | Description |
|---|
200 | Success |
401 | Unauthorized |
403 | Forbidden |
404 | The ontology, the named draft, or the machine named in machineId is not found |
List events
Lists the events of the ontology's state machines, grouped by machine. The response has one entry for each machine that has at least one event, sorted by _stateMachineId. Events are sorted by _id.
Endpoints
GET /aosvc/api/v1/ontologies/{ontologyId}/state-machines/events
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 |
machineId | String | Returns only the events of this machine | Optional |
| Parameter | Type | Description | Required |
|---|
X-Ontology-Draft | Integer | The version number to read. Omit it to read the live version. | Optional |
Response
[
{
"_stateMachineId": "4926c6f5-ec5e-44ca-a793-11b0e86fa46e",
"_events": [
{ "_id": "11b700ba-c9bb-4776-a0f1-36202f24a6b3", "_name": "Approve" }
]
}
]
Codes
| Code | Description |
|---|
200 | Success |
401 | Unauthorized |
403 | Forbidden |
404 | The ontology, the named draft, or the machine named in machineId is not found |
List transitions
Lists the transitions of the ontology's state machines, grouped by machine. The response has one entry for each machine that has at least one transition, sorted by _stateMachineId. Transitions are sorted by _executionOrder and include their _eventIds and _actions.
Endpoints
GET /aosvc/api/v1/ontologies/{ontologyId}/state-machines/transitions
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 |
machineId | String | Returns only the transitions of this machine | Optional |
| Parameter | Type | Description | Required |
|---|
X-Ontology-Draft | Integer | The version number to read. Omit it to read the live version. | Optional |
Response
[
{
"_stateMachineId": "4926c6f5-ec5e-44ca-a793-11b0e86fa46e",
"_transitions": [
{
"_id": "820ec042-810b-470b-be7c-55c6dae882d6",
"_name": "approve",
"_fromStateId": "12198858-9325-4e3b-93a0-d4f8d36db6ed",
"_toStateId": "fd57358f-5686-4f65-9c2c-10eb026f86c7",
"_executionOrder": 0,
"_eventIds": ["11b700ba-c9bb-4776-a0f1-36202f24a6b3"],
"_actions": [
{
"_id": "5b2d9e71-3c4a-4f8b-a6d2-7e1f0c9b8a35",
"_name": "Start approval workflow",
"_actionType": "WORKFLOW",
"_executionOrder": 0,
"_params": {
"_workflowDefId": "37a5d99e-c20d-45f7-8a2f-8d5af5ea6535"
}
}
]
}
]
}
]
Codes
| Code | Description |
|---|
200 | Success |
401 | Unauthorized |
403 | Forbidden |
404 | The ontology, the named draft, or the machine named in machineId is not found |
Fire an event
Queues a state machine event against individuals, grouped by class. The service checks the request before it queues the event, then moves each individual in the background. A 201 response means the event is queued, not that any individual changed state. To see the outcome for each individual, use Get state machine history and match rows on _eventTriggerId. To see what the transition's actions did, use List action executions.
The event always uses the live version of the ontology, so you don't send X-Ontology-Draft. The service takes the from and to states from the transition bound to the event. An individual with no state yet for this machine takes the transition whatever its current state.
Each target class can map to its own collection. The service reads and writes each individual in the collection its target class is mapped to. If a class mapping is removed before the event is processed, only that class's individuals fail.
To fire an event, you need CREATE on the event and INDIVIDUALS_EDIT on every class bound to the machine, not only the classes you target.
Endpoints
POST /aosvc/api/v1/state-machines/{machineId}/events
Parameters
Path
| Parameter | Type | Description | Required |
|---|
machineId | String | The ID of the state machine | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | Namespace filter to apply | Required |
| Parameter | Type | Description | Required |
|---|
Idempotency-Key | String | A key of 1 to 128 letters, digits, ., _, :, or -. It becomes the _eventTriggerId. The service applies an event at most once for each key, and remembers keys for seven days. If you get a 503, retry with the key the error message names. | Optional |
Body
| Parameter | Type | Description | Required |
|---|
_eventId | String | The ID of the event | Required |
_eventName | String | The name of the event. It must name the same event as _eventId. | Required |
_targets | Array of Object | The individuals to move, grouped by class. An individual ID can appear only once across all targets. | Required |
_targets[n]._classId | String | The ID of a class bound to the machine. The class must be mapped to a collection. | Required |
_targets[n]._individualIds | Array of String | The IDs of 1 to 500 individuals of the class | Required |
Example:
{
"_eventId": "11b700ba-c9bb-4776-a0f1-36202f24a6b3",
"_eventName": "Approve",
"_targets": [
{
"_classId": "f5f565dc-4169-4664-909f-b2c6f11e1a27",
"_individualIds": ["66f2a1c9e4b0a37d5c8e9f01", "66f2a1c9e4b0a37d5c8e9f02"]
}
]
}
Response
{
"_eventTriggerId": "c3f1e8a2-5b7d-4c9e-a1f3-8d2b6e4a0c95"
}
Codes
| Code | Description |
|---|
201 | Created. The event is queued. |
400 | Bad Request. _targets is empty, a target has no IDs or more than 500, an ID repeats across targets, or Idempotency-Key is malformed. |
401 | Unauthorized |
403 | Forbidden |
404 | The machine is not found, the event is not in the machine, or a target class is not mapped to a collection |
409 | Conflict. The ontology has no live version, _eventId and _eventName name different events, the event has no bound transition, or a target class is mapped to a collection that doesn't exist yet. |
422 | A target class is not bound to the machine |
503 | The event could not be queued. Retry with the Idempotency-Key the error message names. |
Get state machine history
Lists the newest transition attempts for a state machine, across all individuals, newest first. Each processed individual gets one row, whether it moved or not.
Endpoints
GET /aosvc/api/v1/ontologies/{ontologyId}/state-machines/{machineId}/history
Parameters
Path
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ID of the ontology | Required |
machineId | String | The ID of the state machine | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | Namespace filter to apply | Required |
limit | Integer | The number of rows to return, from 1 to 500. Default is 100. | Optional |
Response
_success says whether the individual moved. _currentState is the individual's state when the event was processed. _actorUserId is the user who fired the event.
[
{
"_id": "7c1e2a90-4b3d-4f6e-9a21-5d8c0b7e3f14",
"_eventTriggerId": "c3f1e8a2-5b7d-4c9e-a1f3-8d2b6e4a0c95",
"_stateMachineId": "4926c6f5-ec5e-44ca-a793-11b0e86fa46e",
"_classId": "f5f565dc-4169-4664-909f-b2c6f11e1a27",
"_individualId": "66f2a1c9e4b0a37d5c8e9f01",
"_eventId": "11b700ba-c9bb-4776-a0f1-36202f24a6b3",
"_eventName": "Approve",
"_eventSourceType": "MANUAL",
"_transitionId": "820ec042-810b-470b-be7c-55c6dae882d6",
"_fromStateId": "12198858-9325-4e3b-93a0-d4f8d36db6ed",
"_toStateId": "fd57358f-5686-4f65-9c2c-10eb026f86c7",
"_fromStateValue": "draft",
"_toStateValue": "approved",
"_success": true,
"_currentState": "draft",
"_actorUserId": "b0a30681-e719-486c-8f03-56091e590940",
"_occurredAt": "2026-09-24T10:00:00Z",
"_committedAt": "2026-09-24T10:00:01Z"
}
]
Codes
| Code | Description |
|---|
200 | Success |
401 | Unauthorized |
403 | Forbidden |
404 | The ontology or the machine is not found |
List action executions
Lists what the actions of a state machine's transitions did, newest first. Each committed transition that has actions gets one execution. The execution lists the individuals that moved and, for each action, its status, attempts, and last error.
Endpoints
GET /aosvc/api/v1/ontologies/{ontologyId}/state-machines/{machineId}/action-executions
Parameters
Path
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ID of the ontology | Required |
machineId | String | The ID of the state machine | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | Namespace filter to apply | Required |
status | String | Returns the executions in which any action has this status: PENDING, RUNNING, SUCCEEDED, RETRY, or FAILED | Optional |
eventTriggerId | String | Returns the executions of the event that returned this _eventTriggerId | Optional |
individualId | String | Returns the executions that include this individual | Optional |
_offset | Integer | The number of executions to skip. Default is 0. | Optional |
_pageSize | Integer | The number of executions to return, from 1 to 200. Default is 50. | Optional |
Response
The response is one page of executions. _pageSize is the number of executions on the page, and _hasMore says whether more pages follow.
The execution _status is SUCCEEDED once every action has finished, even if some failed. To find an action that failed, filter on status=FAILED. An action status of RETRY means the action failed and will run again. _actionName and _actionType are the values when the transition was queued. _lastError holds up to 1000 characters.
{
"_list": [
{
"_id": "3f0a1c2e-8b4d-4e6f-9a1b-2c3d4e5f6a7b",
"_eventTriggerId": "c3f1e8a2-5b7d-4c9e-a1f3-8d2b6e4a0c95",
"_stateMachineId": "4926c6f5-ec5e-44ca-a793-11b0e86fa46e",
"_classId": "f5f565dc-4169-4664-909f-b2c6f11e1a27",
"_eventId": "11b700ba-c9bb-4776-a0f1-36202f24a6b3",
"_eventName": "Approve",
"_transitionId": "820ec042-810b-470b-be7c-55c6dae882d6",
"_fromStateValue": "draft",
"_toStateValue": "approved",
"_individualIds": ["66f2a1c9e4b0a37d5c8e9f01"],
"_targets": [
{ "_classId": "f5f565dc-4169-4664-909f-b2c6f11e1a27", "_individualIds": ["66f2a1c9e4b0a37d5c8e9f01"] }
],
"_actorUserId": "b0a30681-e719-486c-8f03-56091e590940",
"_status": "SUCCEEDED",
"_createdAt": "2026-09-24T10:00:01Z",
"_updatedAt": "2026-09-24T10:00:09Z",
"_completedAt": "2026-09-24T10:00:09Z",
"_actions": [
{
"_actionId": "5b2d9e71-3c4a-4f8b-a6d2-7e1f0c9b8a35",
"_actionName": "Start approval workflow",
"_actionType": "WORKFLOW",
"_executionOrder": 0,
"_status": "SUCCEEDED",
"_attempts": 1,
"_lastError": null,
"_completedAt": "2026-09-24T10:00:09Z"
}
]
}
],
"_offset": 0,
"_pageSize": 1,
"_total": 1,
"_hasMore": false
}
Codes
| Code | Description |
|---|
200 | Success |
400 | Bad Request. status is not an action status. |
401 | Unauthorized |
403 | Forbidden |
404 | The ontology or the machine is not found |
Get an action execution
Gets one action execution of a state machine.
Endpoints
GET /aosvc/api/v1/ontologies/{ontologyId}/state-machines/{machineId}/action-executions/{executionId}
Parameters
Path
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ID of the ontology | Required |
machineId | String | The ID of the state machine | Required |
executionId | String | The _id of the execution | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | Namespace filter to apply | Required |
Response
Returns one execution, with the fields described in List action executions.
Codes
| Code | Description |
|---|
200 | Success |
401 | Unauthorized |
403 | Forbidden |
404 | The ontology, the machine, or the execution is not found |