Skip to content
pilots
Dashboard
All pages

API and SDKs

Every host serves the whole API. There is no control plane in front of it and no host that has to be alive for a call to work, which is why a request about your machine is answered by a host that has never run it.

Calling it 

curl -H "Authorization: Bearer $PILOT_API_KEY" \
  https://api.pilotrun.app/v1/machines

A key goes in an Authorization header as a bearer token. pilot login mints one for your laptop, and the dashboard's tokens page mints the rest. To make a call with the key the CLI already holds, let the CLI make it.

pilot api /v1/machines
pilot api /v1/services --json

Keys and scopes

Three scopes, nested: each one contains the one before it. An unrecognised scope name fails closed rather than being treated as harmless, and a route that is not in the table below needs the highest scope.

Scope Reaches
machines Machines, checkpoints, volumes, plans, your own metrics, your outbound addresses, who you are, and the MCP endpoint.
deploy Everything above, plus services, builds, builders, domains and the repository connections a deploy reads.
admin Everything above, plus the fleet's own inventory, minting keys, and any route not otherwise listed.

A key can also be narrowed further when it is minted, and an MCP client that arrives with no key at all is walked into the browser and comes back with one (agents and MCP).

The shape of an answer

Every non-success body has the same four fields: a sentence for a person, a code to branch on, a next naming the one thing to do about it, and typed details where there are any. Branch on the code, never on the wording. The errors page is the whole list.

The routes you will use

Route What it is
/v1/machines Create, list, inspect, exec, suspend, destroy.
/v1/checkpoints Capture and restore.
/v1/plan What a directory would deploy as, without building it.
/v1/builds Build an image from a directory or a Dockerfile.
/v1/services Services, releases, rollbacks and knobs.
/v1/volumes Volumes and their snapshots.
/v1/domains Custom hostnames and their verification state.
/v1/metrics Your organization’s machines, as Prometheus text.
/v1/health A host’s own view of itself, including whether it has caught up.
/mcp The MCP endpoint (agents and MCP).

The typed clients

There are four, in JavaScript, Python, Go and Elixir. They speak the same API with the same names, each in its own spelling, and three of them carry a test that parses the daemon's own source so a field cannot be dropped from a client without the test failing.

Inside a machine, a client constructed with no key works: the SDKs read the token file the guest agent keeps fresh (what a machine may do).

npm i @pilots/sdk
go get github.com/pilotsrun/pilots/sdks/go
  • The JavaScript client carries no runtime dependencies, and it also ships @pilots/sdk/tanstack and @pilots/sdk/next (deploy).
  • The Python and Elixir clients are not published yet. Until they are, the HTTP API and the CLI are the surfaces to reach for in those two languages, and pilot api covers anything a client would.