---
title: "[Experimental] Deployments API"
date: "2026-11-17"
author: "Lubien"
url: "https://fly.io/changelog/experimental-deployments-api/"
discussion: "https://community.fly.io/t/experimental-deployments-api/29107"
---

# [Experimental] Deployments API

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`).
- `{id}` can be a deployment id or `latest`.

## 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 |
