When you deploy using flyctl you’re letting our go code run api calls to our Machines API based on your current source code and fly.toml.
We also have the Launch UI which is connectable to GitHub and can be used to skip flyctl locally entirely
The deployments API experiment
We deployed an api that matches the UX from launch UI but can be scripted into however you want with simple HTTP calls. As of now it covers launching a repo (if you have permissions on our GitHub integration) and deploying apps with it.
Understandably it is limited (you can’t pass custom image refs or point at non GitHub sources for example) but we will dogfood into it and see what shape this API needs to be.
Try it out
If you are okay with the fact that this API is prone to changes then give it a try. Checkout the open api spec at: https://fly.io/openapi/deployments.json
If you just want to sneak peek into it, I asked an agent to summarize it.
text below here was written by a robot
Endpoints for apps that deploy from GitHub through the Fly.io dashboard: read what happened, find out why a deploy failed, start new deploys, and launch an app from a repository.
- Base URL:
https://api.fly.io/api/v1/apps/{app} - Auth:
Authorization: Bearer <Fly.io token>- Reading needs a token that can read the app (for example
fly tokens create readonly). - Deploying needs one that can deploy it (for example
fly tokens create deploy). - Launching needs a token with a user who belongs to the organization (for example
fly auth token).
- Reading needs a token that can read the app (for example
{id}can be a deployment id orlatest.
Read
| Endpoint | Description |
|---|---|
GET /deployments |
List the app’s deployments, newest first. Query: limit (1–100), before (deployment id, for paging). |
GET /deployments/{id} |
One deployment: status, current step, commit, release, failure, steps, errors, repository settings and the files Fly.io generated for the build. Add ?wait=N (1–30 s) to wait until a running deployment changes. |
GET /deployments/{id}/logs |
The deployment’s log lines. Query: step (e.g. build), limit (last N lines). If the log can’t be read, the answer is still 200, with available: false and a reason (expired or temporarily_unavailable). |
GET /deployments/{id}/diagnosis |
A Markdown brief of the deployment for a person or coding agent: the failed step and where the fix usually is, errors, a log excerpt, generated files, repository settings, the last deployment that worked, and next steps. Query: lines (log lines to include). |
GET /deployments/source |
The app’s repository settings: repository, branch, deploy on push, fly.toml path, working directory. |
Deploy
| Endpoint | Description |
|---|---|
POST /deployments |
Deploy the repository, like “Deploy now” in the dashboard. Body: ref (branch or commit SHA, optional), replace (true to stop a running deployment and start this one). |
POST /deployments/{id}/retry |
Deploy the same commit as that deployment again. |
POST /deployments/{id}/cancel |
Stop a running deployment. |
PATCH /deployments/source |
Change the repository settings. Body: any of branch, auto_deploy, config_path, working_directory. |
Each app can start 5 deployments through the API per 10 minutes, and only one can run at a time unless replace is set.
Launch an app from a repository
| Endpoint | Description |
|---|---|
POST /deployments/launch |
Link a GitHub repository to an existing app and deploy it for the first time. Body: repository (owner/repo, required), branch, config_path, working_directory, review_plan. If the repository has this app’s fly.toml, it deploys it as is. Otherwise Fly.io detects a plan, generates the missing files (pushed to a flyio-new-files branch) and deploys. |
GET /deployments/{id}/plan |
The plan a launch detected: status (detecting, awaiting_confirmation, confirmed, unavailable), settings (region, port, VM size, databases) and the files it will generate. |
POST /deployments/{id}/confirm |
Confirm the plan of a launch started with review_plan: true. Body: settings, optional overrides for region, http_service_port, vm_size, vm_memory, vm_cpus, vm_cpukind. Without review_plan, Fly.io confirms the plan automatically. |
When a person has to act before a launch can continue, the answer is 409 with an action_required object containing a kind and a url to hand them:
kind |
What the person needs to do |
|---|---|
github_app_install |
Install the Fly.io GitHub App on the repository’s owner. |
github_repo_access |
Grant the installed GitHub App access to this repository. |
github_collaborator |
Make a member of the Fly.io organization (with a linked GitHub account) a collaborator on the repository. |
launch_prerequisites |
Fix the organization’s billing, account review or machine quota. |
Errors
Every error is JSON: {"error": "<message meant for the user>"}.
| Status | Meaning |
|---|---|
400 |
Bad parameter or body field |
403 |
The token’s user can’t deploy or launch this app |
404 |
Unknown app or deployment, or a token without access |
409 |
A deployment is already running, it already finished, or a person needs to act (action_required) |
422 |
The app has no linked repository, the branch doesn’t exist, or a setting is invalid |
429 |
Too many API deployments for this app; wait a few minutes |
503 |
GitHub or the deployer is unavailable; try again |