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. Endpoints are available at the root path.

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/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 /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.

• Sessions: start agent sessions, search and read everything they leave behind, and stop or replay them.
• Reviews: start a code review of a pull request and list every review with its outcome.
• Agents: your saved agent configs, the defaults that pick one per repository, and the templates new agents start from.
• Sandbox secrets, files, alerts, and analytics.
• Integrations discovery and the platform surface: identity, budget, usage, and models.
• Webhooks: subscribe your own endpoint to Ellipsis events and verify the payloads it receives.
• Guides: end-to-end problems solved over the API, starting with triggering agents from your own scripts and CI.