API reference

KYE Protocol™ State API — State Machines + Events + Registry

8 operations · state.openapi.yaml

KYE Protocol™ State API: try the first operations

Demo data

You learn: What a call to this API sends and gets back. You can: Send a request.

API client · List state machines visible to the authenticated tenant

Request

GET /api/v1/state-machines

Response `200`

{
  "data": [
    {
      "created_at": "2026-10-01T09:00:00Z",
      "created_by": "<created_by>",
      "entity_class": "<entity_class>",
      "locked_at": "2026-10-01T09:00:00Z",
      "machine_id": "<machine_id>",
      "schema_version": "kye.state.machine.v1",
      "states": [
        {
          "description": "<description>",
          "kind": "initial",
          "name": "<name>",
          "obligations": [
            "<obligations>"
          ]
        }
      ],
      "tenant_scope": "<tenant_scope>"
    }
  ]
}

API client · Get a state machine by ID

Request

GET /api/v1/state-machines/%3Cmachine_id%3E

Response `200`

{
  "data": {
    "created_at": "2026-10-01T09:00:00Z",
    "created_by": "<created_by>",
    "entity_class": "<entity_class>",
    "locked_at": "2026-10-01T09:00:00Z",
    "machine_id": "<machine_id>",
    "schema_version": "kye.state.machine.v1",
    "states": [
      {
        "description": "<description>",
        "kind": "initial",
        "name": "<name>",
        "obligations": [
          "<obligations>"
        ]
      }
    ],
    "tenant_scope": "<tenant_scope>"
  }
}

API client · List state events (append-only log)

Request

GET /api/v1/state-events

Response `200`

{
  "data": [
    {
      "cascade_event_ids": [
        "<cascade_event_ids>"
      ],
      "decided_at": "2026-10-01T09:00:00Z",
      "decided_by": "<decided_by>",
      "entity_id": "<entity_id>",
      "event_id": "<event_id>",
      "evidence_refs": [
        "<evidence_refs>"
      ],
      "from": "<from>",
      "machine_id": "<machine_id>",
      "schema_version": "kye.state.event.v1",
      "signature": {
        "alg": "EdDSA",
        "kid": "<kid>",
        "value_b64": "<value_b64>"
      },
      "to": "<to>",
      "transition_id": "<transition_id>"
    }
  ]
}

How this widget is built

Demonstrates

KYE™ API

Components

The OpenAPI 3.1 contract
Request and response examples from the contract

Flow

Request → response, from the published contract. Architecture diagram

Used on

/developers/api/state/: On every contract's reference page.

Servers: https://api.kyeprotocol.com
Version: 3.0.0
Source: 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
`tenant_id`	query	string
`entity_class`	query	string
`scope`	query	string

Responses

200 List 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

201 Created

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

201 Derived 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

200 State machine
404 Not found

state-events

GET/api/v1/state-eventsList state events (append-only log)

Auth: bearerAuth

Parameters

name	in	type
`entity_id`	query	string
`machine_id`	query	string
`from`	query	string
`to`	query	string

Responses

200 List 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

201 Event fired and recorded
422 Transition 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

200 Registry 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

200 Transitions

Related

KYE Protocol™ Admin Root EndpointsKYE Protocol™ Admin Root Endpoints: 3 operations from admin-root.yaml, a published KYE Protocol™ OpenAPI contract.
KYE Protocol™ Admin APIKYE Protocol™ Admin API: 188 operations from admin.yaml, a published KYE Protocol™ OpenAPI contract.
KYE Protocol™ Cloud Partner-Plane APIKYE Protocol™ Cloud Partner-Plane API: 18 operations from app-partner.yaml, a published KYE Protocol™ OpenAPI contract.
KYE Protocol™ App API (API reference)KYE Protocol™ App API — root paths: 3 operations from app-root.yaml, a published KYE Protocol™ OpenAPI contract.
KYE Protocol™ App APIKYE Protocol™ App API: 132 operations from app.yaml, a published KYE Protocol™ OpenAPI contract.

KYE Protocol™ State API — State Machines + Events + Registry

Request

Response 200

Request

Response 200

Request

Response 200

state-machines

Parameters

Responses

Request body (required)

Responses

Request body (required)

Responses

Parameters

Responses

state-events

Parameters

Responses

Request body (required)

Responses

state-registry

Parameters

Responses

state-transitions

Parameters

Responses

Response `200`

Response `200`

Response `200`