Skip to main content
Two endpoints. Both require X-Platform-Key. /admit is the primary entry point for products — it’s the one you call on every user request.

​
GET /engines/

Look up the engine for a user. Read-only. Doesn’t trigger provisioning.

​
Request

GET /engines/demo-user-001
X-Platform-Key: pk-sept-...

​
Response (200)

{
  "engine_id": "5c2f...",
  "user_id": "demo-user-001",
  "status": "running",
  "url": "http://engine-...:8000",
  "api_key": "sk-sept-...",
  "engine_version": "september-engine:2.3.0",
  "created_at": "2026-04-27T12:34:56.000Z",
  "last_health_at": "2026-04-27T12:35:11.000Z"
}
If the engine is stopped or sleeping, the URL may still be set (the container is just paused). Check status.

​
Errors

  • 404 ENGINE_NOT_FOUND — no engine for this user_id.

​
POST /engines//admit

The product’s main call. Goes through:
  1. Rate limit check (policy.check_admit).
  2. Lookup in the registry.
  3. Auto-provision if no engine and auto_provision=true.
  4. Auto-wake if engine is sleeping and auto_wake=true.
  5. Return the engine’s URL + key, or denial.

​
Request

POST /engines/demo-user-001/admit
X-Platform-Key: pk-sept-...
Content-Type: application/json

{
  "auto_provision": true,
  "auto_wake": true
}
FieldTypeRequiredDefaultPurpose
auto_provisionboolnofalseIf no engine exists, provision one (subject to quota).
auto_wakeboolnofalseIf engine is sleeping, wake it.

​
Response (200)

Admitted: 
{
  "admitted": true,
  "engine": {
    "engine_id": "5c2f...",
    "user_id": "demo-user-001",
    "status": "running",
    "url": "http://engine-...:8000",
    "api_key": "sk-sept-...",
    "engine_version": "september-engine:2.3.0",
    "created_at": "2026-04-27T12:34:56.000Z",
    "last_health_at": "2026-04-27T12:35:11.000Z"
  }
}
Not admitted: 
{
  "admitted": false,
  "engine": null,
  "reason": "engine_unhealthy" | "engine_not_found" | "engine_sleeping"
}

​
When admitted is false

ReasonCauseWhat to do
engine_not_foundNo engine and auto_provision=false.Call /provision explicitly.
engine_sleepingEngine is sleeping and auto_wake=false.Call /start explicitly.
engine_unhealthyEngine is failed and not auto-restarting.Investigate via the audit log.

​
Errors

  • 429 RATE_LIMITED — product over rate_limit_rpm.
  • 429 QUOTA_EXCEEDED — product at max_engines (only when auto_provision=true and a provision was attempted).
  • 503 PORT_EXHAUSTION — port allocator empty.
  • 504 BOOT_TIMEOUT — auto-provisioned engine didn’t become healthy.

​
When to use which

You want toUse
Get engine info for a known-existing userGET /engines/{user_id}
Process a user request, possibly auto-provisioningPOST /admit with auto_provision=true, auto_wake=true
Provision deliberately at signup timePOST /engines/provision directly
/admit is idempotent and safe to call on every user request. It handles the rate-limit and quota concerns for you.

​
See also