{"openapi":"3.1.0","info":{"title":"Lathe customer API","description":"Manage your Lathe Postgres instances from code or from an AI agent.\n\n**Authentication.** Create an API key on the Account page of the portal and send it as\n`Authorization: Bearer lathe_…`. Keys act as the customer who created them; they cannot create or\nrevoke other keys.\n\n**Creating an instance costs money.** `POST /instances` returns `checkout_url` for a paid plan:\nopen it in a browser and pay; the instance is provisioned as soon as the payment page returns and\nthe response's `instance_id` is valid from the start (poll `GET /instances/{id}` — its `status` goes\n`awaiting_payment` → `pending` → `creating` → `running`; `payment_failed` if the card was declined,\n`error` if creation failed). A coupon that covers the whole first month skips the page. Every paid\npurchase goes through the hosted page, card on file or not.\n\n**Slow operations are jobs.** Reset, restore, rotate, allowlist, upgrade, SQL console and delete\nanswer `202` with a `job_id`; one job runs per instance at a time and the instance answers `409`\nwhile one is queued or running. Destructive actions (reset, restore, delete) require\n`confirm` to equal the instance id, exactly as the portal asks you to type it.\n\nThe same operations are available to AI agents over MCP at the `/mcp` endpoint on this host.","version":"1.0"},"paths":{"/me":{"get":{"tags":["account"],"summary":"The account behind this key","operationId":"me_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Me Me Get"}}}}}},"patch":{"tags":["account"],"summary":"Update the profile (what goes on receipts)","operationId":"me_patch_me_patch","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountPatch"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Me Patch Me Patch"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/billing":{"get":{"tags":["account"],"summary":"Subscriptions and charges","operationId":"billing_billing_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Billing Billing Get"}}}}}}},"/plans":{"get":{"tags":["catalogue"],"summary":"Plans, prices and locations","operationId":"plans_plans_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Plans Plans Get"}}}}}}},"/locations":{"get":{"tags":["catalogue"],"summary":"Where an instance can be created","operationId":"locations_locations_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Response Locations Locations Get"}}}}}}},"/instances":{"get":{"tags":["instances"],"summary":"List instances","operationId":"list_instances_instances_get","parameters":[{"name":"tag","in":"query","required":false,"schema":{"type":"string","description":"Only instances carrying this tag.","default":"","title":"Tag"},"description":"Only instances carrying this tag."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true},"title":"Response List Instances Instances Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["instances"],"summary":"Create an instance (starts a checkout)","operationId":"create_instance_instances_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstanceCreate"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedOut"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/instances/{instance_id}":{"get":{"tags":["instances"],"summary":"One instance in full: status, billing, usage, monitoring, backups, activity","operationId":"get_instance_instances__instance_id__get","parameters":[{"name":"instance_id","in":"path","required":true,"schema":{"type":"string","title":"Instance Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Instance Instances  Instance Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["instances"],"summary":"Rename or retag (allowed while a job runs)","operationId":"patch_instance_instances__instance_id__patch","parameters":[{"name":"instance_id","in":"path","required":true,"schema":{"type":"string","title":"Instance Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstancePatch"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Patch Instance Instances  Instance Id  Patch"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["instances"],"summary":"Delete: billing stops, the VM and its backups go, a final snapshot is kept 7 days","operationId":"delete_instance_instances__instance_id__delete","parameters":[{"name":"instance_id","in":"path","required":true,"schema":{"type":"string","title":"Instance Id"}},{"name":"confirm","in":"query","required":true,"schema":{"type":"string","description":"The instance id, typed exactly.","title":"Confirm"},"description":"The instance id, typed exactly."}],"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Accepted"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/instances/{instance_id}/connection":{"get":{"tags":["instances"],"summary":"Connection strings, password included","operationId":"connection_instances__instance_id__connection_get","parameters":[{"name":"instance_id","in":"path","required":true,"schema":{"type":"string","title":"Instance Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Connection Instances  Instance Id  Connection Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/instances/{instance_id}/backups":{"get":{"tags":["instances"],"summary":"Daily backups and undo snapshots that can be restored","operationId":"backups_instances__instance_id__backups_get","parameters":[{"name":"instance_id","in":"path","required":true,"schema":{"type":"string","title":"Instance Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true},"title":"Response Backups Instances  Instance Id  Backups Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/instances/{instance_id}/allowlist":{"put":{"tags":["instances"],"summary":"Replace the IP allowlist","operationId":"allowlist_instances__instance_id__allowlist_put","parameters":[{"name":"instance_id","in":"path","required":true,"schema":{"type":"string","title":"Instance Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowlistIn"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Accepted"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/instances/{instance_id}/sql-console":{"put":{"tags":["instances"],"summary":"Turn the browser SQL console off, read-only or read-write","operationId":"sql_console_instances__instance_id__sql_console_put","parameters":[{"name":"instance_id","in":"path","required":true,"schema":{"type":"string","title":"Instance Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SqlConsoleIn"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Accepted"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/instances/{instance_id}/actions/rotate":{"post":{"tags":["actions"],"summary":"Rotate the database password (the old URL stops working)","operationId":"rotate_instances__instance_id__actions_rotate_post","parameters":[{"name":"instance_id","in":"path","required":true,"schema":{"type":"string","title":"Instance Id"}}],"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Accepted"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/instances/{instance_id}/actions/resize":{"post":{"tags":["actions"],"summary":"Upgrade to a higher plan; the prorated difference is charged to the card on file now","operationId":"resize_instances__instance_id__actions_resize_post","parameters":[{"name":"instance_id","in":"path","required":true,"schema":{"type":"string","title":"Instance Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResizeIn"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Accepted"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/instances/{instance_id}/actions/reset":{"post":{"tags":["actions"],"summary":"Wipe the database and start empty (a snapshot is kept 7 days)","operationId":"reset_instances__instance_id__actions_reset_post","parameters":[{"name":"instance_id","in":"path","required":true,"schema":{"type":"string","title":"Instance Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmIn"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Accepted"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/instances/{instance_id}/actions/restore":{"post":{"tags":["actions"],"summary":"Restore a backup in place (a snapshot of the current state is kept 7 days)","operationId":"restore_instances__instance_id__actions_restore_post","parameters":[{"name":"instance_id","in":"path","required":true,"schema":{"type":"string","title":"Instance Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RestoreIn"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Accepted"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/jobs/{job_id}":{"get":{"tags":["jobs"],"summary":"A queued, running or finished operation","operationId":"job_jobs__job_id__get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Job Jobs  Job Id  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"Accepted":{"properties":{"status":{"type":"string","enum":["queued","already_queued"],"title":"Status","default":"queued"},"job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Id"},"instance_id":{"type":"string","title":"Instance Id"},"message":{"type":"string","title":"Message"},"job_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Url"},"cidrs":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Cidrs","description":"The allowlist as normalised (allowlist only)."}},"type":"object","required":["job_id","instance_id","message"],"title":"Accepted"},"AccountPatch":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Full name; required before the first purchase (it goes on receipts)."},"company":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company","description":"Printed on receipts instead of the name when set."},"tax_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tax Id"},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone"}},"type":"object","title":"AccountPatch"},"AllowlistIn":{"properties":{"cidrs":{"items":{"type":"string"},"type":"array","title":"Cidrs","description":"Source CIDRs allowed on 5432/6432. Empty = anywhere (TLS + password still required)."}},"type":"object","required":["cidrs"],"title":"AllowlistIn"},"ConfirmIn":{"properties":{"confirm":{"type":"string","title":"Confirm","description":"The instance id, typed exactly."}},"type":"object","required":["confirm"],"title":"ConfirmIn"},"CreatedOut":{"properties":{"instance_id":{"type":"string","title":"Instance Id"},"tier":{"type":"string","title":"Tier"},"status":{"type":"string","enum":["awaiting_payment","pending"],"title":"Status"},"checkout_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Checkout Url","description":"Open in a browser and pay. Present for paid purchases."},"job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Id"},"url":{"type":"string","title":"Url"},"message":{"type":"string","title":"Message"}},"type":"object","required":["instance_id","tier","status","url","message"],"title":"CreatedOut"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"InstanceCreate":{"properties":{"tier":{"type":"string","title":"Tier","description":"starter | plus | pro (see GET /plans)"},"name":{"type":"string","title":"Name","description":"A label shown instead of the id; free text, not unique.","default":""},"tags":{"items":{"type":"string"},"type":"array","title":"Tags","description":"Lowercase tokens for grouping: letters, digits, . _ : -"},"location":{"type":"string","title":"Location","description":"Hetzner location name from GET /locations; empty = the default.","default":""},"coupon":{"type":"string","title":"Coupon","description":"A discount code for the first month.","default":""}},"type":"object","required":["tier"],"title":"InstanceCreate"},"InstancePatch":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Omit to keep; empty string clears."},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tags","description":"Omit to keep; empty list clears."}},"type":"object","title":"InstancePatch"},"ResizeIn":{"properties":{"tier":{"type":"string","title":"Tier","description":"A higher tier than the current one; plans move up only."}},"type":"object","required":["tier"],"title":"ResizeIn"},"RestoreIn":{"properties":{"confirm":{"type":"string","title":"Confirm","description":"The instance id, typed exactly."},"image_id":{"type":"integer","title":"Image Id","description":"A backup or undo-snapshot image id from GET /instances/{id}/backups."}},"type":"object","required":["confirm","image_id"],"title":"RestoreIn"},"SqlConsoleIn":{"properties":{"mode":{"type":"string","enum":["off","ro","rw"],"title":"Mode"}},"type":"object","required":["mode"],"title":"SqlConsoleIn"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"servers":[{"url":"/api/v1"}]}