Skip to main content
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

MethodPathPurpose
POST/engines/provisionCreate a new engine for a user.
DELETE/engines/{user_id}Destroy a user’s engine.
POST/engines/{user_id}/startStart a stopped or sleeping engine.
POST/engines/{user_id}/stopStop a running engine.
POST/engines/{user_id}/rotate-keyRotate the engine’s API key.
Reference →

​
Discovery and admission

MethodPathPurpose
GET/engines/{user_id}Get engine info.
POST/engines/{user_id}/admitPrimary entry point. Auto-provisions, auto-wakes.
Reference →

​
Fleet operations

MethodPathPurpose
GET/enginesList all engines for a product.
GET/statusFleet health snapshot.
GET/metricsOperational metrics over the last hour.
Reference →

​
Admin (requires X-Admin-Key)

MethodPathPurpose
POST/products/registerRegister a new product.
PUT/products/{product_id}/policyUpdate a product’s policy.
Reference →

​
Health

MethodPathPurpose
GET/healthOrchestrator liveness check. No auth required.
Reference →

​
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.