Référence des points d'entrée

Cette page est générée depuis le contrat OpenAPI. Si elle contredit l'API, c'est le contrat qui a raison — signalez-le nous.

Adresse de base https://api.ffxf.net/v1
Contrat OpenAPI openapi.v1.json — Le fichier que cette référence rend, tel qu'il est publié.

Sommaire

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 Sans clé

List regions — Where machines can run. A plan or an image may not be offered everywhere.

Paramètres

Aucun paramètre.

Réponses

HTTP	Description
`200`	OK

get /plans Sans clé

List plans

Paramètres

Nom	Où	Type	Requis	Description
`region`	query	`string`	non	Keep only the plans offered in this region.

Réponses

HTTP	Description
`200`	OK

get /plans/{plan} Sans clé

Get a plan

Paramètres

Nom	Où	Type	Requis	Description
`plan`	path	`string`	oui

Réponses

HTTP	Description
`200`	OK
`404`	No such resource, or it does not belong to this account.

get /images Sans clé

List images — The image referential. `slug` is the stable identifier to pass at

Paramètres

Nom	Où	Type	Requis	Description
`region`	query	`string`	non	Keep only the images available in this region.
`plan`	query	`string`	non	Keep only the images that fit this plan.
`category`	query	`linux \| windows \| bsd \| app \| …`	non

Réponses

HTTP	Description
`200`	OK

get /images/{image} Sans clé

Get an image

Paramètres

Nom	Où	Type	Requis	Description
`image`	path	`string`	oui

Réponses

HTTP	Description
`200`	OK
`404`	No such resource, or it does not belong to this account.

Machines

get /vms

List machines

Paramètres

Nom	Où	Type	Requis	Description
`cursor`	query	`string`	non	The `next_cursor` from the previous page.
`limit`	query	`integer`	non
`status`	query	`VmStatus`	non
`region`	query	`string`	non
`billing`	query	`hourly \| monthly`	non

Réponses

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,

Paramètres

Nom	Où	Type	Requis	Description
`Idempotency-Key`	header	`string`	oui	Unique per order, your own value. Kept 24 hours.

Corps de la requête

Nom	Type	Requis	Description
`plan`	`string`	oui
`region`	`string`	oui
`image`	`string`	oui
`hostname`	`Hostname`	oui
`billing`	`hourly \| monthly`	oui
`payment`	`credit \| manual`	non	Monthly only. `credit` settles the invoice from the balance when it
`ssh_keys`	`string[]`	non	Fingerprints or ids of keys on the account. Ignored by images without cloud-init key support.
`password_delivery`	`email \| none`	non	`email` generates a password and mails it. `none` requires at least
`options`	`object`	non	Paid options declared by the plan, by name. Unknown keys are refused.
`dry_run`	`boolean`	non	Run every check and price the order without creating anything.

Réponses

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

Paramètres

Nom	Où	Type	Requis	Description
`vm`	path	`integer`	oui	The machine id. A machine is identified by its service: the id exists

Réponses

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

Paramètres

Nom	Où	Type	Requis	Description
`vm`	path	`integer`	oui	The machine id. A machine is identified by its service: the id exists

Corps de la requête

Nom	Type	Requis	Description
`hostname`	`Hostname`	non

Réponses

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

Paramètres

Nom	Où	Type	Requis	Description
`vm`	path	`integer`	oui	The machine id. A machine is identified by its service: the id exists
`confirm`	query	`string`	oui	The machine's exact hostname.
`when`	query	`period_end \| now`	non	Monthly machines only.

Réponses

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.

Paramètres

Nom	Où	Type	Requis	Description
`vm`	path	`integer`	oui	The machine id. A machine is identified by its service: the id exists
`timeframe`	query	`hour \| day \| week \| month \| …`	non

Réponses

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.

Paramètres

Nom	Où	Type	Requis	Description
`vm`	path	`integer`	oui	The machine id. A machine is identified by its service: the id exists

Réponses

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

Paramètres

