Skip to main content

Admiral REST API & Swagger Reference

The Admiral REST API allows engineering teams, autonomous AI agents, and CI/CD pipelines to manage edge devices, fleets, configurations, and rollouts programmatically.

Base URL: https://api.admrl.co/v1

Authentication​

Admiral supports two independent authentication methods. Pick the one that fits your use case (do not combine them):

PropertyPersonal API Token (PAT)Service Account (OAuth2 Client Credentials)
IdentityTied to an individual human user accountDedicated, independent machine identity
Recommended ForQuick scripts, local developer testingCI/CD pipelines, production backend integrations, automated GitOps
LifecycleTied to the user accountSurvives organizational personnel changes
PermissionsInherits your user rolesScoped via roles or IAM policies
HeadersX-API-Token-ID + X-API-Secret-KeyAuthorization: Bearer ***
  • Service accounts (recommended): exchange a client ID and secret for a short-lived bearer token. See Service Accounts.
  • Personal API tokens (legacy): send X-API-Token-ID and X-API-Secret-Key on every request. See Personal API Tokens below.

Required Header: Multi-Tenant Organization Context​

Admiral is a multi-tenant platform. Nearly all API endpoints require you to specify the operational tenant via the X-Organization-ID header:

X-Organization-ID: your-organisation-uuid

You can copy your Organization ID from Settings > General (app.admrl.co/settings/general) or find it in your user profile metadata.

Example Request​

curl -s "https://api.admrl.co/v1/devices?page=1&limit=10" \
  -H "X-Organization-ID: $ORG_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Endpoint examples for each feature live on that feature's page, for example rollout impact, maintenance windows, AirDetect, telemetry, and alerts.

Personal API Tokens (Legacy)​

Not for automation

Personal API tokens are tied to one user and inherit all of that user's roles, which cannot be narrowed. Sensitive actions such as revealing disk recovery keys, remote disk unlocks, and live screen control are blocked for tokens and require a signed-in dashboard session. Use Service Accounts for scripts, CI/CD, and integrations.

Creating a token​

  1. Go to Account > API tokens.
  2. Click New Token.
  3. Enter a descriptive name (e.g., "Personal testing").
  4. Set an expiration date (recommended).
  5. Click Create Token.

Each token has two parts: a Token ID (starts with admk_) and a Secret Key (starts with adms_).

Important

The Secret Key is only displayed once upon creation. Store it securely immediately. If you lose it, you must create a new token.

Using a token​

Send both parts of the token, plus your organisation, on every request:

curl "https://api.admrl.co/v1/devices" \
  -H "X-Organization-ID: $ORG_ID" \
  -H "X-API-Token-ID: $TOKEN_ID" \
  -H "X-API-Secret-Key: $SECRET_KEY"

A personal token acts with the capabilities granted by the roles assigned to the user who created it. Sensitive operations (revealing disk recovery keys, remote disk unlock grants, and interactive screen control) cannot be performed using API tokens.

Moving to a service account​

  1. Create a Service Account for the workload.
  2. Assign a role (or attach an IAM policy) granting only the capabilities it needs.
  3. Mint a key and update your systems to use the new client credentials.
  4. Revoke the personal token.

Calls That Reach a Device​

Some endpoints ask the device itself rather than stored data: live state reads, diagnostics probes, screenshots, and similar. Their errors are the same everywhere. For the endpoints, see Device Documents, Device State & Diagnostics, Memory Testing, and Rollouts.

Errors​

StatuserrorMeaning
503device_offlineThe device is not connected.
504device_timeoutThe device did not answer in time.
502device_errorThe device answered with an error (detail has it).
409device_busyThe device is already running that kind of request.
429rate_limitedToo many live calls for this device; honour Retry-After.