Using the integration API

The integration API is for customers wiring machines into their own systems: read service state, read traffic, submit power actions.

1. Getting a token

Generate a token under Account settings → Integrations. The full token is shown once at creation — put it straight into your secret store. Rotating invalidates the old token immediately.

2. Authentication

Send the token on every request:

Authorization: Bearer <your-token>

The base path is /api/v1/integration on this site.

3. Endpoints

GET  /services                    list your services
GET  /services/{id}               one service, including connection details
GET  /services/{id}/traffic       usage for the current cycle
POST /services/{id}/actions       submit an action

Body for an action:

{ "action": "power_on" }

Valid values are power_on, power_off, reboot and reinstall.

4. Response shape

Every response looks like:

{ "code": 0, "message": "ok", "data": { ... } }

A code of 0 means success; anything else is a business error with a readable reason in message. The HTTP status reflects the outcome too — do not rely on only one of the two.

5. Actions are asynchronous

Submitting an action returns a task id; it does not mean the action finished. Poll GET /services/{id} and watch active_action, or wait for the in-app notification. Power operations usually settle within seconds; a reinstall takes considerably longer.

6. Rate limits

120 requests per minute per token. Over that you get a 429 with Retry-After set. Keep polling intervals sane — every five seconds is plenty.