API overview
Start sessions, run automations, and integrate reviews with the Ellipsis API.
The base URL is https://api.ellipsis.dev/v1. Authenticate with a bearer token from the dashboard's API page.
Start a session
curl https://api.ellipsis.dev/v1/sessions \
-H "Authorization: Bearer $ELLIPSIS_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"harness": {"type": "claude_code"},
"prompt": "Run the tests and report failures.",
"environment": "api-environment",
"interactive": false,
"budget": 3
}'The response contains session.id. Creation returns before the task finishes.
Choose a resource
| Resource | Operations |
|---|---|
| Sessions | Start tasks, send messages, inspect changes and results |
| Automations | Manage saved definitions and invoke them |
| Environments | Manage reusable sandbox configuration |
| Secrets | Store credentials referenced by environments |
| Reviews | Run and inspect pull request reviews |
| Account | Read model support, budget, and usage |
| Integrations | Read connected integrations and available repositories |
The reference covers supported integration workflows. The OpenAPI document also contains endpoints used by the dashboard.
SDKs
The Python SDK and TypeScript SDK provide session handles, streaming, pagination, and typed errors.
Errors and retries
Errors use {"error":{"code":"...","message":"..."}}. Branch on code; message text can change.
| Status | Action |
|---|---|
400, 422 | Correct the request or unsupported configuration |
401, 403 | Check the credential and its permissions |
404 | Check the resource ID and account |
409 | Resolve a conflict, such as a git-managed definition |
429 | Respect Retry-After |
5xx | Retry with backoff |
Do not blindly retry session creation after an ambiguous timeout; it can create another session. Tag requests with metadata and check existing sessions when needed. Message sends support an idempotency_key.
Pagination
Paginated endpoints accept limit and cursor. Pass the returned next_cursor until has_more is false. SDK iterators fetch subsequent pages automatically.