API Examples

Use an API token from a restricted management Account. Replace the URL and token in every example.

Create or rotate the token on the intended management Account, then grant only the API permissions required by the automation. An API token inherits that Account’s current permissions; it is not a playback User credential.

Authentication

ENGINE_URL=https://engine.example.com
ENGINE_TOKEN=replace-with-a-restricted-token

Do not store tokens in shared shell history, scripts, screenshots, or logs.

Read Data

curl --fail-with-body \
  -H "Authorization: Token ${ENGINE_TOKEN}" \
  "${ENGINE_URL}/api/v1/streams/stats"

Start a Stream

curl --fail-with-body -X POST \
  -H "Authorization: Token ${ENGINE_TOKEN}" \
  "${ENGINE_URL}/api/v1/streams/123/start"

Create a Database Backup

curl --fail-with-body -X POST \
  -H "Authorization: Token ${ENGINE_TOKEN}" \
  "${ENGINE_URL}/api/v1/database/backups"

Protect a Database Backup

Use the backup’s exact filename. This updates only that file’s automatic rotation protection; set kept to false to remove protection. Manual deletion remains available.

Engine 1.0.2+

BACKUP_FILE=xaccel-engine-auto-1.0.2-20260928120000-abcdef0.gz
curl --fail-with-body -X PATCH \
  -H "Authorization: Token ${ENGINE_TOKEN}" \
  -H "Content-Type: application/json" \
  --data '{"kept":true}' \
  "${ENGINE_URL}/api/v1/database/backups/${BACKUP_FILE}"

JSON Requests

Schedule weekdays values use 0 for Sunday, 1 for Monday, through 6 for Saturday. For example, {"weekdays":[1,5],"hours":[3],"minutes":[0]} selects Monday and Friday at 03:00 in the server’s local time.

Use the schema and exact route from the installed API Reference:

curl --fail-with-body -X POST \
  -H "Authorization: Token ${ENGINE_TOKEN}" \
  -H "Content-Type: application/json" \
  --data @request.json \
  "${ENGINE_URL}/api/v1/<route>"

Check the HTTP status and response body. Retry only idempotent operations unless the endpoint explicitly documents safe retries.

When a route accepts a name, URL-encode spaces and other reserved characters. Prefer stable numeric IDs for automation and read the installed API Reference before changing a request body or route.