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_…

A key made while you are working in an organization belongs to that organization and acts for you there, with your role: a viewer's key reads, a developer's runs the instances, an admin's manages them. It stops working the moment you leave the organization, and a change to your role applies to its next request. GET /me says which account a key acts in and as whom (kind, role, actor). A call your role does not allow is answered 403 with code forbidden and a sentence naming the role it needs. Members are invited and removed in the portal, never through a key.

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, 5 and 30 minutes, then 2 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), and who is acting in it: a person's own account or an organization, with the caller's role.
`GET /plans` · `GET /locations`	Plans, prices, hardware, locations.
`GET /instances` · `POST /instances`	List; create. Free, where offered, starts without checkout or a card; a paid purchase returns `checkout_url`.
`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 Apps, Auth, Postgres, Redis, CouchDB, NATS and SeaweedFS) 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}`	A job's progress.
`GET /billing`	Subscriptions and charges.
`GET /webhooks` · `POST /webhooks` · `PATCH /webhooks/{id}` · `DELETE /webhooks/{id}`	List, create, update and remove signed webhook endpoints.
`GET /guides/apps`	The apps-hosting contract as markdown, for a coding agent (also public at /guides/apps here).

To start Free by API, send {"tier": "free"} to POST /instances. The response has free: true, checkout_url: null and an instance id to poll. It costs $0, needs no card and has 1000 GB outbound per month and no daily backups.

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.