Endpoint reference

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.

GET /regions
GET /plans
GET /plans/{plan}
GET /images
GET /images/{image}
GET /vms
POST /vms
GET /vms/{vm}
PATCH /vms/{vm}
DELETE /vms/{vm}
GET /vms/{vm}/metrics
POST /vms/{vm}/console
GET /vms/{vm}/actions
POST /vms/{vm}/actions
GET /actions
GET /actions/{action}
GET /vms/{vm}/network
POST /vms/{vm}/network/ipv6
DELETE /vms/{vm}/network/ipv6/{address}
PUT /vms/{vm}/network/rdns
GET /vms/{vm}/backups
POST /vms/{vm}/backups/{backup}/restore
DELETE /vms/{vm}/backups/{backup}
GET /account
GET /usage
GET /ssh-keys
POST /ssh-keys
DELETE /ssh-keys/{key}

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.
`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.
`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 sampled by the hypervisor.

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 hypervisor did not answer. 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 hypervisor did not answer. 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.

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

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
`422`	The request is well formed but the catalogue refuses it: image below the

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.

Contents

Catalog

Parameters

Responses

Parameters

Responses

Parameters

Responses

Parameters

Responses

Parameters

Responses

Machines

Parameters

Responses

Parameters

Request body

Responses

Parameters

Responses

Parameters

Request body

Responses

Parameters

Responses

Parameters

Responses

Parameters

Responses

Actions

Parameters

Responses

Parameters

Request body

Responses

Parameters

Responses

Parameters

Responses

Networking

Parameters

Responses

Parameters

Request body

Responses

Parameters

Responses

Parameters

Request body

Responses

Backups

Parameters

Responses

Parameters

Responses

Parameters

Responses

Account

Parameters

Responses

Parameters

Responses

SSH keys

Parameters

Responses

Parameters

Request body

Responses

Parameters

Responses