Interactive API reference

Everything in the API reference tab is generated, not written. It is rendered straight from api-gateway's own OpenAPI document — one page per tag, every request and response schema, every status code the handler actually declares — so it can never say something the service does not do.

Using the reference#

The Overview page lists every tag — Organizations, Environments, Charging stations, Commands, and so on — matching the resource groupings the rest of these guides use. Each tag's page lists its operations with the full request and response schema, every documented status code, and which ones require which role.

Two things worth knowing before you rely on it:

• Every schema is the real one. #[utoipa::path] annotations sit next to the Rust handlers they document, and a test in api-gateway's own suite guards the committed openapi.json against the code that generates it — the document cannot ship stale.
• A $ref names a request or response shape once. The same ErrorBody schema — { error, message } — is reused across every 4xx/5xx a handler declares, rather than redefined per endpoint. If you are generating a client from this document, that shared schema is worth generating once too.

Pulling the raw document yourself#

If you want to generate your own client rather than read the rendered reference:

curl -s https://api.flowion.io/v1/api-docs/openapi.json -o openapi.json

It is a standard OpenAPI 3 document — anything that consumes one (openapi-typescript, openapi-generator, and similar) can point at that URL directly.

Next: Roles and permissions.