Skip to main content

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/json with 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" }
StatusMeaning
401The token is wrong, revoked or expired, or tokens are switched off
403The token cannot call this endpoint, or its owner may not do this
404Not found, or not visible to the token's owner. Delegaris gives the same answer for both, so the API does not reveal what exists
409The request clashes with the current state, for example a group already being started
422The 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:

FieldTypeExample
account_id12-digit string"111111111111"
regionstring"eu-west-2"
typestring, one of the types below"ec2"
idstring"i-0abc123def4567890"
typeWhat it is
ec2EC2 instance
rdsRDS instance
rds-clusterAurora, DocumentDB or Neptune cluster
asgAuto Scaling group
ecs-serviceECS service
eks-nodegroupEKS managed node group
redshiftRedshift cluster
sagemakerSageMaker notebook instance
lightsailLightsail 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

ParameterDefaultPurpose
refreshfalsetrue 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

FieldMeaning
stateThe state as AWS reports it, for example running, stopped, available, paused, pending
poweron, off, or busy (changing). Start works only from off, stop only from on
tagsThe tags in AWS now
stashed_tagsTags dropped through Delegaris and remembered, by key: value, by (who dropped it) and at
detailsWhat AWS reports that people find useful, such as instance type and addresses. Varies by type
size, saved_sizeFor Auto Scaling groups, ECS services and EKS node groups: the size now, and the size a start brings back
scheduleWhere its schedule stands, when the hours behind its schedule tag are known: on_now, always, stops_at, starts_at. Otherwise null
keep_onIf it is being kept on: until, by, by_name, stop_at_end, tag_keys (the tags taken off), reason, participants, can_end
approvalA request for approval waiting on it: id, action, by, by_name, created_at, mine, can_decide
bookingsKeep-ons booked ahead for it: id, summary, by, by_name, reason, next_start, next_end, can_cancel
costA rough on-demand price: hourly, saves_weekly (what its schedule saves a week, if known), currency. null where no price is known
remoteWhether a Remote Desktop file can be downloaded. null when not
permissionsWhat 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

FieldMeaning
errorsAccounts or regions that could not be read. Only administrators see the details
incompletetrue if anything could not be read, so the list may be missing resources
labelsFriendly names for tag values, with the hours behind schedule values
configThe 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

FieldTypeRequiredPurpose
actionstringyesOne of the actions below
resourceslist of resource referencesyes1 to 100
keystringfor tag actionsThe tag key
valuestringfor set_tagThe tag value
untiltimefor keep_on, turn_onWhen the resource goes back on its schedule
stop_at_endbooleanno, default trueFor 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
reasonstring, up to 300 charactersnoWhat it is for. Kept in Activity and Reports. Required for a new keep-on if Settings says so

Actions

actionDoesIn the web UI
startStarts itStart
stopStops itStop
rebootRestarts a running EC2 instance, RDS instance, Redshift cluster or Lightsail instance in place. An ECS service replaces its tasksReboot
keep_onTakes 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 timeKeep on until…
turn_onAs keep_on, and starts it first if it is stoppedTurn on until…
keep_on_finishEnds a keep-on now: stops it and puts the schedule tag backStop it now
keep_on_cancelEnds a keep-on now: puts the schedule tag back and leaves it runningPut back on schedule
drop_tagRemoves tag key and remembers its valueDrop
restore_tagPuts the remembered value of key backRe-add
set_tagSets tag key to valueSet 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
}
]
}
  • ok says whether it worked (or was already in the state asked for).
  • message says 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=true to see where it stands.
  • pending: true means the action needs approval: nothing was done, and a request was written instead. request_id is the request's number and message is "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"
}
}
]
}
FieldMeaning
stepsThe members in starting order, one list per step. Members the owner cannot see are left out
total, hiddenHow many members there are, and how many the owner cannot see
runningHow many visible members are running
canWhether the owner may start, stop and keep_on the whole group. Each needs that right, held outright, on every member
runThe 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

Statusdetail
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

FieldTypeRequiredPurpose
untiltimeyesWhen the members go back on their schedules
stop_at_endbooleanno, default trueUsed only for members whose schedule hours are not known
reasonstring, up to 300 charactersnoWhat 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

ParameterDefaultPurpose
everyonefalsetrue 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

FieldTypeRequiredPurpose
resourceresource referenceyesThe resource to book
on_datestring YYYY-MM-DDone of on_date or daysA single date
dayslist of numbersone of on_date or daysDays of the week it repeats on, 0 (Monday) to 6 (Sunday)
start_timestring HH:MM, 24-houryesWhen the window opens
end_timestring HH:MM, 24-houryesWhen it closes. Earlier than the start means it runs past midnight
timezonestringyesThe time zone of those times, for example Europe/London
reasonstring, up to 300 charactersnoWhat 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

Statusdetail
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.

Statusdetail
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.