Nom	Où	Type	Requis	Description
`vm`	path	`integer`	oui	The machine id. A machine is identified by its service: the id exists
`cursor`	query	`string`	non	The `next_cursor` from the previous page.
`limit`	query	`integer`	non

Réponses

HTTP	Description
`200`	OK

post /vms/{vm}/actions

Act on a machine — `start`, `shutdown`, `reboot` ask the guest politely. `stop` cuts the

Paramètres

Nom	Où	Type	Requis	Description
`vm`	path	`integer`	oui	The machine id. A machine is identified by its service: the id exists
`Idempotency-Key`	header	`string`	non

Corps de la requête

Nom	Type	Requis	Description
`type`	`start \| shutdown \| reboot \| stop`	oui

Réponses

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

Paramètres

Nom	Où	Type	Requis	Description
`cursor`	query	`string`	non	The `next_cursor` from the previous page.
`limit`	query	`integer`	non
`status`	query	`ActionStatus`	non

Réponses

HTTP	Description
`200`	OK

get /actions/{action}

Get an action — Poll this until `status` leaves `running`. A completed action is kept 30 days.

Paramètres

Nom	Où	Type	Requis	Description
`action`	path	`integer`	oui

Réponses

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

Paramètres

Nom	Où	Type	Requis	Description
`vm`	path	`integer`	oui	The machine id. A machine is identified by its service: the id exists

Réponses

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

Paramètres

Nom	Où	Type	Requis	Description
`vm`	path	`integer`	oui	The machine id. A machine is identified by its service: the id exists

Corps de la requête

Nom	Type	Requis	Description
`address`	`string`	oui	Full address inside the machine's prefix.

Réponses

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

Paramètres

Nom	Où	Type	Requis	Description
`vm`	path	`integer`	oui	The machine id. A machine is identified by its service: the id exists
`address`	path	`string`	oui

Réponses

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

Paramètres

Nom	Où	Type	Requis	Description
`vm`	path	`integer`	oui	The machine id. A machine is identified by its service: the id exists

Corps de la requête

Nom	Type	Requis	Description
`address`	`string`	oui
`hostname`	`string`	non	Null clears the record and restores the default.

Réponses

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

Paramètres

Nom	Où	Type	Requis	Description
`vm`	path	`integer`	oui	The machine id. A machine is identified by its service: the id exists

Réponses

HTTP	Description
`200`	OK

post /vms/{vm}/backups/{backup}/restore

Restore a backup — Overwrites the current disk. The machine is stopped for the duration.

Paramètres

Nom	Où	Type	Requis	Description
`vm`	path	`integer`	oui	The machine id. A machine is identified by its service: the id exists
`backup`	path	`string`	oui

Réponses

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

Paramètres

Nom	Où	Type	Requis	Description
`vm`	path	`integer`	oui	The machine id. A machine is identified by its service: the id exists
`backup`	path	`string`	oui

Réponses

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

Paramètres

Aucun paramètre.

Réponses

HTTP	Description
`200`	OK

get /usage

List hourly usage — One record per hour charged, per machine. This is the ledger the

Paramètres

Nom	Où	Type	Requis	Description
`from`	query	`string`	non
`to`	query	`string`	non
`vm_id`	query	`integer`	non
`group_by`	query	`hour \| vm`	non	Return one line per machine instead of one per hour.
`cursor`	query	`string`	non	The `next_cursor` from the previous page.
`limit`	query	`integer`	non

Réponses

HTTP	Description
`200`	OK

SSH keys

get /ssh-keys

List SSH keys

Paramètres

Aucun paramètre.

Réponses

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.

Paramètres

Aucun paramètre.

Corps de la requête

Nom	Type	Requis	Description
`name`	`string`	oui
`public_key`	`string`	oui

Réponses

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.

Paramètres

Nom	Où	Type	Requis	Description
`key`	path	`integer`	oui

Réponses

HTTP	Description
`204`	Deleted
`404`	No such resource, or it does not belong to this account.