# CLK Cloud API Base URL: https://api.cloud.clk.no/v1. JSON, TLS only. Authenticate with `Authorization: Bearer clk_live_…` (an organization API key created in the console under API keys). Slow operations (create, delete, start, stop, reboot) return 202 with `{ "jobId", "jobUrl" }`. Poll GET /v1/jobs/{id} until status is `succeeded` or `failed`, or use webhooks. Errors: `{ "error": { "code", "message", "request_id" } }`; codes invalid_request (400), unauthorized (401), forbidden (403), rate_limited (429). Limit 120 requests/minute per key; see X-RateLimit-* and Retry-After headers. ## Guidance for agents - Use a dedicated key per agent with the narrowest role (read-only, operator, admin) and a short expiry. - Label every server you create (e.g. `agent=`), so costs and cleanup can be filtered by label. - Pass `ttl` (e.g. "2h") when creating a server so it deletes itself. Delete what you create when finished. Servers bill per hour. - A key may have caps (maxServers, maxMonthlyEur, see GET /v1/me). A create that would break one returns 422 key_limit_exceeded. - Ready-made clients: the `clk` CLI, a Terraform provider and the `clk-mcp` MCP server (repository clk-cli). ## Roles - read-only: servers, ssh-keys, networks, jobs, events, webhooks, ips and volumes: read - operator: read-only, plus servers:write, ips:write and volumes:write - admin: everything, including webhooks:write, ssh-keys:write and billing:read ## Scopes - servers:read: List and read servers, sizes, images and regions - servers:write: Create, delete, start, stop, reboot and label servers - ssh-keys:read / write: List, add and remove SSH keys - networks:read: List networks - jobs:read: Read job status - events:read: Read the event feed - webhooks:read / write: List, create and delete webhook endpoints - ips:read / write: List, allocate, attach, move and release public IPv4 addresses - volumes:read / write: Volumes and snapshots (when enabled) - billing:read: Costs and invoices ## 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. ## Servers Create, inspect and control servers. Anything slow (create, start, stop, reboot, delete) returns 202 and a job. - GET /v1/servers [servers:read]: List servers. Filter with one or more label=key:value query parameters. - POST /v1/servers [servers:write] (202, returns a job): 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. - GET /v1/servers/{id} [servers:read]: One server, including state, IP address, size and labels. - DELETE /v1/servers/{id} [servers:write] (202, returns a job): Delete a server. - POST /v1/servers/{id}/start [servers:write] (202, returns a job): Start a stopped server. - POST /v1/servers/{id}/stop [servers:write] (202, returns a job): Stop a server. - POST /v1/servers/{id}/reboot [servers:write] (202, returns a job): Reboot a server. - PUT /v1/servers/{id}/labels [servers:write]: Replace the labels on a server. Labels drive filtering and cost reports (up to 20 per server). ## Catalog What you can create servers from. Sizes include the monthly price (excl. VAT). - GET /v1/sizes [servers:read]: Server sizes with vCPU, memory, disk and monthly price. - GET /v1/images [servers:read]: Operating system images (Ubuntu, Debian, Rocky and others) and your own images (custom: true). - POST /v1/images [servers:write] (202, returns a job): 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} [servers:write] (202, returns a job): Delete one of your own images. - GET /v1/regions [servers:read]: Regions. - GET /v1/networks [networks:read]: Your private networks. ## SSH keys Public keys injected into servers when they are created. - GET /v1/ssh-keys [ssh-keys:read]: List SSH keys. - POST /v1/ssh-keys [ssh-keys:write]: Add a public key. Returns 201. - DELETE /v1/ssh-keys/{name} [ssh-keys:write]: Remove a key by name. ## 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-addresses [ips:read]: List addresses and the server each is attached to. - POST /v1/ip-addresses [ips:write] (202, returns a job): Take a new address. Optional network when you have more than one. - POST /v1/ip-addresses/{id}/assign [ips:write]: Attach the address to a server (1:1). Unassign it first to move it. Body: { "serverId": "…" }. - POST /v1/ip-addresses/{id}/unassign [ips:write] (202, returns a job): Detach the address from its server. It stays yours. - DELETE /v1/ip-addresses/{id} [ips:write] (202, returns a job): 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/volumes [volumes:read]: List volumes. - POST /v1/volumes [volumes:write]: Create a volume (name, sizeGb, optional labels, serverId to attach, or snapshotId to restore). Returns 201 when ready. - POST /v1/volumes/{id}/attach [volumes:write]: Attach to a server. Body: { "serverId": "…" }. - POST /v1/volumes/{id}/detach [volumes:write]: Detach from its server. - DELETE /v1/volumes/{id} [volumes:write]: Delete a detached volume and its data. - GET /v1/snapshots [volumes:read]: List snapshots. - POST /v1/volumes/{id}/snapshots [volumes: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. ## Events and webhooks The same events are available by polling and as signed webhook deliveries. - GET /v1/events [events:read]: Events for your organization after a cursor: pass after=, optionally type= and limit=. - GET /v1/webhooks [webhooks:read]: List webhook endpoints. - POST /v1/webhooks [webhooks:write]: Register an https endpoint and the event types it wants. The signing secret is returned once. - DELETE /v1/webhooks/{id} [webhooks:write]: Remove an endpoint. ## Costs and invoices Needs a key with the billing:read scope (the admin role). - GET /v1/usage [billing:read]: Costs for a month. period=2026-10, group_by=label:env or group_by=type. - GET /v1/invoices [billing:read]: List invoices. - GET /v1/invoices/{id} [billing:read]: One invoice, with links to the hosted page and PDF. ## Webhook event types - Servers: server.created, server.creation_failed, server.started, server.stopped, server.rebooted, server.deleted, server.action_failed - Account: account.approved, account.rejected, account.card_changed, account.closure_scheduled, account.closure_cancelled, account.suspended, account.resumed, account.blocked, account.unblocked - Networking: ip.allocated, ip.released, firewall.rule_created, firewall.rule_deleted, port_forward.created, port_forward.deleted - Storage: volume.created, volume.attached, volume.detached, volume.deleted, snapshot.created, snapshot.deleted - Billing: invoice.created, invoice.paid, invoice.payment_failed, budget.threshold, credit.granted, coupon.redeemed, referral.signed_up, referral.rewarded - Platform: announcement.created, announcement.updated, announcement.resolved Webhook deliveries carry `CLK-Signature: t=,v1=`; verify over the raw body and reject old timestamps. Delivery is at least once; dedupe on the event id.