Ellipsis API

The Ellipsis REST API starts, searches, and streams agent sessions, runs code reviews, and manages your configs and platform resources from your own scripts and services. It is the same public API the Agent CLI uses. Every endpoint returns JSON.

Base URL and auth

The base URL is https://api.ellipsis.dev. Every endpoint lives under the /v1 prefix.

Create an API key under Platform → API keys in the Ellipsis dashboard. The secret starts with ellipsis_key_ and is shown only once, so copy it when you create it. API keys authenticate scripts and automations as your organization; the CLI instead uses a user token that agent login mints for you, which acts as you personally. Both are sent the same way.

Store the key in an environment variable rather than committing it. ELLIPSIS_API_TOKEN is the name the CLI reads too, so one variable serves both:

export ELLIPSIS_API_TOKEN="ellipsis_key_..."

Send the key as a bearer token on every request. An invalid key is rejected with 401.

Errors

Every error returns one envelope:

{
  "error": {
    "code": "session_finished",
    "message": "Session session_7Hq2mX4p has already finished (completed)."
  }
}

code is the stable contract: switch on it, never on the message text, which may be reworded at any time. The vocabulary is open, so treat an unknown code by its HTTP status. Codes are either specific (session_finished, session_closed, review_in_flight, default_config_broken, file_quota_exceeded, account_blocked) or the status's generic fallback (invalid_request, unauthorized, forbidden, not_found, conflict, rate_limited). Internal server errors add request_id: quote it when contacting support. Each endpoint's reference page lists the statuses it returns.

curl https://api.ellipsis.dev/v1/me \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN"

{
  "customer_id": "cust_8Rn4wY7kQm2v",
  "customer_login": "splitshift-hq",
  "user_id": null,
  "gh_user": null,
  "api_key_id": "tokens_api_9Qz3vT6wLm2r",
  "sandbox_id": null
}

GET /v1/me returns who the credential is: an API key acts as the organization, so user_id and gh_user are null; a user token fills them with the developer behind it.

Endpoint map

The reference documents every endpoint, generated from the same OpenAPI specification the SDKs are built from. The spec itself is published at /openapi.v1.json. Beyond the endpoints below, Webhooks subscribes your own endpoint to Ellipsis events, and the guides solve end-to-end problems over the API.