The Manager API is the same one the panel itself uses: everything you can do from the web (create and manage VPS, power them on and off, firewall, IPs, backups, billing, tickets...) is available as HTTP calls with JSON responses, ready to integrate into your own software.
Base URL: https://manager.ginernet.com/api. All requests and responses use JSON (Content-Type: application/json).
The interactive reference
With your Manager session open, visit https://manager.ginernet.com/api: it is the full client API reference (Swagger UI), with 400+ operations organised by category, each with its parameters, request body, responses and errors. You can even try real calls there with your own session.
The machine-readable OpenAPI specification lives at https://manager.ginernet.com/api/doc.json: import it into Postman or generate a client for your language with tools like openapi-generator. It is reachable with a session or with an API token.
Authentication: API tokens (recommended)
The recommended way to authenticate your integration is an API token: a credential bound to your client account, sent on every request in the Authorization header. No username, no password, no 2FA, no cookies.
Tokens are created in the Manager under API access (side menu). When creating one you choose:
- Allowed IPs (recommended): a list of IPs or CIDR ranges the token may be used from. Any request from another IP is rejected, so a leaked token is useless outside your servers.
- Read-only: the token can only read information; no writes.
- Sensitive operations: by default a token can not run operations classified as sensitive (revealing or changing passwords, adding SSH keys to an existing VPS, managing accesses, ownership transfers...). Creating, reading, reinstalling or deleting VPS does not need it: enable it only if your integration does.
- Optional expiry.
The token is shown exactly once at creation (it starts with gcpr_); store it in a secrets manager. Using it is one header:
curl -H 'Authorization: Bearer gcpr_YOUR_TOKEN' https://manager.ginernet.com/api/vps
With a token there is no session and no context to select: the token already knows which client it belongs to, and writes do not need the Origin header (that protection is for cookie sessions).
What a token can not do, by design: manage the user's personal account (login, 2FA, profile), manage other tokens or the AI-agent keys, or use the panel's AI agents. Only the client's primary account can create and revoke tokens, and each creation asks for passkey confirmation if you have one configured.
If a call returns 401 with a token, the token is invalid, expired, revoked, or coming from an IP that is not allowed (the message says which). A 403 means the operation exists but that token cannot run it (it is read-only, or the operation is sensitive and the token does not allow it).
Alternative: cookie-based session
The API also accepts the same session the panel uses, meant for trying calls from the interactive reference. The flow, in case you need it:
POST /api/auth/loginwith{"identifier": "...", "password": "..."}. Store the cookies from the response and resend them on every call. If the user has a passkey or TOTP, login requires the second factor (stepother thancomplete), which a script cannot complete in the passkey case.- Every write (
POST,PUT,PATCH,DELETE) must carry theOrigin: https://manager.ginernet.comheader (CSRF protection). - Select the active client before operating services:
GET /api/mereturnsaccessibleClientsandPOST /api/auth/contextwith{"clientId": <id>}selects it. - The session expires after 60 minutes of inactivity: on a
401, log in again.
For real integrations, use tokens: they do not depend on passwords, never expire from inactivity, and can be restricted by IP and permissions.
How the API is organised
Operations are grouped by category. The main ones:
| Category | Typical routes | What it covers |
|---|---|---|
| VDC | /api/vdcs/* | The Virtual Data Centers your VPS live in |
| VPS | /api/vps/*, creation at /api/vdcs/{id}/vps | Full lifecycle: creation, resources, power, reinstall, backups, passwords, metrics |
| VPS Firewall | /api/vps/{id}/firewall/* | The VPS platform firewall: mode, rules, templates |
| VPS Network | /api/vps/{id}/network/* | Primary IP and additional IPs |
| IPv4 / IPv6 / rDNS | /api/ipv4/*, /api/ipv6/* | Contracted subnets, addresses and PTR records |
| SSH Keys | /api/ssh-keys/* | The client's SSH key library |
| Web Hosting | /api/hosting/accounts/* | cPanel hosting and Multidomain Hosting (WHM) |
| Domains | /api/domains/*, /api/domain-contacts/* | Domains, contacts, DNS and transfers |
| Tasks | /api/tasks/* | Tracking of asynchronous operations |
| Billing | /api/billing/* | Balance, movements, top-ups, invoices |
| Support Tickets | /api/support-tickets/* | Support tickets and attachments |
| API Tokens | /api/client/api-tokens | Token management (session only, never with a token) |
The complete, per-operation list is in the interactive reference.
Asynchronous operations: tasks
Anything that is not immediate (creating a VPS, resizing, reinstalling, taking a backup...) returns a task. The response includes its id; poll GET /api/tasks/{id} every 5-10 seconds, not in a tight loop.
succeeded,failed,cancelledandrejectedare final states: they no longer change. Any other (pending,running,waiting...) means it is still in progress.- The resource it acts on is in
metadata.resourceTypeandmetadata.resourceId. If it fails, the lasterror-level event explains why. - To find the tasks of a resource, filter the list:
GET /api/tasks?resourceType=vps&resourceId=<id>. It also acceptstype,status,limitandbeforeIdto page backwards. Tasks are kept indefinitely.
Creating a VPS
Creation is POST /api/vdcs/{id}/vps on a cloud VDC (in GET /api/vdcs, the ones with canCreateVps: true). The data you need comes from calls that reserve and charge nothing:
GET /api/vdcs/{id}/vps/float-groups: the zones (floatGroupId).GET /api/operating-system-images: the operating systems (operatingSystemImageId).GET /api/ssh-keys: your SSH keys (sshKeyIds), only for images withsupportsCloudInit: true.POST /api/vdcs/{id}/vps/pricing-previewwith the same resources as the creation: the price and the allowed sizes (allowedSizes). The hourly cost ispreview.currencies.EUR.hourlyTotal, with the IPv4 already included if you ask for one.
A typical creation (the ids are examples):
curl -X POST https://manager.ginernet.com/api/vdcs/123/vps \
-H 'Authorization: Bearer gcpr_YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: 5f0c2e1a-8d4b-4a7e-9b1d-2f6c3a9e7d10' \
-d '{"name": "web-01", "floatGroupId": 1, "cpuCores": 1, "memoryMb": 1024,
"diskGb": 10, "networkMbps": 5000, "trafficBillingMode": "pay_as_you_go",
"primaryIpv4Mode": "new_32", "operatingSystemImageId": 13, "sshKeyIds": [42]}'
Worth knowing:
- IPv4: if you omit
primaryIpv4Mode, the VPS is created without a public IP. Ask fornew_32for a new one, orexisting_client_ipwithprimaryIpv4AddressIdto reuse one of yours (the candidates are inGET /api/vdcs/{id}/vps/create-context?floatGroupId=<zone>). - Traffic: always send
"trafficBillingMode": "pay_as_you_go"(1 TB per month included, as in the panel). If you omit it, a monthly quota is assumed andmonthlyTrafficLimitGbbecomes mandatory. - Disk: it can only grow. CPU and RAM can be changed later in both directions, so start small.
- Charging: creation requires balance for 720 hours and charges the first hour when accepted.
- Result: it answers
202withvps.idandtask.id. When the task reachessucceeded, the VPS is running (provisioningStatus: "ready"); SSH may take a few more seconds. If it ends infailed, the VPS stays withprovisioningStatus: "failed"and its compute is not charged (what was charged is refunded): reinstall it to try again or delete it. The IPv4 is still billed until you delete it. - Firewall: a new VPS only accepts incoming connections to SSH (RDP on Windows) and ping. Open the ports you need with
POST /api/vps/{id}/firewall/rules. - Retries without duplicates: send the
Idempotency-Keyheader with a different UUID per creation. If you repeat the same request with the same key within 24 hours (for example after a network cut), you get the original response with theIdempotent-Replayed: trueheader instead of a second VPS.
Errors and limits
4xxerrors return{"message": "..."}, sometimes withcodeanddetails. A404also means the resource does not belong to your client.5xxerrors return a generic message with anerrorId: save it and include it if you open a support ticket.- Each token allows 300 requests per minute, and every response carries the
RateLimit-LimitandRateLimit-Remainingheaders so you can slow down before hitting the limit. Writes have their own limit on top: 60 per minute and 1000 per hour. - When you exceed a limit you get a
429with theRetry-Afterheader in seconds: wait that long before retrying. - 30 failed authentications in 5 minutes from the same IP temporarily block every token coming from it. If you rotate a token, remove the old one from all your processes.
Complete PHP example
A minimal script that lists your VPS with their state and primary IP, using an API token:
<?php
// Minimal example: list your VPS using a Manager API token.
// Requirements: PHP 8+ with the curl extension.
// Create the token in the Manager: API access -> Create token.
const BASE_URL = 'https://manager.ginernet.com';
const API_TOKEN = 'gcpr_YOUR_TOKEN'; // better from an environment variable
function api(string $method, string $path, ?array $body = null): array
{
$headers = [
'Accept: application/json',
'Authorization: Bearer ' . API_TOKEN,
];
$ch = curl_init(BASE_URL . $path);
if ($body !== null) {
$headers[] = 'Content-Type: application/json';
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
}
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => $method,
CURLOPT_HTTPHEADER => $headers,
CURLOPT_RETURNTRANSFER => true,
]);
$response = (string) curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
$data = json_decode($response, true);
if (!is_array($data)) {
$data = [];
}
if ($status >= 400) {
throw new RuntimeException(
"HTTP $status on $method $path: " . ($data['message'] ?? $response)
);
}
return $data;
}
// The token is already bound to your client account: no login, no context.
$result = api('GET', '/api/vps');
foreach ($result['items'] as $vps) {
printf(
"#%-5d %-25s %-10s %s\n",
$vps['id'],
$vps['name'],
$vps['powerState'],
$vps['primaryIpAddress']['ipAddress'] ?? 'no IP',
);
}
Save it as list-vps.php, set your token and run it with php list-vps.php.
Good practices
- Restrict the token by IP: the most effective protection. A token limited to your servers' IPs is useless if leaked.
- Least privilege: if your integration only reads, create a read-only token. Leave sensitive operations disabled unless you need them.
- Keep the token out of your code: load it from an environment variable or a secrets manager, never commit it. If it slips into a commit, revoke it immediately under API access and create a new one.
- One token per integration: you can revoke one without breaking the rest, and the "Last used" column shows which IP each one works from.
- Mind operations that cost money: creating VPS, resizing or purchasing licenses is charged to the account's prepaid balance immediately, and deletions are irreversible. Test your integration with reads before automating writes.
Connecting an AI agent?
If what you want to connect is an AI agent (Claude, Cursor, etc.), do not use the REST API: the Manager has an MCP server with dedicated API keys and configurable spend limits. See Deploy VPS with AI: MCP server.