Vexelia API reference

GET /api/v1/orgs/{org}/api-tokens

List API tokens

Every token of the organisation, newest first, with its scopes, limits and use. Includes the scope catalog a token can be given. Owners and admins only, and only with a signed-in session, never with a token.

• Permission: api_tokens.manage
• API token: not available, use a signed-in session

POST /api/v1/orgs/{org}/api-tokens

Create an API token

Needs step-up. The response carries the token once; it is stored only as a hash and can never be shown again. Scopes must be within your own role. A token with servers:rebuild or servers:destroy needs an IP allowlist or an expiry under 30 days (422 on expires_at otherwise). At most 50 active tokens per organisation (token_limit).

• Permission: api_tokens.manage
• API token: not available, use a signed-in session
• Step-up: needs a recent password check

Request body (JSON):

{
  "allowed_ips": [
    null
  ],
  "expires_at": "2026-01-01T00:00:00Z",
  "name": "string",
  "scopes": [
    null
  ]
}

DELETE /api/v1/orgs/{org}/api-tokens/{token}

Revoke an API token

The token stops working on its very next request. Revoking a token that is already revoked is not an error.

• Permission: api_tokens.manage
• API token: not available, use a signed-in session

GET /api/v1/orgs/{org}/audit

Organisation activity

Lists activity in the organisation, newest first. Staff actions are shown, but not who took them. Pages with before and limit (default 50, at most 100).

• Permission: audit.read
• API token: not available, use a signed-in session

POST /api/v1/auth/email-change/cancel

Cancel a change of sign-in address from the link sent to the old address

Cancels a waiting change with the token from the notice sent to the current address. Works once; an unknown, used or expired token returns token_invalid.

• Access: public, no authentication

Request body (JSON):

{
  "token": "string"
}

POST /api/v1/auth/email-change/confirm

Confirm the new sign-in address from the emailed link

Makes the change with the token from the link sent to the new address. The new address becomes the sign-in address and counts as verified, every session of the account is signed out and unused email links are voided. An unknown, used, cancelled or expired token, a locked account, or a request made from an address the account no longer has returns token_invalid; an address that has since been taken returns email_change_failed.

• Access: public, no authentication

Request body (JSON):

{
  "token": "string"
}

POST /api/v1/auth/login

Sign in with email and password

Signs in with email and password. Returns signed_in, or second_factor with the allowed methods when the account has an authenticator app, in which case only a partial session is set until the second step. Wrong credentials, inactive accounts and rate limiting are refused; email_unverified and account_locked are shown only after the password matched. A browser the person marked as trusted skips the second step and gets signed_in (only when it is still valid, was marked for this person and this remembered browser, comes from a network they have signed in from, and no automatic lock is running; never for staff or for a person in an organisation that requires a second factor); ask_second_factor forces the step. Several failed sign-ins in 15 minutes start an automatic temporary lock: sign-in from a browser or network the person has not used is then refused for a few minutes with the same invalid_credentials answer a wrong password gets (right or wrong password, no difference), and the person is emailed.

• Access: public, no authentication

Request body (JSON):

{
  "ask_second_factor": false,
  "email": "string",
  "password": "string"
}

POST /api/v1/auth/login/second-factor

Complete sign-in with a TOTP or recovery code

Completes sign-in with a TOTP code or a recovery code. Needs the partial session from login; any other session gets bad_request. Wrong codes are refused and count towards the automatic temporary lock. With trust_browser and an authenticator code the browser is marked as trusted for the configured number of days (a cookie only the sign-in routes receive; the person is emailed); a recovery code never marks one.

• API token: not available, use a signed-in session

Request body (JSON):

{
  "code": "string",
  "recovery_code": "string",
  "trust_browser": false
}

POST /api/v1/auth/logout

Sign out

Ends the current session and clears the session cookie.

• API token: not available, use a signed-in session

POST /api/v1/auth/passkey/begin

Start passkey sign-in

Starts passkey sign-in and returns the WebAuthn options with a challenge_id. Pass the challenge_id to passkey/finish.

• Access: public, no authentication

POST /api/v1/auth/passkey/finish

Finish passkey sign-in

Completes passkey sign-in with the browser's WebAuthn response and the challenge_id from passkey/begin. A challenge is single-use. Any failure, including an unverified or inactive account, returns invalid_credentials.

• Access: public, no authentication

Request body (JSON):

{}

POST /api/v1/auth/password/forgot

Email a password reset link

Emails a password reset link if the address belongs to an active account. The response is the same either way, so it does not reveal whether an account exists.

• Access: public, no authentication

Request body (JSON):

{
  "email": "string"
}

POST /api/v1/auth/password/reset

Set a new password from a reset link

Sets a new password using the token from a reset email and sends a notice that the password changed. The new password must meet the password policy (weak_password: length) and must not be a very common password or one found in a known breach (password_breached; the breach-list lookup is a platform setting and lets the password through when that service is down); an unknown or used token returns token_invalid.

• Access: public, no authentication

Request body (JSON):

{
  "password": "string",
  "token": "string"
}

POST /api/v1/auth/register

Create an account

Creates an account and a personal organisation, and emails a confirmation link. The password must be 10 to 256 characters and must not be a very common password or one found in a known breach (validation_failed on the password field; the same answer whether or not the address is registered). The response is the same for an address that is already registered, whose owner is told by email instead. When the platform runs a sync hook plugin on signups the request can be refused with 403 request_declined, 409 request_declined_limit or 403 request_declined_region, in the platform's own words and before anything is created; the answer never depends on whether the address has an account. A plugin that fails or is slow is ignored.

• Access: public, no authentication

Request body (JSON):

{
  "email": "string",
  "name": "string",
  "password": "string"
}

POST /api/v1/auth/secure-account

Sign out everywhere from a sign-in alert (this wasn't me)

The link in a new-device or new-network sign-in alert. Signs every session of the account out, forgets the browser and network the alert was about (the next sign-in from them alerts again) and emails a password reset link to the account's address. It does not lock the account and leaves API tokens, passkeys and the authenticator app as they are. The link works once and for seven days; an unknown, used or expired token returns token_invalid.

• Access: public, no authentication

Request body (JSON):

{
  "token": "string"
}

GET /api/v1/auth/sso/providers

Identity providers a visitor can sign in with

The key and name of each provider a visitor can use, for the sign-in page. Public. Empty while the platform flag sso_enabled is off or no provider is configured, so the page shows no button and nothing can be learned about what exists. It never names an issuer, a client id or a secret.

• Access: public, no authentication

POST /api/v1/auth/sso/{provider}/begin

Start signing in with an identity provider

Starts the authorization code flow with PKCE (S256), a state and a nonce, and returns the provider's authorization address. The state is single-use, kept only as a hash, lives ten minutes and is tied to this browser by an HttpOnly cookie (vx_sso), so the callback must come back to the same browser. The PKCE verifier and the nonce are derived from the state with a server key and never stored. return_to is kept only if it is a path on this site. Public. A provider that is unknown or switched off answers not_found; one that cannot be reached answers sso_unavailable and leaves nothing behind.

• Access: public, no authentication

Request body (JSON):

{
  "return_to": "string"
}

GET /api/v1/auth/sso/{provider}/callback

Where the identity provider sends the browser back

The redirect address registered with the provider (exact, one per provider). Public: the single-use state, the browser cookie and the signed id_token are the credentials. Every outcome is a 303 redirect to the panel, never a JSON error. Success lands on the return_to of the request, or on /login?sso=second_factor when an authenticator app is still to be asked for. A refusal lands on /login?sso_error=CODE (or /account/security?sso_error=CODE for a link) with CODE one of sso_failed, sso_cancelled, sso_unavailable, sso_not_linked, sso_link_failed or account_locked; every failure to sign in reads sso_failed or sso_not_linked whatever accounts exist, so nothing says whether an address or identity has an account. The id_token must be signed RS256, PS256, ES256 or EdDSA by a key in the provider's published key set and carry the expected issuer, audience, nonce and a future expiry, and a verified email (on the provider's domain allow-list if it has one). An identity signs in only to the account it was linked to: never by email match, never for staff.

• Access: public, no authentication

POST /api/v1/auth/verify-email

Confirm an email address

Confirms an email address with the token from the confirmation email. An unknown, used or expired token returns token_invalid.

• Access: public, no authentication

Request body (JSON):

{
  "token": "string"
}

POST /api/v1/auth/verify-email/resend

Resend the confirmation email

Sends the confirmation email again. The response is the same whether or not the address exists.

• Access: public, no authentication

Request body (JSON):

{
  "email": "string"
}

GET /api/v1/orgs/{org}/billing

Credit balance and saved cards

Returns the organisation's spendable credit balance (balance minus holds) and its saved cards.

• Permission: billing.read
• API token: not available, use a signed-in session

GET /api/v1/orgs/{org}/billing-profile

Get billing details

An org that never saved details gets empty strings and a null updated_at.

• Permission: billing.read
• API token: not available, use a signed-in session

PUT /api/v1/orgs/{org}/billing-profile

Save billing details

Replaces every field. Only invoices issued afterwards carry the new details; an issued invoice keeps the copy it was issued with. The tax ID is free text and is not checked against a registry.

• Permission: billing.manage
• API token: not available, use a signed-in session

Request body (JSON):

{
  "address": "string",
  "city": "string",
  "country": "string",
  "name": "string",
  "postal_code": "string",
  "tax_id": "string"
}

GET /api/v1/orgs/{org}/billing-profile/vat-check

Show whether the VAT number was validated

The state of the EU VAT number saved on the billing details (TAX-2). It reads what is stored and never calls the registry. `status` is none (no tax ID), not_eu (not an EU VAT number, nothing to check), unmatched (the registry knows the number but its registered name did not match the billing name and country; under staff review, no reverse charge), off (validation is switched off for this organisation), pending (not yet answered), valid, invalid, or unverified (the registry could not answer, or a valid answer is too old to rely on; a retry is queued). `reverse_charge_applies` is true only for a valid answer inside the trust window. The VAT number itself is not repeated.

• Permission: billing.read
• API token: not available, use a signed-in session

POST /api/v1/orgs/{org}/billing-profile/vat-check

Validate the VAT number now

Asks the registry about the saved VAT number once (at most one call per number every 30 seconds; a fresh answer is returned from storage). A registry outage is not an error: the answer is 200 with status `unverified`, the number stays accepted as entered and the worker retries with backoff. 404 while validation is switched off for the organisation; 429 `vat_check_rate_limited` after 5 checks an hour per organisation; 422 on `tax_id` when the saved tax ID is not an EU VAT number. Never blocks saving details or checkout.

• Permission: billing.manage
• API token: not available, use a signed-in session

GET /api/v1/catalog

Regions, plans, prices and images

Lists what can be ordered: active regions, plans with their current prices, operating-system images, the billing currency and the payment provider's public key. Hidden and retired plans are not shown.

• API token: not available, use a signed-in session

POST /api/v1/contacts/verify

Confirm a contact address

Confirms a contact with the token from the confirmation email. The person it was mailed to needs no account. An unknown, used or expired token returns token_invalid.

• Access: public, no authentication

Request body (JSON):

{
  "token": "string"
}

GET /api/v1/orgs/{org}/contacts

List contacts

Lists the organisation's contacts: addresses it wants told about billing, technical or security notices, with whether each has been confirmed.

• Permission: org.members.read
• API token: not available, use a signed-in session

POST /api/v1/orgs/{org}/contacts

Add a contact

Adds an address for billing, technical and/or security notices and emails it a confirmation link that works for 7 days. Nothing is sent to the address for the organisation until its owner confirms it. An address can be a contact once per organisation (409), and an organisation has at most 10 (409 contact_limit). Confirmation mail is limited: a re-add of the same address within five minutes is a resend (409 contact_recently_sent), one address gets at most 3 a day from all organisations and an organisation sends at most 20 a day, 5 for a personal one (429 contact_mail_limit).

• Permission: org.manage
• API token: not available, use a signed-in session

Request body (JSON):

{
  "email": "string",
  "kinds": [
    null
  ],
  "name": "string"
}

DELETE /api/v1/orgs/{org}/contacts/{contact}

Remove a contact

Removes a contact. It gets no further mail and its address is deleted.

• Permission: org.manage
• API token: not available, use a signed-in session

PATCH /api/v1/orgs/{org}/contacts/{contact}

Change a contact

Changes a contact's name and which kinds of notice it gets. The address itself cannot change: add a new contact, which its owner confirms. Narrowing the kinds keeps the confirmation; adding a kind resets it and mails a new link (subject to the same limits as adding).

• Permission: org.manage
• API token: not available, use a signed-in session

Request body (JSON):

{
  "kinds": [
    null
  ],
  "name": "string"
}

POST /api/v1/orgs/{org}/contacts/{contact}/resend

Send the contact's confirmation again

Mails a new confirmation link to an unconfirmed contact; the old link stops working. At most once in five minutes (409 contact_recently_sent). A confirmed contact answers 409.

• Permission: org.manage
• API token: not available, use a signed-in session

GET /api/v1/orgs/{org}/credit-notes

List the organisation's credit notes

Newest first. A credit note reverses part or all of one invoice and says where the money went (the account credit, or the card it was paid with and the state of that refund). The staff reason is not shown.

• Permission: billing.read
• API token: not available, use a signed-in session

GET /api/v1/orgs/{org}/credit-notes/{note}.pdf

Download a credit note as PDF

Rendered only from the issued credit note and the frozen snapshot of the invoice it reverses. Another organisation's credit note is a 404.

• Permission: billing.read
• API token: not available, use a signed-in session

DELETE /api/v1/orgs/{org}/deletion

Cancel a request to delete the organisation

An owner only. Stops a pending request; the owners and admins are emailed.

• Permission: org.manage
• API token: not available, use a signed-in session
• Session only: a person must be present

GET /api/v1/orgs/{org}/deletion

Whether the organisation can be deleted, and any request

As for your account, for this organisation. `allowed` is also false unless you are an owner.

• Permission: org.manage
• API token: not available, use a signed-in session
• Session only: a person must be present

POST /api/v1/orgs/{org}/deletion

Ask for the organisation to be deleted

An owner only (403 otherwise), never a personal organisation (personal_org). Confirm with the organisation's name. Refused with 409 deletion_blocked while servers, money, disputes or holds are in the way. The owners and admins are emailed; after the grace period the organisation's members, SSH keys, tokens, webhooks and variables are deleted and its tickets and billing contact are anonymised, and its invoices and ledger stay. Needs a recent step-up and a panel session.

• Permission: org.manage
• API token: not available, use a signed-in session
• Step-up: needs a recent password check
• Session only: a person must be present

Request body (JSON):

{
  "confirm": "string"
}

GET /api/v1/orgs/{org}/deposits

List recent top-ups

Lists recent account-credit top-ups and the minimum and maximum amount allowed for a new one.

• Permission: billing.read
• API token: not available, use a signed-in session

POST /api/v1/orgs/{org}/deposits

Add account credit

Creates a top-up and returns the card payment to confirm. Send a fresh Idempotency-Key per top-up: repeating it with the same amount returns the same top-up; with another amount it is a conflict.

• Permission: billing.manage
• API token: not available, use a signed-in session

Request body (JSON):

{
  "amount_minor": 0,
  "currency": "USD"
}

GET /api/v1/orgs/{org}/deposits/options

Ways to add account credit

Says which ways of adding account credit this organisation is offered. Card is always listed. PayPal is true only when staff have stored PayPal credentials and switched the paypal_enabled flag on for this organisation; until then the PayPal routes answer 404 as if they did not exist.

