Automations
Automations endpoints of the Ellipsis REST API.
| Method | Path | Required permissions |
|---|---|---|
| POST | /v1/automations | write:configs |
- API key
- Supported.
- CLI user token
- Supported.
- Sandbox token
- Unavailable. Not supported by sandbox tokens, even with permissions.ellipsis enabled.
Higher permission levels include lower levels: read < write < delete.
Grant match patterns can further restrict access to individual resources.
It is live immediately.
curl -X POST "https://api.ellipsis.dev/v1/automations" \
-H "Authorization: Bearer $ELLIPSIS_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"automation": {
"ellipsis": {
"name": "check-tests",
"version": "v1",
"enabled": true,
"metadata": {
"labels": [],
"annotations": {}
}
},
"session": {
"harness": {
"type": "claude_code"
},
"instructions": "Run the tests and report failures.",
"environment": "api-environment",
"budget": {
"session": 3
},
"permissions": {
"github": {},
"ellipsis": true
},
"skills": []
}
}
}'import os
from ellipsis import Ellipsis
from ellipsis import models
client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
request = models.CreateAutomationRequest.model_validate(
{
"automation": {
"ellipsis": {
"name": "check-tests",
"version": "v1",
"enabled": True,
"metadata": {
"labels": [],
"annotations": {}
}
},
"session": {
"harness": {
"type": "claude_code"
},
"instructions": "Run the tests and report failures.",
"environment": "api-environment",
"budget": {
"session": 3
},
"permissions": {
"github": {},
"ellipsis": True
},
"skills": []
}
}
}
)
result = client.automations.create(request.automation)
print(result)import { Ellipsis } from '@ellipsis-dev/sdk';
const client = new Ellipsis({
apiKey: process.env.ELLIPSIS_API_TOKEN!,
});
const request: Parameters<typeof client.automations.create>[0] = {
"automation": {
"ellipsis": {
"name": "check-tests",
"version": "v1",
"enabled": true,
"metadata": {
"labels": [],
"annotations": {}
}
},
"session": {
"harness": {
"type": "claude_code"
},
"instructions": "Run the tests and report failures.",
"environment": "api-environment",
"budget": {
"session": 3
},
"permissions": {
"github": {},
"ellipsis": true
},
"skills": []
}
}
};
const result = await client.automations.create(request);
console.log(result);Request
Body parameters
The automation's definition, in the same schema as a YAML file under .ellipsis/.
Response
| Method | Path | Required permissions |
|---|---|---|
| GET | /v1/automations | read:configs |
- API key
- Supported.
- CLI user token
- Supported.
- Sandbox token
- Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
Higher permission levels include lower levels: read < write < delete.
Grant match patterns can further restrict access to individual resources.
curl "https://api.ellipsis.dev/v1/automations" \
-H "Authorization: Bearer $ELLIPSIS_API_TOKEN"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 | Required permissions |
|---|---|---|
| GET | /v1/automations/{automation_id} | read:configs |
- API key
- Supported.
- CLI user token
- Supported.
- Sandbox token
- Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
Higher permission levels include lower levels: read < write < delete.
Grant match patterns can further restrict access to individual resources.
Path parameters
curl "https://api.ellipsis.dev/v1/automations/{automation_id}" \
-H "Authorization: Bearer $ELLIPSIS_API_TOKEN"import os
from ellipsis import Ellipsis
client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
result = client.automations.get("check-tests")
print(result)import { Ellipsis } from '@ellipsis-dev/sdk';
const client = new Ellipsis({
apiKey: process.env.ELLIPSIS_API_TOKEN!,
});
const result = await client.automations.get("check-tests");
console.log(result);Request
Response
| Method | Path | Required permissions |
|---|---|---|
| PUT | /v1/automations/{automation_id} | write:configs |
- API key
- Supported.
- CLI user token
- Supported.
- Sandbox token
- Unavailable. Not supported by sandbox tokens, even with permissions.ellipsis enabled.
Higher permission levels include lower levels: read < write < delete.
Grant match patterns can further restrict access to individual resources.
Edit git-managed definitions in their repository or unlink them first.
Path parameters
curl -X PUT "https://api.ellipsis.dev/v1/automations/{automation_id}" \
-H "Authorization: Bearer $ELLIPSIS_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"automation": {
"ellipsis": {
"name": "check-tests",
"version": "v1",
"enabled": true,
"metadata": {
"labels": [],
"annotations": {}
}
},
"session": {
"harness": {
"type": "claude_code"
},
"instructions": "Run the tests and report failures.",
"environment": "api-environment",
"budget": {
"session": 3
},
"permissions": {
"github": {},
"ellipsis": true
},
"skills": []
}
}
}'import os
from ellipsis import Ellipsis
from ellipsis import models
client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
request = models.UpdateAutomationRequest.model_validate(
{
"automation": {
"ellipsis": {
"name": "check-tests",
"version": "v1",
"enabled": True,
"metadata": {
"labels": [],
"annotations": {}
}
},
"session": {
"harness": {
"type": "claude_code"
},
"instructions": "Run the tests and report failures.",
"environment": "api-environment",
"budget": {
"session": 3
},
"permissions": {
"github": {},
"ellipsis": True
},
"skills": []
}
}
}
)
result = client.automations.update("check-tests", request.automation)
print(result)import { Ellipsis } from '@ellipsis-dev/sdk';
const client = new Ellipsis({
apiKey: process.env.ELLIPSIS_API_TOKEN!,
});
const request: Parameters<typeof client.automations.update>[1] = {
"automation": {
"ellipsis": {
"name": "check-tests",
"version": "v1",
"enabled": true,
"metadata": {
"labels": [],
"annotations": {}
}
},
"session": {
"harness": {
"type": "claude_code"
},
"instructions": "Run the tests and report failures.",
"environment": "api-environment",
"budget": {
"session": 3
},
"permissions": {
"github": {},
"ellipsis": true
},
"skills": []
}
}
};
const result = await client.automations.update("check-tests", request);
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 | Required permissions |
|---|---|---|
| DELETE | /v1/automations/{automation_id} | write:configs |
- API key
- Supported.
- CLI user token
- Supported.
- Sandbox token
- Unavailable. Not supported by sandbox tokens, even with permissions.ellipsis enabled.
Higher permission levels include lower levels: read < write < delete.
Grant match patterns can further restrict access to individual resources.
Existing session history remains available.
Path parameters
curl -X DELETE "https://api.ellipsis.dev/v1/automations/{automation_id}" \
-H "Authorization: Bearer $ELLIPSIS_API_TOKEN"import os
from ellipsis import Ellipsis
client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
result = client.automations.delete("check-tests")
print(result)import { Ellipsis } from '@ellipsis-dev/sdk';
const client = new Ellipsis({
apiKey: process.env.ELLIPSIS_API_TOKEN!,
});
const result = await client.automations.delete("check-tests");
console.log(result);Request
Response
| Method | Path | Required permissions |
|---|---|---|
| POST | /v1/automations/{automation_id}/link | write:configs |
- API key
- Supported.
- CLI user token
- Supported.
- Sandbox token
- Unavailable. Not supported by sandbox tokens, even with permissions.ellipsis enabled.
Higher permission levels include lower levels: read < write < delete.
Grant match patterns can further restrict access to individual resources.
Git takes ownership when that pull request merges and syncs.
Path parameters
curl -X POST "https://api.ellipsis.dev/v1/automations/{automation_id}/link" \
-H "Authorization: Bearer $ELLIPSIS_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"repository": "api-repo"
}'import os
from ellipsis import Ellipsis
from ellipsis import models
client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
request = models.LinkAutomationRequest.model_validate(
{
"repository": "api-repo"
}
)
result = client.automations.link("check-tests", request.repository)
print(result)import { Ellipsis } from '@ellipsis-dev/sdk';
const client = new Ellipsis({
apiKey: process.env.ELLIPSIS_API_TOKEN!,
});
const request: Parameters<typeof client.automations.link>[1] = {
"repository": "api-repo"
};
const result = await client.automations.link("check-tests", request);
console.log(result);Request
Body parameters
File path within the repo. Omit for the default .ellipsis/automations/<slug>.yaml; if set it must be a location the sync scans (a .yaml/.yml file under .ellipsis/ at any depth; in the repository named .ellipsis the repo root is that directory).
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 | Required permissions |
|---|---|---|
| GET | /v1/automations/{automation_id}/metrics | read:configs |
- API key
- Supported.
- CLI user token
- Supported.
- Sandbox token
- Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
Higher permission levels include lower levels: read < write < delete.
Grant match patterns can further restrict access to individual resources.
Path parameters
curl "https://api.ellipsis.dev/v1/automations/{automation_id}/metrics" \
-H "Authorization: Bearer $ELLIPSIS_API_TOKEN"import os
from ellipsis import Ellipsis
client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
result = client.automations.metrics("check-tests")
print(result)import { Ellipsis } from '@ellipsis-dev/sdk';
const client = new Ellipsis({
apiKey: process.env.ELLIPSIS_API_TOKEN!,
});
const result = await client.automations.metrics("check-tests");
console.log(result);Request
Response
| Method | Path | Required permissions |
|---|---|---|
| POST | /v1/automations/{automation_id}/sessions | write:sessions |
- API key
- Supported.
- CLI user token
- Supported.
- Sandbox token
- Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.
Higher permission levels include lower levels: read < write < delete.
Grant match patterns can further restrict access to individual resources.
Supply input when it declares an input schema; otherwise supply prompt. Send exactly one.
Path parameters
curl -X POST \
"https://api.ellipsis.dev/v1/automations/{automation_id}/sessions" \
-H "Authorization: Bearer $ELLIPSIS_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Run the tests."
}'import os
from ellipsis import Ellipsis
from ellipsis import models
client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
request = models.StartAutomationSessionRequest.model_validate(
{
"prompt": "Run the tests."
}
)
result = client.automations.run("check-tests", prompt=request.prompt)
print(result)import { Ellipsis } from '@ellipsis-dev/sdk';
const client = new Ellipsis({
apiKey: process.env.ELLIPSIS_API_TOKEN!,
});
const request: Parameters<typeof client.automations.run>[1] = {
"prompt": "Run the tests."
};
const result = await client.automations.run("check-tests", request);
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. Required when the automation declares a schema; rejected when it does not. Validated against the schema and rendered through input.message, or as formatted JSON if no template is set. The rendered message must be non-empty. Cannot be combined with prompt.
{}objectArbitrary string key/value metadata stored on the session.
The initial user message, passed verbatim to Claude. Required when the automation declares no input.json_schema; rejected when it does. Must contain non-whitespace text and cannot be combined with input.
Response
| Method | Path | Required permissions |
|---|---|---|
| POST | /v1/automations/{automation_id}/unlink | write:configs |
- API key
- Supported.
- CLI user token
- Supported.
- Sandbox token
- Unavailable. Not supported by sandbox tokens, even with permissions.ellipsis enabled.
Higher permission levels include lower levels: read < write < delete.
Grant match patterns can further restrict access to individual resources.
Its repository file stops controlling the definition.
Path parameters
curl -X POST "https://api.ellipsis.dev/v1/automations/{automation_id}/unlink" \
-H "Authorization: Bearer $ELLIPSIS_API_TOKEN"import os
from ellipsis import Ellipsis
client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
result = client.automations.unlink("check-tests")
print(result)import { Ellipsis } from '@ellipsis-dev/sdk';
const client = new Ellipsis({
apiKey: process.env.ELLIPSIS_API_TOKEN!,
});
const result = await client.automations.unlink("check-tests");
console.log(result);