API reference

The Hotrail REST API: authentication, endpoints, errors and rate limits.

Base URL and authentication

All requests go to https://hotrail.buffersoltech.com/api/v1 over HTTPS and need an x-api-key header. Bodies and responses are JSON.

GET /api/v1/me

Returns the organization the API key belongs to. Use it to check that a key works.

json

{
  "orgId": "org_123"
}

Key scopes

Each key has a scope, chosen when you create it. All can upload, release and roll back. Upload only can upload bundles and nothing else, which is what a CI job needs. Read only can list apps, bundles and channels. A key used outside its scope gets 403 with the code insufficient_scope.

Upload and release endpoints

POST /api/v1/bundles?appId=com.example.app&version=1.2.3 takes a zip as the request body, checks it against the native file and archive size policy, signs the manifest with the app's key and returns the new bundle and its headcode. Only files the app has not stored before are written. The CLI uses POST /api/v1/upload/plan, a direct PUT for each missing file, then POST /api/v1/upload/finalize, so an unchanged build sends almost nothing.

POST /api/v1/channels/release with appId, channel, bundle (a headcode) or version, and percent points a channel at a bundle. POST /api/v1/channels/rollback, /pause and /resume take appId and channel. GET /api/v1/channels?appId= lists channels, GET /api/v1/bundles?appId= lists bundles, and GET /api/v1/line?appId= returns everything the console shows.

json

{
  "headcode": "1A01",
  "version": "2.14.1",
  "percent": 25,
  "channel": "production",
  "action": "release"
}

Device endpoints for the updater plugin

Point @capgo/capacitor-updater at POST /api/v1/updates/check (updateUrl), POST /api/v1/updates/stats (statsUrl) and /api/v1/updates/channel (channelUrl). These need no API key. The check endpoint always answers HTTP 200: an update object with version, url and checksum, or a message saying no new version is available.

Errors

Errors use a matching HTTP status and a JSON body with a stable snake case code. Match on the code, not on the status text.

json

{
  "error": "invalid_api_key"
}

Rate limits

Each API key can make 600 requests per minute. Beyond that you get a 429 status with the error code rate_limited. Wait for the next minute and retry with exponential backoff.

Account export and deletion

GET /api/account/export returns a JSON copy of your account data. DELETE /api/account permanently deletes your account and organization. Both require a signed in session and are also available in Settings, then Account.