• Permission: billing.read
• API token: not available, use a signed-in session

POST /api/v1/orgs/{org}/deposits/paypal

Add account credit with PayPal

Creates a top-up paid with PayPal and returns the PayPal address the customer approves it at. Nothing is charged yet: after approval the customer returns to the panel, which calls the capture operation. Send a fresh Idempotency-Key per top-up (up to 90 characters): repeating it with the same amount returns the same top-up and the same PayPal order; with another amount it is a conflict. The amount limits and the US dollar currency are those of a card top-up. Answers 404 while PayPal is not offered to the organisation (credentials not stored or the paypal_enabled flag off), and 503 paypal_unavailable when PayPal cannot be reached (nothing was charged; repeat the request).

• Permission: billing.manage
• API token: not available, use a signed-in session

Request body (JSON):

{
  "amount_minor": 0,
  "currency": "USD"
}

POST /api/v1/orgs/{org}/deposits/{deposit}/paypal/capture

Finish a PayPal top-up after approval

Called when the customer comes back from PayPal. The core reads the PayPal order recorded for this top-up (the request names no order), checks that it is the order made for this top-up, in US dollars and for exactly its amount, and that the top-up can still be paid, and only then captures it and adds the credit. Nothing is captured for an expired, cancelled or mismatching top-up. Repeating the call for a paid top-up returns it unchanged. Answers 409 paypal_not_approved while the customer has not approved, 409 topup_not_payable after expiry, 409 paypal_declined when PayPal declines, and 404 while PayPal is not offered or for a top-up of another organisation. A payment PayPal holds for review stays awaiting_payment until PayPal completes it.

• Permission: billing.manage
• API token: not available, use a signed-in session

GET /api/v1/orgs/{org}/exports

The organisation's data exports

The organisation's exports, newest first. Needs the manage permission (owner or admin). Panel session only.

• Permission: org.manage
• API token: not available, use a signed-in session
• Session only: a person must be present

POST /api/v1/orgs/{org}/exports

Ask for a copy of the organisation's data

Queues an export of one organisation's data (members, billing profile, servers, invoice references, support tickets, SSH keys, API token and webhook metadata, activity) as a zip of JSON files. Never another organisation's data, a secret, a signing secret or a variable. Needs the manage permission, a recent step-up, a panel session, and at most three a day for you.

• Permission: org.manage
• API token: not available, use a signed-in session
• Step-up: needs a recent password check
• Session only: a person must be present

GET /api/v1/orgs/{org}/exports/{export}

One organisation data export

State, size, checksum and expiry of one of the organisation's exports. 404 for another organisation's.

• Permission: org.manage
• API token: not available, use a signed-in session
• Session only: a person must be present

POST /api/v1/orgs/{org}/exports/{export}/download-link

Get a short-lived download link for an organisation export

As for a personal export. The link is used at /api/v1/me/export-downloads/{token}, and works only for someone who still has the manage permission when they use it.

• Permission: org.manage
• API token: not available, use a signed-in session
• Step-up: needs a recent password check
• Session only: a person must be present

GET /api/v1/orgs/{org}/features

Which features are on for the organisation

The effective value of every feature flag for this organisation, from the cached values (a staff change reaches here within 30 seconds). A flag the platform does not define is not listed and counts as off.

• Permission: org.read
• API token: not available, use a signed-in session

GET /api/v1/orgs/{org}/firewall-groups

List firewall rule groups

Lists the organisation's rule groups with their rule counts and the number of policies using each, ordered by name.

• Permission: servers.read
• API token scope: firewall:read

Example:

curl -X GET "$VEXELIA_URL/api/v1/orgs/$org/firewall-groups" \
  -H "Authorization: Bearer $VEXELIA_TOKEN"

POST /api/v1/orgs/{org}/firewall-groups

Create a firewall rule group

A group is an ordered rule list that is defined once and used by several firewall policies. At most 50 groups per organisation and 200 rules per group. Creating a group sends nothing to any server.

• Permission: servers.manage
• API token scope: firewall:write

Request body (JSON):

{
  "description": "string",
  "name": "string",
  "rules": [
    null
  ]
}

Example:

curl -X POST "$VEXELIA_URL/api/v1/orgs/$org/firewall-groups" \
  -H "Authorization: Bearer $VEXELIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description":"string","name":"string","rules":[null]}'

DELETE /api/v1/orgs/{org}/firewall-groups/{group}

Delete a rule group

Refused with 409 firewall_group_in_use while any firewall policy uses the group.

• Permission: servers.manage
• API token scope: firewall:write

Example:

curl -X DELETE "$VEXELIA_URL/api/v1/orgs/$org/firewall-groups/$group" \
  -H "Authorization: Bearer $VEXELIA_TOKEN"

GET /api/v1/orgs/{org}/firewall-groups/{group}

Get a rule group with its rules, policies and servers

Returns the group's rules in evaluation order, the policies using it and every server that gets its rules with how far each has applied them. The version field is what If-Match takes on a later change.

• Permission: servers.read
• API token scope: firewall:read

Example:

curl -X GET "$VEXELIA_URL/api/v1/orgs/$org/firewall-groups/$group" \
  -H "Authorization: Bearer $VEXELIA_TOKEN"

PATCH /api/v1/orgs/{org}/firewall-groups/{group}

Change a rule group and send it to every server using it

Changing the rules bumps the version of every policy using the group and queues one apply per server using those policies; a busy server is applied as soon as it is free and shows pending. Refused with 409 firewall_too_many_rules when a policy using the group would pass 200 rules (its own plus its groups'); the message in fields.rules names the policy and a server, and nothing is changed. Refused with 409 firewall_lockout when it newly blocks the caller's own SSH on a server (acknowledge_lockout to apply anyway), and with 409 firewall_version_conflict when If-Match names an older version. A rename queues nothing.

• Permission: servers.manage
• API token scope: firewall:write

Request body (JSON):

{
  "description": "string",
  "name": "string",
  "rules": [
    null
  ]
}

Example:

curl -X PATCH "$VEXELIA_URL/api/v1/orgs/$org/firewall-groups/$group" \
  -H "Authorization: Bearer $VEXELIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description":"string","name":"string","rules":[null]}'

GET /api/v1/orgs/{org}/firewall-presets

List the firewall presets

The shipped starting sets: web server, SSH from one address, mail server, and block everything. A preset expands into ordinary rules that can then be edited; nothing remembers where a rule came from.

• Permission: servers.read
• API token scope: firewall:read

Example:

curl -X GET "$VEXELIA_URL/api/v1/orgs/$org/firewall-presets" \
  -H "Authorization: Bearer $VEXELIA_TOKEN"

GET /api/v1/orgs/{org}/firewalls

List firewall policies

Lists the organisation's firewall policies with their rule counts and the number of servers using each, ordered by name (case-insensitive) with the id as tiebreak. Without limit and cursor every policy is returned; with them the list is cursor paged (limit 1 to 200) and next_cursor is the cursor for the next page, null on the last. The rules of one policy are returned with it, at most 200 in evaluation order, and are not paged.

• Permission: servers.read
• API token scope: firewall:read

Example:

curl -X GET "$VEXELIA_URL/api/v1/orgs/$org/firewalls" \
  -H "Authorization: Bearer $VEXELIA_TOKEN"

POST /api/v1/orgs/{org}/firewalls

Create a firewall policy

A new policy allows traffic in both directions until its rules and defaults say otherwise; locking down (inbound default drop) is an explicit choice. At most 50 policies per organisation.

• Permission: servers.manage
• API token scope: firewall:write

Request body (JSON):

{
  "default_inbound": "accept",
  "default_outbound": "accept",
  "description": "string",
  "name": "string"
}

Example:

curl -X POST "$VEXELIA_URL/api/v1/orgs/$org/firewalls" \
  -H "Authorization: Bearer $VEXELIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"default_inbound":"accept","default_outbound":"accept","description":"string","name":"string"}'

DELETE /api/v1/orgs/{org}/firewalls/{firewall}

Delete a firewall policy

Refused with firewall_in_use while a provisioning, active or suspended server uses the policy. Terminated or failed servers that still name it are detached as it is deleted.

• Permission: servers.manage
• API token scope: firewall:write

Example:

curl -X DELETE "$VEXELIA_URL/api/v1/orgs/$org/firewalls/$firewall" \
  -H "Authorization: Bearer $VEXELIA_TOKEN"

GET /api/v1/orgs/{org}/firewalls/{firewall}

Get a firewall policy with its rules and servers

Returns one firewall with its rules in evaluation order, the servers using it, and a lockout warning when the policy would block SSH. The version field is what If-Match takes on a later change.

• Permission: servers.read
• API token scope: firewall:read

Example:

curl -X GET "$VEXELIA_URL/api/v1/orgs/$org/firewalls/$firewall" \
  -H "Authorization: Bearer $VEXELIA_TOKEN"

PATCH /api/v1/orgs/{org}/firewalls/{firewall}

Rename a firewall policy or change its defaults

Changing a default queues an apply on every server using the policy. A rename queues nothing. A change that newly blocks the caller's own SSH on a server using the policy is refused with 409 firewall_lockout (the sentence is in fields.lockout) unless acknowledge_lockout is true. With If-Match naming the version you saw, a changed policy answers 409 firewall_version_conflict.

• Permission: servers.manage
• API token scope: firewall:write

Request body (JSON):

{
  "default_inbound": "accept",
  "default_outbound": "accept",
  "description": "string",
  "name": "string"
}

Example:

curl -X PATCH "$VEXELIA_URL/api/v1/orgs/$org/firewalls/$firewall" \
  -H "Authorization: Bearer $VEXELIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"default_inbound":"accept","default_outbound":"accept","description":"string","name":"string"}'

PUT /api/v1/orgs/{org}/firewalls/{firewall}/groups

Set the rule groups a firewall policy uses

Replaces the policy's groups with the list given, each at a position (the number of the policy's own rules, per direction, that come before the group's rules there). The group's rules count toward the policy's 200-rule limit; a list that would pass it is refused with 409 firewall_too_many_rules, naming a server. Queues an apply on every server using the policy. Refused with 409 firewall_lockout (acknowledge_lockout to apply anyway) and 409 firewall_version_conflict as for rule changes. A group from another organisation answers 404.

• Permission: servers.manage
• API token scope: firewall:write

Request body (JSON):

{
  "groups": [
    null
  ]
}

Example:

curl -X PUT "$VEXELIA_URL/api/v1/orgs/$org/firewalls/$firewall/groups" \
  -H "Authorization: Bearer $VEXELIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"groups":[null]}'

GET /api/v1/orgs/{org}/firewalls/{firewall}/lockout-check

Whether the policy would block your own SSH connection

Follows the policy's inbound rules for a TCP connection to port 22 from the address the API sees you at, and says what decides it. Advisory: the address is yours only if you connect to the server from where you use the panel. The source and the verdict are null when the API has no address that could be yours (a private or loopback address). The same check refuses changes that newly block you.

• Permission: servers.read
• API token scope: firewall:read

Example:

curl -X GET "$VEXELIA_URL/api/v1/orgs/$org/firewalls/$firewall/lockout-check" \
  -H "Authorization: Bearer $VEXELIA_TOKEN"

POST /api/v1/orgs/{org}/firewalls/{firewall}/presets/{preset}

Apply a preset to a firewall policy

Writes the preset into the policy as ordinary rules (replace or append, said in the request) and queues an apply on every server using the policy. Refused with 409 firewall_limit when the rules would not fit, firewall_lockout when it would newly block your own SSH on a server using the policy (acknowledge_lockout to apply anyway), and firewall_version_conflict when If-Match names an older version.

• Permission: servers.manage
• API token scope: firewall:write

Request body (JSON):

{
  "address": "string",
  "mode": "replace"
}

Example:

curl -X POST "$VEXELIA_URL/api/v1/orgs/$org/firewalls/$firewall/presets/$preset" \
  -H "Authorization: Bearer $VEXELIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"address":"string","mode":"replace"}'

POST /api/v1/orgs/{org}/firewalls/{firewall}/presets/{preset}/preview

What applying a preset would change

Writes nothing. replace removes every rule the policy has and sets the preset's defaults; append adds the preset's rules after the existing ones and leaves the defaults. A preset that asks for an address answers 422 on address when it is missing or not an address.

• Permission: servers.read
• API token scope: firewall:read

Request body (JSON):

{
  "address": "string",
  "mode": "replace"
}

Example:

curl -X POST "$VEXELIA_URL/api/v1/orgs/$org/firewalls/$firewall/presets/$preset/preview" \
  -H "Authorization: Bearer $VEXELIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"address":"string","mode":"replace"}'

POST /api/v1/orgs/{org}/firewalls/{firewall}/rules

Add a rule at the end of a direction

Validates the rule, then queues an apply on every server using the policy. Addresses may be CIDR blocks, single IPv4 or IPv6 addresses, or ranges; ranges are stored as the fewest CIDR blocks that cover them. At most 200 rules per policy. Rules cannot match link-local or multicast addresses, which Vexelia manages for the server. Refused with 409 firewall_lockout when it newly blocks the caller's own SSH (see PATCH on the policy), and with 409 firewall_version_conflict when If-Match names an older version.

• Permission: servers.manage
• API token scope: firewall:write

Request body (JSON):

{}

Example:

curl -X POST "$VEXELIA_URL/api/v1/orgs/$org/firewalls/$firewall/rules" \
  -H "Authorization: Bearer $VEXELIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

POST /api/v1/orgs/{org}/firewalls/{firewall}/rules/reorder

Set the order of the rules in one direction

The list must name every rule of that direction exactly once, highest priority first; otherwise 422 on rule_ids, so a stale editor cannot drop a rule added elsewhere.

• Permission: servers.manage
• API token scope: firewall:write

Request body (JSON):

{
  "direction": "inbound",
  "rule_ids": [
    null
  ]
}

Example:

curl -X POST "$VEXELIA_URL/api/v1/orgs/$org/firewalls/$firewall/rules/reorder" \
  -H "Authorization: Bearer $VEXELIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"direction":"inbound","rule_ids":[null]}'

DELETE /api/v1/orgs/{org}/firewalls/{firewall}/rules/{rule}

Remove a rule

Closes the gap in the order and queues an apply on every server using the policy. Answers with the policy.

• Permission: servers.manage
• API token scope: firewall:write

Example:

curl -X DELETE "$VEXELIA_URL/api/v1/orgs/$org/firewalls/$firewall/rules/$rule" \
  -H "Authorization: Bearer $VEXELIA_TOKEN"

PATCH /api/v1/orgs/{org}/firewalls/{firewall}/rules/{rule}

Change a rule

Changes one rule. Send only the fields to change. A change that would cut your own SSH answers 409 firewall_lockout unless acknowledge_lockout=true.

• Permission: servers.manage
• API token scope: firewall:write

Request body (JSON):

{}

Example:

curl -X PATCH "$VEXELIA_URL/api/v1/orgs/$org/firewalls/$firewall/rules/$rule" \
  -H "Authorization: Bearer $VEXELIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

POST /api/v1/orgs/{org}/floating-ip-charges/{charge}/pay

Pay for buying a floating IP

Pays a floating IP charge: wallet credit is held first, then one card intent covers the rest (the client secret is returned for Stripe.js), or the charge settles at once when credit covers it. Settlement issues an invoice, takes an address from the location's pool and makes the floating IP (billed from then), and voids the renewal that was issued without it. If the pool ran out between the quote and the payment the charge is credited back whole to the wallet. Repeating the call shows the same intent. quote_expired after 30 minutes (ask again), paid_period_ended if a renewal settled or the period ended since the quote, amount_below_minimum when the card part is below what the processor can charge.

