{"openapi":"3.1.0","info":{"title":"Lumcells Cloud API","description":"Everything the console can do for your organisation, for scripts. Authenticate with an API token (Your account > API tokens) sent as a Bearer token. A token has the permissions of the person who made it, or read-only if created that way. Amounts are US cents.","license":{"name":""},"version":"1"},"paths":{"/api/v1/firewalls":{"get":{"tags":["servers"],"summary":"Firewall groups with their rules","operationId":"firewalls","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/FirewallOut"}}}}}},"security":[{"token":[]}]}},"/api/v1/images":{"get":{"tags":["catalogue"],"summary":"Operating system images","operationId":"images","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ImageOut"}}}}}}}},"/api/v1/invoices":{"get":{"tags":["billing"],"summary":"Invoices","operationId":"invoices","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceOut"}}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorBody"}}}}},"security":[{"token":[]}]}},"/api/v1/me":{"get":{"tags":["account"],"summary":"Who this token acts as","operationId":"me","responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeOut"}}}},"401":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorBody"}}}}},"security":[{"token":[]}]}},"/api/v1/notices":{"get":{"tags":["billing"],"summary":"Announced changes with their countdown","operationId":"notices_list","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/NoticeOut"}}}}}},"security":[{"token":[]}]}},"/api/v1/orders":{"get":{"tags":["billing"],"summary":"Orders with their locked prices","operationId":"orders","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/OrderOut"}}}}}},"security":[{"token":[]}]}},"/api/v1/plans":{"get":{"tags":["catalogue"],"summary":"Plans and today's prices","operationId":"plans","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PlanOut"}}}}}}}},"/api/v1/regions":{"get":{"tags":["catalogue"],"summary":"Regions open for new orders","operationId":"regions","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RegionOut"}}}}}}}},"/api/v1/servers":{"get":{"tags":["servers"],"summary":"List your servers","operationId":"servers","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ServerOut"}}}}}},"security":[{"token":[]}]},"post":{"tags":["servers"],"summary":"Create a server","description":"Starts an order at today's price, locked for 12 months. The server is \"provisioning\" until it is built.","operationId":"server_create","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerCreateIn"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerCreatedOut"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorBody"}}}},"422":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorBody"}}}},"503":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorBody"}}}}},"security":[{"token":[]}]}},"/api/v1/servers/{id}":{"get":{"tags":["servers"],"summary":"One server","operationId":"server","parameters":[{"name":"id","in":"path","description":"Server id","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerOut"}}}},"404":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorBody"}}}}},"security":[{"token":[]}]},"delete":{"tags":["servers"],"summary":"Delete a server for good","description":"Destroys the server and its snapshots on the node and stops metering. The body must repeat the hostname.","operationId":"server_delete","parameters":[{"name":"id","in":"path","description":"Server id","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteIn"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DoneOut"}}}},"422":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorBody"}}}}},"security":[{"token":[]}]}},"/api/v1/servers/{id}/metrics":{"get":{"tags":["servers"],"summary":"CPU, memory, network and disk samples","operationId":"server_metrics","parameters":[{"name":"id","in":"path","description":"Server id","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"range","in":"query","description":"hour (default), day or week.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MetricOut"}}}}}},"security":[{"token":[]}]}},"/api/v1/servers/{id}/power":{"post":{"tags":["servers"],"summary":"Start, shut down, power off or reboot","operationId":"server_power","parameters":[{"name":"id","in":"path","description":"Server id","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PowerIn"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerOut"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorBody"}}}}},"security":[{"token":[]}]}},"/api/v1/servers/{id}/reinstall":{"post":{"tags":["servers"],"summary":"Wipe the disk and install an image again","operationId":"server_reinstall","parameters":[{"name":"id","in":"path","description":"Server id","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReinstallIn"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerCreatedOut"}}}}},"security":[{"token":[]}]}},"/api/v1/servers/{id}/resize":{"post":{"tags":["servers"],"summary":"Resize to a bigger plan","description":"Starts a new order at today's price with a fresh 12-month price lock.","operationId":"server_resize","parameters":[{"name":"id","in":"path","description":"Server id","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResizeIn"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerOut"}}}},"409":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorBody"}}}}},"security":[{"token":[]}]}},"/api/v1/servers/{id}/snapshots":{"get":{"tags":["servers"],"summary":"Snapshots and backups of a server","operationId":"snapshots","parameters":[{"name":"id","in":"path","description":"Server id","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SnapshotOut"}}}}}},"security":[{"token":[]}]},"post":{"tags":["servers"],"summary":"Take a snapshot or backup now","operationId":"snapshot_create","parameters":[{"name":"id","in":"path","description":"Server id","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SnapshotIn"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SnapshotOut"}}}}}},"security":[{"token":[]}]}},"/api/v1/ssh-keys":{"get":{"tags":["servers"],"summary":"SSH keys","operationId":"ssh_keys","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SshKeyOut"}}}}}},"security":[{"token":[]}]},"post":{"tags":["servers"],"summary":"Add an SSH public key","operationId":"ssh_key_add","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SshKeyIn"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SshKeyOut"}}}}},"422":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorBody"}}}}},"security":[{"token":[]}]}},"/api/v1/staff/features":{"get":{"tags":["staff"],"summary":"Staff: the feature registry","operationId":"staff_features","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/FeatureOut"}}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorBody"}}}}},"security":[{"token":[]}]}},"/api/v1/staff/jobs":{"get":{"tags":["staff"],"summary":"Staff: background jobs","operationId":"staff_jobs","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/JobOut"}}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorBody"}}}}},"security":[{"token":[]}]}},"/api/v1/staff/jobs/{key}/run":{"post":{"tags":["staff"],"summary":"Staff: run a job now","operationId":"staff_job_run","parameters":[{"name":"key","in":"path","description":"Job key, for example fleet.health","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DoneOut"}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorBody"}}}}},"security":[{"token":[]}]}},"/api/v1/staff/nodes":{"get":{"tags":["staff"],"summary":"Staff: nodes with capacity ratios and alarms","operationId":"staff_nodes","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/NodeOut"}}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorBody"}}}}},"security":[{"token":[]}]}},"/api/v1/staff/reality":{"get":{"tags":["staff"],"summary":"Staff: what is real (live integration checks and blockers)","operationId":"staff_reality","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RealityOut"}}}}},"403":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorBody"}}}}},"security":[{"token":[]}]}},"/api/v1/status":{"get":{"tags":["status"],"summary":"Region status and open incidents (same data as the status page)","operationId":"status","responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusOut"}}}}}}},"/api/v1/tickets":{"get":{"tags":["support"],"summary":"Support tickets","operationId":"tickets","responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TicketOut"}}}}}},"security":[{"token":[]}]},"post":{"tags":["support"],"summary":"Open a support ticket","operationId":"ticket_open","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketIn"}}},"required":true},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketOut"}}}},"422":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorBody"}}}}},"security":[{"token":[]}]}},"/api/v1/usage":{"get":{"tags":["billing"],"summary":"This month's usage and the credit balance","operationId":"usage","responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageOut"}}}}},"security":[{"token":[]}]}}},"components":{"schemas":{"ApiErrorBody":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Short machine-readable kind: unauthorized, forbidden, not_found, invalid, conflict, upstream, internal."},"message":{"type":"string","description":"Plain-language explanation."}}},"DeleteIn":{"type":"object","required":["confirm_hostname"],"properties":{"confirm_hostname":{"type":"string","description":"Must equal the server's hostname."}}},"DoneOut":{"type":"object","required":["ok","message"],"properties":{"message":{"type":"string"},"ok":{"type":"boolean"}}},"FeatureOut":{"type":"object","required":["key","name","area","status","screens","api_endpoints","roles","depends_on","reality","blocker"],"properties":{"api_endpoints":{"type":"array","items":{"type":"string"}},"area":{"type":"string"},"blocker":{"type":"string","description":"What is missing, when it is blocked. Empty when real."},"depends_on":{"type":"array","items":{"type":"string"}},"key":{"type":"string"},"name":{"type":"string"},"reality":{"type":"string","description":"What its screens show right now: real or blocked."},"roles":{"type":"array","items":{"type":"string"}},"screens":{"type":"array","items":{"type":"string"}},"status":{"type":"string"}}},"FirewallOut":{"type":"object","required":["id","name","rules","servers"],"properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"},"rules":{"type":"array","items":{"type":"string"}},"servers":{"type":"integer","format":"int64"}}},"ImageOut":{"type":"object","required":["key","name"],"properties":{"key":{"type":"string"},"name":{"type":"string"}}},"IncidentOut":{"type":"object","required":["title","impact","status","region","started_at","latest_update"],"properties":{"impact":{"type":"string"},"latest_update":{"type":"string"},"region":{"type":"string"},"started_at":{"type":"string","format":"date-time"},"status":{"type":"string"},"title":{"type":"string"}}},"InvoiceOut":{"type":"object","required":["id","number","period","status","subtotal_cents","tax_cents","credit_applied_cents","total_cents","issued_at"],"properties":{"credit_applied_cents":{"type":"integer","format":"int64"},"id":{"type":"integer","format":"int64"},"issued_at":{"type":"string","format":"date-time"},"number":{"type":"string"},"paid_at":{"type":["string","null"],"format":"date-time"},"period":{"type":"string"},"status":{"type":"string"},"subtotal_cents":{"type":"integer","format":"int64"},"tax_cents":{"type":"integer","format":"int64"},"total_cents":{"type":"integer","format":"int64"}}},"JobOut":{"type":"object","required":["key","name","enabled","interval_seconds","last_status","last_error"],"properties":{"enabled":{"type":"boolean"},"interval_seconds":{"type":"integer","format":"int32"},"key":{"type":"string"},"last_error":{"type":"string"},"last_run_at":{"type":["string","null"],"format":"date-time"},"last_status":{"type":"string"},"name":{"type":"string"}}},"MeOut":{"type":"object","required":["email","name","role","read_only"],"properties":{"email":{"type":"string"},"name":{"type":"string"},"organisation_id":{"type":["integer","null"],"format":"int64"},"read_only":{"type":"boolean"},"role":{"type":"string","description":"Role this token acts with."}}},"MetricOut":{"type":"object","required":["at","cpu_pct","ram_pct","net_in_mbps","net_out_mbps","disk_read_mbps","disk_write_mbps"],"properties":{"at":{"type":"string","format":"date-time"},"cpu_pct":{"type":"number","format":"float"},"disk_read_mbps":{"type":"number","format":"float"},"disk_write_mbps":{"type":"number","format":"float"},"net_in_mbps":{"type":"number","format":"float"},"net_out_mbps":{"type":"number","format":"float"},"ram_pct":{"type":"number","format":"float"}}},"NodeOut":{"type":"object","required":["id","name","region","state","servers","ram_ratio","cpu_ratio","nvme_ratio","alarm"],"properties":{"alarm":{"type":"boolean"},"cpu_ratio":{"type":"number","format":"double"},"id":{"type":"integer","format":"int64"},"name":{"type":"string"},"nvme_ratio":{"type":"number","format":"double"},"ram_ratio":{"type":"number","format":"double"},"region":{"type":"string"},"servers":{"type":"integer","format":"int64"},"state":{"type":"string"}}},"NoticeOut":{"type":"object","required":["title","body","kind","effective_at","days_left"],"properties":{"body":{"type":"string"},"days_left":{"type":"integer","format":"int64"},"effective_at":{"type":"string","format":"date-time"},"kind":{"type":"string"},"new_price_cents":{"type":["integer","null"],"format":"int64"},"old_price_cents":{"type":["integer","null"],"format":"int64"},"server_id":{"type":["integer","null"],"format":"int64"},"title":{"type":"string"}}},"OrderOut":{"type":"object","required":["id","server_id","plan","vcpu","ram_gb","disk_gb","monthly_price_cents","launch_price","ordered_at","price_locked_until"],"properties":{"disk_gb":{"type":"integer","format":"int64"},"ended_at":{"type":["string","null"],"format":"date-time"},"id":{"type":"integer","format":"int64"},"launch_price":{"type":"boolean"},"monthly_price_cents":{"type":"integer","format":"int64"},"ordered_at":{"type":"string","format":"date-time"},"plan":{"type":"string"},"price_locked_until":{"type":"string","format":"date-time"},"ram_gb":{"type":"integer","format":"int64"},"server_id":{"type":"integer","format":"int64"},"vcpu":{"type":"integer","format":"int32"}}},"PlanOut":{"type":"object","required":["key","name","vcpu","ram_gb","disk_gb","traffic_tb","list_price_cents","price_cents","launch_price"],"properties":{"disk_gb":{"type":"integer","format":"int64"},"key":{"type":"string"},"launch_price":{"type":"boolean"},"list_price_cents":{"type":"integer","format":"int64"},"name":{"type":"string"},"price_cents":{"type":"integer","format":"int64","description":"What a new order pays per month today."},"ram_gb":{"type":"integer","format":"int64"},"traffic_tb":{"type":"integer","format":"int32"},"vcpu":{"type":"integer","format":"int32"}}},"PowerIn":{"type":"object","required":["action"],"properties":{"action":{"type":"string","description":"start, shutdown, stop or reboot"}}},"RealityOut":{"type":"object","required":["kind","label","state","text","have","unblocks","keys"],"properties":{"checked_at":{"type":["string","null"],"format":"date-time"},"have":{"type":"string","description":"What exists today."},"keys":{"type":"array","items":{"type":"string"},"description":"The .env keys it waits for."},"kind":{"type":"string","description":"compute, image, addresses, storage, backups, isos, dns, mailer or billing."},"label":{"type":"string"},"state":{"type":"string","description":"real, failing or blocked."},"text":{"type":"string","description":"Real: what the live check saw. Failing: the error. Blocked: what is missing."},"unblocks":{"type":"string","description":"What unblocks it."}}},"RegionOut":{"type":"object","required":["key","name","country"],"properties":{"country":{"type":"string"},"key":{"type":"string"},"name":{"type":"string"}}},"RegionStatusOut":{"type":"object","required":["name","state"],"properties":{"name":{"type":"string"},"state":{"type":"string"}}},"ReinstallIn":{"type":"object","required":["image"],"properties":{"image":{"type":"string"}}},"ResizeIn":{"type":"object","required":["plan"],"properties":{"plan":{"type":"string"}}},"ServerCreateIn":{"type":"object","required":["hostname","plan","region","image"],"properties":{"hostname":{"type":"string"},"image":{"type":"string","description":"Image key, for example \"debian-12\"."},"plan":{"type":"string","description":"Plan key, for example \"s\"."},"region":{"type":"string","description":"Region key, for example \"hel\"."},"ssh_key_ids":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Root logs in with these keys. Leave empty to get a generated root password instead."}}},"ServerCreatedOut":{"type":"object","description":"A server that was just created or reinstalled.","required":["server"],"properties":{"root_password":{"type":["string","null"],"description":"Present only when no SSH key was chosen: the generated root password. It is in this one\nanswer and nowhere else; only its hash is kept."},"server":{"$ref":"#/components/schemas/ServerOut"}}},"ServerOut":{"type":"object","required":["id","hostname","status","plan","region","vcpu","ram_gb","disk_gb","image","busy","error","monthly_price_cents","price_locked_until","created_at"],"properties":{"busy":{"type":"boolean","description":"True while a task for this server is running on the node."},"created_at":{"type":"string","format":"date-time"},"disk_gb":{"type":"integer","format":"int64"},"error":{"type":"string","description":"Why the last task failed, when it did."},"hostname":{"type":"string"},"id":{"type":"integer","format":"int64"},"image":{"type":"string"},"monthly_price_cents":{"type":"integer","format":"int64","description":"Monthly price of the current order, add-ons included."},"plan":{"type":"string"},"price_locked_until":{"type":"string","format":"date-time"},"private_ipv4":{"type":["string","null"],"description":"The private address on the node's network. There are no public addresses yet."},"ram_gb":{"type":"integer","format":"int64"},"region":{"type":"string"},"status":{"type":"string"},"vcpu":{"type":"integer","format":"int32"}}},"SnapshotIn":{"type":"object","required":["name"],"properties":{"name":{"type":"string"}}},"SnapshotOut":{"type":"object","required":["id","server_id","kind","name","status","created_at"],"properties":{"created_at":{"type":"string","format":"date-time"},"id":{"type":"integer","format":"int64"},"kind":{"type":"string"},"name":{"type":"string"},"server_id":{"type":"integer","format":"int64"},"status":{"type":"string","description":"creating, ready or deleting."}}},"SshKeyIn":{"type":"object","required":["name","public_key"],"properties":{"name":{"type":"string"},"public_key":{"type":"string"}}},"SshKeyOut":{"type":"object","required":["id","name","fingerprint"],"properties":{"fingerprint":{"type":"string"},"id":{"type":"integer","format":"int64"},"name":{"type":"string"}}},"StatusOut":{"type":"object","required":["regions","active_incidents"],"properties":{"active_incidents":{"type":"array","items":{"$ref":"#/components/schemas/IncidentOut"}},"regions":{"type":"array","items":{"$ref":"#/components/schemas/RegionStatusOut"}}}},"TicketIn":{"type":"object","required":["subject","body"],"properties":{"body":{"type":"string"},"server_id":{"type":["integer","null"],"format":"int64"},"subject":{"type":"string"}}},"TicketOut":{"type":"object","required":["id","subject","status","updated_at"],"properties":{"id":{"type":"integer","format":"int64"},"server_id":{"type":["integer","null"],"format":"int64"},"status":{"type":"string"},"subject":{"type":"string"},"updated_at":{"type":"string","format":"date-time"}}},"UsageLineOut":{"type":"object","required":["server_id","hostname","hours","amount_cents"],"properties":{"amount_cents":{"type":"integer","format":"int64"},"hostname":{"type":"string"},"hours":{"type":"integer","format":"int64"},"server_id":{"type":"integer","format":"int64"}}},"UsageOut":{"type":"object","required":["so_far_cents","projected_cents","credit_cents","servers"],"properties":{"credit_cents":{"type":"integer","format":"int64"},"projected_cents":{"type":"integer","format":"int64"},"servers":{"type":"array","items":{"$ref":"#/components/schemas/UsageLineOut"}},"so_far_cents":{"type":"integer","format":"int64"}}}},"securitySchemes":{"token":{"type":"http","scheme":"bearer"}}}}