DEVELOPER DOCUMENTATION

Cloud REST API v1.

Automate your own servers with scoped access tokens. Read the reference before you build your integration.

Base URL: https://www.geekydigital.cloud/api/v1. All requests require a bearer token from API access. Tokens expire after 1–365 days and may be revoked at any time.

Read the catalogue

Create a token with servers:read permission in API access. In your own terminal, set CLOUD_API_TOKEN to that token using your secret manager or an environment variable, then request the plans. Do not put real tokens in shared examples, source control or browser JavaScript.

curl --request GET 'https://www.geekydigital.cloud/api/v1/plans?per_page=25' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $CLOUD_API_TOKEN"

This read request does not create a server or charge your account. Use data for the plans and ordering for availability. Select an allowed location_ids, image_ids and billing_periods combination before preparing a separate create request.

Legal documents and new orders

Before creating a server, retrieve GET /legal with servers:read permission. Review the linked documents and obtain the customer's agreement. When data.enabled is true, send legal_version and legal_content_hash exactly as returned, together with terms_accepted: true, aup_accepted: true and privacy_acknowledged: true in the POST /servers body. Agreement covers the Terms and SLA; the privacy field records that the notice was read, not marketing consent. A missing or outdated agreement returns 422. Retrieve and review the current version before making a new request. Retrying an already successful idempotent request preserves its original order and accepted version.

Endpoints

Method / path	Permission	Behavior
`GET /servers, /servers/{id}`	servers:read	Read your servers; identifiers are service UUIDs.
`GET /servers/{id}/operations/{operation}`	servers:read	Poll the operation UUID returned by a write.
`GET /locations, /plans, /images, /ssh-keys`	servers:read	Read the public catalog and your SSH key IDs.
`POST /servers`	servers:create	Create and confirm an order. Provisioning follows payment.
`GET /orders/{id}`	servers:create	Track order, invoice link and assigned server UUIDs.
`POST /servers/{id}/start, /stop, /restart`	servers:control	Queue start, hard stop or restart.
`POST /servers/{id}/rebuild`	servers:control	Replace the OS and erase existing server data.
`DELETE /servers/{id}`	servers:delete	Permanently delete VM and snapshots; release verified resources.
`GET /billing/invoices, /billing/invoices/{id}, /billing/wallet`	billing:read	Read invoices and balance in EUR cents.

Writes and retries

Send JSON with confirmed: true and a UUID Idempotency-Key header. A retry with identical validated input returns the existing result. A changed request with the same key returns 409. Writes return 202; poll the operation or order until complete. A failed or uncertain operation needs review and must not be blindly repeated with a new key.

Rebuild and delete require confirm_hostname matching the server hostname. Rebuild also needs operating_system_id and your ssh_key_id or a strong root_password. Delete does not refund monthly charges or remove outstanding debt. Hourly usage ends when resources are confirmed released.

Create a server

Required fields: vps_plan_id, datacenter_id, operating_system_id, billing_period (monthly/hourly), hostname, ssh_key_id or root_password, backups (false), additional_ipv4, confirmed, max_initial_total (including VAT) and max_recurring_price (excluding VAT), in EUR cents. A price above either limit returns 409 without creating an order.

The account needs a verified email and complete billing address. Ordering and provisioning must be enabled. Use the returned invoice URL to pay; wallet auto-pay is enabled by default and applies unless you switch it off. HTTP 202 is an accepted order, not an active VPS.

Responses and limits

Lists of servers, plans and invoices support per_page (1–100) and page. Plans accept location_id and image_id; servers accept status. Power data is cached; inspect fresh and observed_at. Credentials, VMIDs and node connections are never returned.

Plans include only active EUR offers with an active location, at least one compatible image and an available billing period. image_ids checks each image's RAM and disk requirements; image_id filtering applies the same checks. The /locations and /images endpoints are reference lists; use each plan's location_ids and image_ids to choose a supported combination.

billing_periods lists available cycles. period_options gives each cycle's price, backup_available, backup_price, max_additional_ipv4 and ipv4_price, in EUR cents excluding VAT. Unavailable price fields are null; zero is a valid free price. Use the per-period IPv4 limit, as it can differ between monthly and hourly billing. Hourly offers require billing automation when provisioning is enabled; automated VPS backups are currently unavailable in that mode.

The plans response also includes ordering.available and ordering.reason for account and platform restrictions: ordering_closed, provisioning_unavailable, billing_details_required or payment_review. A catalog entry does not reserve capacity or IP addresses. Prices, compatibility and account eligibility are checked again when creating and confirming an order.

Errors contain error.code, error.message and error.request_id; validation errors include error.fields. Codes include 401 unauthenticated, 403 forbidden, 404 not_found, 409 conflict, 422 validation_failed, 429 rate_limited and 503 unavailable. Every response includes X-Request-ID. Respect Retry-After on 429.

Limits are 120 requests per minute per account and IP and 10 writes per minute per account. Keep tokens server-side and grant only needed permissions. API tokens grant access only to their owner's resources; administrative cross-account access remains in the admin panel.

Maintained by Geeky Digital Cloud. Reference checked against the application on 16 September 2026.

Back to getting started