Deployments

Create, list, inspect, and roll back deployments.

A deployment is an immutable build of your project, served from a unique URL. Promoting to production aliases a deployment to your custom domain.

Create a deployment

http

POST /v1/deployments

project_id string body required

The project to deploy. Get from GET /v1/projects.

files object body required

Map of path → sha256. Halo asks you to upload only the files it doesn’t already have cached.

target string body

production or preview. Defaults to preview.

env object body

Per-deployment environment overrides. Merged on top of project env.

Response

id string

Deployment identifier, e.g. dpl_x7k2qz.

url string

Stable URL for this exact deployment.

status string

queued → building → ready → (optional) error.

Request example

bash

curl https://api.halo.app/v1/deployments \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "prj_abc123",
    "files": { "index.html": "abc...", "app.js": "def..." },
    "target": "production"
  }'

Response example

json

{
  "id": "dpl_x7k2qz",
  "url": "https://my-app-x7k2qz.halo.app",
  "status": "queued",
  "created_at": "2026-04-29T14:32:11Z"
}

Get a deployment

http

GET /v1/deployments/{id}

Returns the full deployment object including build logs reference and timing breakdown.

List deployments

http

GET /v1/deployments?project_id=prj_abc123&target=production

Filters: project_id, target, status, created_after, created_before.

Roll back

http

POST /v1/deployments/{id}/promote

Aliases the given deployment to the production domain. Atomic — no traffic gap.

Last updated 3 d ago Edit this page