Automations
Automations endpoints of the Ellipsis REST API.
| Method | Path |
|---|---|
| POST | /v1/automations |
To put its definition in a repository instead, create it here and then POST /v1/automations/{automation_id}/link. 409 when another live automation already holds the name.
curl -X POST "https://api.ellipsis.dev/v1/automations" \
-H "Authorization: Bearer $ELLIPSIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"automation":"..."}'import os
from ellipsis import Ellipsis
client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
result = client.automations.create("...")
print(result)import { Ellipsis } from '@ellipsis-dev/sdk';
const client = new Ellipsis({
apiKey: process.env.ELLIPSIS_API_TOKEN!,
});
const result = await client.automations.create({ automation: '...' });
console.log(result);Request
Body parameters
The automation's definition, in the same schema as a YAML file under agents/.
Response
| Method | Path |
|---|---|
| GET | /v1/automations |
curl "https://api.ellipsis.dev/v1/automations" \
-H "Authorization: Bearer $ELLIPSIS_API_KEY"import os
from ellipsis import Ellipsis
client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
result = client.automations.list()
print(result)import { Ellipsis } from '@ellipsis-dev/sdk';
const client = new Ellipsis({
apiKey: process.env.ELLIPSIS_API_TOKEN!,
});
const result = await client.automations.list();
console.log(result);Request
Response
| Method | Path |
|---|---|
| GET | /v1/automations/{automation_id} |
Path parameters
curl "https://api.ellipsis.dev/v1/automations/{automation_id}" \
-H "Authorization: Bearer $ELLIPSIS_API_KEY"import os
from ellipsis import Ellipsis
client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
result = client.automations.get("...")
print(result)import { Ellipsis } from '@ellipsis-dev/sdk';
const client = new Ellipsis({
apiKey: process.env.ELLIPSIS_API_TOKEN!,
});
const result = await client.automations.get('...');
console.log(result);Request
Response
| Method | Path |
|---|---|
| PUT | /v1/automations/{automation_id} |
The whole definition is replaced, and the change is live at once. Only for automations managed through this API: one defined by a repository file is a 409, since the next push to that file would revert the change — unlink it first to take ownership.
Path parameters
curl -X PUT "https://api.ellipsis.dev/v1/automations/{automation_id}" \
-H "Authorization: Bearer $ELLIPSIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"automation":"..."}'import os
from ellipsis import Ellipsis
client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
result = client.automations.update("...", "...")
print(result)import { Ellipsis } from '@ellipsis-dev/sdk';
const client = new Ellipsis({
apiKey: process.env.ELLIPSIS_API_TOKEN!,
});
const result = await client.automations.update('...', { automation: '...' });
console.log(result);Request
Body parameters
The automation's new definition. Replaces the previous one wholesale — this is not a partial update.
Response
| Method | Path |
|---|---|
| DELETE | /v1/automations/{automation_id} |
It stops running and its name is freed immediately; its past sessions remain readable. Only for automations managed through this API — delete the file to remove one defined by a repository.
Path parameters
curl -X DELETE "https://api.ellipsis.dev/v1/automations/{automation_id}" \
-H "Authorization: Bearer $ELLIPSIS_API_KEY"import os
from ellipsis import Ellipsis
client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
result = client.automations.delete("...")
print(result)import { Ellipsis } from '@ellipsis-dev/sdk';
const client = new Ellipsis({
apiKey: process.env.ELLIPSIS_API_TOKEN!,
});
const result = await client.automations.delete('...');
console.log(result);Request
Response
| Method | Path |
|---|---|
| POST | /v1/automations/{automation_id}/link |
Opens a pull request adding its definition file. The automation keeps running unchanged meanwhile; merging hands it over to the file, after which the file is what changes it. Nothing happens if the pull request is never merged.
Path parameters
curl -X POST "https://api.ellipsis.dev/v1/automations/{automation_id}/link" \
-H "Authorization: Bearer $ELLIPSIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"repository":"..."}'import os
from ellipsis import Ellipsis
client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
result = client.automations.link("...", "...")
print(result)import { Ellipsis } from '@ellipsis-dev/sdk';
const client = new Ellipsis({
apiKey: process.env.ELLIPSIS_API_TOKEN!,
});
const result = await client.automations.link('...', { repository: '...' });
console.log(result);Request
Body parameters
File path within the repo. Omit for the default agents/<slug>.yaml; if set it must be a location the sync scans (a .yaml/.yml file under agents/, .agents/, ellipsis/, or .ellipsis/ at any depth).
Repository name within the caller's account; the owner is always the account, so pass a bare name (e.g. "my-service"), not "owner/my-service".
Response
| Method | Path |
|---|---|
| GET | /v1/automations/{automation_id}/metrics |
`samples` carries one entry per finished session (duration, cost, tokens) for distributions; `spend_windows` carries what the automation's sessions cost over the last 1, 7, and 28 days against its budget for each window.
Path parameters
curl "https://api.ellipsis.dev/v1/automations/{automation_id}/metrics" \
-H "Authorization: Bearer $ELLIPSIS_API_KEY"import os
from ellipsis import Ellipsis
client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
result = client.automations.metrics("...")
print(result)import { Ellipsis } from '@ellipsis-dev/sdk';
const client = new Ellipsis({
apiKey: process.env.ELLIPSIS_API_TOKEN!,
});
const result = await client.automations.metrics('...');
console.log(result);Request
Response
| Method | Path |
|---|---|
| POST | /v1/automations/{automation_id}/sessions |
Runs the automation exactly as defined — its persona, model, environment, permissions, skills, and budget bind — and returns the session it started. The body carries only what a caller may supply: the typed `input` its schema demands, an optional tighter `budget`, and `metadata`. For a different persona or environment, start a raw session with POST /v1/sessions instead.
Path parameters
curl -X POST \
"https://api.ellipsis.dev/v1/automations/{automation_id}/sessions" \
-H "Authorization: Bearer $ELLIPSIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'import os
from ellipsis import Ellipsis
client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
result = client.automations.run("...")
print(result)import { Ellipsis } from '@ellipsis-dev/sdk';
const client = new Ellipsis({
apiKey: process.env.ELLIPSIS_API_TOKEN!,
});
const result = await client.automations.run('...');
console.log(result);Request
Body parameters
Tighten this run's spend cap, in US dollars. May only lower the automation's own session budget; a higher number, or one above the organization's ceiling, is a 400.
The typed payload for an automation that declares input.json_schema: validated against it (422 on mismatch) and rendered into the session's first message through the automation's input.message template. Required when the automation declares a schema; a 422 when it does not.
{}objectArbitrary string key/value metadata stored on the session.
Response
| Method | Path |
|---|---|
| POST | /v1/automations/{automation_id}/unlink |
The file stops governing it immediately and further changes go through this API. The file is left in place, inert — delete it whenever you like.
Path parameters
curl -X POST "https://api.ellipsis.dev/v1/automations/{automation_id}/unlink" \
-H "Authorization: Bearer $ELLIPSIS_API_KEY"import os
from ellipsis import Ellipsis
client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
result = client.automations.unlink("...")
print(result)import { Ellipsis } from '@ellipsis-dev/sdk';
const client = new Ellipsis({
apiKey: process.env.ELLIPSIS_API_TOKEN!,
});
const result = await client.automations.unlink('...');
console.log(result);