• Permission: servers.manage
• API token: not available, use a signed-in session
• Step-up: needs a recent password check

Request body (JSON):

{
  "payment_method": "00000000-0000-0000-0000-000000000000"
}

GET /api/v1/orgs/{org}/floating-ips

Every floating IP of the organisation, with price and limits

The organisation's floating IPs (the Floating IPs page), newest first, with the server that pays for each, the one it is assigned to and, during a reassign, the one waiting for it; the monthly price of one, the monthly total, the floating IP limit, open_charges (floating IP charges waiting to be paid: quoted and not yet expired; pay one with POST .../floating-ip-charges/{charge}/pay until expires_at) and servers, the active servers a floating IP can be bought for or assigned to, each with an opaque location label. A floating IP is a routable IPv4 address that belongs to the organisation and can be assigned to any of its servers in the same location (equal location labels), one at a time; it is not part of any server and outlives the server it is on. Released floating IPs are not listed.

• Permission: servers.read
• API token scope: servers:read

Example:

curl -X GET "$VEXELIA_URL/api/v1/orgs/$org/floating-ips" \
  -H "Authorization: Bearer $VEXELIA_TOKEN"

POST /api/v1/orgs/{org}/floating-ips

Buy a floating IP

Prices a new floating IP named name, bought for the server server_id, whose subscription pays for it and whose location the address comes from. The charge is the monthly price for the rest of the period the customer has paid for (remaining over total as an exact duration, rounded half up once), plus tax. The response carries it as charge, which stands for 30 minutes and is paid with POST .../floating-ip-charges/{charge}/pay (credit first, then card or 3-D Secure); the floating IP and its address exist and are billed only after payment settles. A charge below the minimum a card can be charged is added to the next renewal invoice instead (deferred is true and the floating IP exists at once), and a charge of zero makes it at once (charge is null). The renewal after the paid period bills it whole, on that server's subscription. The new floating IP is not assigned to any server; assign it with POST .../assign. Asking again for the same name while the quote stands returns the same quote. Refused with floating_ip_name_taken when one has the name, floating_ip_limit at the limit, floating_ip_no_pool when the location has no floating address to give, floating_ip_host_unsupported when no active host in the location reports that it applies floating IPs, renewal_charging while the server's renewal is being paid, volume_charge_open while another volume or floating IP charge is waiting to be paid, server_not_active when the server is not an active VPS, paid_period_ended when the paid period has ended. Answers 503 tax_unavailable while tax cannot be worked out yet for the buyer's location; nothing is created or charged.

• Permission: servers.manage
• API token: not available, use a signed-in session
• Step-up: needs a recent password check

Request body (JSON):

{
  "name": "string",
  "server_id": "00000000-0000-0000-0000-000000000000"
}

DELETE /api/v1/orgs/{org}/floating-ips/{floating_ip}

Release a floating IP

Gives a floating IP that is not assigned back to the pool: the address goes into quarantine for 7 days like a server's, and any reverse DNS record for it is removed. It happens at once (no host is involved). There is no credit for the rest of the paid period (decision 0008 applied), so the period stands as paid and the next renewal no longer bills it. A floating IP a server holds is never released this way: it is refused with floating_ip_assigned (unassign it first), so a delete can not take an address off a live server. Refused with floating_ip_busy while it is changing.

• Permission: servers.manage
• API token: not available, use a signed-in session
• Step-up: needs a recent password check

GET /api/v1/orgs/{org}/floating-ips/{floating_ip}

One floating IP

One floating IP of the organisation, as the list shows it. A released floating IP is a 404.

• Permission: servers.read
• API token scope: servers:read

Example:

curl -X GET "$VEXELIA_URL/api/v1/orgs/$org/floating-ips/$floating_ip" \
  -H "Authorization: Bearer $VEXELIA_TOKEN"

POST /api/v1/orgs/{org}/floating-ips/{floating_ip}/assign

Assign a floating IP to a server

Assigns an unassigned floating IP to the server server_id. The server's host routes the address to the server and lets it send from it; the guest is not configured, so the address must be added inside the guest (as an extra address on its network interface). The server must be an active VPS in the floating IP's location whose host reports that it applies floating IPs. The assign is one operation: the floating IP reads assigning until the host answers, assigned after, and unassigned again with error_code if it could not. Reverse DNS set for the address follows it to the server. Refused with floating_ip_assigned when it is assigned already, floating_ip_busy while it is changing, floating_ip_other_group when the server is in another location, floating_ip_server_full when the server holds as many as a server may, floating_ip_billing_ended when the server that pays for the floating IP has ended (release it, or contact support to move its billing), floating_ip_other_node when the server is on another host from the one the address was first assigned on (unless staff allowed the pool to move between hosts), server_not_active when the server is not an active VPS, renewal_charging while its renewal is being paid, floating_ip_host_unsupported when the host has not reported that it applies floating IPs (an older host software version), server_busy while another action runs on the server.

• Permission: servers.manage
• API token: not available, use a signed-in session
• Step-up: needs a recent password check

Request body (JSON):

{
  "server_id": "00000000-0000-0000-0000-000000000000"
}

POST /api/v1/orgs/{org}/floating-ips/{floating_ip}/reassign

Move a floating IP to another server

Moves the floating IP from the server that holds it to server_id, another active server in the same location. It is two host operations in order, so two servers never answer for the address: the address is taken off the first server (one operation, queued now) and, when the host has done that, put on the second (queued by the platform shortly after). The address is unreachable between the two. Because it stops working on the first server at once, the body must say confirm true (floating_ip_confirm_required otherwise). While waiting, the floating IP is unassigned with target_server_id set; if the new server ends or can not take it within 24 hours the move is dropped, the floating IP stays unassigned and error_code says why. Reverse DNS follows the address to the new server. The new server is checked with exactly the rules an assign applies, before anything is done to the first one, so a move that could not finish never takes the address off. Refused as assign and unassign are, and with a 422 on server_id when it is the server that holds it now.

• Permission: servers.manage
• API token: not available, use a signed-in session
• Step-up: needs a recent password check

Request body (JSON):

{
  "confirm": false,
  "server_id": "00000000-0000-0000-0000-000000000000"
}

POST /api/v1/orgs/{org}/floating-ips/{floating_ip}/unassign

Take a floating IP off its server

Takes the floating IP off the server that holds it. Traffic to the address stops reaching that server as soon as the host has applied it, so the body must say confirm true: without it nothing happens and the answer is floating_ip_confirm_required. The floating IP stays the organisation's and stays billed; it can be assigned again or released. Refused with floating_ip_not_assigned when no server holds it, floating_ip_busy while it is changing, floating_ip_host_unsupported when the host has not reported that it applies floating IPs, server_busy while another action runs on the server.

• Permission: servers.manage
• API token: not available, use a signed-in session
• Step-up: needs a recent password check

Request body (JSON):

{
  "confirm": false
}

POST /api/v1/orgs/{org}/game-orders

Order a game server

Orders a game server on a game plan: the plan's price, a region, a name and the game (template_id) the plan runs, with optional automatic renewal. Needs a verified email (email_unverified). Priced, taxed and paid like a server order (credit is held, then the card is charged); answers 201 with the order and a client_secret when a card payment is needed. Startup variables that break the game's rules refuse the order (422, field variables.KEY) before anything is held. Refused with no_capacity when no game node in the region has room, and with game_unavailable when that game cannot be built right now (no published version or no signed image), in which case nothing is charged. When payment arrives the server is built; if it cannot be built as bought the payment is refunded. A token is never allowed to order.

• Permission: games.manage
• API token: not available, use a signed-in session

Request body (JSON):

{
  "autopay": false,
  "name": "string",
  "price_id": "00000000-0000-0000-0000-000000000000",
  "region": "string",
  "template_id": "string",
  "variables": {}
}

GET /api/v1/orgs/{org}/game-orders/{order}

Get a game server order

Returns a game server order and, once paid, the server id and how its setup stands (setup: provisioning, active or failed). A VPS order, or an order of another organisation, is not found. Poll it after placing an order.

• Permission: games.read
• API token: not available, use a signed-in session

GET /api/v1/game-plans

Game plans on sale, with slots, resources and prices

Only plans that are active and have a price in force. Hidden and retired plans never appear. With the template registry present, a plan whose every template was removed is left out, and the template query parameter keeps only plans big enough for that template. Buying a game server is a later milestone.

• API token: not available, use a signed-in session

GET /api/v1/game-templates

Games on sale, with the startup variables a customer may set

The newest published version of every game that a plan on sale runs, with the startup variables the customer may set when ordering (editable ones that are not secrets), each with its type, default and limits, so the order page can offer the right control. The server checks every value again when the order is placed. A secret is set once the server exists (has_secrets says the game has one). Nothing of the installer, the image or the start command is shown.

• API token: not available, use a signed-in session

GET /api/v1/orgs/{org}/games

List game servers

The organisation's game servers, newest first, with the state the node last reported. Creating one is part of the purchase flow.

• Permission: games.read
• API token: not available, use a signed-in session

GET /api/v1/orgs/{org}/games/{game}

Show a game server

The server with its resources, ports and startup variables. Secret variables show only whether one is set. A server of another organisation, or a VPS, is not found.

• Permission: games.read
• API token: not available, use a signed-in session

PATCH /api/v1/orgs/{org}/games/{game}

Rename a game server or change its variables

Fields left out keep their value. Variables are checked against the template's types and limits; a variable that is read-only, unknown, or no longer declared by the template is refused, and one refusal rejects the whole change. A change is recorded in Activity by key; for a secret only that it changed.

• Permission: games.manage
• API token: not available, use a signed-in session

Request body (JSON):

{
  "name": "string",
  "variables": {}
}

GET /api/v1/orgs/{org}/games/{game}/access

List who has been given access to a game server

The server's invitations and guests (live ones first, then the last ones that ended), the five rights a grant can carry, which of them the caller may give (`grantable`: a right is given only by someone who holds it), and the limits. A guest is another account with a scoped part of one server and no membership of the organisation. A server of another organisation is not found. Needs games.subusers (owners and admins by default); no API token scope opens it. State: integrated on fakes.

• Permission: games.subusers
• API token: not available, use a signed-in session

POST /api/v1/orgs/{org}/games/{game}/access

Invite another account to a game server

Invites the person at `email` with one or more rights: console, power, files, backups, schedules. They are sent an email (no link that works by itself: they sign in with that address, or create an account with it, and accept on the Games page), and the invitation can be accepted for 14 days. Seeing the server, its state, address and graphs is implied. A right is given only by someone who holds it (grant_escalation otherwise), and the check is made again when the invitation is accepted (invite_inviter_changed if the person who set it can no longer give it). Needs step-up. Refused with subuser_exists for a person with a live invitation or access, and subuser_limit_reached at the server's limit (an invitation past its time is closed first and does not count). The email goes to an address that may not have asked for it, so the MAIL is limited: one an hour to the same address for the same server, three a day to one address across all organisations, ten a day from one person and twenty a day from one organisation (counted in keyed fingerprints, never the address; plus-tags and gmail dots do not make a new address). A limit never blocks the invitation: it is still made and listed (and the person sees it under their own invitations), and the answer says `mail_sent: false`. The names in the mail are quoted and marked as the sender's. Audited as game.subuser_invited, with no address in the event. Needs games.subusers. State: integrated on fakes.

• Permission: games.subusers
• API token: not available, use a signed-in session
• Step-up: needs a recent password check

Request body (JSON):

{
  "email": "string",
  "permissions": [
    null
  ]
}

DELETE /api/v1/orgs/{org}/games/{game}/access/{grant}

Revoke an invitation or a grant on a game server

Ends a pending invitation or an active grant. It takes effect on the guest's next request, and any console they have open on the server ends at the gateway's next heartbeat. Needs no step-up: taking access away is never held up. A short-lived SFTP credential the guest already holds stays valid until it expires (10 minutes; the SFTP service itself is not built). Audited as game.subuser_revoked. Needs games.subusers. State: integrated on fakes.

• Permission: games.subusers
• API token: not available, use a signed-in session

PUT /api/v1/orgs/{org}/games/{game}/access/{grant}

Change what an invited account may do on a game server

Replaces the rights of a pending or active grant. The new set must be one the caller holds in full (grant_escalation). It is read on every request, so a right taken away is gone on the guest's next one, and a console that was open when the console right is taken away ends at the gateway's next heartbeat (within seconds). Needs step-up. Audited as game.subuser_changed. Needs games.subusers. State: integrated on fakes.

• Permission: games.subusers
• API token: not available, use a signed-in session
• Step-up: needs a recent password check

Request body (JSON):

{
  "permissions": [
    null
  ]
}

GET /api/v1/orgs/{org}/games/{game}/backups

List a game server's backups

The server's backups, newest first (at most 200; a deleted one is not listed), the restores asked for on it (the latest 20), what the plan allows (`limits.backups` backups at once, `limits.used` held now, `limits.max_locked` of them lockable, one slot always stays free so a scheduled backup can replace the oldest), and why a new backup or a restore would be refused right now (`can_create`, `can_restore`) so the panel can say so first. A backup is a copy of the server's data directory only: never its environment, its startup command, its secret variables or the host's files. It IS the whole data directory, so a config file the game keeps a secret in is in it, encrypted under your organisation's key; a game's template can name such files to leave out. State pending means waiting for the host; running, the host is archiving it; ready, its manifest was read back and checked; failed, with `error_code` (store_unavailable, backup_too_large, backup_too_many_files, node_no_backups, window_missed, server_busy, superseded and others); deleting, its stored objects are being removed. A ready backup may carry `error_code` resume_failed: the game did not confirm that writes were switched back on after the backup, so restart the server. `quiesced` says whether the game confirmed it had stopped writing first; false means the copy is crash-consistent (like a power cut), which games recover from. A server of another organisation is not found. Needs games.backups; no API token scope opens it. State: integrated on fakes; no real container node, object store or key service has run this.

• Permission: games.backups
• API token: not available, use a signed-in session

POST /api/v1/orgs/{org}/games/{game}/backups

Back a game server up now

