# HTTP API reference

The generated [OpenAPI 3.0 contract](/openapi.yaml) is the canonical reference
for request bodies, response bodies, authentication, and status codes.

## Endpoint groups

| Group | Paths | Purpose |
| --- | --- | --- |
| Metadata | `/meta/version`, `/meta/openapi.json` | Inspect the running server and its embedded contract. |
| Realms | `/v1/realms`, `/v1/realms/{id}` | Create, list, inspect, and delete realms. |
| Apps | `/v1/realms/{realm_id}/apps` | Manage apps within a realm. |
| API keys | `/v1/realms/{realm_id}/apps/{app_id}/api-keys` | Create, list, inspect, and delete customer API keys. |
| Verification | `/v1/verify-key` | Verify a customer API key. |

## Authentication

Metadata endpoints are public. Other endpoints use the `systemKey` bearer
security scheme unless the operation explicitly overrides it.

## Contract URLs

- [`/openapi.yaml`](/openapi.yaml) is the static contract published with this site.
- `/meta/openapi.json` is the contract embedded in a running Enzo server.

Use the static YAML for code generation and documentation tooling. Use the
runtime JSON endpoint when you need to inspect the exact server you are calling.