API reference - Docs

bap-engine exposes a single HTTP API on :8000. Every endpoint except /health requires authentication via X-Platform-Key. Admin endpoints additionally require X-Admin-Key.

Conventions

Base URL — your deployment’s URL. No version prefix.
Auth header — X-Platform-Key: <key> on every product call. X-Admin-Key: <key> on admin calls.
Content type — application/json for request bodies.
Errors — non-2xx responses include {"error": {"code": "...", "message": "..."}}. See Errors.

Endpoints by category

Engine lifecycle

Method	Path	Purpose
`POST`	`/engines/provision`	Create a new engine for a user.
`DELETE`	`/engines/{user_id}`	Destroy a user’s engine.
`POST`	`/engines/{user_id}/start`	Start a stopped or sleeping engine.
`POST`	`/engines/{user_id}/stop`	Stop a running engine.
`POST`	`/engines/{user_id}/rotate-key`	Rotate the engine’s API key.

Discovery and admission

Method	Path	Purpose
`GET`	`/engines/{user_id}`	Get engine info.
`POST`	`/engines/{user_id}/admit`	Primary entry point. Auto-provisions, auto-wakes.

Fleet operations

Method	Path	Purpose
`GET`	`/engines`	List all engines for a product.
`GET`	`/status`	Fleet health snapshot.
`GET`	`/metrics`	Operational metrics over the last hour.

Admin (requires `X-Admin-Key`)

Method	Path	Purpose
`POST`	`/products/register`	Register a new product.
`PUT`	`/products/{product_id}/policy`	Update a product’s policy.

Health

Method	Path	Purpose
`GET`	`/health`	Orchestrator liveness check. No auth required.

See also

Auth — X-Platform-Key and X-Admin-Key flows.
Errors — every error code and what it means.
Engine contract — what the orchestrator promises engines and vice versa.