Skip to main content
Version: v5.3

State machines

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​

ParameterTypeDescriptionRequired
ontologyIdStringThe ID of the ontologyRequired

Query​

ParameterTypeDescriptionRequired
nsfilterStringNamespace filter to applyRequired
classIdStringReturns only the machines bound to this classOptional
ParameterTypeDescriptionRequired
X-Ontology-DraftIntegerThe 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​

CodeDescription
200Success
400Bad Request. nsfilter is missing.
401Unauthorized
403Forbidden
404The 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​

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
_idStringA UUID for the machine. The service creates one if you omit it.Optional
_nameStringThe machine name, up to 500 characters. It must be unique among machines bound to the same classes.Required
_descriptionStringA description of the machineOptional
_classIdsArray of StringThe 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
_statesArray of ObjectThe states of the machine. Exactly one state must have _initial set to true.Required
_states[n]._idStringA UUID for the state. The service creates one if you omit it.Optional
_states[n]._nameStringThe state name, up to 500 characters. It must be unique in the machine.Required
_states[n]._valueString, Number, or BooleanThe 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]._initialBooleanWhether new individuals start in this stateOptional
_eventsArray of ObjectThe events of the machineRequired
_events[n]._idStringA UUID for the event. The service creates one if you omit it.Optional
_events[n]._nameStringThe event name, up to 500 characters. It must be unique in the machine.Required
_events[n]._descriptionStringA description of the eventOptional
_transitionsArray of ObjectThe transitions of the machineRequired
_transitions[n]._idStringA UUID for the transition. The service creates one if you omit it.Optional
_transitions[n]._nameStringThe transition name, up to 500 characters. It must be unique in the machine.Required
_transitions[n]._fromStateIdStringThe ID of the state the transition starts fromRequired
_transitions[n]._toStateIdStringThe ID of the state the transition ends inRequired
_transitions[n]._executionOrderIntegerThe order of the transition. Orders must run from 0 without gaps. When several transitions share an event, the lowest order wins.Required
_transitions[n]._eventIdsArray of StringThe IDs of the events that fire the transitionRequired
_transitions[n]._actionsArray of ObjectThe 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]._executionOrderIntegerThe 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​

CodeDescription
201Created
400Bad 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.
401Unauthorized
403Forbidden
404The ontology, the named draft, or a class in _classIds is not found
409Conflict. 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.
412The If-Match revision is stale
422The 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.
423The ontology uses edit locking and you don't hold the lock
502An 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​

ParameterTypeDescriptionRequired
ontologyIdStringThe ID of the ontologyRequired
machineIdStringThe ID of the state machineRequired

Query​

ParameterTypeDescriptionRequired
nsfilterStringNamespace filter to applyRequired

Header​

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

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

ParameterTypeDescriptionRequired
ontologyIdStringThe ID of the ontologyRequired
machineIdStringThe ID of the state machineRequired

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​

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​

CodeDescription
200Success
400Bad 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.
401Unauthorized
403Forbidden
404The ontology, the named draft, the machine, or a class in _classIds is not found
409Conflict. 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.
412The If-Match revision is stale
422The 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.
423The ontology uses edit locking and you don't hold the lock
502An 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​

ParameterTypeDescriptionRequired
ontologyIdStringThe ID of the ontologyRequired
machineIdStringThe ID of the state machineRequired

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 machine 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

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​

ParameterTypeDescriptionRequired
ontologyIdStringThe ID of the ontologyRequired
machineIdStringThe ID of the state machineRequired

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
_classIdsArray of StringThe 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​

CodeDescription
200Success
400Bad Request. _classIds is empty or names a platform lifecycle class.
401Unauthorized
403Forbidden
404The ontology, the named draft, the machine, or a class 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

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​

ParameterTypeDescriptionRequired
ontologyIdStringThe ID of the ontologyRequired
machineIdStringThe ID of the state machineRequired

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
_classIdsArray of StringThe IDs of the classes to unbindRequired

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​

CodeDescription
200Success
400Bad Request. _classIds is empty.
401Unauthorized
403Forbidden
404The ontology, the named draft, or the machine 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
422The request would leave no class bound
423The 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​

ParameterTypeDescriptionRequired
ontologyIdStringThe ID of the ontologyRequired

Query​

ParameterTypeDescriptionRequired
nsfilterStringNamespace filter to applyRequired
machineIdStringReturns only the states of this machineOptional

Header​

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

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

ParameterTypeDescriptionRequired
ontologyIdStringThe ID of the ontologyRequired

Query​

ParameterTypeDescriptionRequired
nsfilterStringNamespace filter to applyRequired
machineIdStringReturns only the events of this machineOptional

Header​

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

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

ParameterTypeDescriptionRequired
ontologyIdStringThe ID of the ontologyRequired

Query​

ParameterTypeDescriptionRequired
nsfilterStringNamespace filter to applyRequired
machineIdStringReturns only the transitions of this machineOptional

Header​

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

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

ParameterTypeDescriptionRequired
machineIdStringThe ID of the state machineRequired

Query​

ParameterTypeDescriptionRequired
nsfilterStringNamespace filter to applyRequired

Header​

ParameterTypeDescriptionRequired
Idempotency-KeyStringA 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​

ParameterTypeDescriptionRequired
_eventIdStringThe ID of the eventRequired
_eventNameStringThe name of the event. It must name the same event as _eventId.Required
_targetsArray of ObjectThe individuals to move, grouped by class. An individual ID can appear only once across all targets.Required
_targets[n]._classIdStringThe ID of a class bound to the machine. The class must be mapped to a collection.Required
_targets[n]._individualIdsArray of StringThe IDs of 1 to 500 individuals of the classRequired

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​

CodeDescription
201Created. The event is queued.
400Bad Request. _targets is empty, a target has no IDs or more than 500, an ID repeats across targets, or Idempotency-Key is malformed.
401Unauthorized
403Forbidden
404The machine is not found, the event is not in the machine, or a target class is not mapped to a collection
409Conflict. 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.
422A target class is not bound to the machine
503The 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​

ParameterTypeDescriptionRequired
ontologyIdStringThe ID of the ontologyRequired
machineIdStringThe ID of the state machineRequired

Query​

ParameterTypeDescriptionRequired
nsfilterStringNamespace filter to applyRequired
limitIntegerThe 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​

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

ParameterTypeDescriptionRequired
ontologyIdStringThe ID of the ontologyRequired
machineIdStringThe ID of the state machineRequired

Query​

ParameterTypeDescriptionRequired
nsfilterStringNamespace filter to applyRequired
statusStringReturns the executions in which any action has this status: PENDING, RUNNING, SUCCEEDED, RETRY, or FAILEDOptional
eventTriggerIdStringReturns the executions of the event that returned this _eventTriggerIdOptional
individualIdStringReturns the executions that include this individualOptional
_offsetIntegerThe number of executions to skip. Default is 0.Optional
_pageSizeIntegerThe 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​

CodeDescription
200Success
400Bad Request. status is not an action status.
401Unauthorized
403Forbidden
404The 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​

ParameterTypeDescriptionRequired
ontologyIdStringThe ID of the ontologyRequired
machineIdStringThe ID of the state machineRequired
executionIdStringThe _id of the executionRequired

Query​

ParameterTypeDescriptionRequired
nsfilterStringNamespace filter to applyRequired

Response​

Returns one execution, with the fields described in List action executions.

Codes​

CodeDescription
200Success
401Unauthorized
403Forbidden
404The ontology, the machine, or the execution is not found