Skip to content

REST API

The PyStator REST API is documented and tryable in two places:

  • Swagger UI — When the API is running, open /docs (e.g. http://localhost:8004/docs) for interactive request/response documentation and "Try it out" for every endpoint.
  • In-app API Playground — From the PyStator UI, open the API Playground (Documentation) page to call endpoints with a minimal request body editor.

Both use the same OpenAPI schema; Swagger is the single source of truth for endpoint paths, methods, request bodies, and responses.

Running the API

Start the API server:

pystator api

Or with uvicorn:

uvicorn pystator.api.main:app --host 0.0.0.0 --port 8004

Then open http://localhost:8004/docs for the full REST API reference.

Entity lifecycle

  • Create (initial state only): POST /api/v1/entities/{entity_id}/create with JSON body { "machine_name": "...", "machine_version": "..." (optional), "context": {} (optional) }. Persists the entity at the machine’s initial state and writes a history row with trigger __entity_created__. Returns 409 if entity_id already exists.
  • Process an event: POST /api/v1/entities/{entity_id}/events with a trigger — full transition, persist, and history as today.