Records a backup as pending and answers 202; the worker queues the host's job as soon as the server's lane is free. Only one backup of a server waits or runs at a time (backup_in_progress), and while it runs a graceful stop or restart answers server_busy (a kill still works and ends the backup as superseded). Works while the server runs (the template's save commands are sent first and resume afterwards) and while it is stopped. A manual backup at the plan's count is refused with backup_limit_reached: delete one first (a scheduled backup at the count goes ahead if an unlocked scheduled one can be replaced, and only once it is verified ready does the oldest go: a failed backup never costs a restore point); backups of a plan that has none are refused with backups_not_included. Refused with backup_daily_cap (429) after twice the plan's count of backups in 24 hours, whatever became of them, and with server_not_active unless the server is active, and backups_host_unsupported when the host's software has not reported that it makes backups (nothing is queued). The size is capped by the plan's disk and the platform's own ceiling; a larger one fails as backup_too_large. A backup is encrypted with a key that belongs to your organisation before it leaves the host. A server of another organisation is not found. Needs games.backups.

• Permission: games.backups
• API token: not available, use a signed-in session

Request body (JSON):

{
  "name": "string"
}

DELETE /api/v1/orgs/{org}/games/{game}/backups/{backup}

Delete a game server backup

Marks a ready or failed backup for deletion and answers 202; the worker then removes every stored object with the credential only it holds, and the backup disappears from the list. A locked backup is refused with backup_locked; one that is still waiting or running with backup_state (as is one a restore is waiting on or running from). A backup of another server or organisation is not found. Needs games.backups.

• Permission: games.backups
• API token: not available, use a signed-in session

PATCH /api/v1/orgs/{org}/games/{game}/backups/{backup}

Lock or unlock a game server backup

A locked backup is never removed by retention and cannot be deleted until it is unlocked. At most one fewer than the plan's count may be locked (backup_lock_limit), so a scheduled backup can always replace the oldest unlocked one. A failed or deleting backup cannot be locked (backup_state). A backup of another server or organisation is not found. Needs games.backups.

• Permission: games.backups
• API token: not available, use a signed-in session

Request body (JSON):

{
  "locked": false
}

POST /api/v1/orgs/{org}/games/{game}/backups/{backup}/restore

Restore a backup over a stopped game server

Replaces the server's files with the backup's and answers 202; the worker queues the host's job. The server must be stopped (offline or crashed) when this is asked and again when the job is queued, or the restore fails as server_not_stopped with nothing changed (restore_needs_stopped answers now). Needs step-up and the server's name in `confirm_name` (case and spaces do not matter; validation_failed otherwise). The host first reads and checks every part of the backup and unpacks it beside the live files; a damaged backup is refused (corrupt) with the server's files untouched. The files it replaces are kept beside them on the host as the pre-restore copy until the next restore. The server stays in state restoring until the host reports; a restore left in review is shown to support. Only one restore of a server is open at a time (restore_in_progress). Refused with backup_state unless the backup is ready. A backup of another server or organisation is not found. Needs games.backups. State: integrated on fakes; the pre-restore copy's 72-hour removal, the quota and ownership of the staging directory and a real object store are not built or run.

• Permission: games.backups
• API token: not available, use a signed-in session
• Step-up: needs a recent password check

Request body (JSON):

{
  "confirm_name": "string"
}

GET /api/v1/orgs/{org}/games/{game}/config

List the config files of a game server that the editor can open

The files the server's signed template declares as editable (`config_editors`), with the format each is checked against and whether a save needs a restart. `managed_keys` are keys the platform itself sets at every start (the template's `config_files`), which an edit to them does not survive. Needs games.files and a server whose node is reachable (the refusals of the file list apply). Built on the file manager's typed requests (GF-1), and integrated on fakes only: it has not run against a real container node.

• Permission: games.files
• API token: not available, use a signed-in session

GET /api/v1/orgs/{org}/games/{game}/config/file

Open a config file of a game server with its saved versions

Returns the text, the `version` to send back when saving, and the saved versions (newest first, without their text). A file that does not exist yet comes back with `exists` false and empty text. A path the template does not declare is config_path_unknown (404). Opening is recorded in Activity by path and size, never content.

• Permission: games.files
• API token: not available, use a signed-in session

PUT /api/v1/orgs/{org}/games/{game}/config/file

Save a config file of a game server after checking its syntax

Checks the text against the file's format first (json, yaml, properties and ini; `text` is not checked) and refuses a syntax error with validation_failed, naming the line in `fields.content`; nothing is written. Writes over the `version` that was opened (file_conflict, 409, if the file changed since; a file that does not exist is created and takes no version) through the file manager's atomic write, so the denylist, quota and ownership rules apply. What the file held before is kept first when no saved version is that text (as `baseline`, or `external` if it was changed elsewhere), then the new text is kept as a version; the newest 20 per file are kept. The text of a version is sealed, because a config file can hold a password. `restart_required` is the hint to restart the server for the change to apply. Saving the text the file already holds changes nothing (`changed` false). Recorded in Activity by path, size and the number of lines changed, never the text.

• Permission: games.files
• API token: not available, use a signed-in session

Request body (JSON):

{
  "content": "string",
  "path": "string",
  "version": "string"
}

POST /api/v1/orgs/{org}/games/{game}/config/undo

Restore an earlier saved version of a config file

Writes a saved version back as the file, the same way a save does: over the `version` the editor last saw (file_conflict if it changed), keeping what is there first so the undo can itself be undone, and recording the restore as a new version of source `undo`. Recorded in Activity.

• Permission: games.files
• API token: not available, use a signed-in session

Request body (JSON):

{
  "path": "string",
  "version": "string",
  "version_id": "00000000-0000-0000-0000-000000000000"
}

GET /api/v1/orgs/{org}/games/{game}/config/version

Read one saved version of a config file

The text of one saved version, to look at before restoring it. Another file's version, or another server's, is not found.

• Permission: games.files
• API token: not available, use a signed-in session

POST /api/v1/orgs/{org}/games/{game}/console

Get a single-use token to open a game server's console

Returns a token valid for 60 seconds and one connection, and the edgegw WebSocket URL for the game server's text console: the container's output, and its standard input for the commands the person types. The browser opens `new WebSocket(ws_url, [protocol, token])`; the token travels in Sec-WebSocket-Protocol and never in a URL. edgegw verifies the token, refuses a second use, and checks the person's games.manage permission, the server and the caps again when the token is used and while the session lasts; the node verifies the token again. A new session starts with the recent output the node saw (not a durable log). What is typed or shown is never recorded. Refused with console_server_stopped (the server is not running), console_server_suspended, server_not_active (still being set up), server_busy (being created or removed), console_node_unreachable or console_session_limit (one session per server, four per person), and console_unavailable while the console is turned off. A server of another organisation, or a VPS, is not found. State: GC-1 is integrated on fakes only. On a real container runtime the console does NOT work yet: Containerd.Attach is read-only and reaches EOF immediately (it reads the existing log once, does not tail it, and refuses input), so it works only after GH-R4 (containerd console attach: tail the log + stdin).

• Permission: games.manage
• API token: not available, use a signed-in session
• Session only: a person must be present

Request body (JSON):

{}

POST /api/v1/orgs/{org}/games/{game}/destroy

Destroy a game server

Ends the server and its billing and asks the node to remove it; when the node confirms, its address range and ports are given back. Needs the server's name in confirm_name and a recent step-up. Refused with server_not_active while the server is still being set up, and with server_protected while it is marked do-not-destroy. There is no trash: a destroyed game server's data is gone.

• Permission: servers.destroy
• API token: not available, use a signed-in session
• Step-up: needs a recent password check

Request body (JSON):

{
  "confirm_name": "string"
}

GET /api/v1/orgs/{org}/games/{game}/eula

Show a game server's EULA and whether it is accepted

Returns the current EULA text for the server's game and whether this server has accepted that version, and by whom and when. Returns eula_unavailable when no text is published for the game. A server of another organisation is not found.

• Permission: games.read
• API token: not available, use a signed-in session

POST /api/v1/orgs/{org}/games/{game}/eula

Accept a game server's current EULA

Records that the signed-in customer accepted the given EULA version for this server (who, organisation, time, version, text hash and address). The version must be the current one, otherwise eula_version_changed: read the new text and accept it. A new version needs a new acceptance before the next start. Accepting again is a no-op. A panel session only: an API token or a staff viewing session cannot accept.

• Permission: games.manage
• API token: not available, use a signed-in session
• Session only: a person must be present

Request body (JSON):

{
  "version": 0
}

GET /api/v1/orgs/{org}/games/{game}/files

List a folder of a game server

