Start runs from CI and scripts

Triggers cover schedules, events, and mentions; everything else starts a run explicitly. The CLI and the REST API drive the same /v1 surface, so anything shown here works from a laptop, a CI job, or your own service.

Authenticate non-interactive environments with an API key (created under Platform → API keys in the dashboard) exported as ELLIPSIS_API_TOKEN. The CLI and your own curl calls both read it.

Start a run

From a saved agent, by config id:

agent run start --config agent_x9Kd3Fq2 --watch

The same over HTTP:

curl https://api.ellipsis.dev/v1/agents/runs \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"config_id": "agent_x9Kd3Fq2", "metadata": {"trigger": "post-deploy"}}'

The response is the created run, including its id (a runs_... identifier) and status. Runs started this way record source: api (or cli), so they are distinguishable from cron and event runs in history.

Steer a single run

Two per-run knobs need no config edit:

prompt appends run-specific instructions after the config's system prompt.
config_override_yaml merges a partial config onto the saved one and re-validates it. Raising one run's budget:

curl https://api.ellipsis.dev/v1/agents/runs \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "config_id": "agent_x9Kd3Fq2",
    "prompt": "Focus on the trade-expiry changes merged this week.",
    "config_override_yaml": "limits:\n  run: 5.0"
  }'

Watch and fetch results

agent run get runs_7Hq2mX4p --watch     # follow until it finishes
agent run list --source api --days 7    # recent API-started runs

Over HTTP, GET /v1/agents/runs/{run_id} returns the run with its status, output, and cost; the WebSocket at /v1/runs/{run_id}/stream streams live output and supports resuming with ?after_seq=. See the REST API for frame formats.

Replay a run

Re-run a finished run, optionally with changes. Useful when a run hit its budget and you want a second attempt with more room:

curl https://api.ellipsis.dev/v1/agents/runs/runs_7Hq2mX4p/replay \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{"config_override_yaml": "limits:\n  run: 10.0"}'

By default a replay reuses the original run's config snapshot, so it reproduces the run as it was, not as the config is now.

In CI

Store the API key as a CI secret exported as ELLIPSIS_API_TOKEN and run the same curl (or the CLI) as a pipeline step, e.g. starting a post-deploy audit agent with the deploy SHA in metadata. Runs record who started them, so CI-started runs stay attributable in history.

Everything the API exposes: REST API. Every CLI command: CLI.