API reference
This page lists every endpoint an API token can call, with its fields and an example request and response. The examples use https://delegaris.example.com; use your own PUBLIC_URL.
Authentication
Send the token in the Authorization header on every call:
curl -H "Authorization: Bearer dlg_your-token-here" https://delegaris.example.com/api/me
- Bodies are JSON. Send
Content-Type: application/jsonwith them. - Calls made with a token need no CSRF header.
- The token acts as the person who made it, with their access rules, approvals and protected resources applied exactly as in the browser.
Times
Times in responses are UTC, in ISO 8601 with a Z, for example 2026-11-13T21:00:00Z. Times you send should carry Z or an offset (2026-11-13T21:00:00+00:00). A time sent without either is read as UTC.
Errors
Errors come back with an HTTP status and a detail:
{ "detail": "You do not have permission for every member of this group" }
| Status | Meaning |
|---|---|
| 401 | The token is wrong, revoked or expired, or tokens are switched off |
| 403 | The token cannot call this endpoint, or its owner may not do this |
| 404 | Not found, or not visible to the token's owner. Delegaris gives the same answer for both, so the API does not reveal what exists |
| 409 | The request clashes with the current state, for example a group already being started |
| 422 | The body is not valid. For a field that fails validation, detail is a list saying which field and why |
POST /api/actions is different: it answers 200 with a result for each resource, and a resource it could not act on has "ok": false and a message saying why.
Resource references
Several endpoints take resources as references:
| Field | Type | Example |
|---|---|---|
account_id | 12-digit string | "111111111111" |
region | string | "eu-west-2" |
type | string, one of the types below | "ec2" |
id | string | "i-0abc123def4567890" |
type | What it is |
|---|---|
ec2 | EC2 instance |
rds | RDS instance |
rds-cluster | Aurora, DocumentDB or Neptune cluster |
asg | Auto Scaling group |
ecs-service | ECS service |
eks-nodegroup | EKS managed node group |
redshift | Redshift cluster |
sagemaker | SageMaker notebook instance |
lightsail | Lightsail instance |
The easiest way to get a reference is from GET /api/resources: each resource there carries account_id, region, type and id.
GET /api/me
Who the token acts as.
Request
curl -H "Authorization: Bearer dlg_your-token-here" \
https://delegaris.example.com/api/me
Response
{
"username": "jsmith",
"display_name": "Jane Smith",
"email": "jane.smith@corp.example",
"provider": "token:Release pipeline",
"groups": ["AWS-Web-Team", "AWS-Ops-Leads"],
"is_admin": false,
"is_auditor": false,
"csrf_token": ""
}
provider is token: followed by the token's name. groups are those reported at the owner's most recent sign-in.
GET /api/resources
The resources the token's owner can see, with what they may do to each.
Query parameters
| Parameter | Default | Purpose |
|---|---|---|
refresh | false | true asks AWS again now, instead of reusing a list fetched in the last few seconds (INVENTORY_CACHE_SECONDS, default 30) |
Request
curl -H "Authorization: Bearer dlg_your-token-here" \
"https://delegaris.example.com/api/resources?refresh=true"
Response (one resource shown)
{
"resources": [
{
"account_id": "111111111111",
"account_name": "Development",
"region": "eu-west-2",
"type": "ec2",
"id": "i-0abc123def4567890",
"name": "uat-web-1",
"state": "running",
"power": "on",
"tags": { "Name": "uat-web-1", "Schedule": "8-8", "Team": "web" },
"stashed_tags": {},
"details": {
"instance_type": "t3.medium",
"az": "eu-west-2a",
"private_ip": "10.0.1.15",
"platform": "Linux/UNIX"
},
"size": null,
"saved_size": null,
"schedule": {
"on_now": true,
"always": false,
"stops_at": "2026-11-13T20:00:00Z",
"starts_at": "2026-11-16T08:00:00Z"
},
"keep_on": null,
"approval": null,
"bookings": [],
"cost": { "hourly": 0.0472, "saves_weekly": 3.96, "currency": "USD" },
"remote": null,
"permissions": {
"start": true,
"stop": true,
"reboot": false,
"protected": false,
"tag_keys": [],
"keep_on": true,
"approval": ["stop"],
"approval_tag_keys": []
}
}
],
"errors": [],
"incomplete": false,
"account_count": 2,
"fetched_at": "2026-11-13T15:02:11Z",
"labels": [
{
"id": 1,
"tag_key": "Schedule",
"tag_value": "8-8",
"label": "Office hours",
"description": null,
"hours": { "tz": "Europe/London", "periods": [{ "days": [0, 1, 2, 3, 4], "start": "08:00", "stop": "20:00" }] }
}
],
"config": {
"schedule_tag_keys": ["Schedule"],
"schedule_stop_keys": ["Schedule"],
"schedule_tag_roles": { "Schedule": "both" },
"keep_on_max_hours": 24,
"warn_minutes": 15,
"timezone": "Europe/London",
"require_reason": false,
"slack": true
}
}
Fields of each resource
| Field | Meaning |
|---|---|
state | The state as AWS reports it, for example running, stopped, available, paused, pending |
power | on, off, or busy (changing). Start works only from off, stop only from on |
tags | The tags in AWS now |
stashed_tags | Tags dropped through Delegaris and remembered, by key: value, by (who dropped it) and at |
details | What AWS reports that people find useful, such as instance type and addresses. Varies by type |
size, saved_size | For Auto Scaling groups, ECS services and EKS node groups: the size now, and the size a start brings back |
schedule | Where its schedule stands, when the hours behind its schedule tag are known: on_now, always, stops_at, starts_at. Otherwise null |
keep_on | If it is being kept on: until, by, by_name, stop_at_end, tag_keys (the tags taken off), reason, participants, can_end |
approval | A request for approval waiting on it: id, action, by, by_name, created_at, mine, can_decide |
bookings | Keep-ons booked ahead for it: id, summary, by, by_name, reason, next_start, next_end, can_cancel |
cost | A rough on-demand price: hourly, saves_weekly (what its schedule saves a week, if known), currency. null where no price is known |
remote | Whether a Remote Desktop file can be downloaded. null when not |
permissions | What the token's owner may do: start, stop, reboot, keep_on, tag_keys (key patterns they may manage), protected, and approval / approval_tag_keys (which of those need approval first) |
Top-level fields
| Field | Meaning |
|---|---|
errors | Accounts or regions that could not be read. Only administrators see the details |
incomplete | true if anything could not be read, so the list may be missing resources |
labels | Friendly names for tag values, with the hours behind schedule values |
config | The schedule tags, the longest keep-on in hours, the reminder lead time, the time zone, whether a reason is required for a keep-on, and whether Slack is set up |
POST /api/actions
Run one action on up to 100 resources. Each resource is looked up in AWS and checked against the owner's rules at that moment.
Body
| Field | Type | Required | Purpose |
|---|---|---|---|
action | string | yes | One of the actions below |
resources | list of resource references | yes | 1 to 100 |
key | string | for tag actions | The tag key |
value | string | for set_tag | The tag value |
until | time | for keep_on, turn_on | When the resource goes back on its schedule |
stop_at_end | boolean | no, default true | For keep_on and turn_on: whether to stop it at the end. Used only when the schedule's hours are not known; when they are, Delegaris decides |
reason | string, up to 300 characters | no | What it is for. Kept in Activity and Reports. Required for a new keep-on if Settings says so |
Actions
action | Does | In the web UI |
|---|---|---|
start | Starts it | Start |
stop | Stops it | Stop |
reboot | Restarts a running EC2 instance, RDS instance, Redshift cluster or Lightsail instance in place. An ECS service replaces its tasks | Reboot |
keep_on | Takes its schedule tag off until until, then puts it back (and stops it if the schedule would have it off). The resource must carry a schedule tag. Calling it again moves the time | Keep on until… |
turn_on | As keep_on, and starts it first if it is stopped | Turn on until… |
keep_on_finish | Ends a keep-on now: stops it and puts the schedule tag back | Stop it now |
keep_on_cancel | Ends a keep-on now: puts the schedule tag back and leaves it running | Put back on schedule |
drop_tag | Removes tag key and remembers its value | Drop |
restore_tag | Puts the remembered value of key back | Re-add |
set_tag | Sets tag key to value | Set tag |
until must be in the future and no further ahead than the longest keep-on (keep_on_max_hours in config, 24 hours by default).
Request: start two machines
curl -X POST \
-H "Authorization: Bearer dlg_your-token-here" \
-H "Content-Type: application/json" \
-d '{
"action": "start",
"resources": [
{"account_id": "111111111111", "region": "eu-west-2", "type": "ec2", "id": "i-0abc123def4567890"},
{"account_id": "111111111111", "region": "eu-west-2", "type": "rds", "id": "uat-db"}
]
}' \
https://delegaris.example.com/api/actions
Response
{
"results": [
{
"account_id": "111111111111",
"region": "eu-west-2",
"type": "ec2",
"id": "i-0abc123def4567890",
"name": "uat-web-1",
"ok": true,
"message": "Start requested",
"pending": false,
"request_id": null
},
{
"account_id": "111111111111",
"region": "eu-west-2",
"type": "rds",
"id": "uat-db",
"name": "uat-db",
"ok": true,
"message": "Already available",
"pending": false,
"request_id": null
}
]
}
oksays whether it worked (or was already in the state asked for).messagesays what happened, for example "Start requested", "Kept on", "Back on its schedule", or why not, for example "You do not have permission to stop this resource" or "Not found, or you do not have permission for this resource".- "Start requested" means AWS accepted the request. The resource takes a while to change; call
GET /api/resources?refresh=trueto see where it stands. pending: truemeans the action needs approval: nothing was done, and a request was written instead.request_idis the request's number andmessageis "Sent for approval (request #…)". See Approvals.
Request: keep a machine on until 21:00 UTC
curl -X POST \
-H "Authorization: Bearer dlg_your-token-here" \
-H "Content-Type: application/json" \
-d '{
"action": "turn_on",
"until": "2026-11-13T21:00:00Z",
"reason": "Overnight regression run",
"resources": [
{"account_id": "111111111111", "region": "eu-west-2", "type": "ec2", "id": "i-0abc123def4567890"}
]
}' \
https://delegaris.example.com/api/actions
Response
{
"results": [
{
"account_id": "111111111111",
"region": "eu-west-2",
"type": "ec2",
"id": "i-0abc123def4567890",
"name": "uat-web-1",
"ok": true,
"message": "Turned on",
"pending": false,
"request_id": null
}
]
}
Request: drop the Schedule tag
curl -X POST \
-H "Authorization: Bearer dlg_your-token-here" \
-H "Content-Type: application/json" \
-d '{
"action": "drop_tag",
"key": "Schedule",
"resources": [
{"account_id": "111111111111", "region": "eu-west-2", "type": "ec2", "id": "i-0abc123def4567890"}
]
}' \
https://delegaris.example.com/api/actions
The result's message is, for example, "Dropped Schedule (was '8-8')".
GET /api/groups
The server groups the token's owner can see, with what they may do to each.
Request
curl -H "Authorization: Bearer dlg_your-token-here" \
https://delegaris.example.com/api/groups
Response
{
"groups": [
{
"id": 3,
"name": "Development stack",
"description": "Database first, then the web servers",
"steps": [
[
{
"account_id": "111111111111",
"region": "eu-west-2",
"type": "rds",
"id": "dev-db",
"name": "dev-db",
"account_name": "Development",
"state": "stopped",
"power": "off",
"missing": false
}
],
[
{
"account_id": "111111111111",
"region": "eu-west-2",
"type": "ec2",
"id": "i-0def4567890abc123",
"name": "dev-web-1",
"account_name": "Development",
"state": "stopped",
"power": "off",
"missing": false
}
]
],
"total": 2,
"hidden": 0,
"running": 0,
"can": { "start": true, "stop": true, "keep_on": true },
"run": {
"action": "stop",
"status": "done",
"step": 2,
"steps": 2,
"waiting_for": null,
"error": null,
"by": "jsmith",
"started_at": "2026-11-12T19:00:03Z",
"finished_at": "2026-11-12T19:04:41Z"
}
}
]
}
| Field | Meaning |
|---|---|
steps | The members in starting order, one list per step. Members the owner cannot see are left out |
total, hidden | How many members there are, and how many the owner cannot see |
running | How many visible members are running |
can | Whether the owner may start, stop and keep_on the whole group. Each needs that right, held outright, on every member |
run | The latest start or stop: action, status (running, done or failed), the current step of steps, what it is waiting_for, any error, who started it and when. null if it has never run |
POST /api/groups/{id}/start
Starts a group's members in order: step one, then once everything in it is running, step two, and so on.
POST /api/groups/{id}/stop
Stops a group's members in reverse order, from the last step back to the first.
Neither takes a body.
Request
curl -X POST -H "Authorization: Bearer dlg_your-token-here" \
https://delegaris.example.com/api/groups/3/start
Response
{
"run": {
"action": "start",
"status": "running",
"step": 1,
"steps": 2,
"waiting_for": null,
"error": null,
"by": "jsmith",
"started_at": "2026-11-13T07:45:00Z",
"finished_at": null
}
}
The run carries on in the background. Poll GET /api/groups and watch run.status until it is done or failed. A step that has not finished within 20 minutes fails the run, and error says why.
Refusals
| Status | detail |
|---|---|
| 403 | "You do not have permission for every member of this group" |
| 403 | "name is protected: only administrators can start or stop it" |
| 403 | "name needs approval for this, so the group cannot be run as one. Ask for it from the resource list." |
| 409 | "group is already being started or stopped" |
| 409 | "None of this group's members can be found" |
POST /api/groups/{id}/on
Turns the whole group on until a time: every member comes off its schedule now, the members start in order, and each is put back on its schedule (and stopped, if the schedule would have it off) when the time arrives.
Body
| Field | Type | Required | Purpose |
|---|---|---|---|
until | time | yes | When the members go back on their schedules |
stop_at_end | boolean | no, default true | Used only for members whose schedule hours are not known |
reason | string, up to 300 characters | no | What it is for |
Request
curl -X POST \
-H "Authorization: Bearer dlg_your-token-here" \
-H "Content-Type: application/json" \
-d '{"until": "2026-11-13T22:00:00Z", "reason": "Release testing"}' \
https://delegaris.example.com/api/groups/3/on
Response
{
"results": [
{
"account_id": "111111111111",
"region": "eu-west-2",
"type": "rds",
"id": "dev-db",
"name": "dev-db",
"ok": true,
"message": "Turned on",
"pending": false,
"request_id": null
}
],
"run": {
"action": "start",
"status": "running",
"step": 1,
"steps": 2,
"waiting_for": null,
"error": null,
"by": "jsmith",
"started_at": "2026-11-13T17:30:00Z",
"finished_at": null
}
}
results has one entry per member, as for POST /api/actions. run is the ordered start, or null if no member could be kept on. It needs the keep-on right, held outright, on every member.
GET /api/bookings
The token owner's bookings that are still to run, soonest first.
Query parameters
| Parameter | Default | Purpose |
|---|---|---|
everyone | false | true lists everyone's bookings, for administrators. Ignored for anyone else |
Request
curl -H "Authorization: Bearer dlg_your-token-here" \
https://delegaris.example.com/api/bookings
Response
{
"bookings": [
{
"id": 12,
"account_id": "111111111111",
"region": "eu-west-2",
"type": "ec2",
"resource_id": "i-0abc123def4567890",
"resource_name": "uat-web-1",
"owner": "jsmith",
"owner_name": "Jane Smith",
"mine": true,
"can_cancel": true,
"on_date": null,
"days": [1, 3],
"start_time": "18:00",
"end_time": "22:00",
"timezone": "Europe/London",
"reason": "Release testing",
"status": "active",
"summary": "Every Tue and Thu, 18:00 to 22:00 (Europe/London)",
"next_start": "2026-11-17T18:00:00Z",
"next_end": "2026-11-17T22:00:00Z",
"last_run_at": null,
"last_ok": null,
"last_message": null,
"created_at": "2026-11-10T09:12:40Z"
}
]
}
last_run_at, last_ok and last_message say how the most recent window went, for example why it could not start.
POST /api/bookings
Books a keep-on ahead: once on a date, or every week on chosen days. When a window opens, Delegaris turns the resource on until the window closes, as the token's owner.
Body
| Field | Type | Required | Purpose |
|---|---|---|---|
resource | resource reference | yes | The resource to book |
on_date | string YYYY-MM-DD | one of on_date or days | A single date |
days | list of numbers | one of on_date or days | Days of the week it repeats on, 0 (Monday) to 6 (Sunday) |
start_time | string HH:MM, 24-hour | yes | When the window opens |
end_time | string HH:MM, 24-hour | yes | When it closes. Earlier than the start means it runs past midnight |
timezone | string | yes | The time zone of those times, for example Europe/London |
reason | string, up to 300 characters | no | What it is for |
A window can be no longer than the longest keep-on. Booking needs the keep-on right held outright: where keeping the resource on needs approval, it cannot be booked.
Request
curl -X POST \
-H "Authorization: Bearer dlg_your-token-here" \
-H "Content-Type: application/json" \
-d '{
"resource": {"account_id": "111111111111", "region": "eu-west-2", "type": "ec2", "id": "i-0abc123def4567890"},
"days": [1, 3],
"start_time": "18:00",
"end_time": "22:00",
"timezone": "Europe/London",
"reason": "Release testing"
}' \
https://delegaris.example.com/api/bookings
Response (status 201): the new booking, in the same form as in GET /api/bookings.
Refusals
| Status | detail |
|---|---|
| 403 | "You do not have permission to keep this resource on" |
| 403 | "Keeping this resource on needs approval each time, so it cannot be booked ahead. Ask on the day." |
| 404 | "Not found, or you do not have permission for this resource" |
| 422 | "A booking can be at most n hours long" |
| 422 | "That time has already passed" |
| 422 | "You already have n bookings; cancel some first" (the limit is 50) |
DELETE /api/bookings/{id}
Cancels a booking. The owner can cancel their own; administrators can cancel any. Cancelling does not end a keep-on the booking has already started.
Request
curl -X DELETE -H "Authorization: Bearer dlg_your-token-here" \
https://delegaris.example.com/api/bookings/12
Response: the booking, with "status": "cancelled" and next_start and next_end set to null.
| Status | detail |
|---|---|
| 404 | "Booking not found" |
| 409 | "This booking has already finished or been cancelled" |
A pipeline example
Start a test environment before a run and stop it afterwards:
#!/usr/bin/env bash
set -euo pipefail
DELEGARIS=https://delegaris.example.com
AUTH="Authorization: Bearer ${DELEGARIS_TOKEN}"
# Start the "Development stack" group (id 3) and wait for it to finish.
curl -fsS -X POST -H "$AUTH" "$DELEGARIS/api/groups/3/start" > /dev/null
until curl -fsS -H "$AUTH" "$DELEGARIS/api/groups" \
| jq -e '.groups[] | select(.id == 3) | .run.status != "running"' > /dev/null; do
sleep 20
done
# ... run the tests ...
curl -fsS -X POST -H "$AUTH" "$DELEGARIS/api/groups/3/stop" > /dev/null
Keep the token in your pipeline's secret store, not in the script.