Skip to main content

Documentation Index

Fetch the complete documentation index at: https://septemberai.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

Five endpoints drive the engine state machine. All require X-Platform-Key. They translate directly to transitions in the lifecycle state machine.

​
POST /engines/provision

Create a new engine for a user.

​
Request

POST /engines/provision
X-Platform-Key: pk-sept-...
Content-Type: application/json

{
  "user_id": "demo-user-001",
  "engine_version": "september-engine:2.3.0"
}
FieldTypeRequiredDefaultPurpose
user_idstringyes—Per-product unique user identifier.
engine_versionstringnoORCH_ENGINE_IMAGEOverride the default engine image (e.g. for testing a new version).

​
Response (200)

{
  "engine_id": "5c2f...",
  "user_id": "demo-user-001",
  "status": "running",
  "url": "http://engine-...:8000",
  "api_key": "sk-sept-..."
}
The plaintext api_key is returned once. Save it.

​
Errors

  • 409 ENGINE_ALREADY_EXISTS — there’s already an engine for this user_id. Use /admit if you want idempotent behavior.
  • 429 QUOTA_EXCEEDED — product at max_engines cap.
  • 503 PORT_EXHAUSTION — no free port in the allocator range.
  • 504 BOOT_TIMEOUT — engine didn’t become healthy within ORCH_BOOT_TIMEOUT_S.

​
DELETE /engines/

Destroy a user’s engine. Removes the container, the brain volume, the port allocation, and the registry row.

​
Request

DELETE /engines/demo-user-001
X-Platform-Key: pk-sept-...
No body.

​
Response (200)

{
  "status": "destroyed",
  "engine_id": "5c2f..."
}

​
Errors

  • 404 ENGINE_NOT_FOUND — no engine for this user_id.
The destroy is irreversible. Brain data is gone. Take a backup first if you need it.

​
POST /engines//start

Start a stopped or sleeping engine.

​
Request

POST /engines/demo-user-001/start
X-Platform-Key: pk-sept-...
No body.

​
Response (200)

{
  "status": "running",
  "url": "http://engine-...:8000"
}

​
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

POST /engines/demo-user-001/stop
X-Platform-Key: pk-sept-...
No body.

​
Response (200)

{
  "status": "stopped"
}

​
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

POST /engines/demo-user-001/rotate-key
X-Platform-Key: pk-sept-...
No body.

​
Response (200)

{
  "new_api_key": "sk-sept-..."
}
The old key is invalid immediately. Update your product’s cached key.

​
Errors

  • 404 ENGINE_NOT_FOUND — no engine for this user_id.
  • 409 ENGINE_NOT_RUNNING — can’t rotate a non-running engine.

​
See also