contact@ffxf.net
Console
This page is generated from the OpenAPI contract. Where it disagrees with the API, the contract is right: tell us.
Base URL https://api.ffxf.net/v1
OpenAPI contract openapi.v1.json
(The file this reference renders, as published.)
Contents
GET /regionsGET /plansGET /plans/{plan}GET /imagesGET /images/{image}GET /vmsPOST /vmsGET /vms/{vm}PATCH /vms/{vm}DELETE /vms/{vm}GET /vms/{vm}/metricsPOST /vms/{vm}/consoleGET /vms/{vm}/actionsPOST /vms/{vm}/actionsGET /actionsGET /actions/{action}GET /vms/{vm}/networkPOST /vms/{vm}/network/ipv6DELETE /vms/{vm}/network/ipv6/{address}PUT /vms/{vm}/network/rdnsGET /vms/{vm}/backupsPOST /vms/{vm}/backups/{backup}/restoreDELETE /vms/{vm}/backups/{backup}POST /auth/tokenGET /policiesPOST /policiesGET /policies/{policy}PUT /policies/{policy}DELETE /policies/{policy}GET /rolesPOST /rolesGET /roles/{role}PUT /roles/{role}DELETE /roles/{role}GET /api-keysPOST /api-keysGET /api-keys/{apiKey}DELETE /api-keys/{apiKey}GET /oidc/providersGET /oidc/bindingsPOST /oidc/bindingsGET /oidc/bindings/{binding}PUT /oidc/bindings/{binding}DELETE /oidc/bindings/{binding}GET /accountPUT /account/budgetGET /usageGET /ssh-keysPOST /ssh-keysDELETE /ssh-keys/{key}GET /vpcsPOST /vpcsGET /vpcs/{vpc}DELETE /vpcs/{vpc}POST /vpcs/{vpc}/membersDELETE /vpcs/{vpc}/members/{vm}POST /vpcs/{vpc}/members/{vm}/moveGET /firewallsPOST /firewallsGET /firewalls/{firewall}PUT /firewalls/{firewall}DELETE /firewalls/{firewall}POST /firewalls/{firewall}/membersDELETE /firewalls/{firewall}/members/{vm}GET /load-balancersPOST /load-balancersGET /load-balancers/{lb}PATCH /load-balancers/{lb}DELETE /load-balancers/{lb}GET /load-balancers/{lb}/metricsPOST /load-balancers/{lb}/poolsPATCH /load-balancers/{lb}/pools/{pool}DELETE /load-balancers/{lb}/pools/{pool}PUT /load-balancers/{lb}/pools/{pool}/targetsPATCH /load-balancers/{lb}/pools/{pool}/targets/{target}DELETE /load-balancers/{lb}/pools/{pool}/targets/{target}POST /load-balancers/{lb}/listenersPATCH /load-balancers/{lb}/listeners/{listener}DELETE /load-balancers/{lb}/listeners/{listener}PUT /load-balancers/{lb}/listeners/{listener}/rulesGET /databasesPOST /databasesGET /databases/optionsGET /databases/{database}PATCH /databases/{database}DELETE /databases/{database}GET /databases/{database}/credentialsPOST /databases/{database}/usersPATCH /databases/{database}/users/{username}DELETE /databases/{database}/users/{username}POST /databases/{database}/users/{username}/reset-passwordPOST /databases/{database}/databasesDELETE /databases/{database}/databases/{name}POST /databases/{database}/databases/{name}/extensionsDELETE /databases/{database}/databases/{name}/extensions/{extension}PUT /databases/{database}/public-accessGET /databases/{database}/backupsPOST /databases/{database}/backupsPOST /databases/{database}/restorePOST /databases/{database}/forksPOST /databases/{database}/resizePOST /databases/{database}/detachGET /databases/{database}/metricsGET /databases/{database}/queriesGET /runnersGET /runners/jobs
Catalog
get
/regions
No key
List regions. Where machines can run. A plan or an image may not be offered everywhere.
Parameters
No parameters.
Responses
| HTTP | Description |
|---|---|
200 | OK |
get
/plans
No key
List plans
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
region | query | string | no | Keep only the plans offered in this region. |
Responses
| HTTP | Description |
|---|---|
200 | OK |
get
/plans/{plan}
No key
Get a plan
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
plan | path | string | yes |
Responses
| HTTP | Description |
|---|---|
200 | OK |
404 | No such resource, or it does not belong to this account. |
get
/images
No key
List images. The image referential. `slug` is the stable identifier to pass at
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
region | query | string | no | Keep only the images available in this region. |
plan | query | string | no | Keep only the images that fit this plan. |
category | query | linux | windows | bsd | app | … | no |
Responses
| HTTP | Description |
|---|---|
200 | OK |
get
/images/{image}
No key
Get an image
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
image | path | string | yes |
Responses
| HTTP | Description |
|---|---|
200 | OK |
404 | No such resource, or it does not belong to this account. |
Machines
get
/vms
List machines
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
cursor | query | string | no | The `next_cursor` from the previous page. |
limit | query | integer | no | |
status | query | VmStatus | no | |
region | query | string | no | |
billing | query | hourly | monthly | no |
Responses
| HTTP | Description |
|---|---|
200 | OK |
401 | Missing, unknown, disabled or expired key. |
post
/vms
Create a machine. Runs the same checks as the console, in this order: account standing,
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | yes | Unique per order, your own value. Kept 24 hours. |
Request body
| Name | Type | Required | Description |
|---|---|---|---|
plan | string | yes | |
region | string | yes | |
image | string | yes | |
hostname | Hostname | yes | |
billing | hourly | monthly | yes | |
payment | credit | manual | no | Monthly only. `credit` settles the invoice from the balance when it |
ssh_keys | string[] | no | Fingerprints or ids of keys on the account. Ignored by images without cloud-init key support, and by `netboot` (nothing is injected; the network settings are mailed instead). |
password_delivery | email | none | no | `email` generates a password and mails it. `none` requires at least |
options | object | no | Paid options declared by the plan, by name. Unknown keys are refused. |
ipv4 | boolean | no | `false` orders an IPv6-only machine, at a lower price: no public |
vpc | integer | no | Private network to connect the machine to, in the same region. Its |
private_only | boolean | no | No public address at all (requires `vpc`): the machine is reachable |
dry_run | boolean | no | Run every check and price the order without creating anything. |
Responses
| HTTP | Description |
|---|---|
202 | Order accepted. `action` follows the provisioning; it is null when |
200 | Estimate returned (`dry_run: true`). Nothing was created. |
400 | Malformed request. |
402 | Not enough credit, or a budget cap reached. An hourly order needs the |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
409 | The resource is not in a state that allows this: machine suspended, |
422 | The request is well formed but the catalogue refuses it: image below the |
429 | Too many requests. |
get
/vms/{vm}
Get a machine
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
vm | path | integer | yes | The machine id. A machine is identified by its service: the id exists |
Responses
| HTTP | Description |
|---|---|
200 | OK |
404 | No such resource, or it does not belong to this account. |
patch
/vms/{vm}
Update a machine. Only the hostname is editable. It is applied inside the guest and to the
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
vm | path | integer | yes | The machine id. A machine is identified by its service: the id exists |
Request body
| Name | Type | Required | Description |
|---|---|---|---|
hostname | Hostname | no |
Responses
| HTTP | Description |
|---|---|
200 | OK |
409 | The resource is not in a state that allows this: machine suspended, |
delete
/vms/{vm}
Destroy a machine. Destroys the machine and its disk. There is no undo and no backup is
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
vm | path | integer | yes | The machine id. A machine is identified by its service: the id exists |
confirm | query | string | yes | The machine's exact hostname. |
when | query | period_end | now | no | Monthly machines only. |
Responses
| HTTP | Description |
|---|---|
202 | Accepted |
400 | Malformed request. |
404 | No such resource, or it does not belong to this account. |
409 | The resource is not in a state that allows this: machine suspended, |
get
/vms/{vm}/metrics
Get machine metrics. CPU, memory, disk and network, as measured from outside the machine.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
vm | path | integer | yes | The machine id. A machine is identified by its service: the id exists |
timeframe | query | hour | day | week | month | … | no |
Responses
| HTTP | Description |
|---|---|
200 | OK |
503 | The infrastructure did not answer in time. Nothing was changed; retry. |
post
/vms/{vm}/console
Open a console session. Returns a single-use URL to the VNC console, valid for a few minutes.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
vm | path | integer | yes | The machine id. A machine is identified by its service: the id exists |
Responses
| HTTP | Description |
|---|---|
201 | Created |
409 | The resource is not in a state that allows this: machine suspended, |
Actions
get
/vms/{vm}/actions
List a machine's actions
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
vm | path | integer | yes | The machine id. A machine is identified by its service: the id exists |
cursor | query | string | no | The `next_cursor` from the previous page. |
limit | query | integer | no |
Responses
| HTTP | Description |
|---|---|
200 | OK |
post
/vms/{vm}/actions
Act on a machine. `start`, `shutdown`, `reboot` ask the guest politely. `stop` cuts the
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
vm | path | integer | yes | The machine id. A machine is identified by its service: the id exists |
Idempotency-Key | header | string | no |
Request body
| Name | Type | Required | Description |
|---|---|---|---|
type | start | shutdown | reboot | stop | yes |
Responses
| HTTP | Description |
|---|---|
202 | Accepted |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
409 | The resource is not in a state that allows this: machine suspended, |
422 | The request is well formed but the catalogue refuses it: image below the |
503 | The infrastructure did not answer in time. Nothing was changed; retry. |
get
/actions
List actions
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
cursor | query | string | no | The `next_cursor` from the previous page. |
limit | query | integer | no | |
status | query | ActionStatus | no |
Responses
| HTTP | Description |
|---|---|
200 | OK |
get
/actions/{action}
Get an action. Poll this until `status` leaves `running`. A completed action is kept 30 days.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
action | path | integer | yes |
Responses
| HTTP | Description |
|---|---|
200 | OK |
404 | No such resource, or it does not belong to this account. |
Networking
get
/vms/{vm}/network
Get a machine's addresses
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
vm | path | integer | yes | The machine id. A machine is identified by its service: the id exists |
Responses
| HTTP | Description |
|---|---|
200 | OK |
post
/vms/{vm}/network/ipv6
Add an address from the machine's IPv6 prefix. Each machine carries a routed /64. An address taken here is registered
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
vm | path | integer | yes | The machine id. A machine is identified by its service: the id exists |
Request body
| Name | Type | Required | Description |
|---|---|---|---|
address | string | yes | Full address inside the machine's prefix. |
Responses
| HTTP | Description |
|---|---|
201 | Created |
409 | The resource is not in a state that allows this: machine suspended, |
422 | The request is well formed but the catalogue refuses it: image below the |
delete
/vms/{vm}/network/ipv6/{address}
Release an IPv6 address
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
vm | path | integer | yes | The machine id. A machine is identified by its service: the id exists |
address | path | string | yes |
Responses
| HTTP | Description |
|---|---|
204 | Released |
404 | No such resource, or it does not belong to this account. |
put
/vms/{vm}/network/rdns
Set reverse DNS on an address
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
vm | path | integer | yes | The machine id. A machine is identified by its service: the id exists |
Request body
| Name | Type | Required | Description |
|---|---|---|---|
address | string | yes | |
hostname | string | no | Null clears the record and restores the default. |
Responses
| HTTP | Description |
|---|---|
200 | OK |
422 | The request is well formed but the catalogue refuses it: image below the |
Backups
get
/vms/{vm}/backups
List backups
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
vm | path | integer | yes | The machine id. A machine is identified by its service: the id exists |
Responses
| HTTP | Description |
|---|---|
200 | OK |
post
/vms/{vm}/backups/{backup}/restore
Restore a backup. Overwrites the current disk. The machine is stopped for the duration.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
vm | path | integer | yes | The machine id. A machine is identified by its service: the id exists |
backup | path | string | yes |
Responses
| HTTP | Description |
|---|---|
202 | Accepted |
409 | The resource is not in a state that allows this: machine suspended, |
delete
/vms/{vm}/backups/{backup}
Delete a backup
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
vm | path | integer | yes | The machine id. A machine is identified by its service: the id exists |
backup | path | string | yes |
Responses
| HTTP | Description |
|---|---|
204 | Deleted |
404 | No such resource, or it does not belong to this account. |
Auth
post
/auth/token
Exchange a credential for a temporary access token. Authenticate with an API key or an OIDC token that may assume the
Parameters
No parameters.
Request body
| Name | Type | Required | Description |
|---|---|---|---|
role | any | yes | Id or name of a role the credential may assume. |
duration_seconds | integer | no | Lifetime. Values outside 900–3600 are clamped. |
Responses
| HTTP | Description |
|---|---|
201 | Token issued. |
401 | Missing, unknown, disabled or expired key. |
403 | `role_not_assumable`, `exchange_forbidden` or `ip_not_allowed`. |
Access management
get
/policies
List policys
Parameters
No parameters.
Responses
| HTTP | Description |
|---|---|
200 | OK |
401 | Missing, unknown, disabled or expired key. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
post
/policies
Create a policy
Parameters
No parameters.
Request body
| Name | Type | Required | Description |
|---|---|---|---|
name | string | yes | |
description | string | no | |
document | any | yes | A policy document (object or JSON string), see the security scheme. |
Responses
| HTTP | Description |
|---|---|
201 | OK |
401 | Missing, unknown, disabled or expired key. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
400 | Malformed request. |
get
/policies/{policy}
Get a policy
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
policy | path | integer | yes |
Responses
| HTTP | Description |
|---|---|
200 | OK |
401 | Missing, unknown, disabled or expired key. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
put
/policies/{policy}
Replace a policy
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
policy | path | integer | yes |
Request body
| Name | Type | Required | Description |
|---|---|---|---|
name | string | yes | |
description | string | no | |
document | any | yes | A policy document (object or JSON string), see the security scheme. |
Responses
| HTTP | Description |
|---|---|
200 | OK |
401 | Missing, unknown, disabled or expired key. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
400 | Malformed request. |
delete
/policies/{policy}
Delete a policy
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
policy | path | integer | yes |
Responses
| HTTP | Description |
|---|---|
204 | Deleted. |
401 | Missing, unknown, disabled or expired key. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
409 | The resource is not in a state that allows this: machine suspended, |
get
/roles
List roles
Parameters
No parameters.
Responses
| HTTP | Description |
|---|---|
200 | OK |
401 | Missing, unknown, disabled or expired key. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
post
/roles
Create a role
Parameters
No parameters.
Request body
| Name | Type | Required | Description |
|---|---|---|---|
name | string | yes | |
description | string | no | |
policy_ids | integer[] | yes | Ids from `GET /policies`, yours or provided (`vms.read`…). |
Responses
| HTTP | Description |
|---|---|
201 | OK |
401 | Missing, unknown, disabled or expired key. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
400 | Malformed request. |
get
/roles/{role}
Get a role
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
role | path | integer | yes |
Responses
| HTTP | Description |
|---|---|
200 | OK |
401 | Missing, unknown, disabled or expired key. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
put
/roles/{role}
Replace a role
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
role | path | integer | yes |
Request body
| Name | Type | Required | Description |
|---|---|---|---|
name | string | yes | |
description | string | no | |
policy_ids | integer[] | yes | Ids from `GET /policies`, yours or provided (`vms.read`…). |
Responses
| HTTP | Description |
|---|---|
200 | OK |
401 | Missing, unknown, disabled or expired key. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
400 | Malformed request. |
delete
/roles/{role}
Delete a role
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
role | path | integer | yes |
Responses
| HTTP | Description |
|---|---|
204 | Deleted. |
401 | Missing, unknown, disabled or expired key. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
409 | The resource is not in a state that allows this: machine suspended, |
get
/api-keys
List API keys
Parameters
No parameters.
Responses
| HTTP | Description |
|---|---|
200 | OK |
401 | Missing, unknown, disabled or expired key. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
post
/api-keys
Create an API key (the token is returned once)
Parameters
No parameters.
Request body
| Name | Type | Required | Description |
|---|---|---|---|
name | string | yes | |
role | any | no | Id or name of the role the key has the rights of. Required unless `exchange_only`. |
exchange_only | boolean | no | |
assumable_roles | any[] | no | Roles obtainable through `POST /auth/token`. Required when `exchange_only`. |
ip_addresses | string[] | no | |
expires_at | string | no |
Responses
| HTTP | Description |
|---|---|
201 | OK |
401 | Missing, unknown, disabled or expired key. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
400 | Malformed request. |
get
/api-keys/{apiKey}
Get an API key
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
apiKey | path | integer | yes |
Responses
| HTTP | Description |
|---|---|
200 | OK |
401 | Missing, unknown, disabled or expired key. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
delete
/api-keys/{apiKey}
Revoke an API key
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
apiKey | path | integer | yes |
Responses
| HTTP | Description |
|---|---|
204 | Deleted. |
401 | Missing, unknown, disabled or expired key. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
409 | The resource is not in a state that allows this: machine suspended, |
get
/oidc/providers
List OIDC providers
Parameters
No parameters.
Responses
| HTTP | Description |
|---|---|
200 | OK |
401 | Missing, unknown, disabled or expired key. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
get
/oidc/bindings
List OIDC bindings
Parameters
No parameters.
Responses
| HTTP | Description |
|---|---|
200 | OK |
401 | Missing, unknown, disabled or expired key. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
post
/oidc/bindings
Create a OIDC binding
Parameters
No parameters.
Request body
| Name | Type | Required | Description |
|---|---|---|---|
provider_id | integer | yes | |
name | string | yes | |
claim_conditions | object[] | yes | Must include a `sub` condition naming the owner. |
role | any | no | |
exchange_only | boolean | no | |
assumable_roles | any[] | no | |
expires_at | string | no |
Responses
| HTTP | Description |
|---|---|
201 | OK |
401 | Missing, unknown, disabled or expired key. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
400 | Malformed request. |
get
/oidc/bindings/{binding}
Get a OIDC binding
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
binding | path | integer | yes |
Responses
| HTTP | Description |
|---|---|
200 | OK |
401 | Missing, unknown, disabled or expired key. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
put
/oidc/bindings/{binding}
Replace a OIDC binding
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
binding | path | integer | yes |
Request body
| Name | Type | Required | Description |
|---|---|---|---|
provider_id | integer | yes | |
name | string | yes | |
claim_conditions | object[] | yes | Must include a `sub` condition naming the owner. |
role | any | no | |
exchange_only | boolean | no | |
assumable_roles | any[] | no | |
expires_at | string | no |
Responses
| HTTP | Description |
|---|---|
200 | OK |
401 | Missing, unknown, disabled or expired key. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
400 | Malformed request. |
delete
/oidc/bindings/{binding}
Delete a OIDC binding
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
binding | path | integer | yes |
Responses
| HTTP | Description |
|---|---|
204 | Deleted. |
401 | Missing, unknown, disabled or expired key. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
409 | The resource is not in a state that allows this: machine suspended, |
Account
get
/account
Get account standing. Everything an automated fleet needs to decide on its own: balance, what
Parameters
No parameters.
Responses
| HTTP | Description |
|---|---|
200 | OK |
put
/account/budget
Set the monthly budget. The same budget as the console's Usage page. Warnings are sent at 50, 80
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | no |
Request body
| Name | Type | Required | Description |
|---|---|---|---|
monthly | any | yes | Amount in the account currency, 0 to 1,000,000, rounded to the cent. Null removes the budget. |
Responses
| HTTP | Description |
|---|---|
200 | The budget as it now stands, in the same shape as `budget` in `GET /account`. |
400 | Malformed request. |
get
/usage
List hourly usage. One record per hour charged, per machine. This is the ledger the
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
from | query | string | no | |
to | query | string | no | |
vm_id | query | integer | no | |
group_by | query | hour | vm | no | Return one line per machine instead of one per hour. |
cursor | query | string | no | The `next_cursor` from the previous page. |
limit | query | integer | no |
Responses
| HTTP | Description |
|---|---|
200 | OK |
SSH keys
get
/ssh-keys
List SSH keys
Parameters
No parameters.
Responses
| HTTP | Description |
|---|---|
200 | OK |
post
/ssh-keys
Add an SSH key. Up to 20 keys per account. Re-adding a known fingerprint returns the existing key.
Parameters
No parameters.
Request body
| Name | Type | Required | Description |
|---|---|---|---|
name | string | yes | |
public_key | string | yes |
Responses
| HTTP | Description |
|---|---|
201 | Created |
400 | Malformed request. |
delete
/ssh-keys/{key}
Delete an SSH key. Machines already deployed with this key keep it; only future deployments change.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
key | path | integer | yes |
Responses
| HTTP | Description |
|---|---|
204 | Deleted |
404 | No such resource, or it does not belong to this account. |
Private networks
get
/vpcs
List private networks. Scope `vms.read`.
Parameters
No parameters.
Responses
| HTTP | Description |
|---|---|
200 | OK |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
post
/vpcs
Create a private network. Scope `network.write`. The network is ready when the call returns (a
Parameters
No parameters.
Request body
| Name | Type | Required | Description |
|---|---|---|---|
name | string | yes | |
cidr | string | yes | A private IPv4 range, from /16 to /29, within 10.0.0.0/8, 172.16.0.0/12 or 192.168.0.0/16. |
region | string | yes |
Responses
| HTTP | Description |
|---|---|
201 | Created |
400 | Malformed request. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
409 | The resource is not in a state that allows this: machine suspended, |
get
/vpcs/{vpc}
Get a private network. Scope `vms.read`.
Parameters
No parameters.
Responses
| HTTP | Description |
|---|---|
200 | OK |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
delete
/vpcs/{vpc}
Delete a private network. Scope `network.write`. Refused with `action_conflict` while a machine is still on it.
Parameters
No parameters.
Responses
| HTTP | Description |
|---|---|
204 | Deleted |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
409 | The resource is not in a state that allows this: machine suspended, |
post
/vpcs/{vpc}/members
Connect a machine. Scope `network.write`. A network card is hot-added and its address set
Parameters
No parameters.
Request body
| Name | Type | Required | Description |
|---|---|---|---|
vm | integer | yes | Machine id, as in `GET /vms`. |
ip | string | no | Address wanted in the range. Default: the next free one. |
Responses
| HTTP | Description |
|---|---|
200 | Already connected |
201 | Connected |
400 | Malformed request. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
409 | The resource is not in a state that allows this: machine suspended, |
delete
/vpcs/{vpc}/members/{vm}
Disconnect a machine. Scope `network.write`. The address is removed from the system and the
Parameters
No parameters.
Responses
| HTTP | Description |
|---|---|
204 | Disconnected |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
409 | The resource is not in a state that allows this: machine suspended, |
post
/vpcs/{vpc}/members/{vm}/move
Move a machine to another private network. Scope `network.write`. The machine joins the target network, then
Parameters
No parameters.
Request body
| Name | Type | Required | Description |
|---|---|---|---|
to | integer | yes | Target private network id. |
Responses
| HTTP | Description |
|---|---|
200 | Moved |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
409 | The resource is not in a state that allows this: machine suspended, |
Firewalls
get
/firewalls
List firewalls. Scope `vms.read`.
Parameters
No parameters.
Responses
| HTTP | Description |
|---|---|
200 | OK |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
post
/firewalls
Create a firewall. Scope `network.write`. Without `rules`, the firewall starts with SSH
Parameters
No parameters.
Request body
| Name | Type | Required | Description |
|---|---|---|---|
name | string | yes | |
rules | FirewallRule[] | no |
Responses
| HTTP | Description |
|---|---|
201 | Created |
400 | Malformed request. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
409 | The resource is not in a state that allows this: machine suspended, |
get
/firewalls/{firewall}
Get a firewall. Scope `vms.read`.
Parameters
No parameters.
Responses
| HTTP | Description |
|---|---|
200 | OK |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
put
/firewalls/{firewall}
Rename a firewall or replace its rules. Scope `network.write`. `rules` replaces the whole list: describe the
Parameters
No parameters.
Request body
| Name | Type | Required | Description |
|---|---|---|---|
name | string | no | |
rules | FirewallRule[] | no |
Responses
| HTTP | Description |
|---|---|
200 | Updated |
400 | Malformed request. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
delete
/firewalls/{firewall}
Delete a firewall. Scope `network.write`. Refused with `action_conflict` while it is attached to a machine.
Parameters
No parameters.
Responses
| HTTP | Description |
|---|---|
204 | Deleted |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
409 | The resource is not in a state that allows this: machine suspended, |
post
/firewalls/{firewall}/members
Attach a firewall to a machine. Scope `network.write`. The rules are written when the call returns and
Parameters
No parameters.
Request body
| Name | Type | Required | Description |
|---|---|---|---|
vm | integer | yes | Machine id, as in `GET /vms`. |
Responses
| HTTP | Description |
|---|---|
200 | Already attached |
201 | Attached |
400 | Malformed request. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
409 | The resource is not in a state that allows this: machine suspended, |
delete
/firewalls/{firewall}/members/{vm}
Detach a firewall from a machine. Scope `network.write`. Its rules are removed from the machine; with no
Parameters
No parameters.
Responses
| HTTP | Description |
|---|---|
204 | Detached |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
Load balancers
get
/load-balancers
List load balancers. Scope `vms.read`.
Parameters
No parameters.
Responses
| HTTP | Description |
|---|---|
200 | OK |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
post
/load-balancers
Create a load balancer. Scope `vms.create`; `Idempotency-Key` required. Billed by the hour from
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | yes | Unique per order, your own value. Kept 24 hours. |
Request body
| Name | Type | Required | Description |
|---|---|---|---|
name | string | yes | |
vpc | integer | yes | Private network id, as in `GET /vpcs`. Its machines are the possible targets. |
billing | hourly | monthly | yearly | no | hourly (default), monthly (the price of 730 hours: 7.30 CAD) or yearly (ten months: 73 CAD). A monthly or yearly period comes out of credit if it covers it; otherwise `billing.pending_invoice` holds the invoice to pay and the resource stays hourly until it is paid. |
Responses
| HTTP | Description |
|---|---|
202 | Ordered |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
409 | The resource is not in a state that allows this: machine suspended, |
get
/load-balancers/{lb}
Get a load balancer. Scope `vms.read`. Everything at once; pools with their targets and health, listeners with their rules, certificates.
Parameters
No parameters.
Responses
| HTTP | Description |
|---|---|
200 | OK |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
patch
/load-balancers/{lb}
Rename a load balancer. Scope `network.write`.
Parameters
No parameters.
Request body
| Name | Type | Required | Description |
|---|---|---|---|
name | string | yes |
Responses
| HTTP | Description |
|---|---|
200 | OK |
400 | Malformed request. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
delete
/load-balancers/{lb}
Delete a load balancer. Scope `vms.destroy`. The load balancer, its address and its
Parameters
No parameters.
Responses
| HTTP | Description |
|---|---|
202 | Deletion started |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
get
/load-balancers/{lb}/metrics
Load balancer statistics. Scope `vms.read`. Per-minute counters kept 7 days, grouped by 1 minute
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | 1h | 24h | 7d | no |
Responses
| HTTP | Description |
|---|---|
200 | OK |
400 | Malformed request. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
post
/load-balancers/{lb}/pools
Create a pool. Scope `network.write`. Up to 10 pools. An `http` pool serves `http`/`https` listeners, a `tcp` pool `tcp` listeners.
Parameters
No parameters.
Request body
| Name | Type | Required | Description |
|---|---|---|---|
name | string | no | |
protocol | http | tcp | no | |
algorithm | roundrobin | leastconn | no | |
health_type | tcp | http | no | `http` pools only: GET `health_path`, 2xx or 3xx is healthy. |
health_path | string | no | |
health_interval | integer | no | Seconds; 3 failures mark a target down, 2 successes up. |
send_proxy | boolean | no | `tcp` pools only: PROXY protocol v2 towards the targets. |
Responses
| HTTP | Description |
|---|---|
201 | Created |
400 | Malformed request. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
patch
/load-balancers/{lb}/pools/{pool}
Update a pool. Scope `network.write`. Only the fields sent change. The protocol of a pool already used by a listener or rule cannot change.
Parameters
No parameters.
Request body
| Name | Type | Required | Description |
|---|---|---|---|
name | string | no | |
protocol | http | tcp | no | |
algorithm | roundrobin | leastconn | no | |
health_type | tcp | http | no | `http` pools only: GET `health_path`, 2xx or 3xx is healthy. |
health_path | string | no | |
health_interval | integer | no | Seconds; 3 failures mark a target down, 2 successes up. |
send_proxy | boolean | no | `tcp` pools only: PROXY protocol v2 towards the targets. |
Responses
| HTTP | Description |
|---|---|
200 | OK |
400 | Malformed request. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
delete
/load-balancers/{lb}/pools/{pool}
Delete a pool. Scope `network.write`. Its targets and the rules leading to it go too; a listener using it as default answers 503 until given another.
Parameters
No parameters.
Responses
| HTTP | Description |
|---|---|
204 | Deleted |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
put
/load-balancers/{lb}/pools/{pool}/targets
Replace the targets of a pool. Scope `network.write`. The pool ends up with exactly these targets
Parameters
No parameters.
Request body
| Name | Type | Required | Description |
|---|---|---|---|
targets | object[] | yes |
Responses
| HTTP | Description |
|---|---|
200 | OK |
400 | Malformed request. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
patch
/load-balancers/{lb}/pools/{pool}/targets/{target}
Weight or drain a target. Scope `network.write`. `drain: true` stops new connections to it; current ones finish.
Parameters
No parameters.
Request body
| Name | Type | Required | Description |
|---|---|---|---|
weight | integer | no | |
drain | boolean | no |
Responses
| HTTP | Description |
|---|---|
200 | OK |
400 | Malformed request. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
delete
/load-balancers/{lb}/pools/{pool}/targets/{target}
Remove a target. Scope `network.write`.
Parameters
No parameters.
Responses
| HTTP | Description |
|---|---|
204 | Removed |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
post
/load-balancers/{lb}/listeners
Open a listener. Scope `network.write`. Up to 5. Ports 22 and 8402 are reserved. A
Parameters
No parameters.
Request body
| Name | Type | Required | Description |
|---|---|---|---|
port | integer | no | |
protocol | http | https | tcp | no | |
default_pool | integer | no | Where traffic no rule matches goes; none answers 503 (HTTP). Required for `tcp`. |
redirect_https | boolean | no | `https` only: port 80 redirects to this listener. |
sources | string[] | no | IPv4/IPv6 addresses or ranges allowed in; null or empty: everyone. |
Responses
| HTTP | Description |
|---|---|
201 | Created |
400 | Malformed request. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
patch
/load-balancers/{lb}/listeners/{listener}
Update a listener. Scope `network.write`. Only the fields sent change. Switching to `tcp` drops its rules.
Parameters
No parameters.
Request body
| Name | Type | Required | Description |
|---|---|---|---|
port | integer | no | |
protocol | http | https | tcp | no | |
default_pool | integer | no | Where traffic no rule matches goes; none answers 503 (HTTP). Required for `tcp`. |
redirect_https | boolean | no | `https` only: port 80 redirects to this listener. |
sources | string[] | no | IPv4/IPv6 addresses or ranges allowed in; null or empty: everyone. |
Responses
| HTTP | Description |
|---|---|
200 | OK |
400 | Malformed request. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
delete
/load-balancers/{lb}/listeners/{listener}
Close a listener. Scope `network.write`. Its rules go too, and its port closes.
Parameters
No parameters.
Responses
| HTTP | Description |
|---|---|
204 | Closed |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
put
/load-balancers/{lb}/listeners/{listener}/rules
Replace the rules of a listener. Scope `network.write`. HTTP(S) listeners only; all or nothing, up to
Parameters
No parameters.
Request body
| Name | Type | Required | Description |
|---|---|---|---|
rules | LoadBalancerRule[] | yes |
Responses
| HTTP | Description |
|---|---|
200 | OK |
400 | Malformed request. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
Databases
get
/databases
List databases. Scope `vms.read`. No passwords here; see `GET /databases/{database}/credentials`.
Parameters
No parameters.
Responses
| HTTP | Description |
|---|---|
200 | OK |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
post
/databases
Create a database. Scope `vms.create`; `Idempotency-Key` required. Billed by the hour from
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | yes | Unique per order, your own value. Kept 24 hours. |
Request body
| Name | Type | Required | Description |
|---|---|---|---|
name | string | yes | |
vpc | integer | yes | Private network id, as in `GET /vpcs`. The database gets an address in it. |
engine | postgresql | mysql | mariadb | valkey | no | `mysql` is Percona Server; `valkey` is Redis-compatible. |
version | string | no | Major version from `GET /databases/options`; the newest when omitted. |
size_gb | integer | no | Memory in GB, one of the sizes of `GET /databases/options` for the region. |
billing | hourly | monthly | yearly | no | hourly (default), monthly (the price of 730 hours) or yearly (ten months). A monthly or yearly period comes out of credit if it covers it; otherwise `billing.pending_invoice` holds the invoice to pay and the resource stays hourly until it is paid. |
Responses
| HTTP | Description |
|---|---|
202 | Ordered |
400 | Malformed request. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
409 | The resource is not in a state that allows this: machine suspended, |
get
/databases/options
What can be ordered. Scope `vms.read`. Engines and versions, available extensions (PostgreSQL), eviction policies (Valkey), sizes with their hourly, monthly and yearly prices in the account's currency, and the price of disk beyond what a size includes.
Parameters
No parameters.
Responses
| HTTP | Description |
|---|---|
200 | OK |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
get
/databases/{database}
Get a database. Scope `vms.read`.
Parameters
No parameters.
Responses
| HTTP | Description |
|---|---|
200 | OK |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
patch
/databases/{database}
Update a database. Scope `databases.write`. Any of: the name; the weekly maintenance
Parameters
No parameters.
Request body
| Name | Type | Required | Description |
|---|---|---|---|
name | string | no | |
maintenance_day | integer | no | |
maintenance_hour | integer | no | |
disk_cap_gb | integer | no | |
eviction_policy | noeviction | allkeys-lru | allkeys-lfu | allkeys-random | … | no | Valkey only. |
Responses
| HTTP | Description |
|---|---|
200 | OK |
400 | Malformed request. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
delete
/databases/{database}
Delete a database. Scope `vms.destroy`. The database and its data go away; billing stops.
Parameters
No parameters.
Responses
| HTTP | Description |
|---|---|
202 | Deletion started |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
409 | The resource is not in a state that allows this: machine suspended, |
get
/databases/{database}/credentials
Users, passwords and connection strings. Scope `databases.write`: reading a password is enough to connect, so
Parameters
No parameters.
Responses
| HTTP | Description |
|---|---|
200 | OK |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
post
/databases/{database}/users
Add a user. Scope `databases.write`. Lowercase letters, digits and `_`, starting
Parameters
No parameters.
Request body
| Name | Type | Required | Description |
|---|---|---|---|
username | string | yes | |
databases | DatabaseUserDatabases | no | The logical databases the user connects to; null: all of them, future ones included. Always null for the admin and on Valkey. |
read_only | boolean | no | SELECT only (MySQL, MariaDB: SELECT and SHOW VIEW). |
Responses
| HTTP | Description |
|---|---|
201 | Created; live within seconds. |
400 | Malformed request. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
patch
/databases/{database}/users/{username}
Change a user's access. Scope `databases.write`. The logical databases the user connects to
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | no |
Request body
| Name | Type | Required | Description |
|---|---|---|---|
databases | DatabaseUserDatabases | no | The logical databases the user connects to; null: all of them, future ones included. Always null for the admin and on Valkey. |
read_only | boolean | no |
Responses
| HTTP | Description |
|---|---|
200 | OK |
400 | Malformed request. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
delete
/databases/{database}/users/{username}
Delete a user. Scope `databases.write`. Its objects are handed to the admin, then the role is dropped. The admin cannot be deleted.
Parameters
No parameters.
Responses
| HTTP | Description |
|---|---|
204 | Deleted |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
409 | The resource is not in a state that allows this: machine suspended, |
post
/databases/{database}/users/{username}/reset-password
Reset a password. Scope `databases.write`. A new password, returned here; the old one stops working within seconds. No `Idempotency-Key` (see adding a user).
Parameters
No parameters.
Responses
| HTTP | Description |
|---|---|
200 | OK |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
post
/databases/{database}/databases
Add a logical database. Scope `databases.write`. Same naming rules as users; 30 at most. Owned by the admin.
Parameters
No parameters.
Request body
| Name | Type | Required | Description |
|---|---|---|---|
name | string | yes |
Responses
| HTTP | Description |
|---|---|
201 | Created; live within seconds. |
400 | Malformed request. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
delete
/databases/{database}/databases/{name}
Delete a logical database. Scope `databases.write`. Dropped with everything in it; the backups keep it 7 days.
Parameters
No parameters.
Responses
| HTTP | Description |
|---|---|
204 | Deleted |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
post
/databases/{database}/databases/{name}/extensions
Enable an extension. Scope `databases.write`. PostgreSQL only. One of the extensions of `GET /databases/options`; installed on demand when needed (a few seconds to a minute).
Parameters
No parameters.
Request body
| Name | Type | Required | Description |
|---|---|---|---|
extension | string | yes |
Responses
| HTTP | Description |
|---|---|
200 | OK |
400 | Malformed request. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
delete
/databases/{database}/databases/{name}/extensions/{extension}
Remove an extension. Scope `databases.write`. Dropped without `CASCADE`: if objects depend
Parameters
No parameters.
Responses
| HTTP | Description |
|---|---|
200 | OK |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
put
/databases/{database}/public-access
Set public access. Scope `network.write`. Off at creation. On, the database answers at
Parameters
No parameters.
Request body
| Name | Type | Required | Description |
|---|---|---|---|
enabled | boolean | yes | |
sources | string[] | no |
Responses
| HTTP | Description |
|---|---|
200 | OK |
400 | Malformed request. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
409 | The resource is not in a state that allows this: machine suspended, |
get
/databases/{database}/backups
List backups. Scope `vms.read`. A full backup weekly, differentials daily, and the
Parameters
No parameters.
Responses
| HTTP | Description |
|---|---|
200 | OK |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
post
/databases/{database}/backups
Back up now. Scope `backups.write`. A differential backup starts within a minute; not available on a linked fork.
Parameters
No parameters.
Responses
| HTTP | Description |
|---|---|
202 | Requested |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
409 | The resource is not in a state that allows this: machine suspended, |
post
/databases/{database}/restore
Restore into a new database. Scope `vms.create`; `Idempotency-Key` required. A new database, billed
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | yes | Unique per order, your own value. Kept 24 hours. |
Request body
| Name | Type | Required | Description |
|---|---|---|---|
at | string | yes | UTC unless an offset is given. |
name | string | yes | |
vpc | integer | no | |
size_gb | integer | no |
Responses
| HTTP | Description |
|---|---|
202 | Ordered (`status` is `restoring`, then `active`). |
400 | Malformed request. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
409 | The resource is not in a state that allows this: machine suspended, |
post
/databases/{database}/forks
Fork a database. Scope `vms.create`; `Idempotency-Key` required. A new database whose
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | yes | Unique per order, your own value. Kept 24 hours. |
Request body
| Name | Type | Required | Description |
|---|---|---|---|
name | string | yes | |
vpc | integer | no | |
size_gb | integer | no |
Responses
| HTTP | Description |
|---|---|
202 | Ordered |
400 | Malformed request. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
409 | The resource is not in a state that allows this: machine suspended, |
post
/databases/{database}/resize
Upgrade to a larger size. Scope `vms.create`; `Idempotency-Key` required. More CPU, memory and
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | yes | Unique per order, your own value. Kept 24 hours. |
Request body
| Name | Type | Required | Description |
|---|---|---|---|
size_gb | integer | yes | Memory in GB, larger than the current size. |
Responses
| HTTP | Description |
|---|---|
202 | Started (`resize.to_gb` set; `status` turns `maintenance`, then `active` with the new `size_gb`). |
400 | Malformed request. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
409 | The resource is not in a state that allows this: machine suspended, |
post
/databases/{database}/detach
Make a fork independent. Scope `vms.action`. Its data gets its own copy; the database is unavailable for about 30 seconds, then its backups start.
Parameters
No parameters.
Responses
| HTTP | Description |
|---|---|
202 | Started |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
409 | The resource is not in a state that allows this: machine suspended, |
get
/databases/{database}/metrics
Database statistics. Scope `vms.read`. Per-minute samples kept 7 days, grouped by 1 minute
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
range | query | 1h | 24h | 7d | no |
Responses
| HTTP | Description |
|---|---|
200 | OK |
400 | Malformed request. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
get
/databases/{database}/queries
Most expensive queries. Scope `vms.read`. The 20 queries with the most total time, as counted by `pg_stat_statements` (PostgreSQL) or `performance_schema` (MySQL, MariaDB, without the user), normalized (values replaced by `$1`, `$2`… or `?`). On Valkey, per command since the engine last started (`INFO commandstats`), without database or user. Refreshed every few minutes.
Parameters
No parameters.
Responses
| HTTP | Description |
|---|---|
200 | OK |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
404 | No such resource, or it does not belong to this account. |
GitHub runners
get
/runners
Runner sizes, linked GitHub accounts and this month. Scope `billing.read`. The labels to put in `runs-on`, their price,
Parameters
No parameters.
Responses
| HTTP | Description |
|---|---|
200 | OK |
401 | Missing, unknown, disabled or expired key. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |
get
/runners/jobs
List runner jobs. Scope `billing.read`. Most recent first. Jobs of unlinked installations are not kept.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
repository | query | string | no | `owner/name` |
status | query | queued | running | succeeded | failed | … | no | |
cursor | query | string | no | The `next_cursor` from the previous page. |
limit | query | integer | no |
Responses
| HTTP | Description |
|---|---|
200 | OK |
401 | Missing, unknown, disabled or expired key. |
403 | Key out of scope, IP not allowed, e-mail unverified or account suspended. |