API reference

Everything the portal does, from code. Same rules, same checks, same jobs. See the MCP reference for the same ground from an AI agent.

API keys

One credential for both the REST API and the MCP server.

Sign in, then create a key on the Access page. A key acts as the customer who created it and cannot create or revoke other keys. Send it on every request:

Authorization: Bearer lathe_…

Webhooks

Every event about your instances, posted to an https URL of yours. Add endpoints on the Integrations page or with POST /webhooks.

Each delivery is a POST with a JSON body {"id", "type", "instance_id", "at", "data"} and three headers: X-Lathe-Event (the type), X-Lathe-Delivery (an id, the same on every retry) and X-Lathe-Signature - sha256= followed by the hex HMAC-SHA256 of the raw body with the endpoint's secret. Verify the signature before trusting the body. Answer any 2xx within 10 seconds; anything else is retried after 1 minute, 5, 30, 2 hours and 12 hours, then given up. An endpoint that fails 20 deliveries in a row is disabled until you enable it again.

Types you will see: created ready allowlist label resize reset restore rotate console engines engine_settings health_alert health_reset verify_ok verify_failed job_failed pg_database_created pg_database_dropped couch_database_created couch_database_deleted nats_stream_created nats_stream_purged nats_stream_deleted auth_user_created auth_user_invited auth_user_banned auth_user_unbanned auth_user_deleted auth_link_sent api_key_created api_key_revoked oauth_granted oauth_disconnected. New types appear as features do; ignore what you do not know.

REST API

Base URL https://app.lathe.live/api/v1 · interactive docs · OpenAPI

curl -H "Authorization: Bearer lathe_…" https://app.lathe.live/api/v1/instances

curl -H "Authorization: Bearer lathe_…" https://app.lathe.live/api/v1/instances/ID/connection

curl -X POST -H "Authorization: Bearer lathe_…" -H "Content-Type: application/json" \
  -d '{"tier": "starter", "name": "acme-prod", "tags": ["prod"]}' https://app.lathe.live/api/v1/instances

Method and path	Purpose
`GET /me` · `PATCH /me`	The account and its profile (what goes on receipts).
`GET /plans` · `GET /locations`	Plans, prices, hardware, locations.
`GET /instances` · `POST /instances`	List; create (returns `checkout_url` for a paid plan).
`GET /instances/{id}` · `PATCH` · `DELETE ?confirm=`	Status, usage, monitoring, backups, activity; rename and retag; delete.
`GET /instances/{id}/connection`	Connection strings, password included.
`GET /instances/{id}/backups`	Daily backups and undo snapshots.
`PUT /instances/{id}/allowlist` · `PUT …/sql-console`	IP allowlist; SQL console off / ro / rw.
`PUT /instances/{id}/engines`	The engines on the box (any subset of Postgres, Redis, CouchDB, NATS, Apps and Auth) and their memory budgets; `GET /plans` lists each engine's floor, port, category and licence.
`POST /instances/{id}/actions/rotate \| resize \| reset \| restore`	Queue an operation; answers 202 with a job id.
`GET /jobs/{id}` · `GET /billing`	A job's progress; subscriptions and charges.
`GET /guides/apps`	The apps-hosting contract as markdown, for a coding agent (also public at /guides/apps here).

Errors are JSON: {"detail": "…", "code": "…"}. One job runs per instance at a time; a busy instance answers 409. Reset, restore and delete need confirm = the instance id.