API

Manage your fleets, devices and releases from scripts, with a key from your own organization.

Get a key

In the hub open Settings, API and create a key. Choose Read only for dashboards and reports, or Read and write for automation. The key is shown once; copy it then. Revoke it there at any time.

Use it

Send the key as a bearer token. Everything is JSON over HTTPS.

export TUNA_API_KEY=bft_...
curl -H "authorization: Bearer $TUNA_API_KEY" https://tunalicious.io/api/fleets

Example: set the default variables of a fleet

curl -X PATCH https://tunalicious.io/api/fleets/flt_xxxxxxxx \
  -H "authorization: Bearer $TUNA_API_KEY" -H "content-type: application/json" \
  -d '{"defaultEnv": {"TZ": "Europe/Athens", "location_id": "site-001", "latitude": "38.9461"}}'

Example: restart the app on a device

curl -X POST https://tunalicious.io/api/devices/dev_xxxxxxxx/commands \
  -H "authorization: Bearer $TUNA_API_KEY" -H "content-type: application/json" -d '{"kind": "restart-app"}'

Good to know

A key belongs to one organization and acts with the role of the person who created it, or less: a read-only key can only read.
Errors are JSON like {"error": "not-found"} with the usual status: 401 for a missing or revoked key, 403 when the key may not do that, 404 when it does not exist, 400 for a bad request.
Variable names are letters, digits and underscores. Lowercase names are fine.
The same endpoints power the hub itself, so anything you see in the hub can be automated.
A machine-readable description is at /api/openapi.json (OpenAPI 3).

Organization

GET /api/org

The organization of the key: name, company details, your role and the number of members.

PATCH /api/org

Change the organization name and company details.

{"name": "Acme", "email": "billing@acme.test", "address": "1 Main St", "phone": "+30 210 0000000", "taxId": "EL123456789", "country": "GR"}

Fleets

GET /api/fleets

All fleets with their device and release counts, default environment variables and which devices override them.

POST /api/fleets

Create a fleet, optionally with default environment variables for new devices.

{"name": "Greenhouse", "defaultEnv": {"TZ": "Europe/Athens", "location_id": "site-001"}}

PATCH /api/fleets/{id}

Rename a fleet, change the name `tuna push` uses (slug) or replace its default environment variables. New devices start with the defaults; existing devices keep their own.

{"name": "Greenhouse v2", "slug": "greenhouse-v2", "defaultEnv": {"TZ": "Europe/Athens"}}

DELETE /api/fleets/{id}

Delete an empty fleet (no devices, no releases).

Devices

GET /api/devices

All devices with status, release, last check-in and fleet. Filter with ?q= and ?group=.

GET /api/devices/{id}

One device in full: information, telemetry, services, tunnel and recent commands.

PATCH /api/devices/{id}

Change a device: name, group, tags, check-in interval, fleet, public address, terminal, canary, pinned release, hold or suspension.

{"name": "Bluefin", "group": "Kitchen", "tags": ["floor-1"], "fleet": "flt_..."}

DELETE /api/devices/{id}

Remove a device. Add ?uninstall=1 to uninstall the supervisor from it, or ?force=1 to delete the record of an offline device.

GET /api/devices/{id}/settings

The environment variables of one device.

PUT /api/devices/{id}/settings

Replace the environment variables of one device. Removed names are removed on the device at its next check-in.

{"env": {"wind_id": "1", "zone1nodes": "1,2,3"}}

POST /api/devices/{id}/commands

Send a command: identify, collect-diagnostics, restart-app, reboot, speed-test, update-now, rollback, service-start, service-stop, service-restart (with args.service).

{"kind": "restart-app"}

POST /api/bulk

Apply a patch or a command to up to 500 devices at once.

{"ids": ["dev_..."], "action": "command", "kind": "update-now"}

Releases

GET /api/releases

Releases of the organization. Filter with ?project=<fleet name>.

GET /api/releases/{number}

One release in full: notes, services, rollout and the devices running it. Add ?project=<fleet name>.

POST /api/releases/{number}/activate

Make a release current for a fleet, for everyone or for a percentage.

{"project": "greenhouse", "fleet": "flt_...", "percent": 100}

PATCH /api/releases/{number}

Move a staged rollout to a higher percentage.

{"project": "greenhouse", "fleet": "flt_...", "percent": 50}

POST /api/releases

Publish a signed release.

Releases are signed on your machine. Use the command line (tuna push) or an agent rather than calling this directly.

Adding devices

POST /api/installations

Create an install command for a fleet. It enrols any number of devices for the time given.

{"unlimited": true, "fleet": "flt_...", "ttlS": 86400}

GET /api/cards

Ready SD cards created for the organization, with how many devices each started.

POST /api/cards

Create the boot files of a ready SD card: Wi-Fi, CAN board, screen and a long-lived enrolment token.

{"fleet": "flt_...", "ssid": "depot", "password": "...", "country": "GR", "can": {"board": "waveshare-rs485-can", "bitrate": 0}, "screen": "800x480"}

DELETE /api/cards/{id}

Switch a card off: devices can no longer enrol with it.

GET /api/card-configs

Saved card configurations (the Wi-Fi password is never returned).

Members

GET /api/members

People in the organization with their roles.

POST /api/invites

Invite someone by email, or create an invitation link.

{"email": "name@company.com", "role": "member"}

Activity

GET /api/audit

The audit log of the organization. Use ?limit= (up to 500).

Billing

GET /api/billing

Devices, the free allowance, the plan, the card on file and the next invoice.