API reference

The Ellipsis REST API lets you start agent runs, read run history, stream live output, and inspect your agent configs and usage from your own scripts and services. It is the same /v1 surface the Ellipsis CLI uses.

The base URL is https://api.ellipsis.dev. Every endpoint returns JSON.

Get an API key

Create an API key under Platform → API keys in the Ellipsis dashboard. The secret is shown only once, so copy it when you create it.

There are two kinds of credential:

• API keys authenticate scripts and automations against the public API as your organization. Use these for CI pipelines, deploy hooks, and backend services.
• User tokens authenticate the Ellipsis CLI as you. The CLI mints one for you through agent login, so you rarely create these by hand.

Store the key in an environment variable rather than committing it:

export ELLIPSIS_API_KEY="ellipsis_key_..."

Authentication

Authenticate with your API key sent as a bearer token:

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

A request without a valid Authorization: Bearer header is rejected with 401.

Endpoints

Start an agent run

POST /v1/agents/runs starts a run from an existing config or from an inline config. Pass config_id to run a saved agent, or config to run an inline agent config.

curl https://api.ellipsis.dev/v1/agents/runs \
  -H "Authorization: Bearer $ELLIPSIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "config_id": "cfg_123",
    "metadata": {"trigger": "nightly-batch"}
  }'

Pass exactly one of config_id or config. The response is the created agent run, including its id and status.

List agent runs

GET /v1/agents/runs returns recent runs, newest first. All query parameters are optional.

curl "https://api.ellipsis.dev/v1/agents/runs?config_id=cfg_123&limit=20" \
  -H "Authorization: Bearer $ELLIPSIS_API_KEY"

The response is { "runs": [...] }.

Fetch a run

GET /v1/agents/runs/{run_id} returns one run, including its status, cost, tokens, config snapshot, and output.

curl https://api.ellipsis.dev/v1/agents/runs/run_8f2c \
  -H "Authorization: Bearer $ELLIPSIS_API_KEY"

A run's status is one of scheduled, creating_sandbox, running, completed, error, cancelled, or stopped.

Stream a run

GET /v1/runs/{run_id}/stream upgrades to a WebSocket and streams the run's live output. Pass the bearer token in the Authorization header, or as a ?token= query parameter when a header is not available (for example from a browser).

websocat "wss://api.ellipsis.dev/v1/runs/run_8f2c/stream?token=$ELLIPSIS_API_KEY"

Each frame is a JSON object with a type:

To resume after a disconnect without missing or duplicating output, reconnect with ?after_seq=<last_seq>, where <last_seq> is the highest seq you received.

List agent configs

GET /v1/agents/configs returns the account's saved agent configs, including each config's GitHub source, last run, and any pending "store in GitHub" pull request.

curl https://api.ellipsis.dev/v1/agents/configs \
  -H "Authorization: Bearer $ELLIPSIS_API_KEY"

The response is { "configs": [...] }. Fetch one config with GET /v1/agents/configs/{config_id}.

Sandbox variables

Sandbox variables are environment variables, stored once on your account, that an agent can pull into its sandbox at run time. Store a secret or shared config value here, then reference it by name from an agent's sandbox.variables so the secret never lives in your config file. Only the variables an agent names reach that agent's sandbox.

Values are write-only. You upload them, but the API never returns them. Listing a variable shows its name and timestamps, never its value.

GET /v1/sandboxes/variables lists the stored variables, sorted by name.

curl https://api.ellipsis.dev/v1/sandboxes/variables \
  -H "Authorization: Bearer $ELLIPSIS_API_KEY"

The response is { "variables": [...] }, where each entry has a name, created_at, and updated_at.

PUT /v1/sandboxes/variables creates or updates one or more variables in a single request. Each variable is upserted by name: an existing name is overwritten, a new name is created, and variables you do not send are left untouched.

curl https://api.ellipsis.dev/v1/sandboxes/variables \
  -H "Authorization: Bearer $ELLIPSIS_API_KEY" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{
    "variables": [
      {"name": "NPM_TOKEN", "value": "npm_..."},
      {"name": "API_BASE_URL", "value": "https://example.com"}
    ]
  }'

Names are validated before anything is written, so one invalid name rejects the whole request with 400 and stores nothing. An account can hold up to 500 variables; a request that would exceed that is rejected with 400. Both GET and PUT return the full, current variable list.

DELETE /v1/sandboxes/variables/{name} removes one variable by name and returns the remaining list. Deleting a name that does not exist still succeeds.

curl https://api.ellipsis.dev/v1/sandboxes/variables/NPM_TOKEN \
  -H "Authorization: Bearer $ELLIPSIS_API_KEY" \
  -X DELETE

Identity, budget, and usage

GET /v1/me returns the customer, user, and API key behind the current credential. GET /v1/budget returns the account's current spend against its run, daily, weekly, and monthly limits. GET /v1/usage returns the usage dashboard: per-day and per-model token and cost breakdowns for the current period, with a prior-period comparison.

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