API overview
Automate Pyo over HTTP with an API key.
The API is what the dashboard and the CLI use. It works in one simple way. You read everything from a snapshotOne request that returns everything you can see: teams, projects, clusters, services and recent deployments., and change anything through one endpointOne address in the API that you send requests to..
Base URL
The API lives on your own Pyo:
https://your-pyo/api/v1Authentication
Create an API key on the API keys page, then send it as a Bearer tokenA key sent in the Authorization header of each request. Whoever holds it gets its access.:
curl https://your-pyo/api/v1/state \
-H "Authorization: Bearer $PYO_TOKEN"A key is shown once, so save it when you create it.
A key expires after 30 days, 90 days (the default) or a year, or never. The API keys page shows when each key was last used and when it expires, and warns in its last week. An expired key gets a 401:
{ "error": "This API key expired. Create a new one." }What a key can do
| Access | What it allows |
|---|---|
| Read | Reading only |
| Deploy | Reading, plus deploying, cancelling, restarting, stopping and scaling |
| Full | Anything its owner can do |
A key can also be limited to some of your teams. Whatever its access, a key acts as you, with your role in each team. It can't manage your account or the installation.
Errors
Failed requests use a standard HTTP statusThe number every web response carries, like 200 for success or 404 for not found., with the reason in the body:
{ "error": "This API key can only read." }Pyo is at version 0.1, so the API can still change between releases.