X-Platform-Key. They translate directly to transitions in the
lifecycle state machine.
POST /engines/provision
Create a new engine for a user.Request
Response (200)
api_key is returned once. Save it.
Errors
409 ENGINE_ALREADY_EXISTS— there’s already an engine for this user_id. Use/admitif you want idempotent behavior.429 QUOTA_EXCEEDED— product atmax_enginescap.503 PORT_EXHAUSTION— no free port in the allocator range.504 BOOT_TIMEOUT— engine didn’t become healthy withinORCH_BOOT_TIMEOUT_S.
DELETE /engines/
Destroy a user’s engine. Removes the container, the brain volume, the port allocation, and the registry row.Request
Response (200)
Errors
404 ENGINE_NOT_FOUND— no engine for this user_id.
POST /engines//start
Start a stopped or sleeping engine.Request
Response (200)
Errors
404 ENGINE_NOT_FOUND— no engine for this user_id.409 ENGINE_ALREADY_RUNNING— engine is already running. No-op.
POST /engines//stop
Stop a running engine. The container is stopped (SIGTERM, 30s grace, then SIGKILL). Brain volume preserved.Request
Response (200)
Errors
404 ENGINE_NOT_FOUND— no engine for this user_id.409 ENGINE_NOT_RUNNING— engine isn’t currently running.
POST /engines//rotate-key
Generate a new engine API key, swap it on the engine, return the new plaintext.Request
Response (200)
Errors
404 ENGINE_NOT_FOUND— no engine for this user_id.409 ENGINE_NOT_RUNNING— can’t rotate a non-running engine.
See also
- Lifecycle — the state machine these endpoints drive.
- Discovery endpoints —
/admitfor idempotent provision. - Errors — full error catalog.