General

Integrate your software with the Manager API

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.

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).

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:

  1. POST /api/auth/login with {"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 (step other than complete), which a script cannot complete in the passkey case.
  2. Every write (POST, PUT, PATCH, DELETE) must carry the Origin: https://manager.ginernet.com header (CSRF protection).
  3. Select the active client before operating services: GET /api/me returns accessibleClients and POST /api/auth/context with {"clientId": <id>} selects it.
  4. 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:

CategoryTypical routesWhat it covers
VDC/api/vdcs/*The Virtual Data Centers your VPS live in
VPS/api/vps/*, creation at /api/vdcs/{id}/vpsFull 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-tokensToken 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, cancelled and rejected are 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.resourceType and metadata.resourceId. If it fails, the last error-level event explains why.
  • To find the tasks of a resource, filter the list: GET /api/tasks?resourceType=vps&resourceId=<id>. It also accepts type, status, limit and beforeId to 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 with supportsCloudInit: true.
  • POST /api/vdcs/{id}/vps/pricing-preview with the same resources as the creation: the price and the allowed sizes (allowedSizes). The hourly cost is preview.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 for new_32 for a new one, or existing_client_ip with primaryIpv4AddressId to reuse one of yours (the candidates are in GET /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 and monthlyTrafficLimitGb becomes 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 202 with vps.id and task.id. When the task reaches succeeded, the VPS is running (provisioningStatus: "ready"); SSH may take a few more seconds. If it ends in failed, the VPS stays with provisioningStatus: "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-Key header 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 the Idempotent-Replayed: true header instead of a second VPS.

Errors and limits

  • 4xx errors return {"message": "..."}, sometimes with code and details. A 404 also means the resource does not belong to your client.
  • 5xx errors return a generic message with an errorId: save it and include it if you open a support ticket.
  • Each token allows 300 requests per minute, and every response carries the RateLimit-Limit and RateLimit-Remaining headers 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 429 with the Retry-After header 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.