Discovery and admission endpoints

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:

Rate limit check (policy.check_admit).
Lookup in the registry.
Auto-provision if no engine and auto_provision=true.
Auto-wake if engine is sleeping and auto_wake=true.
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
}

Field	Type	Required	Default	Purpose
`auto_provision`	bool	no	`false`	If no engine exists, provision one (subject to quota).
`auto_wake`	bool	no	`false`	If 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

Reason	Cause	What to do
`engine_not_found`	No engine and `auto_provision=false`.	Call `/provision` explicitly.
`engine_sleeping`	Engine is sleeping and `auto_wake=false`.	Call `/start` explicitly.
`engine_unhealthy`	Engine 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 to	Use
Get engine info for a known-existing user	`GET /engines/{user_id}`
Process a user request, possibly auto-provisioning	`POST /admit` with `auto_provision=true, auto_wake=true`
Provision deliberately at signup time	`POST /engines/provision` directly

/admit is idempotent and safe to call on every user request. It handles the rate-limit and quota concerns for you.

Architecture

BAP Engine

Engineering

Discovery and admission endpoints

GET /engines/

Request

Response (200)

Errors

POST /engines//admit

Request

Response (200)

When admitted is false

Errors

When to use which

See also

​GET /engines/

​Request

​Response (200)

​Errors

​POST /engines//admit

​Request

​Response (200)

​When admitted is false

​Errors

​When to use which

​See also

GET /engines/

Request

Response (200)

Errors

POST /engines//admit

Request

Response (200)

When admitted is false

Errors

When to use which

See also