API reference

Every endpoint, with the scope it needs and the fields it takes. Developer documentation is in English.

Overview

Base URL https://api.cloud.clk.no/v1. Authenticate with Authorization: Bearer clk_live_…. Each endpoint shows the scope the key needs. New to the API? Start with the guide.

Machine-readable: OpenAPI 3 spec (JSON), for client generators, Postman and AI agents.

Account

Check who a key belongs to and what it may do.

GET/v1/me

The organization, key id, scopes and caps (maxServers, maxMonthlyEur) of the key you are calling with.

Parameters and fields

Response (KeyInfo)

Field	Type
organizationId	string (uuid)	required
keyId	string (uuid)	required
scopes	string[]	required

Servers

Create, inspect and control servers. Anything slow (create, start, stop, reboot, delete) returns 202 and a job.

GET/v1/serversservers:read

List servers. Filter with one or more label=key:value query parameters.

Parameters and fields

Parameters

Name	In	Type
label	query	string[]

Response (Server[])

Field	Type
id	string	required
name	string	required
state	string	required
ipAddress	string
network	NetworkRef
sshKey	string
size	string	required
vcpus	integer	required
memoryMb	integer	required
diskGb	integer
image	string	required
region	string	required
labels	map<string, string>	required
createdAt	string	required

POST/v1/servers202 · returns a jobservers:write

Create a server. name, size and labels are required. network and sshKey may be omitted when the organization has exactly one of each; userData is cloud-init. Optional ttl (30m, 2h, 7d; 5 minutes to 30 days) deletes the server automatically when it is over. Optional diskGb sets a larger root disk (extra GB are billed per GB), and publicIpv4: true orders a dedicated public IPv4 attached when the server is ready.

Parameters and fields

Request body

Field	Type
name	string	required
size	string	required
sshKey	string
network	string
image	string
userData	string
labels	map<string, string>	required

Response (JobAccepted)

Field	Type
jobId	string (uuid)	required
jobUrl	string	required

GET/v1/servers/{id}servers:read

One server, including state, IP address, size and labels.

Parameters and fields

Parameters

Name	In	Type
id	path	string	required

Response (Server)

Field	Type
id	string	required
name	string	required
state	string	required
ipAddress	string
network	NetworkRef
sshKey	string
size	string	required
vcpus	integer	required
memoryMb	integer	required
diskGb	integer
image	string	required
region	string	required
labels	map<string, string>	required
createdAt	string	required

DELETE/v1/servers/{id}202 · returns a jobservers:write

Delete a server.

Parameters and fields

Parameters

Name	In	Type
id	path	string	required

Response (JobAccepted)

Field	Type
jobId	string (uuid)	required
jobUrl	string	required

POST/v1/servers/{id}/start202 · returns a jobservers:write

Start a stopped server.

Parameters and fields

Parameters

Name	In	Type
id	path	string	required

Response (JobAccepted)

Field	Type
jobId	string (uuid)	required
jobUrl	string	required

POST/v1/servers/{id}/stop202 · returns a jobservers:write

Stop a server.

Parameters and fields

Parameters

Name	In	Type
id	path	string	required

Response (JobAccepted)

Field	Type
jobId	string (uuid)	required
jobUrl	string	required

POST/v1/servers/{id}/reboot202 · returns a jobservers:write

Reboot a server.

Parameters and fields

Parameters

Name	In	Type
id	path	string	required

Response (JobAccepted)

Field	Type
jobId	string (uuid)	required
jobUrl	string	required

PUT/v1/servers/{id}/labelsservers:write

Replace the labels on a server. Labels drive filtering and cost reports (up to 20 per server).

Parameters and fields

Parameters

Name	In	Type
id	path	string	required

Request body

Field	Type
labels	map<string, string>	required

Catalog

What you can create servers from. Sizes include the monthly price (excl. VAT).

GET/v1/sizesservers:read

Server sizes with vCPU, memory, disk and monthly price.

Parameters and fields

Response (Size[])

Field	Type
id	string	required
name	string	required
vcpus	integer	required
memoryMb	integer	required
diskGb	integer	required
monthlyPrice	Price

GET/v1/imagesservers:read

Operating system images (Ubuntu, Debian, Rocky and others) and your own images (custom: true).

Parameters and fields

Response (Image[])

Field	Type
id	string	required
name	string	required
description	string
default	boolean	required

POST/v1/images202 · returns a jobservers:write

Make an image from a server, with your tools already installed, and start new servers from it. Body: { "serverId", "name" }. Not enabled yet: answers 404 not_available.

DELETE/v1/images/{id}202 · returns a jobservers:write

Delete one of your own images.

GET/v1/regionsservers:read

Regions.

Parameters and fields

Response (Region[])

Field	Type
id	string	required
name	string	required

GET/v1/networksnetworks:read

Your private networks.

Parameters and fields

Response (Network[])

Field	Type
id	string (uuid)	required
name	string	required
cidr	string	required
state	string	required

SSH keys

Public keys injected into servers when they are created.

GET/v1/ssh-keysssh-keys:read

List SSH keys.