Lists the folder at `path` (default: the server's data directory). The node lists at most 5000 items: the first 5000 by name, then shown folders first within that page, so the page is the same each time; `truncated` says there were more. Every path is relative to the server's own data directory: `..`, `.`, backslashes and control characters are refused with file_path_invalid, and a leading slash is read as the data directory, never as the host. A symbolic link is listed as kind `link` and a device, pipe or socket as `special`; neither is ever followed or opened. Files the template denies (file_denylist) are not listed. Works while the server is stopped or running. Refused with files_node_unreachable (the host is away; nothing is lost), server_busy (being created, removed, installed, moved or restored), files_server_suspended, files_busy (two requests per server and six per organisation at once) or files_unavailable (turned off), files_node_unsupported (the host's vexd does not report the file capability, so nothing is sent to it). Anything that changes files, and anything that reads file content (read, download, archive), is also refused with files_unavailable when the template's file denylist cannot be found for the server; only this listing (names and sizes) still works. A server of another organisation is not found. Needs games.files; no API token scope opens it. State: GF-1 is integrated on fakes only; it has not run against a real container node.

• Permission: games.files
• API token: not available, use a signed-in session

GET /api/v1/orgs/{org}/games/{game}/files/archive

Download a file or folder of a game server as a zip

A zip of the file or folder at `path` ("" is the whole data directory) of at most 2000 entries, 16 MiB uncompressed and 2 MiB zipped (archive too large is file_too_large). Links, devices and denied files are left out. Recorded in Activity before any byte is sent.

• Permission: games.files
• API token: not available, use a signed-in session

GET /api/v1/orgs/{org}/games/{game}/files/content

Read a text file of a game server

Returns the file as text for the editor, with the `version` to send back when saving. Refused with file_too_large (413, more than 1 MiB; `fields.size` is its size) and not_text_file (415: not valid UTF-8 or holds control bytes; download it instead). A folder, link or device is refused (file_wrong_type, file_special); a denied file is file_denied; a missing one file_not_found. Opening a file is recorded in Activity by path and size (never content) before the content is returned. See the list route for the other refusals.

• Permission: games.files
• API token: not available, use a signed-in session

PUT /api/v1/orgs/{org}/games/{game}/files/content

Save a text file of a game server

Writes the text atomically (a temporary file beside it, then a rename), so a failure leaves the original. Set `create` for a new file (refused with file_exists when it is there) or send the `version` that was read. A save with neither is refused (422): this route never overwrites a file it was not told the version of; a file that changed since is refused with file_conflict and nothing is written. The content must be text of at most 1 MiB (file_too_large, not_text_file). A write that would pass the plan's disk size is refused whole with file_disk_full. Recorded in Activity by path and size, never by content.

• Permission: games.files
• API token: not available, use a signed-in session

Request body (JSON):

{
  "content": "string",
  "create": false,
  "path": "string",
  "version": "string"
}

POST /api/v1/orgs/{org}/games/{game}/files/delete

Delete a file or folder of a game server

Deletes a file or an empty folder. A folder with contents needs `recursive: true` (folder_not_empty otherwise); a folder holding a denied file is not deleted. The data directory itself cannot be deleted. There is no trash yet: a deleted file is gone (the 7-day restore is not built). Recorded in Activity by path.

• Permission: games.files
• API token: not available, use a signed-in session

Request body (JSON):

{
  "path": "string",
  "recursive": false
}

GET /api/v1/orgs/{org}/games/{game}/files/download

Download a file of a game server

The file's bytes as an attachment (never rendered, never sniffed, never cached), at most 2 MiB; bigger files go by SFTP (file_too_large). The download is recorded in Activity before any byte is sent.

• Permission: games.files
• API token: not available, use a signed-in session

POST /api/v1/orgs/{org}/games/{game}/files/mkdir

Create a folder in a game server

Creates one folder; its parent must exist (file_not_found) and it must not (file_exists).

• Permission: games.files
• API token: not available, use a signed-in session

Request body (JSON):

{
  "path": "string"
}

POST /api/v1/orgs/{org}/games/{game}/files/rename

Rename or move a file or folder of a game server

Moves a file or folder inside the data directory. It never replaces: a destination that exists is refused (file_exists). A folder cannot be moved into itself, and a folder holding a denied file is not moved.

• Permission: games.files
• API token: not available, use a signed-in session

Request body (JSON):

{
  "from_path": "string",
  "to_path": "string"
}

PUT /api/v1/orgs/{org}/games/{game}/files/upload

Upload a file to a game server

The body is the raw file with Content-Type application/octet-stream, at most 2 MiB (file_too_large; bigger files go by SFTP). It never replaces a file unless `overwrite=true` is explicit (file_exists); with it the file is replaced whatever its version, which is the upload's meaning. The folder it goes in must exist. The same atomic write, quota and denylist rules as saving apply.

• Permission: games.files
• API token: not available, use a signed-in session

GET /api/v1/orgs/{org}/games/{game}/mods

List the mods and plugins a game server's template allows

The allow-list from the server's signed template (`mods`), each item with its state in the mods folder: `available`, `installed` (the file is there with the pinned size) or `different` (a file of that name is there with another size, which an install will not replace). `available` is false when the template declares none. A customer never supplies a URL: an item is installed by its id.

• Permission: games.files
• API token: not available, use a signed-in session

POST /api/v1/orgs/{org}/games/{game}/mods/install

Install an allow-listed mod or plugin on a game server

Downloads the item from the URL the signed template names (never one the customer gives), refuses it unless its length and SHA-256 are exactly the pinned ones (mod_checksum_mismatch, 502; mod_fetch_failed, 502, when the download did not complete), and writes it into the mods folder through the file manager's atomic write, creating the folder if needed. The file must not exist with other contents (mod_file_present, 409); installing what is already there is a no-op. Items are at most 2 MiB, the file manager's transfer limit. The download uses the SSRF-hardened client and happens before any slot on the node is taken. Recorded in Activity by mod id, file name, version and size. A restart is needed for the game to load it (`restart_required`).

• Permission: games.files
• API token: not available, use a signed-in session

Request body (JSON):

{
  "id": "string"
}

POST /api/v1/orgs/{org}/games/{game}/mods/remove

Remove an allow-listed mod or plugin from a game server

Deletes the file the item put in the mods folder. Only an item that is `installed` (the pinned name and size) is removed; a file of the same name with another size is the customer's own and is left (mod_not_installed, 409). Recorded in Activity.

• Permission: games.files
• API token: not available, use a signed-in session

Request body (JSON):

{
  "id": "string"
}

POST /api/v1/orgs/{org}/games/{game}/power

Start, stop, restart or kill a game server

Queues one power action for the node and answers 202 with an operation_id. Start works from offline or crashed; stop from running or starting; kill from running, starting or stopping, and it also works while a stop or start is in flight, which it supersedes; restart stops a running server and starts it again when the stop is confirmed, and starts one that is not running. Start and restart are refused with eula_required until the current EULA version for the game is accepted for the server (see the eula route), and with eula_unavailable when no text is published for the game; stop and kill are never refused for that. Refused with server_busy while another action runs on the server, and with server_not_active when the server is not active (still being set up, suspended or failed) or is in a state that cannot do that. The state shown changes at once; the node confirms it. A server of another organisation, or a VPS, is not found.

• Permission: games.manage
• API token: not available, use a signed-in session

Request body (JSON):

{
  "action": "start"
}

POST /api/v1/orgs/{org}/games/{game}/reinstall

Reinstall a game server

Runs the game's installer again on a stopped server. Needs the server's name in confirm_name and a recent step-up. Reinstalling can replace game files and reset settings the installer owns: take a backup first (the server's own files are kept or replaced by the installer, never by this route). Refused with reinstall_needs_stopped unless the server is offline or crashed, server_busy while another action runs, server_not_active while it is still being set up, suspended or failed, and reinstall_unavailable when its host cannot reinstall yet (nothing is queued). The state shows installing at once and returns to offline when the host confirms; the outcome is reported in the server's reinstall field.

• Permission: games.manage
• API token: not available, use a signed-in session
• Step-up: needs a recent password check

Request body (JSON):

{
  "confirm_name": "string"
}

GET /api/v1/orgs/{org}/games/{game}/schedules

List a game server's schedules

The server's schedules, oldest first, with each one's next run, last run and its outcome (`last_status`: ok, failed, skipped or missed; `last_error_code`), the failures in a row, and what the plan allows. A schedule that fails `limits.failure_limit` runs in a row is switched off (`enabled` false) and says why in `last_error_code`; saving it again switches it back on. A server of another organisation is not found. Needs games.schedules; no API token scope opens it. State: integrated on fakes.

• Permission: games.schedules
• API token: not available, use a signed-in session

POST /api/v1/orgs/{org}/games/{game}/schedules

Create a schedule for a game server

Creates a schedule: a five-field cron expression (minute hour day-of-month month weekday; numbers, ranges, lists and steps) in an IANA time zone, and one to ten tasks run in order. A task is a power action (start, stop or restart), one console command line (up to 1,024 characters, sent as written) or a backup; each waits `offset_seconds` (0 to 3,600, at most six hours in all) after the one before finished, and the run stops at a failed task unless it sets `continue_on_failure`. A time that does not exist when clocks go forward runs once at the first moment after the gap; a repeated hour runs once. Runs must be at least five minutes apart. `missed_policy` says what happens if the worker was down at the due time: run_once makes the run up (once) if it is less than 30 minutes late, skip records it as missed; later than that it is always missed, never run. A server that is not active at run time skips the run and says so. A backup task while another backup is running is skipped with the reason backup_running. A schedule may hold only a task its author could do by hand (power and commands need games.manage, backups games.backups): refused with schedule_task_forbidden, and a task whose author has lost the permission fails when it runs (permission_revoked). The plan allows a number of schedules (schedule_limit_reached, schedules_not_included) and names are unique per server, ignoring case (schedule_name_taken). Needs games.schedules. State: integrated on fakes; nothing has run on a real node.

• Permission: games.schedules
• API token: not available, use a signed-in session

Request body (JSON):

{
  "cron": "0 4 * * *",
  "enabled": false,
  "missed_policy": "run_once",
  "name": "string",
  "tasks": [
    null
  ],
  "tz": "Europe/Berlin"
}

DELETE /api/v1/orgs/{org}/games/{game}/schedules/{schedule}

Delete a game server schedule

Switches the schedule off and removes it from the list; its past runs stay in the history the audit trail points to. A run in flight finishes. A schedule of another server or organisation is not found. Needs games.schedules.

• Permission: games.schedules
• API token: not available, use a signed-in session

PUT /api/v1/orgs/{org}/games/{game}/schedules/{schedule}

Change a game server schedule

Replaces the schedule's definition (the same fields and rules as creating one). Saving clears the failures in a row and switches a schedule that was switched off back on (when `enabled` is true), and makes the person who saved it the one it acts as: its tasks run with the permissions that person has when they run. A run in flight finishes with the tasks it started with, or fails as schedule_changed if the list changed under it. A schedule of another server or organisation is not found. Needs games.schedules.

• Permission: games.schedules
• API token: not available, use a signed-in session

Request body (JSON):

{
  "cron": "0 4 * * *",
  "enabled": false,
  "missed_policy": "run_once",
  "name": "string",
  "tasks": [
    null
  ],
  "tz": "Europe/Berlin"
}

GET /api/v1/orgs/{org}/games/{game}/schedules/{schedule}/runs

List the runs of a game server schedule

The latest 20 runs, newest first, each with its due time, how it ended (running, ok, failed, skipped or missed, with `reason` such as server_not_active, worker_down, missed_policy or task_failed) and the outcome of each task (pending, running, ok, failed or skipped, with a curated `code`: not_running, server_busy, eula_required, permission_revoked, backup_running, backup_limit_reached, timeout and others). No operation or backup ids are shown. A schedule of another server or organisation is not found. Needs games.schedules.

• Permission: games.schedules
• API token: not available, use a signed-in session

POST /api/v1/orgs/{org}/games/{game}/sftp

Get a short-lived SFTP credential for a game server

Issues a credential for this person, from this panel session, for this one server on its node: the user name encodes the server and the person, and the password is a signed token that is good for 10 minutes to log in (a session that began in time lasts as long as the person's right to the server). It is shown only here and stored nowhere, so there is nothing to look up; ask for another. Account passwords never reach a node. Refused with sftp_unavailable while SFTP is turned off, files_node_unreachable, server_busy or files_server_suspended. State: GF-1 issues the credential on fakes; the SFTP service that accepts it (vex-sftp) is not built.

• Permission: games.files
• API token: not available, use a signed-in session
• Session only: a person must be present

Request body (JSON):

{}

GET /api/v1/orgs/{org}/games/{game}/usage

CPU, memory, disk, network and players of a game server

One series per metric over a time range, downsampled to the step, in the shape of a VPS server's usage. Samples are kept at one-minute resolution for 30 days. A bucket with no sample is a gap: its value and max are null and samples is 0. It is never zero. A gap can mean the server was off, the node was unreachable, or the reading was not available: the node reads CPU against the server's own cap (cpu.max) and memory from its cgroup, the disk in use from its data directory (every ten minutes, and not at all for a directory too large to measure cheaply), network at the server's routed interface once the game network exists on the node, and players only from a game that answers a query (Minecraft Java). Network is bytes per second. Buckets start at multiples of the step since the Unix epoch (UTC); the answer covers whole buckets. Value is the mean over the minutes that have a sample; max is the largest per-minute value. A server of another org is a 404. Needs games.read; no API token scope opens it. State: integrated on fakes; no real node has measured a real container.

• Permission: games.read
• API token: not available, use a signed-in session

GET /api/v1/health

Liveness check

Liveness check. Returns status ok when the API process is running. Needs no sign-in.

• Access: public, no authentication

POST /api/v1/invites/accept

Accept an organisation invite

Accepts an organisation invite with the token from the invite email, and adds you with the invited role. The token must match your own email address; otherwise it returns token_invalid.

• API token: not available, use a signed-in session

Request body (JSON):

{
  "token": "string"
}

GET /api/v1/orgs/{org}/invites

List pending invites

Lists pending invites with the invited email, role and expiry.

• Permission: org.members.manage
• API token: not available, use a signed-in session

POST /api/v1/orgs/{org}/invites

Invite a member

Invites an email address to the organisation as admin, member, billing or viewer (not owner), and emails the invite link. You can only invite into a role whose permissions you hold in full (403 role_escalation), and that is checked again when the invite is accepted. Personal organisations cannot have invites (personal_org).

• Permission: org.members.manage
• API token: not available, use a signed-in session

Request body (JSON):

{
  "email": "string",
  "role": "admin"
}

DELETE /api/v1/orgs/{org}/invites/{invite}

Revoke an invite

Revokes a pending invite so its link can no longer be accepted. Returns not_found if the invite does not exist in this organisation.

• Permission: org.members.manage
• API token: not available, use a signed-in session

GET /api/v1/orgs/{org}/invoices

List invoices

Newest first. With status unpaid or all, open renewals appear as rows of kind proforma (pay them with POST /proformas/{id}/pay).

• Permission: billing.read
• API token: not available, use a signed-in session

GET /api/v1/orgs/{org}/invoices/{invoice}

Get an invoice

Returns one of the organisation's invoices with its lines, tax and the part paid from credit. Returns not_found if the invoice belongs to another organisation.

• Permission: billing.read
• API token: not available, use a signed-in session

GET /api/v1/orgs/{org}/invoices/{invoice}.pdf

Download an invoice as PDF

Rendered only from the immutable invoice (its lines and frozen snapshot). Another org's invoice is a 404.

• Permission: billing.read
• API token: not available, use a signed-in session

GET /api/v1/orgs/{org}/isos

List the organisation's ISOs and the system library

The organisation's own ISOs in any state, then the ready ISOs of the read-only system library, with the library's usage against its quota. ISOs are never shared between organisations. With arch, only ISOs built for that CPU architecture are listed (what a server of that architecture can mount); without it every ISO is listed, each with its arch.

• Permission: servers.read
• API token: not available, use a signed-in session

POST /api/v1/orgs/{org}/isos

Fetch an ISO by URL into the library

Queues a fetch. The URL must be https on port 443 of a public host with no credentials in it; every address the fetch connects to must be public too. Redirects are not followed, so a URL that redirects fails with redirect_not_allowed (give the final address). The fetch is capped at the space left in the quota and at 10 GiB, stops after 90 minutes, and is aborted (too_slow) if it moves less than 64 KiB/s over a whole minute; an interrupted fetch starts again from scratch up to 3 times. An organisation may have 3 fetches waiting or running at once; a fourth is refused with 429 iso_fetch_queue_full. If sha256 is given the bytes must match it. Poll the list for the outcome.

• Permission: iso.manage
• API token: not available, use a signed-in session

Request body (JSON):

{
  "arch": "x86_64",
  "name": "string",
  "sha256": "string",
  "url": "string"
}

POST /api/v1/orgs/{org}/isos/upload

Upload an ISO into the library

The body is the raw image, with Content-Type application/octet-stream and a Content-Length, which is reserved against the quota before any byte is read (iso_quota_exceeded otherwise). The body must be exactly that long and an ISO 9660 or UDF image, and must match sha256 if it is given. A stalled upload is cut off after a minute without data.

• Permission: iso.manage
• API token: not available, use a signed-in session

DELETE /api/v1/orgs/{org}/isos/{iso}

Delete an ISO from the library

Removes one of the organisation's own ISOs and its bytes. Refused with iso_in_use while a server has it mounted or a mount of it is queued. System ISOs can't be deleted here.

• Permission: iso.manage
• API token: not available, use a signed-in session

POST /api/v1/orgs/{org}/limit-requests

Ask for a different limit

One request per limit can be open (409 limit_request_open otherwise). It reaches the staff queue; automatic approval does not exist. 422 when the number is the current limit.

• Permission: org.manage
• API token: not available, use a signed-in session

Request body (JSON):

{
  "limit": "servers",
  "reason": "string",
  "requested": 0
}

GET /api/v1/orgs/{org}/limits

The organisation's limits, its use and its requests

Every limit with what the organisation uses now and whether staff changed it from the default, then the organisation's limit requests, newest first.

• Permission: org.read
• API token: not available, use a signed-in session

POST /api/v1/orgs/{org}/marketplace/installs

Install a marketplace app on a new server

Places an order for a new server whose first-boot configuration is the chosen app, filled with the inputs. Needs what ordering a server needs: a verified email (email_unverified), the server limit not reached, capacity (no_capacity) and a plan at least as large as the app's minimums (validation_failed on price_id). Input problems are validation_failed on inputs. Values for password inputs that were left blank are generated and sealed; collect them once with the reveal call. A repeat with the same Idempotency-Key returns the same install. Returns 201 with the install, the order and a client_secret to confirm payment when one is needed. Answers 503 tax_unavailable while tax cannot be worked out yet for the buyer's location; nothing is created or charged, and trying again later succeeds once it is set up.

• Permission: servers.manage
• API token: not available, use a signed-in session

Request body (JSON):

{
  "hostname": "string",
  "image_id": "00000000-0000-0000-0000-000000000000",
  "price_id": "00000000-0000-0000-0000-000000000000",
  "recipe_id": "string",
  "region": "string",
  "ssh_key_ids": [
    null
  ]
}

GET /api/v1/orgs/{org}/marketplace/installs/{install}

Show an install and its progress

The app and version, the order and server it produced, whether the credentials were already shown, and the install state the server reported: pending until the server exists and reports, then installing, ready or failed. The state comes from the customer's own server, so treat it as a hint. An install of another organisation is not found.

• Permission: servers.read
• API token: not available, use a signed-in session

POST /api/v1/orgs/{org}/marketplace/installs/{install}/credentials/reveal

Show an install's generated credentials once

Returns the values the control plane generated for this install and marks them shown. The first call gets them (Cache-Control: no-store); every later call is 409 credentials_viewed. Recorded in Activity by key count, never by value. Closed to API tokens.

• Permission: servers.manage
• API token: not available, use a signed-in session

GET /api/v1/orgs/{org}/marketplace/recipes

List marketplace apps

The signed one-click apps that can be installed on a new server, ordered by id, each with the inputs its form needs and the smallest plan it runs on. Only recipes whose signature verified are listed, so the list is empty until the owner has signed one. Answers not_found when the marketplace is switched off.

• Permission: servers.read
• API token: not available, use a signed-in session

GET /api/v1/orgs/{org}/marketplace/recipes/{recipe}

Show a marketplace app

One app with its inputs and minimums. The template is never returned. An id that is not in the catalog is not found.

• Permission: servers.read
• API token: not available, use a signed-in session

GET /api/v1/me

Current user

Returns the signed-in user: profile, whether email is verified, authenticator and passkey status, staff permissions, the time until which a step-up is valid, and any active impersonation.

• API token: not available, use a signed-in session

PATCH /api/v1/me

Update profile

Changes your display name (up to 80 characters).

• API token: not available, use a signed-in session

Request body (JSON):

{
  "name": "string"
}

GET /api/v1/me/audit

Your account activity

Lists activity on your own account, newest first. Pages with before and limit (default 50, at most 100).

• API token: not available, use a signed-in session

DELETE /api/v1/me/deletion

Cancel a request to delete your account

Stops a pending request. Nothing has been erased during the grace period, so it needs no step-up. You are emailed. 404 when nothing is pending.

• API token: not available, use a signed-in session
• Session only: a person must be present

GET /api/v1/me/deletion

Whether your account can be deleted, and any request

The pending request if there is one, the last one that ended, and what is in the way now (servers, money owed either way, disputes, holds, unpaid invoices, an organisation you solely own that has other members). `allowed` is true when nothing is.

• API token: not available, use a signed-in session
• Session only: a person must be present

POST /api/v1/me/deletion

Ask for your account to be deleted

Confirm with your sign-in email. Refused with 409 deletion_blocked, naming each reason in `fields`, while anything is in the way. Otherwise the request waits out the grace period (14 days by default), during which you can cancel, and is then carried out: your credentials, cards, SSH keys, API tokens and support conversations are deleted or anonymised; invoices, payments and tax records stay. Needs a recent step-up and a panel session. You are emailed.

• API token: not available, use a signed-in session
• Step-up: needs a recent password check
• Session only: a person must be present

Request body (JSON):

{
  "confirm": "string"
}

DELETE /api/v1/me/email-change

Cancel a waiting change of sign-in address

Withdraws the change waiting for confirmation. Its links stop working. 404 when none is waiting.

• API token: not available, use a signed-in session
• Session only: a person must be present

GET /api/v1/me/email-change

Your sign-in address and any change waiting for confirmation

Your current sign-in address and, if you asked to change it and the new address has not confirmed yet, the address and when the request runs out. Panel session only.

• API token: not available, use a signed-in session
• Session only: a person must be present

POST /api/v1/me/email-change

Ask to change your sign-in email address

Needs a recent step-up and a panel session. Sends a confirmation link to the NEW address and a notice with a cancel link to the OLD one; nothing changes until the new address opens its link, within 24 hours. The answer is the same whether or not the new address already belongs to an account (no link is sent in that case, and the change can never be confirmed), so it cannot be used to find out who has one. A newer request replaces a waiting one. At most five an hour. When the change is confirmed every session is signed out and unused email links are voided; passkeys and the authenticator app stay.

• API token: not available, use a signed-in session
• Step-up: needs a recent password check
• Session only: a person must be present

Request body (JSON):

{
  "new_email": "string"
}

GET /api/v1/me/export-downloads/{token}

Download an export with a link

Serves the zip for a valid link made for the signed-in person. An expired, altered or someone else's link is token_invalid. Sent with Cache-Control no-store; each download is audited.

• API token: not available, use a signed-in session
• Session only: a person must be present

GET /api/v1/me/exports

Your data exports

Your own account exports, newest first, with their state and how many days a finished one can be downloaded. Panel session only.

• API token: not available, use a signed-in session
• Session only: a person must be present

POST /api/v1/me/exports

Ask for a copy of your data

Queues an export of the personal data held about you (profile, organisations, sessions, support tickets, SSH keys, API token metadata, your own activity) as a zip of JSON files. It never holds a secret or another person's data. The worker builds it and emails you when it is ready. Needs a recent step-up, a panel session, and at most three a day; one at a time (export_open).

• API token: not available, use a signed-in session
• Step-up: needs a recent password check
• Session only: a person must be present

GET /api/v1/me/exports/{export}

One data export

State, size, checksum and expiry of one of your exports. 404 for anyone else's.

• API token: not available, use a signed-in session
• Session only: a person must be present

POST /api/v1/me/exports/{export}/download-link

Get a short-lived download link for an export

Needs a recent step-up. Makes a link that works for five minutes, once, for you only in this session, and while the export is ready (export_not_ready otherwise). Making another link cancels the earlier one.

• API token: not available, use a signed-in session
• Step-up: needs a recent password check
• Session only: a person must be present

GET /api/v1/me/game-access

The game servers shared with me and the invitations waiting

The signed-in person's active grants and the invitations sent to their address that are still open (not expired), across organisations. Each says which server, whose organisation, which rights, and who invited them. Nothing else about the organisation is shown. State: integrated on fakes.

• API token: not available, use a signed-in session

DELETE /api/v1/me/game-access/{grant}

Decline an invitation or give up access to a game server

The person's own act, with no step-up: a pending invitation is declined (game.subuser_declined), an active grant ends (game.subuser_left) and a console they have open ends at the gateway's next heartbeat. Another person's grant is not found. State: integrated on fakes.

• API token: not available, use a signed-in session

POST /api/v1/me/game-access/{grant}/accept

Accept an invitation to a game server

Accepts a pending invitation sent to the signed-in person's verified address. Another account, an expired or withdrawn invitation and an unverified address are all invite_invalid (404). The inviter's rights are checked again now (invite_inviter_changed, nothing is accepted); that includes the inviter still being an active member whose role holds games.subusers, checked under the organisation lock. Audited as game.subuser_accepted. State: integrated on fakes.

• API token: not available, use a signed-in session

GET /api/v1/me/mail-status

Whether email to your address is stopped

True when email to your sign-in address bounced for good or was marked as spam, so it is no longer sent.

• API token: not available, use a signed-in session

GET /api/v1/me/notification-preferences

Which emails you receive

Every kind of email, whether it is required (`locked`) and whether you receive it. Security and billing email is locked on.

• API token: not available, use a signed-in session

PUT /api/v1/me/notification-preferences

Choose which optional emails you receive

Names the kinds to change and leaves the others as they are. Asking to switch off a locked kind (security, billing) is refused with 422 and nothing changes. Takes effect for email queued from now on.

• API token: not available, use a signed-in session

Request body (JSON):

{
  "preferences": {}
}

GET /api/v1/me/orgs

Organisations you belong to

Lists the organisations you belong to with your role in each. A viewing session started by staff sees only the organisation it was opened for.

• API token: not available, use a signed-in session

GET /api/v1/me/passkeys

List passkeys

Lists your passkeys with their names, creation time and last use.

• API token: not available, use a signed-in session

POST /api/v1/me/passkeys/begin

Start adding a passkey

Starts adding a passkey and returns the WebAuthn options with a challenge_id. Needs a recent step-up.

• API token: not available, use a signed-in session
• Step-up: needs a recent password check

POST /api/v1/me/passkeys/finish

Finish adding a passkey

Finishes adding a passkey from the browser's WebAuthn response and the challenge_id from passkeys/begin. The optional name query parameter labels it. Needs a recent step-up.

• API token: not available, use a signed-in session
• Step-up: needs a recent password check

Request body (JSON):

{}

DELETE /api/v1/me/passkeys/{passkey}

Remove a passkey

Removes one of your passkeys. Needs a recent step-up. Returns not_found if the passkey is not yours.

• API token: not available, use a signed-in session
• Step-up: needs a recent password check

POST /api/v1/me/password

Change password

Changes your password and signs out all your other sessions. Needs the current password (invalid_credentials) and a new one that meets the password policy (weak_password: length) and is not a very common password or one found in a known breach (password_breached; the breach-list lookup lets the password through when that service is down). A notice is emailed.

• API token: not available, use a signed-in session

Request body (JSON):

{
  "current_password": "string",
  "new_password": "string"
}

POST /api/v1/me/recovery-codes

Regenerate recovery codes

Replaces your recovery codes with a new set, shown once. Needs a recent step-up. Returns conflict if the authenticator app is not set up.

• API token: not available, use a signed-in session
• Step-up: needs a recent password check

GET /api/v1/me/sessions

List signed-in sessions

Lists your signed-in sessions with IP address, browser and last activity, and marks the current one.

• API token: not available, use a signed-in session

DELETE /api/v1/me/sessions/{session}

Sign out a session

Signs out one of your own sessions, which can be the current one (the session cookie is then cleared). Returns not_found if the session is not yours.

• API token: not available, use a signed-in session

GET /api/v1/me/sso

Your linked identity providers

The providers on offer with whether each is linked to your account, and links to providers that are no longer offered (so they can still be removed). Also whether this is a staff account (which cannot use a provider) and whether you can sign in with a password. Never the provider's subject. Panel session only.

• API token: not available, use a signed-in session
• Session only: a person must be present

DELETE /api/v1/me/sso/{provider}

Unlink an identity provider from your account

Needs a recent step-up and a panel session. Refused with sso_last_sign_in_method when it is the only way you can sign in (no password you can use, no passkey, no other provider that is switched on); the check runs under a lock on your account, so two unlinks at once cannot remove both. A mail tells you it happened.

• API token: not available, use a signed-in session
• Step-up: needs a recent password check
• Session only: a person must be present

POST /api/v1/me/sso/{provider}/link

Start linking an identity provider to your account

Needs a recent step-up and a panel session. Returns the provider's authorization address; the provider asks you to sign in again (prompt=login) and the callback must return in this browser and this session. The identity is tied to this account whatever its email says, and only if no other account has it. Refused for staff accounts (sso_not_for_staff) and when this provider is already linked (sso_already_linked). A mail tells you it happened.

• API token: not available, use a signed-in session
• Step-up: needs a recent password check
• Session only: a person must be present

POST /api/v1/me/step-up

Re-authenticate for sensitive actions

Re-authenticates with your password or authenticator code and returns the time until which sensitive actions are allowed (5 minutes). Wrong credentials return invalid_credentials.

• API token: not available, use a signed-in session

Request body (JSON):

{
  "code": "string",
  "password": "string"
}

DELETE /api/v1/me/totp

Remove authenticator app

Turns off authenticator-app sign-in and deletes your recovery codes. Needs a recent step-up. A confirmation email is queued to your address.

• API token: not available, use a signed-in session
• Step-up: needs a recent password check

POST /api/v1/me/totp

Start authenticator app setup

Starts authenticator-app setup and returns the secret and otpauth URL. Needs a recent step-up. Returns conflict if an authenticator app is already confirmed. Setup completes with totp/confirm.

• API token: not available, use a signed-in session
• Step-up: needs a recent password check

POST /api/v1/me/totp/confirm

Confirm authenticator app and get recovery codes

Confirms authenticator-app setup with a current code and returns your recovery codes, shown once. Needs a recent step-up. A wrong code returns invalid_code.

• API token: not available, use a signed-in session
• Step-up: needs a recent password check

Request body (JSON):

{
  "code": "string"
}

GET /api/v1/me/transfers

Ownership offers made to you

Lists the open offers to take over an organisation that were made to you, with what you would take on: how many servers it has and how many payment methods stay on it. Expired offers are not listed.

• API token: not available, use a signed-in session

POST /api/v1/me/transfers/{transfer}/accept

Accept an ownership offer

Makes you the owner and the person who handed it over the role they chose, in one step. Needs a recent step-up and accept_billing: true, confirming you take over the organisation's billing: its renewals charge the payment methods and credit already on it until you change them. An offer that is expired, answered, or no longer the giver's to make returns 409 transfer_invalid. Someone else's offer is 404.

• API token: not available, use a signed-in session
• Step-up: needs a recent password check

Request body (JSON):

{
  "accept_billing": false
}

POST /api/v1/me/transfers/{transfer}/decline

Decline an ownership offer

Turns the offer down; the owner is told and nothing changes.

• API token: not available, use a signed-in session

DELETE /api/v1/me/trusted-browsers

Remove every trusted browser

Removes all of your trusted browsers, so the authenticator code is asked at every password sign-in again, and clears this browser's trusted-browser cookie. Needs no step-up: it only takes a convenience away. Audited when anything was removed. Panel session only.

• API token: not available, use a signed-in session
• Session only: a person must be present

GET /api/v1/me/trusted-browsers

Browsers you marked as trusted

Lists the browsers you marked as trusted when you signed in with your authenticator app code, newest first, with the browser name, the address it was marked from, when it was last used to skip the code and when the trust ends; the one you are using is marked current. enabled is false when the service has turned the feature off, and days is how long a new trust lasts. Panel session only.

• API token: not available, use a signed-in session
• Session only: a person must be present

DELETE /api/v1/me/trusted-browsers/{browser}

Remove one trusted browser

Removes one of your trusted browsers; the next password sign-in from it asks for the authenticator code. If it is the browser making the request, its trusted-browser cookie is cleared too. Returns not_found if it is not yours. Needs no step-up. Audited. Panel session only.

• API token: not available, use a signed-in session
• Session only: a person must be present

GET /api/v1/me/two-factor

Your second factor and which organisations require one

Whether you have a second factor (a confirmed authenticator app or a passkey), how many recovery codes are left, and which of your organisations require one, with each grace period. enrolment_required is true when you have none and a rule already holds you out; signin_required when you have one but this session did not use it (a password-only session of a person with a passkey is not compliant) (an organisation whose grace period ended, or the staff rule): turn one on before anything else works. must_keep says removing your last one would be refused. Panel session only. No secret is returned.

• API token: not available, use a signed-in session
• Session only: a person must be present

GET /api/v1/orgs/{org}/members

List members

Lists the organisation's members with email, name, role and the date they joined.

• Permission: org.members.read
• API token: not available, use a signed-in session

DELETE /api/v1/orgs/{org}/members/{user}

Remove a member

Removes a member from the organisation (not one who holds more than you do: 403 member_outranks), and revokes the API tokens they created and the support access they granted here. Needs a recent step-up. Only an owner may remove an owner, the last owner cannot be removed (last_owner), and a personal organisation has no removable members (personal_org).

• Permission: org.members.manage
• API token: not available, use a signed-in session
• Step-up: needs a recent password check

PATCH /api/v1/orgs/{org}/members/{user}

Change a member's role

Changes a member's role to owner, admin, member, billing or viewer (role), or to one of the organisation's own roles (role_id), not both. Needs a recent step-up. You can only give a role whose permissions you hold in full (403 role_escalation) and only change a member who holds nothing you do not (403 member_outranks). Only an owner may grant or remove the owner role, the last owner cannot be demoted (last_owner), and a personal organisation's roles cannot be changed (personal_org).

• Permission: org.members.manage
• API token: not available, use a signed-in session
• Step-up: needs a recent password check

Request body (JSON):

{
  "role": "owner",
  "role_id": "00000000-0000-0000-0000-000000000000"
}

GET /api/v1/orgs/{org}/operations

List server actions

Lists the actions (power, rebuild, destroy and the like) run on the organisation's servers, newest first with the id as tiebreak, 50 a page unless limit says otherwise (1 to 200). Pass server to see one server's actions. Cursor paged: send next_cursor back as cursor; it is null on the last page. An invalid cursor, limit or server is 422. Follow one action at GET /orgs/{org}/operations/{operation}.

• Permission: servers.read
• API token scope: servers:read

Example:

curl -X GET "$VEXELIA_URL/api/v1/orgs/$org/operations" \
  -H "Authorization: Bearer $VEXELIA_TOKEN"

GET /api/v1/orgs/{org}/operations/{operation}

Progress of a server action

Returns one operation (power, rebuild, rescue, firewall apply) with its status: queued, running, succeeded or failed, and an error_code when it failed. Operation ids come from the 202 answers of the calls that queue work.

• Permission: servers.read
• API token scope: servers:read

Example:

curl -X GET "$VEXELIA_URL/api/v1/orgs/$org/operations/$operation" \
  -H "Authorization: Bearer $VEXELIA_TOKEN"

POST /api/v1/orgs/{org}/orders

Order a server

Orders a server: price, region, image, hostname and at least one SSH key, with optional user data and automatic renewal. Needs a verified email (email_unverified). Refused when the organisation's server limit is reached or no node has capacity (no_capacity). The plan and the image must be of the same CPU architecture (x86_64 or aarch64): an order that mixes them is a validation_failed on image_id saying which to choose. A dedicated plan is placed only on a host that reports it pins servers to cores of their own and has whole cores free; where none does, the order is a validation_failed on price_version_id (no free dedicated cores in this region). The catalog's regions[].offers say which architectures and which dedicated cores each region can place. Returns 201 with the order and a client_secret to confirm payment when one is needed. With restore_backup_id the order is for a new server restored from one of the organisation's backups: it is a purchase like any other (it counts against the server limit and is paid in full), the original server is not touched, and if the backup is gone when payment arrives the order is refunded and no server is built. An order with restore_backup_id needs a recent step-up (403 step_up_required without one), because it copies a whole disk onto a server the given keys can log in to; an ordinary order needs none, and a token is never allowed to order. Answers 503 tax_unavailable while tax cannot be worked out yet for the buyer's location; nothing is created or charged, and trying again later succeeds once it is set up. When the platform runs sync hook plugins, an order can be refused with 403 request_declined, 409 request_declined_limit or 403 request_declined_region, in the platform's own words, before anything is created; a retry of an order that already exists is answered by that order. A plugin may lower the price within a cap (at most 10% and 500.00); the order then shows the amount as discount_minor, and the invoice and the payment are for exactly the order's total, priced by the platform. A plugin that fails or is slow is ignored.

• Permission: servers.manage
• API token: not available, use a signed-in session

Request body (JSON):

{
  "hostname": "string",
  "price_id": "00000000-0000-0000-0000-000000000000",
  "region": "string",
  "ssh_key_ids": [
    null
  ]
}

GET /api/v1/orgs/{org}/orders/{order}

Get an order

Returns an order and, once the server exists, its server id. Poll it after placing an order in the panel.

• Permission: servers.read
• API token scope: servers:read

Example:

curl -X GET "$VEXELIA_URL/api/v1/orgs/$org/orders/$order" \
  -H "Authorization: Bearer $VEXELIA_TOKEN"

POST /api/v1/orgs

Create an organisation

Creates an organisation with you as its owner.

• API token: not available, use a signed-in session

Request body (JSON):

{
  "name": "string"
}

GET /api/v1/orgs/{org}

Organisation details

Returns the organisation the token belongs to: its name and your role in it.

• Permission: org.read
• API token scope: org:read

Example:

curl -X GET "$VEXELIA_URL/api/v1/orgs/$org" \
  -H "Authorization: Bearer $VEXELIA_TOKEN"

PATCH /api/v1/orgs/{org}

Rename organisation

Renames the organisation.

• Permission: org.manage
• API token: not available, use a signed-in session

Request body (JSON):

{
  "name": "string"
}

GET /api/v1/orgs/{org}/payment-methods

List saved cards

Lists the organisation's saved cards.

• Permission: billing.read
• API token: not available, use a signed-in session

POST /api/v1/orgs/{org}/payment-methods/setup

Start saving a card

Starts saving a card and returns a client secret and the provider's public key for the browser to confirm the card.

• Permission: billing.manage
• API token: not available, use a signed-in session

DELETE /api/v1/orgs/{org}/payment-methods/{method}

Remove a card

Refused with autopay_needs_card (fields.servers lists them) when it is the last card and automatic renewal is on.

• Permission: billing.manage
• API token: not available, use a signed-in session
• Step-up: needs a recent password check

POST /api/v1/orgs/{org}/payment-methods/{method}/default

Make a card the default

Makes a saved card the organisation's default. Returns not_found if the card is not one of this organisation's.

• Permission: billing.manage
• API token: not available, use a signed-in session

GET /api/v1/orgs/{org}/private-networks

Every private network of the organisation, with its servers and limits

The organisation's private networks (the Private networks page), newest first, each with the servers attached to it (and the ones being attached or taken off), the private networks limit and servers, the active servers a network can be made for or attached to, each with an opaque location label. A private network is a layer-2 segment the organisation owns in one location, with a range the customer chose (RFC 1918, /16 to /24); its servers reach each other on it with private addresses and nothing else can: another organisation's servers are never on it. It is not billed. Deleted networks are not listed.

• Permission: servers.read
• API token scope: servers:read

Example:

curl -X GET "$VEXELIA_URL/api/v1/orgs/$org/private-networks" \
  -H "Authorization: Bearer $VEXELIA_TOKEN"

POST /api/v1/orgs/{org}/private-networks

Create a private network

Creates a private network named name with the range cidr (an IPv4 network written with its network address, such as 10.20.0.0/24: inside 10.0.0.0/8, 172.16.0.0/12 or 192.168.0.0/16, and between /16 and /24) in the location of the server server_id (which only says where: nothing is attached). It costs nothing and touches no host. The range may not overlap another live network of the organisation (another organisation can use the same one: separate segments). The first host address of the range is kept (a gateway may be offered later), as are the network and broadcast addresses. Refused with 422 on cidr or name when they are not valid, private_network_name_taken, private_network_overlap, private_network_limit at the limit, private_network_host_unsupported when no active host in the location reports that it applies private networks, and server_not_active when the server is not an active VPS.

• Permission: servers.manage
• API token: not available, use a signed-in session
• Step-up: needs a recent password check

Request body (JSON):

{
  "cidr": "string",
  "name": "string",
  "server_id": "00000000-0000-0000-0000-000000000000"
}

DELETE /api/v1/orgs/{org}/private-networks/{private_network}

Delete a private network

Deletes a private network that no server is on. It happens at once (no host is involved). A network with a server attached, being attached or being taken off is refused with private_network_in_use: a delete never takes a network away from a running server, so detach the servers first (each detach is confirmed). The bridge number of a deleted network is never reused.

• Permission: servers.manage
• API token: not available, use a signed-in session
• Step-up: needs a recent password check

GET /api/v1/orgs/{org}/private-networks/{private_network}

One private network

One private network of the organisation, as the list shows it. A deleted network is a 404.

• Permission: servers.read
• API token scope: servers:read

Example:

curl -X GET "$VEXELIA_URL/api/v1/orgs/$org/private-networks/$private_network" \
  -H "Authorization: Bearer $VEXELIA_TOKEN"

POST /api/v1/orgs/{org}/private-networks/{private_network}/attach

Attach a server to a private network

Gives the server server_id a second network interface on the network, with a private address from its range: address if given (it must be inside the range and not the network, first-host or broadcast address), else the lowest free one. The server's host plugs the interface into the network's own bridge and locks it to its MAC address and its private address: it can send nothing else, cannot run DHCP, and sees only IPv4 and ARP of its own network. The guest is not configured; the customer sets the address inside it (a static address on the new interface). The attach is one operation: the member reads attaching until the host answers, attached after, and is gone again with error_code if the host could not. The server's firewall policy filters its public interface only and does not filter private network traffic (firewall_applies is false): when the server has a firewall policy attached, the body must say firewall_ack true to show that this is understood (private_network_firewall_ack_required otherwise). Every server of a network runs on the same host: private_network_other_node when the server is on another host from the network's other servers, private_network_other_group when it is in another location. A server may be on two networks and a network may hold 32 servers. Refused also with private_network_already_member, private_network_address_taken, private_network_no_room, private_network_server_full, private_network_full, server_not_active, renewal_charging while its renewal is being paid, private_network_host_unsupported when the host has not reported that it applies private networks, and server_busy while another action runs on the server.

• Permission: servers.manage
• API token: not available, use a signed-in session
• Step-up: needs a recent password check

Request body (JSON):

{
  "address": "string",
  "firewall_ack": false,
  "server_id": "00000000-0000-0000-0000-000000000000"
}

POST /api/v1/orgs/{org}/private-networks/{private_network}/detach

Take a server off a private network

Removes the server's interface from the network. Its traffic on the network stops as soon as the host has applied it, so the body must say confirm true (private_network_confirm_required otherwise); nothing else ever takes an interface off a running server. The detach is one operation: the member reads detaching until the host answers, then it is gone, or attached again with error_code if the host could not. The private address is free for another server afterwards. Refused with private_network_not_member when the server is not on the network, private_network_busy while its interface is changing, server_busy while another action runs on the server and private_network_host_unsupported when the host has not reported that it applies private networks.

• Permission: servers.manage
• API token: not available, use a signed-in session
• Step-up: needs a recent password check

Request body (JSON):

{
  "confirm": false,
  "server_id": "00000000-0000-0000-0000-000000000000"
}

GET /api/v1/orgs/{org}/proformas/{proforma}

A renewal that is due

Returns a renewal that is due: the period, totals, credit held and card amount, charge attempts, next retry and suspension date, and whether it can still be paid (payable). Returns not_found if it belongs to another organisation.

• Permission: billing.read
• API token: not available, use a signed-in session

POST /api/v1/orgs/{org}/proformas/{proforma}/pay

Pay or confirm a renewal

Pays or confirms a renewal with credit and a saved card or a new card, and returns the status, a client secret if the card needs confirmation, and the credit and card amounts. Returns proforma_not_payable if it is no longer open and payment_unavailable if payments are not available.

• Permission: billing.manage
• API token: not available, use a signed-in session

Request body (JSON):

{
  "new_card": false,
  "payment_method": "00000000-0000-0000-0000-000000000000"
}

POST /api/v1/orgs/{org}/promotions/validate

Check promotion codes against a plan before ordering

Prices a plan with the codes the customer typed, using the same rules and arithmetic as the order, and records nothing: no use of a code is taken. Answers the list price, the discount, the price after it, the tax estimated on that price and the total. A code that does not hold is validation_failed on promo_code with a message that says why. Rate limited like a write, so codes cannot be guessed quickly.

• Permission: servers.read
• API token: not available, use a signed-in session

Request body (JSON):

{
  "price_id": "00000000-0000-0000-0000-000000000000",
  "promo_codes": [
    null
  ]
}

GET /api/v1/public/catalog

What is on sale: regions, plans, prices in force and images

No sign-in. Only what a customer could buy today, with the prices in force now, so a pricing page matches checkout. Hidden and retired plans, future price versions, stock figures, internal ids and payment details are never included. Answers carry Cache-Control public, max-age=300, and Access-Control-Allow-Origin only for the configured site origins (VEXELIA_SITE_ORIGINS; default vexelia.com and www.vexelia.com). Has its own rate limit per address.

• Access: public, no authentication

GET /api/v1/public/status

The platform's current status, by component, with open incidents

No sign-in. A component's status comes from the open incidents that affect it, never from a setting, so it cannot read operational while one is open. Answers carry Cache-Control public, max-age=30 and CORS headers for the configured site origins.

• Access: public, no authentication

GET /api/v1/public/status/incidents

Past and current incidents with updates and post-mortems

No sign-in. Newest first. Incidents are never deleted, so this is the platform's whole incident history.

• Access: public, no authentication

GET /api/v1/orgs/{org}/quotes

List the quotes sent to this account

Quotes staff issued to this organisation, newest first, with their state (an open quote past its date is expired). Quotes of other organisations are never shown.

• Permission: billing.read
• API token: not available, use a signed-in session

GET /api/v1/orgs/{org}/quotes/{quote}

Get a quote

One quote with its line, discount, validity date and an estimate of tax and total.

• Permission: billing.read
• API token: not available, use a signed-in session

POST /api/v1/orgs/{org}/quotes/{quote}/accept

Accept a quote and start its order

Turns an open quote into the normal order path: the customer gives the region, image, hostname and keys, and an order is made at the quote's price (the discount staff gave is applied before tax like a promotion code), with the same limits, capacity checks and payment as any order. Returns 201 with the order and a client_secret when a card payment is needed. The quote becomes accepted when that order is paid. Repeating the call returns the order already made while it awaits payment, or the paid one. Refused with validation_failed on quote when the quote has expired, was declined or withdrawn, or the plan's price changed since it was written.

• Permission: servers.manage
• API token: not available, use a signed-in session

Request body (JSON):

{
  "autopay": false,
  "hostname": "string",
  "image_id": "00000000-0000-0000-0000-000000000000",
  "region": "string",
  "ssh_key_ids": [
    null
  ],
  "user_data": "string"
}

POST /api/v1/orgs/{org}/quotes/{quote}/decline

Decline a quote

Turns an open quote down. Refused while an order made from it is waiting for payment. Audited.

• Permission: billing.manage
• API token: not available, use a signed-in session

GET /api/v1/orgs/{org}/roles

List roles and the permission catalog

Lists the five built-in roles (fixed), the organisation's own roles with how many members hold each, and every permission a role can hold with a one-line meaning.

• Permission: org.members.read
• API token: not available, use a signed-in session

POST /api/v1/orgs/{org}/roles

Create a role

Defines a role of the organisation's own from permissions in the catalog. You can only include permissions you hold yourself (403 role_escalation), a name may not be a built-in role's or already used (422), and an organisation has at most 20 (409 role_limit). A personal organisation has none (409 personal_org). Nobody holds the role until a member is given it.

• Permission: org.members.manage
• API token: not available, use a signed-in session

Request body (JSON):

{
  "description": "string",
  "name": "string",
  "permissions": [
    null
  ]
}

DELETE /api/v1/orgs/{org}/roles/{role}

Delete a role

Deletes a role nobody holds. A role in use is refused (409 role_in_use): move its members to another role first. Needs a recent step-up and a role whose permissions you hold in full.

• Permission: org.members.manage
• API token: not available, use a signed-in session
• Step-up: needs a recent password check

PATCH /api/v1/orgs/{org}/roles/{role}

Change a role

Replaces the name, description and permissions of a role. Everyone who holds it changes with it. Needs a recent step-up. You can only change a role whose permissions you hold in full, and only to permissions you hold (403 role_escalation).

• Permission: org.members.manage
• API token: not available, use a signed-in session
• Step-up: needs a recent password check

Request body (JSON):

{
  "description": "string",
  "name": "string",
  "permissions": [
    null
  ]
}

GET /api/v1/orgs/{org}/servers

List servers

Newest first, with the server id as tiebreak. Repeat the label query parameter to keep only servers that carry every label given (case does not matter). Without limit and cursor every matching server is returned; with them the list is cursor paged (limit 1 to 200) and next_cursor is the cursor for the next page, null on the last. An invalid cursor or limit is 422.

• Permission: servers.read
• API token scope: servers:read

Example:

curl -X GET "$VEXELIA_URL/api/v1/orgs/$org/servers" \
  -H "Authorization: Bearer $VEXELIA_TOKEN"

GET /api/v1/orgs/{org}/servers/{server}

Get a server

Returns one server: its plan, image, addresses, power state, lifecycle and any action still running. Poll it, or the operation it names, after a power, rebuild or firewall change.

• Permission: servers.read
• API token scope: servers:read

Example:

curl -X GET "$VEXELIA_URL/api/v1/orgs/$org/servers/$server" \
  -H "Authorization: Bearer $VEXELIA_TOKEN"

GET /api/v1/orgs/{org}/servers/{server}/apps

The apps installed on a server and the apps it can install

The server's apps, newest first (installed, being installed, failed, and removed by a rebuild), each with its state, where it answers, where its credentials are, and the choices made; and the apps that may be installed on an existing server. A queued or running install the server has said nothing about for 45 minutes shows as unconfirmed. Answers not_found when the marketplace is switched off. Closed to API tokens.

• Permission: servers.read
• API token: not available, use a signed-in session

POST /api/v1/orgs/{org}/servers/{server}/apps

Install an app on an existing server

Queues the install of one signed first-party app on a server that is already in use. Run the plan first: it shows every check and what will change. The server restarts once (confirm_restart must be true, app_restart_confirm_required otherwise); the host verifies the app's signature with its own key, generates every password itself and a Vexelia installer runs as root inside the server, refusing to run over files, packages, users or ports it did not create. Refused with 409 when the server is not running (app_server_not_running), is not Debian or Ubuntu (app_unsupported_os), the plan is too small (app_plan_too_small), the host cannot install apps (app_host_unsupported), the app is already installed (app_already_installed), another install runs (app_install_busy), a port is taken by another app (app_port_conflict), or a limit is reached (app_limit, app_too_many_failures, app_rate_limited); with 422 on inputs (including a password, which is never accepted). A repeat with the same Idempotency-Key returns the same install. Returns 202; progress is the app's state. Needs a verified email and step-up. Closed to API tokens.

• Permission: servers.manage
• API token: not available, use a signed-in session
• Step-up: needs a recent password check

Request body (JSON):

{
  "confirm_restart": false,
  "inputs": {},
  "recipe_id": "string"
}

POST /api/v1/orgs/{org}/servers/{server}/apps/plan

Check an app install on a server and show what it would change

A dry run: validates the choices exactly as the host will, checks the server (running, supported system and processor, enough disk and memory, a host that can install, no other install running, no port clash with the apps already there) and lists what would change, including the restart and whether a snapshot first is advised. Nothing is written and no host is asked. Every finding is in the answer, with ok false when any check failed. Answers 422 on recipe_id for an app that is not offered for existing servers.

• Permission: servers.manage
• API token: not available, use a signed-in session

Request body (JSON):

{
  "inputs": {},
  "recipe_id": "string"
}

GET /api/v1/orgs/{org}/servers/{server}/apps/{app}

One app on a server and its install progress

The app, its state and where it answers. The state comes from the customer's own server, so treat it as a hint. An app of another server or organisation is not found.

• Permission: servers.read
• API token: not available, use a signed-in session

POST /api/v1/orgs/{org}/servers/{server}/apps/{app}/abandon

Give up on an install that is not finishing

Ends a queued or running install: it becomes failed with the reason user_gave_up, leaves the live set (the app can be installed again) and releases the server (a resize or a restore is no longer held back). Nothing is undone on the server: what the installer already did stays. Refused with 409 app_install_running while the host reports the install running (its operation running, or progress in the last ten minutes) and 409 app_not_abandonable when it already ended. Installs that no host picks up are ended automatically after 2 hours, and ones silent for hours after the stale window. Needs step-up. Closed to API tokens.

• Permission: servers.manage
• API token: not available, use a signed-in session
• Step-up: needs a recent password check

POST /api/v1/orgs/{org}/servers/{server}/apps/{app}/changes

Uninstall or update an app on an existing server

Queues the uninstall or the update of one installed app. Run the plan first. The server restarts once (confirm_restart must be true, app_restart_confirm_required otherwise); the host verifies the app's signature with its own key and a Vexelia script runs as root inside the server, removing only what the installer created or updating the app in place. Choosing to remove the app's data needs confirm_data_removal: true (app_data_removal_confirm_required otherwise) and the plan's data_digest echoed as data_digest (app_data_removal_changed when what would be deleted is no longer what the plan listed); keep_data defaults to true. The change carries no password or other secret. Refused with 409 when the app is not ready (app_change_not_ready), the recipe has no such step or the installed version is too old to update (app_change_unsupported), it is already at the newest version (app_up_to_date), another install or change holds the server (app_change_busy), the server is not running (app_server_not_running), the host cannot change apps (app_host_unsupported), or a limit is reached (app_too_many_failures, app_rate_limited). A repeat with the same Idempotency-Key returns the same change. Returns 202; progress is the change's state, and an uninstall that succeeds moves the app to removed, an update records the new version. Needs a verified email and step-up. Closed to API tokens.

• Permission: servers.manage
• API token: not available, use a signed-in session
• Step-up: needs a recent password check

Request body (JSON):

{
  "action": "uninstall",
  "confirm_data_removal": false,
  "confirm_restart": false,
  "data_digest": "string",
  "keep_data": false
}

GET /api/v1/orgs/{org}/servers/{server}/apps/{app}/changes/{change}

One uninstall or update of an app and its progress

The change, its state and the step it stopped at. The state comes from the customer's own server, so treat it as a hint. A change of another app, server or organisation is not found.

• Permission: servers.read
• API token: not available, use a signed-in session

POST /api/v1/orgs/{org}/servers/{server}/apps/{app}/changes/{change}/abandon

Give up on an uninstall or update that is not finishing

Ends a queued or running change: it becomes failed with the reason user_gave_up and releases the server (a resize or a restore is no longer held back). The app stays installed as the record had it; nothing is undone on the server, so what the script already did stays. Refused with 409 app_change_running while the host reports the change running (its operation running, or progress in the last ten minutes) and 409 app_change_not_abandonable when it already ended. Changes that no host picks up are ended automatically after 2 hours, and ones silent for hours after the stale window. Needs step-up. Closed to API tokens.

• Permission: servers.manage
• API token: not available, use a signed-in session
• Step-up: needs a recent password check

POST /api/v1/orgs/{org}/servers/{server}/apps/{app}/credentials/reveal

Show an app's generated credentials once

Returns the passwords the host generated for this install and marks them shown. The first call gets them (Cache-Control: no-store); every later call is 409 credentials_viewed, and a call before the host delivered them is 409 app_no_credentials. Recorded in Activity by key count, never by value. Needs step-up. Closed to API tokens.

• Permission: servers.manage
• API token: not available, use a signed-in session
• Step-up: needs a recent password check

POST /api/v1/orgs/{org}/servers/{server}/apps/{app}/plan

Check an uninstall or update of an app and show what it would change

A dry run for uninstalling or updating an installed app: checks the app (finished installing, the recipe still offered with the step you asked for, and for an update a newer version the recipe can update this install to), the server (active, running, not in rescue or on an ISO), the host (it reports it can change apps), that no install or other change holds the server, and the abuse limits. It says what goes whatever you choose (removes), the data that is kept or removed with your choice (data_choice, keep_data, data_kept, data_removed; the choice defaults to keeping the data), what an update changes (notes), what happens to the server (the restart and the root script; a failure part-way leaves what it did, and a snapshot taken first is the only way back) and whether a snapshot is advised. Nothing is written and no host is asked. An app of another server or organisation is not found.

• Permission: servers.manage
• API token: not available, use a signed-in session

Request body (JSON):

{
  "action": "uninstall",
  "keep_data": false
}

GET /api/v1/orgs/{org}/servers/{server}/automation

A server's user-data, startup scripts and cloud-init switch

What the server is given on its first boot after a rebuild: the cloud-init user-data, the named startup scripts in order, the cloud-init switch, and the variables the text may use. The text may hold the caller's own secrets, so it needs servers.manage, is never cached, and never appears in the audit log. It runs as root on the first boot only; changing it does not touch a running server, it is used at the next rebuild.

• Permission: servers.manage
• API token: not available, use a signed-in session

PUT /api/v1/orgs/{org}/servers/{server}/automation

Set a server's user-data or cloud-init switch

Sets the user-data (a #cloud-config document or a #! script, up to 64 KiB; #include is refused; a cloud-config that is not valid YAML is accepted with a warning) and/or the cloud-init switch. Variables are written ${vexelia.server.id}, ${vexelia.server.hostname}, ${vexelia.net.ipv4}, ${vexelia.net.ipv6_prefix} and ${vexelia.org.KEY}; any other ${vexelia.x} is refused naming it, and other ${...} (a shell's own) is left alone. Substitution happens once, so a value that contains ${vexelia.x} is not expanded again. The user-data and scripts together are at most 192 KiB.

• Permission: servers.manage
• API token: not available, use a signed-in session

Request body (JSON):

{
  "cloud_init_enabled": false,
  "user_data": "string"
}

POST /api/v1/orgs/{org}/servers/{server}/automation/scripts

Add a startup script

Adds a named script that starts with a

• Permission: servers.manage
• API token: not available, use a signed-in session

Request body (JSON):

{
  "content": "string",
  "name": "string",
  "position": 0
}

DELETE /api/v1/orgs/{org}/servers/{server}/automation/scripts/{script}

Delete a startup script

Deletes a startup script from the server. Returns not_found if the script does not exist on this server.

• Permission: servers.manage
• API token: not available, use a signed-in session

PUT /api/v1/orgs/{org}/servers/{server}/automation/scripts/{script}

Change a startup script

Replaces the script's name and text. Its position stays.

• Permission: servers.manage
• API token: not available, use a signed-in session

Request body (JSON):

{
  "content": "string",
  "name": "string"
}

POST /api/v1/orgs/{org}/servers/{server}/autopay

Turn automatic renewal on or off

Turns automatic renewal on or off for a server. Turning it on needs a saved card to charge (autopay_needs_card).

• Permission: billing.manage
• API token: not available, use a signed-in session

Request body (JSON):

{
  "autopay": false
}

GET /api/v1/orgs/{org}/servers/{server}/backups

List a server's backups

The server's backups, newest first, and its backup requests that are waiting or were refused. A backup is ready once its manifest has been read back and checked; incomplete means the node stopped part way; unusable means a stored object failed its check and it is never restored from. A stopped server's last ready backup stands (power_state says whether the server is stopped). consistency is application when the guest agent froze the disk, crash otherwise.

• Permission: servers.read
• API token scope: servers:read

Example:

curl -X GET "$VEXELIA_URL/api/v1/orgs/$org/servers/$server/backups" \
  -H "Authorization: Bearer $VEXELIA_TOKEN"

POST /api/v1/orgs/{org}/servers/{server}/backups

Back a server up now

Asks for a backup of the primary disk, or of the disks named, now. The worker starts it as soon as the server is free; it is incremental unless full is true or the server's disk was replaced, and a stopped server's backup is a full read of its disk. Limited to 2 requests per server in any 10 minutes (backup_cooldown, with retry_at), refused with backup_queued when that disk already has one waiting or running, and with server_not_active unless the server is active.

• Permission: servers.manage
• API token: not available, use a signed-in session

Request body (JSON):

{
  "disks": [
    null
  ],
  "full": false
}

DELETE /api/v1/orgs/{org}/servers/{server}/backups/addon

Turn the Backups addon off at the end of the paid period

The addon keeps working until the end of what is paid for (ends_at) and the renewal that starts then no longer carries it. There is no credit for the rest of the period (decision 0008 applied to addons). Existing backups stay listed and restorable until retention removes them; no new manual or scheduled backup is made once the addon ends, and the schedule is switched off then. Repeating the call changes nothing; turning the addon on again before ends_at withdraws it at no charge. addon_not_enabled when the addon is not on; renewal_charging while the server's renewal is being paid.

• Permission: servers.manage
• API token: not available, use a signed-in session
• Step-up: needs a recent password check

GET /api/v1/orgs/{org}/servers/{server}/backups/addon

Show a server's Backups addon and its price

Whether the Backups addon is on (state off, on, or ending: turned off, still working until ends_at), its price for one billing period at the price the next renewal uses (the greater of floor_minor_per_month times the months of the period and share_bp ten-thousandths of the plan's price for the period; both are staff settings), any open quote to pay, and the amount of a small charge deferred to the next renewal. Manual and scheduled backups need the addon (backup_addon_required without it); restoring and listing backups do not.

• Permission: servers.read
• API token scope: servers:read

Example:

curl -X GET "$VEXELIA_URL/api/v1/orgs/$org/servers/$server/backups/addon" \
  -H "Authorization: Bearer $VEXELIA_TOKEN"

POST /api/v1/orgs/{org}/servers/{server}/backups/addon

Turn the Backups addon on

Prices the addon for the rest of the period the customer has paid for (remaining over total as an exact duration, rounded half up once; a renewal paid before its period began adds that whole period too), plus tax. The response carries it as charge, which stands for 30 minutes and is paid with POST .../backups/addon/charges/{charge}/pay (credit first, then card or 3-D Secure); the addon is on once the payment settles. When nothing is to be paid first (a zero charge, a charge below the card minimum that the billing policy defers to the renewal, a turn-off withdrawn before it took effect, or the addon already on) enabled is true. The renewal after the paid period bills the addon whole as a line of its own at the plan's price then (decision 0012). Refused with renewal_charging while the server's renewal is being paid, addon_charge_open while another quote is being paid, paid_period_ended when the paid period has ended, server_not_active unless the server is active. Answers 503 tax_unavailable while tax cannot be worked out yet for the buyer's location; nothing is created or charged, and trying again later succeeds once it is set up.

• Permission: servers.manage
• API token: not available, use a signed-in session
• Step-up: needs a recent password check

POST /api/v1/orgs/{org}/servers/{server}/backups/addon/charges/{charge}/pay

Pay for turning the Backups addon on

Pays the addon's charge: wallet credit is held first, then one card intent covers the rest (the client secret is returned for Stripe.js), or the charge settles at once when credit covers it. Settlement issues an addon invoice, turns the addon on and voids the renewal that was issued without it. Repeating the call shows the same intent. quote_expired after 30 minutes (ask again), paid_period_ended if a renewal settled or the period ended since the quote, amount_below_minimum when the card part is below what the processor can charge. A payment that arrives after the quote can no longer be used is refunded to the card as a stray payment.

• Permission: servers.manage
• API token: not available, use a signed-in session
• Step-up: needs a recent password check

Request body (JSON):

{
  "payment_method": "00000000-0000-0000-0000-000000000000"
}

GET /api/v1/orgs/{org}/servers/{server}/backups/offsite

Show a server's off-site backup copy

Whether an off-site provider is connected (available), whether the weekly off-site copy is on for this server (decision 0019; on only while the Backups addon works), when it was turned on, when the last copy and the last monthly test restore succeeded, and the most recent runs (newest first, at most 12). A copy is an independent encrypted full image of the server's first disk kept with a second storage provider; a week with no succeeded run is a missed week. Listing needs no addon.

• Permission: servers.read
• API token: not available, use a signed-in session

PUT /api/v1/orgs/{org}/servers/{server}/backups/offsite

Turn a server's off-site backup copy on or off

Opts the server in (enabled true) or out (enabled false) of the weekly off-site copy. Turning it on needs an off-site provider to be connected (offsite_unavailable, 409, when none is) and the Backups addon (backup_addon_required without it); turning it off never needs either, and repeating either call changes nothing and is not audited again. Existing copies are not deleted by turning it off. The copy itself is made later by the platform's worker, not by this call. Audited when the state changes.

• Permission: servers.manage
• API token: not available, use a signed-in session

Request body (JSON):

{
  "enabled": false
}

POST /api/v1/orgs/{org}/servers/{server}/backups/restore

Restore a backup over a server

Replaces the server's first disk with the backup chosen. The server in the path is the one restored onto; the backup may be one of another server of the same organisation (a backup of another organisation answers not_found). The server's current disk is kept in node trash for 72 hours, the server keeps its addresses, and the node checks the whole backup before it touches the disk (a damaged backup is refused with the server untouched). The server is stopped, its disk swapped, started, and must report running before the restore counts as done. Needs step-up and the server's hostname in confirm_hostname. Refused with server_not_active unless the server is active, restore_open when another restore onto it is waiting or running, and validation_failed when the backup is not of a first disk or the server's disk is smaller than the backup. To restore into a new server instead, order one with restore_backup_id (POST /orgs/{org}/orders).

• Permission: servers.manage
• API token: not available, use a signed-in session
• Step-up: needs a recent password check

Request body (JSON):

{
  "backup_id": "00000000-0000-0000-0000-000000000000",
  "confirm_hostname": "string"
}

GET /api/v1/orgs/{org}/servers/{server}/backups/restore-point

Find the backup to restore for a time

Restore to a point in time. Backups are taken by schedule or on request with nothing stored between them, so the closest point is the newest ready backup of the server's first disk taken at or before the time in at (RFC 3339; a time in the future is read as now). The answer names the backup and taken_at, the time its disk image was frozen, so the customer sees what a restore will really bring back. Answers not_found when no ready backup that early is kept. Use the backup's id with the restore route, or as restore_backup_id on an order. Finer points between backups cannot be restored.

• Permission: servers.read
• API token scope: servers:read

Example:

curl -X GET "$VEXELIA_URL/api/v1/orgs/$org/servers/$server/backups/restore-point" \
  -H "Authorization: Bearer $VEXELIA_TOKEN"

GET /api/v1/orgs/{org}/servers/{server}/backups/restores

List restores onto a server

The latest restores requested onto this server. refusal says why a restore failed or was refused (server_busy, server_not_ready, server_changed, backup_unusable, corrupt, store_unavailable, post_restore_check_failed). mode is overwrite for a restore over this server's disk, and new_server for the restore a new-server order owes (order_id names the order). A new-server restore is refused with server_changed when the customer has rebuilt, resized, restored or otherwise worked on the new server before it started: the backup is then not put over that work.

• Permission: servers.read
• API token scope: servers:read

Example:

curl -X GET "$VEXELIA_URL/api/v1/orgs/$org/servers/$server/backups/restores" \
  -H "Authorization: Bearer $VEXELIA_TOKEN"

GET /api/v1/orgs/{org}/servers/{server}/backups/schedule

Show a server's backup schedule

Whether daily backups are on, the preferred start time and window in the chosen time zone, the allowed days (a bit mask, Monday 1 to Sunday 64), the extra disks included, the next three start times, and when the last run started or was missed. next_runs is empty while the schedule is off or paused; a suspended server's schedule pauses and resumes at the first window after it is active again. disks lists the disks that can be chosen.

• Permission: servers.read
• API token scope: servers:read

Example:

curl -X GET "$VEXELIA_URL/api/v1/orgs/$org/servers/$server/backups/schedule" \
  -H "Authorization: Bearer $VEXELIA_TOKEN"

PUT /api/v1/orgs/{org}/servers/{server}/backups/schedule

Change a server's backup schedule

Turns daily backups on or off and sets the preferred start, window and days. The start is best effort; if the worker cannot start it inside the window the run shows as missed. Extra disks must be attached now. Refused with server_not_active when turning it on for a server that is not active.

• Permission: servers.manage
• API token: not available, use a signed-in session

Request body (JSON):

{
  "allowed_days": 0,
  "enabled": false,
  "extra_disks": [
    null
  ],
  "tz": "string",
  "window_minutes": 0,
  "window_start_min": 0
}

GET /api/v1/orgs/{org}/servers/{server}/bandwidth