Spawn an agent session from the API and CLI

Triggers cover schedules, events, and mentions; everything else starts a session 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 session

From a saved agent, by config id:

agent session start --config agent_x9Kd3Fq2 --watch

The same over HTTP:

curl https://api.ellipsis.dev/v1/sessions \
  -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 session, including its id (a session_... identifier) and status. Sessions started this way record source: api (or cli), so they are distinguishable from cron and event sessions in history.

Steer a single session

Two per-session knobs need no config edit:

• prompt appends session-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 session's budget:

curl https://api.ellipsis.dev/v1/sessions \
  -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": "budget:\n  session: 5.0"
  }'

Watch and fetch results

agent session get session_7Hq2mX4p --watch     # follow until it finishes
agent session list --source api --days 7       # recent API-started sessions

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

Stop a session

Stop an in-flight session early:

agent session stop session_7Hq2mX4p

The same over HTTP:

curl https://api.ellipsis.dev/v1/sessions/session_7Hq2mX4p/stop \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN" \
  -X POST

The session's status becomes stopped.

Replay a session

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

curl https://api.ellipsis.dev/v1/sessions/session_7Hq2mX4p/replay \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{"config_override_yaml": "budget:\n  session: 10.0"}'

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

Get structured output

When a script consumes a session's result, free-text summaries are the wrong interface. Declare structured_output on the config and the session must exit through a submission matching your JSON schema:

structured_output:
  json_schema:
    type: object
    properties:
      unfilled_shifts:
        type: integer
      needs_attention:
        type: boolean
    required: [unfilled_shifts, needs_attention]

The agent cannot finish with prose: its exit is a StructuredOutput tool call validated against the schema, retried on validation failure, and a session that never produces a valid submission ends with exit status tool_call_failed instead of silently returning junk.

The submission is recorded as the session's last StructuredOutput tool call. Read it from the steps endpoint:

curl -s https://api.ellipsis.dev/v1/sessions/session_7Hq2mX4p/steps \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN" |
  jq '[.steps[] | select(.step_type == "assistant") | .data.message.content[]?
      | select(.name? == "StructuredOutput")] | last.input'

{
  "unfilled_shifts": 4,
  "needs_attention": true
}

A custom schema replaces the standard exit flow, so it belongs on API, CLI, cron, and react agents. Do not combine it with a mention trigger: a mention session's reply is built from the standard output, so a custom schema means no response is posted back to the thread.

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. Sessions record who started them, so CI-started sessions stay attributable in history.

Next

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