HTTP API

The hosted API is available at https://assemble-vms-api.fly.dev with an operator-issued product key. The OpenAPI reference also includes http://localhost:8787 for local development. Use the Fly address for hosted requests; docs.assemble.ai serves documentation. SDK packages remain unpublished.

Use the API to open sessions, work with files, run commands, issue SSH access, and call the provided harness. The public API has no automatic VM-replacement endpoint.

Authentication

Send your product API key in the Authorization header:

Authorization: Bearer YOUR_ASSEMBLE_API_KEY

The key identifies the owner whose sessions you can access. All active keys for the same owner share access to that owner's sessions; resource IDs alone do not grant access. Contact the Assemble team for a test key or to rotate or revoke an existing key. Self-service key creation is not yet available.

Health and readiness

GET /healthz and GET /readyz require no API key. Liveness returns 200 {"status":"ok"} when the process responds. Readiness returns 200 {"status":"ready"} when its database probe succeeds and the service accepts work, or 503 {"status":"unavailable"} when the probe fails, exceeds two seconds, or shutdown is draining requests. Neither endpoint verifies VM or session-storage availability.

While draining, new business requests receive 503 with error code service_draining and Retry-After: 5. An accepted operation may still be finishing; use its known ID to inspect its state before retrying an operation that could create resources.

JSON and file bytes

JSON requests use Content-Type: application/json. File writes send raw bytes with Content-Type: application/octet-stream; file reads return bytes. File paths are relative to /workspace, or absolute within that directory.

The file API and VM processes share one writable session filesystem. Version 1 has no automatic per-command file rollback. A completed command or successful readback alone does not prove that dirty writes reached durable storage; see Persistence.

The service returns an X-Request-Id response header. Errors have this shape:

{
  "error": {
    "code": "session_not_running",
    "message": "Resume the session before starting an execution.",
    "requestId": "REQUEST_ID"
  }
}

Streams

Execution and agent streams use application/x-ndjson: one JSON record followed by a newline. They are not SSE streams.

Execution events have increasing sequence values and can be replayed with ?after=LAST_SEQUENCE. Agent events are live for one request and have no replay cursor. The SDK handles parsing and detects a stream that ends without completion.

An accepted command continues independently of its reader. Explicitly cancel it when you want it to stop. An agent-stream disconnect requests cancellation of that agent's work.

Bounds

The service also enforces owner quotas and one active managed command per session. A provided-agent request reserves the session for its whole conversation. SSH processes can operate outside this coordination. See Lifecycle and Troubleshooting.