How to trigger agents from your own scripts and CI

Triggers cover schedules, events, and mentions. The rest of the time the thing that knows an agent should run is your own code: a CI job that just went red, a deploy script, an internal tool. Those need to start a session directly and read the result.

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 records endpoint:

curl -s https://api.ellipsis.dev/v1/sessions/session_7Hq2mX4p/records \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN" |
  jq '[.records[] | select(.record_type == "assistant") | .payload.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.