API Reference¶

The CIAB REST API provides full programmatic control over sandboxes, sessions, files, credentials, and OAuth flows.

Base URL¶

http://localhost:8080

The port is configurable via server.port in config.toml.

Authentication¶

If API keys are configured in security.api_keys, requests must include an Authorization header:

Authorization: Bearer <api-key>

If no API keys are configured, authentication is disabled.

Common Response Format¶

Success¶

Responses return JSON with appropriate HTTP status codes:

• 200 OK — Successful read/update
• 201 Created — Resource created
• 202 Accepted — Async operation started (e.g., sandbox creation)
• 204 No Content — Successful deletion

Errors¶

All errors return JSON with an error object:

{
  "error": {
    "code": "sandbox_not_found",
    "message": "Sandbox with ID 550e8400-... not found"
  }
}

Error Codes¶

Health Endpoints¶

GET /health¶

Returns 200 OK if the server is running.

GET /ready¶

Returns 200 OK if the server is ready to accept requests (database connected, runtime available).

Content Types¶