---
title: "KYE Protocol™ State API — State Machines + Events + Registry | API reference"
description: "KYE Protocol™ State API — State Machines + Events + Registry: 8 operations from state.openapi.yaml, a published KYE Protocol™ OpenAPI contract."
url: https://kyeprotocol.com/developers/api/state/
lang: en
source: "KYE Protocol"
---

> KYE Protocol™ State API — State Machines + Events + Registry: 8 operations from state.openapi.yaml, a published KYE Protocol™ OpenAPI contract.

API reference

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

8 operations · `state.openapi.yaml`

**Servers**

`https://api.kyeprotocol.com`

**Version**

3.0.0

**Source**

[state.openapi.yaml](https://kyeprotocol.com/developers/api/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 4 state-events 2 state-registry 1 state-transitions 1

## state-machines

GET `/api/v1/state-machines` List 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

- `200` List of state machines

POST `/api/v1/state-machines` Create 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-library` Derive 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-events` List 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

- `200` List of state events

POST `/api/v1/state-events` Fire 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-transitions` List declared state transitions for a machine

**Auth:** bearerAuth

### Parameters

| name | in | type | description |
| --- | --- | --- | --- |
| `machine_id` **required** | query | string |  |

### Responses

- `200` Transitions