Servers¶

Virtual machine instances running on OpenStack compute. Each server belongs to a project and is defined by a flavor (CPU/RAM/disk profile) and a base image.

Endpoints¶

Method	Path	Description
`GET`	`/cloud/servers?project_id=<uuid>`	List servers in a project
`POST`	`/cloud/servers`	Create a server
`GET`	`/cloud/servers/{id}?project_id=<uuid>`	Show a server
`DELETE`	`/cloud/servers/{id}?project_id=<uuid>`	Delete a server

project_id is required on every request; the API uses it to resolve the project's OpenStack credentials.

List servers¶

GET /cloud/servers?project_id=<uuid>
Authorization: Bearer <token>

Returns an array of server objects. List responses are cached for up to 5 minutes; use individual GET /cloud/servers/{id} calls when you need the freshest status.

Create a server¶

POST /cloud/servers
Authorization: Bearer <token>
Content-Type: application/json

{
  "project_id": "<uuid>",
  "name": "web-01",
  "flavor_id": "m1.small",
  "image_id": "<image-uuid>",
  "network_ids": ["<network-uuid>"],
  "key_name": "my-keypair"
}

Returns 202 Accepted — server creation is asynchronous. Poll GET /cloud/servers/{id} and watch status progress from BUILD to ACTIVE.

Show a server¶

GET /cloud/servers/{id}?project_id=<uuid>
Authorization: Bearer <token>

Key response fields:

Field	Description
`id`	OpenStack server UUID
`name`	Display name
`status`	`ACTIVE`, `SHUTOFF`, `BUILD`, `ERROR`, etc.
`task_state`	Current task (e.g. `spawning`); `null` when idle
`power_state`	1 = running, 4 = shutdown
`addresses`	Map of network name → array of `{addr, version, type}`
`flavor`	Object with `id`
`image`	Object with `id`; `null` for volume-booted servers
`key_name`	SSH keypair name, or `null`
`availability_zone`	AZ the server was scheduled to
`volumes_attached`	Array of `{id, delete_on_termination}`
`metadata`	Key-value user metadata

Delete a server¶

DELETE /cloud/servers/{id}?project_id=<uuid>
Authorization: Bearer <token>

Returns 204 No Content. Deletion is asynchronous; the server disappears from list results once OpenStack confirms removal.

Supporting resources¶

Before creating a server you will typically need:

A flavor — GET /cloud/flavors?project_id=<uuid> lists available sizes.
An image — GET /cloud/images?project_id=<uuid> lists available OS images.
A network — GET /cloud/networks?project_id=<uuid>. See Networks.
An SSH keypair — GET /cloud/ssh-keypairs?project_id=<uuid>.

Volumes — attach persistent block storage
Networks — private networks and subnets
Floating IPs — assign public IP addresses (managed via the OpenStack dashboard or CLI)
Load Balancers — distribute traffic across servers