VirtFusion Global API

You can use this API to access all Administrator API endpoints, such as the server API to deploy and manage servers, or the system API to configure and manage the system.

The API is organized around REST. All requests should be made over SSL. All request and response bodies, including errors, are encoded in JSON.

Base URL

https://cp.domain.com/api/v1

Replace the host with your Control Server's address. Every path in this reference is relative to it.

Authentication

Every request carries an API token as a bearer token. Tokens are created under Configuration → API in the admin area, where each token can be restricted to a list of IP addresses, given a rate limit and an expiry.

Authorization: Bearer <token>
Accept: application/json

A missing, invalid or expired token returns 401 with no body.

Responses

Successful responses wrap their payload in data. Paged lists use the paginator envelope described under Pagination; the results and page query parameters move through the set. Errors return a JSON body with an errors array, or msg on the older endpoints. Every operation page lists the statuses it can return.

Token permissions

A token carries a list of permissions, chosen when it is created under Configuration → API. The list is an opt-in set of the operations considered dangerous, and a token is allowed every operation that is not on it. Ticking nothing therefore grants everything except the listed operations, and ticking an operation grants that one as well. An operation that requires a permission says so on its own page and answers 403 without it.

Rate limiting

Two limits apply, both measured per minute.

Requests per token

Each token has a Rate Limit (RPM), set when the token is created or edited under Configuration → API. The default is 5000 requests per minute; 0 removes the limit for that token. Every response carries the token's standing:

Once the limit is reached, requests are refused with 429, the body {"errors": ["Too Many Requests"]} and a Retry-After header giving the seconds to wait. Refused requests do not count against the limit, so a client that honours Retry-After recovers at the reset.

Failed authentication per address

An address that fails authentication 10 times within a minute is refused for the rest of that minute with 429, a Retry-After header and the body {"errors": ["Too many authentication attempts. Try again later."], "retry_after_seconds": 42}. A successful request clears the count.

Groups