API reference
KYE Protocol™ State API — State Machines + Events + Registry
8 operations · state.openapi.yaml
Endpoints for creating and managing declarative state machines, firing state transition events, querying the State Registry, and listing state transitions.
state-machines
GET/api/v1/state-machinesList state machines visible to the authenticated tenant
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
tenant_id | query | string | |
entity_class | query | string | |
scope | query | string |
Responses
200List of state machines
POST/api/v1/state-machinesCreate a tenant-scoped state machine (or extension)
Auth: bearerAuth
Request body (required)
| field | type | description |
|---|---|---|
entity_class required | string | |
tenant_scope | string | |
states required | array |
Responses
201Created
POST/api/v1/state-machines/from-libraryDerive a tenant state machine from a State Library entry
Auth: bearerAuth
Request body (required)
| field | type | description |
|---|---|---|
library_id required | string | kye:state-library:<sector>.<name>.v<n> |
tenant_id required | string | |
tightened_guards | array | |
added_states | array |
Responses
201Derived machine created
GET/api/v1/state-machines/{machine_id}Get a state machine by ID
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
machine_id required | path | string |
Responses
200State machine404Not found
state-events
GET/api/v1/state-eventsList state events (append-only log)
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
entity_id | query | string | |
machine_id | query | string | |
from | query | string | |
to | query | string |
Responses
200List of state events
POST/api/v1/state-eventsFire a state transition event for an entity
Auth: bearerAuth
Request body (required)
| field | type | description |
|---|---|---|
entity_id required | string | Any KYE™ entity URN |
to_state required | string | Target state name |
evidence_refs | array | |
decided_by | string |
Responses
201Event fired and recorded422Transition not permitted by machine
state-registry
GET/api/v1/state-registry/{tenant_id}Get the State Registry summary for a tenant
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
tenant_id required | path | string |
Responses
200Registry envelope
state-transitions
GET/api/v1/state-transitionsList declared state transitions for a machine
Auth: bearerAuth
Parameters
| name | in | type | description |
|---|---|---|---|
machine_id required | query | string |
Responses
200Transitions