Parameters and fields

Response (SshKey[])

Field	Type
name	string	required
fingerprint	string	required

POST/v1/ssh-keysssh-keys:write

Add a public key. Returns 201.

Parameters and fields

Request body

Field	Type
name	string	required
publicKey	string	required

Response (SshKey)

Field	Type
name	string	required
fingerprint	string	required

DELETE/v1/ssh-keys/{name}ssh-keys:write

Remove a key by name.

Parameters and fields

Parameters

Name	In	Type
name	path	string	required

IP addresses

Public IPv4 addresses (billed per month, limited per organization) that you can attach to a server and move between servers, for example for failover. IPv6 is included with every server.

GET/v1/ip-addressesips:read

List addresses and the server each is attached to.

POST/v1/ip-addresses202 · returns a jobips:write

Take a new address. Optional network when you have more than one.

POST/v1/ip-addresses/{id}/assignips:write

Attach the address to a server (1:1). Unassign it first to move it. Body: { "serverId": "…" }.

POST/v1/ip-addresses/{id}/unassign202 · returns a jobips:write

Detach the address from its server. It stays yours.

DELETE/v1/ip-addresses/{id}202 · returns a jobips:write

Release the address.

Volumes and snapshots

Extra disks and backups of them. Not enabled yet: until they are, these endpoints answer 404 not_available.

GET/v1/volumesvolumes:read

List volumes.

POST/v1/volumesvolumes:write

Create a volume (name, sizeGb, optional labels, serverId to attach, or snapshotId to restore). Returns 201 when ready.

POST/v1/volumes/{id}/attachvolumes:write

Attach to a server. Body: { "serverId": "…" }.

POST/v1/volumes/{id}/detachvolumes:write

Detach from its server.

DELETE/v1/volumes/{id}volumes:write

Delete a detached volume and its data.

GET/v1/snapshotsvolumes:read

List snapshots.

POST/v1/volumes/{id}/snapshotsvolumes:write

Snapshot a volume. Returns 201.

DELETE/v1/snapshots/{id}volumes:write

Delete a snapshot.

Jobs

Every slow operation is a job. Poll it, or subscribe to webhooks instead.

GET/v1/jobs/{id}jobs:read

Job status: pending until it ends as succeeded or failed (error holds the reason). When a server job has succeeded, serverId is the server it concerns.

Parameters and fields

Parameters

Name	In	Type
id	path	string (uuid)	required

Response (Job)

Field	Type
id	string (uuid)	required
type	string	required
status	string	required
error	string
createdAt	string (date-time)

Events and webhooks

The same events are available by polling and as signed webhook deliveries.

GET/v1/eventsevents:read

Events for your organization after a cursor: pass after=<last event id>, optionally type= and limit=.

Parameters and fields

Parameters

Name	In	Type
after	query	string (uuid)
type	query	string
limit	query	integer

Response (EventPage)

Field	Type
data	Event[]	required
hasMore	boolean	required

GET/v1/webhookswebhooks:read

List webhook endpoints.

Parameters and fields

Response (WebhookEndpoint[])

Field	Type
id	string (uuid)	required
url	string	required
description	string
eventTypes	string[]	required
enabled	boolean	required
failingSince	string (date-time)
createdAt	string (date-time)	required

POST/v1/webhookswebhooks:write

Parameters and fields

Request body

Field	Type
url	string	required
description	string
eventTypes	string[]	required

Response (CreatedWebhookEndpoint)

Field	Type
endpoint	WebhookEndpoint	required
secret	string	required

DELETE/v1/webhooks/{id}webhooks:write

Remove an endpoint.

Parameters and fields

Parameters

Name	In	Type
id	path	string (uuid)	required

Costs and invoices

Needs a key with the billing:read scope (the admin role).

GET/v1/usagebilling:read

Costs for a month. period=2026-10, group_by=label:env or group_by=type.

Parameters and fields

Parameters

Name	In	Type
period	query	string
group_by	query	string

Response (MonthCosts)

Field	Type
period	string	required
currency	string	required
from	string (date-time)	required
to	string (date-time)	required
total	number	required
forecast	number
resources	CostResource[]	required
groups	CostGroup[]	required
daily	DayTotal[]	required

GET/v1/invoicesbilling:read

List invoices.

Parameters and fields

Response (Invoice[])

Field	Type
id	string	required
number	string
period	string
currency	string	required
subtotal	number	required
tax	number	required
total	number	required
status	string	required
hostedInvoiceUrl	string
pdfUrl	string
createdAt	string (date-time)	required
dueAt	string (date-time)
paidAt	string (date-time)

GET/v1/invoices/{id}billing:read

One invoice, with links to the hosted page and PDF.

Parameters and fields

Parameters

Name	In	Type
id	path	string	required

Response (Invoice)

Field	Type
id	string	required
number	string
period	string
currency	string	required
subtotal	number	required
tax	number	required
total	number	required
status	string	required
hostedInvoiceUrl	string
pdfUrl	string
createdAt	string (date-time)	required
dueAt	string (date-time)
paidAt	string (date-time)