API Endpoints

Learn how to use the Hatchbox REST API Endpoints

Hatchbox API

The Hatchbox API lets you create and deploy apps, manage environment variables, domains, processes, and cron jobs, discover your accounts, clusters, database clusters, and git providers, inspect and manage the servers in a cluster, create databases and attach them to your apps, download or trigger database backups, and read the logs of any operation, whether you queued it or a git push did — all from your own scripts and tooling.

Table of contents

• Authentication
• Base URL
• Active subscription required
• Finding IDs
• Errors
• Pagination
• Accounts
  • List your accounts
• Apps
  • The app object
  • List apps
  • Get an app
  • Create an app
  • Update an app
  • Caddy configuration
  • Delete an app
  • Deploy an app
  • Restart an app
  • Enable auto-deploy
  • Disable auto-deploy
• Environment variables
  • Create environment variables
  • Add or update environment variables
  • Remove environment variables
• Domains
  • List domains
  • Get a domain
  • Add a domain
  • Update a domain
  • Remove a domain
• Processes
  • The process object
  • List processes
  • Get a process
  • Create a process
  • Update a process
  • Delete a process
  • Restart a process
  • Enable a process
  • Disable a process
• Cron jobs
  • The cron job object
  • List cron jobs
  • Get a cron job
  • Create a cron job
  • Update a cron job
  • Delete a cron job
• Clusters
  • List clusters
  • Get a cluster
• Servers
  • The server object
  • List servers
  • Get a server
  • Update server roles
  • Provision a server
  • Reboot a server
  • The firewall rule object
  • List firewall rules
  • Get a firewall rule
  • Add a firewall rule
  • Remove a firewall rule
• Git providers
  • List git providers
• Database clusters
  • List database clusters
• Databases
  • The database object
  • SQLite databases
  • List databases
  • Get a database
  • Create a database
  • Update a database
  • List an app's databases
  • Get an app's database
  • Attach a database to an app
  • Detach a database from an app
  • The backup configuration object
  • Get the backup configuration
  • Enable or update backups
  • Disable backups
  • Test the backup connection
  • Trigger a backup
  • Download the latest backup
• Logs
  • The log object
  • Where the output lives
  • Get a log
  • List an app's logs
  • Waiting for an operation to finish

Authentication

All requests require an API token, sent as a Bearer token:

Authorization: Bearer [TOKEN]

You can find your API token in your Hatchbox account under API Tokens.

Requests with a missing or invalid token return 401 Unauthorized with an empty body.

Base URL

https://hatchbox.io/api/v1

All responses are JSON.

Active subscription required

The API is available on accounts with an active Hatchbox subscription. Every endpoint scoped to an account's resources — listing, reading, creating, or acting on apps, clusters, servers, database clusters, git providers, domains, processes, environment variables, and database backups — requires the account that owns the resource to have an active subscription (a trial counts). When it doesn't, the response is 402 Payment Required:

{ "error": "An active subscription is required for [Account Name]" }

Listing your accounts is the one exception — it stays available without a subscription, so a client can always discover which accounts it can act on.

Finding IDs

Most endpoints are scoped to a resource and need its ID. Start from your accounts and work down:

• Account ID — use List your accounts. Accepts either the numeric id or the prefixed form (acct_…) shown in the dashboard URL.
• App ID — use List apps for an account.
• Cluster ID — use List clusters for an account.
• Server ID — use Get a cluster, which includes the cluster's servers.
• Database cluster ID — use List database clusters for an account.
• Database ID — use List databases for a database cluster, or read it from the database's dashboard URL.
• Process ID — use List processes for an app.
• Firewall rule ID — use List firewall rules for a server.
• Log ID — returned by the operation that created it. For an operation you didn't queue yourself — an auto-deploy from a git push, say — use List an app's logs.

Errors

Pagination

Endpoints that can return an unbounded number of records are paginated. They still return a plain JSON array — the page state comes back in response headers:

curl "https://hatchbox.io/api/v1/apps/[APP_ID]/logs?page=2&limit=50" \
  -H "Authorization: Bearer [TOKEN]"

Follow link rather than incrementing page yourself if you're walking a whole collection — it's the stable way to know when to stop:

URL="https://hatchbox.io/api/v1/apps/[APP_ID]/logs?limit=100"

while [ -n "$URL" ]; do
  BODY=$(curl -sD /tmp/h "$URL" -H "Authorization: Bearer $TOKEN")
  echo "$BODY" | jq -r '.[] | "\(.state)\t\(.name)"'
  URL=$(grep -i '^link:' /tmp/h | tr ',' '\n' | grep 'rel="next"' | sed -e 's/.*<//' -e 's/>.*//')
done

Endpoints not marked as paginated return every record.

Accounts

Your accounts are the top of the hierarchy — apps, clusters, and git providers all belong to one. Use this endpoint to discover the accounts your token can act on, then pass an account's id to the account-scoped list endpoints below.

List your accounts

Returns the accounts your token's user belongs to. Unlike the rest of the API, this endpoint does not require an active subscription, so you can always determine which accounts are available.

GET /api/v1/accounts

curl https://hatchbox.io/api/v1/accounts \
  -H "Authorization: Bearer [TOKEN]"

[
  { "id": 3, "name": "My Team" }
]

An account's id accepts either the numeric form or the prefixed acct_… form from the dashboard URL wherever an [ACCOUNT_ID] is required.

Apps

The app object

{
  "id": 1,
  "name": "my-app",
  "cluster_id": 12,
  "connected_account_id": 5,
  "repo_path": "myuser/my-app",
  "branch": "main",
  "auto_deploy": false,
  "pre_build_script": null,
  "build_script": null,
  "post_build_script": null,
  "post_deploy_script": null,
  "failed_deploy_script": null,
  "dns_provider": null,
  "dns_api_user": null,
  "caddyfile": null,
  "health_check_uri": null,
  "last_deploy_at": "2026-07-14T18:22:10.000Z",
  "last_deploy_sha": "abc1234def5678"
}

The DNS access token is never returned, even though it can be set.

List apps

Returns the apps for a single account, sorted by name.

GET /api/v1/accounts/[ACCOUNT_ID]/apps

curl https://hatchbox.io/api/v1/accounts/[ACCOUNT_ID]/apps \
  -H "Authorization: Bearer [TOKEN]"

Returns an array of app objects. An account you're not a member of returns 404 {"error": "Account not found"}.

Get an app

GET /api/v1/apps/[APP_ID]

curl https://hatchbox.io/api/v1/apps/[APP_ID] \
  -H "Authorization: Bearer [TOKEN]"

Returns a single app object.

Create an app

Creates an app on a cluster. cluster_id and name are required; the app is created with auto-deploy off (enable it separately once a git provider is connected).

POST /api/v1/apps

curl -X POST https://hatchbox.io/api/v1/apps \
  -H "Authorization: Bearer [TOKEN]" \
  -H "Content-Type: application/json" \
  -d '{"app": {"cluster_id": 12, "name": "my-app", "branch": "main", "repo_path": "myuser/my-app", "connected_account_id": 5}}'

Returns 201 Created with the app object. A cluster_id you don't own returns 404 {"error": "Cluster not found"}; validation failures return 422 with errors.

Update an app

Updates an app's configuration. Accepts the same fields as create except cluster_id — an app can't be moved between clusters via the API. To toggle auto-deploy, use the auto-deploy endpoints below.

PATCH /api/v1/apps/[APP_ID]

curl -X PATCH https://hatchbox.io/api/v1/apps/[APP_ID] \
  -H "Authorization: Bearer [TOKEN]" \
  -H "Content-Type: application/json" \
  -d '{"app": {"build_script": "bundle install", "branch": "production"}}'

Returns 200 OK with the updated app object.

Caddy configuration

Two fields control an app's Caddy setup:

curl -X PATCH https://hatchbox.io/api/v1/apps/[APP_ID] \
  -H "Authorization: Bearer [TOKEN]" \
  -H "Content-Type: application/json" \
  -d '{"app": {"caddyfile": "import /home/deploy/my-app/current/hatchbox/Caddyfile.pre*\n\n{{encode}}\n{{file_server}}\n{{default}}\n\nimport /home/deploy/my-app/current/hatchbox/Caddyfile.post*", "health_check_uri": "/up"}}'

The configuration is applied on submission, not on change. Sending a caddyfile identical to the stored one still re-applies it. This is deliberate: a version-controlled Caddyfile is typically a wrapper that imports other files out of your repository, so the wrapper your deploy script sends is byte-for-byte the same every time even though the imported files have changed. Sending it on every deploy is the intended usage.

health_check_uri must be a relative path. An absolute URL returns 422 and nothing is applied:

{ "errors": ["Health check uri must be a relative path like '/example'"] }

Delete an app

Deletes an app and removes it from your servers. This runs the following, in order:

• Deletes the app's folder and its contents from all the servers
• Stops the app's processes and completely removes them from all the servers
• Detaches the app's databases — the databases themselves are not deleted

This cannot be undone. To confirm, send the app's own name in the request body. A request without it, or with a name that doesn't match, is refused.

DELETE /api/v1/apps/[APP_ID]

curl -X DELETE https://hatchbox.io/api/v1/apps/[APP_ID] \
  -H "Authorization: Bearer [TOKEN]" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-app"}'

{ "id": 4320 }

The returned id is the log for the deletion. The work is queued, so a successful response means it was accepted, not that it finished — the app record still exists at the moment you get this response and is removed once the job reaches that step.

If the name doesn't match, the response is 422 and nothing is queued:

{ "error": "App name does not match. Resend with the app's name to confirm deletion." }

The expected name is deliberately not echoed back, so fetch the app first if you need it.

If a deletion is already running for this app, the response is 409:

{ "error": "App is already being deleted" }

Following the log. Logs belong to the app that produced them, so this log is deleted along with the app. Expect state to reach completed and then, moments later, for GET /api/v1/logs/[LOG_ID] to start returning 404 {"error": "Log not found"} — that 404 is the normal end state for this operation, not an error. Treat either a completed state or a subsequent 404 as success, and a failed state as failure.

Avoid deploying the app while a deletion is in flight. A deploy that starts mid-deletion can recreate the app's files and services after the deletion has removed them, leaving processes on your servers that Hatchbox no longer tracks.

Deploy an app

Queues a deploy of the app's configured branch.

POST /api/v1/apps/[APP_ID]/deploy

curl -X POST https://hatchbox.io/api/v1/apps/[APP_ID]/deploy \
  -H "Authorization: Bearer [TOKEN]"

{ "id": 4212 }

The returned id is the log for this deploy. Deploys are queued, so a successful response means the deploy was accepted, not that it finished — fetch the log to follow it, and see Waiting for an operation to finish. If the app has no active servers:

{ "error": "No active servers available to deploy to" }

Restart an app

Restarts all of the app's processes.

POST /api/v1/apps/[APP_ID]/restart

curl -X POST https://hatchbox.io/api/v1/apps/[APP_ID]/restart \
  -H "Authorization: Bearer [TOKEN]"

{ "id": 4213 }

The returned id is the log for this restart.

Enable auto-deploy

Registers a webhook on the git host and turns on automatic deploys. Requires a connected git provider.

POST /api/v1/apps/[APP_ID]/auto_deploy

curl -X POST https://hatchbox.io/api/v1/apps/[APP_ID]/auto_deploy \
  -H "Authorization: Bearer [TOKEN]"

Returns 200 OK with the app object (auto_deploy now true). If the app has no connected git provider:

{ "error": "Auto deploy requires a connected git provider" }

If the git host rejects the webhook, the response is 502:

{ "error": "Could not enable auto deploy" }

Disable auto-deploy

Removes the webhook and turns off automatic deploys. Idempotent — succeeds even if auto-deploy wasn't on.

DELETE /api/v1/apps/[APP_ID]/auto_deploy

curl -X DELETE https://hatchbox.io/api/v1/apps/[APP_ID]/auto_deploy \
  -H "Authorization: Bearer [TOKEN]"

Returns 204 No Content.

Environment variables

Environment variable names are normalized to uppercase and may only contain letters, numbers, and underscores. Changing environment variables triggers an update on your servers. Values are never returned by the API.

Create environment variables

Adds new variables. All-or-nothing: if any variable is invalid, none are created. To change an existing variable, use Add or update — creating a duplicate name returns 422.

POST /api/v1/apps/[APP_ID]/env_vars

curl -X POST https://hatchbox.io/api/v1/apps/[APP_ID]/env_vars \
  -H "Authorization: Bearer [TOKEN]" \
  -H "Content-Type: application/json" \
  -d '{"env_vars": [{"name": "FOO", "value": "bar"}, {"name": "BAZ", "value": "qux"}]}'

[
  { "id": 91, "name": "FOO" },
  { "id": 92, "name": "BAZ" }
]

Add or update environment variables

Updates variables that already exist (matched by name) and creates any that don't. Include "_destroy": "1" to remove one in the same request.

PUT /api/v1/apps/[APP_ID]/env_vars

curl -X PUT https://hatchbox.io/api/v1/apps/[APP_ID]/env_vars \
  -H "Authorization: Bearer [TOKEN]" \
  -H "Content-Type: application/json" \
  -d '{"env_vars": [{"name": "FOO", "value": "new-value"}, {"name": "BAZ", "_destroy": "1"}]}'

Returns 200 OK with an empty body.

Remove environment variables

DELETE /api/v1/apps/[APP_ID]/env_vars

curl -X DELETE https://hatchbox.io/api/v1/apps/[APP_ID]/env_vars \
  -H "Authorization: Bearer [TOKEN]" \
  -H "Content-Type: application/json" \
  -d '{"env_vars": ["FOO", "BAZ"]}'

Returns 200 OK with an empty body.

Domains

Domains are identified by their name — e.g. /domains/example.com. Wildcard domains use *.example.com.

List domains

GET /api/v1/apps/[APP_ID]/domains

[
  { "id": 5, "name": "example.com", "created_at": "2026-07-14T18:22:10.000Z", "updated_at": "2026-07-14T18:22:10.000Z" }
]

Get a domain

GET /api/v1/apps/[APP_ID]/domains/[DOMAIN_NAME]

Returns a single domain. If it isn't on this app: {"error": "Domain not found"}.

Add a domain

POST /api/v1/apps/[APP_ID]/domains

curl -X POST https://hatchbox.io/api/v1/apps/[APP_ID]/domains \
  -H "Authorization: Bearer [TOKEN]" \
  -H "Content-Type: application/json" \
  -d '{"domain": {"name": "example.com"}}'

Returns 201 Created with the domain. A domain already connected to another app in the same cluster returns 422:

{ "errors": ["Name is already connected to another App in this Cluster"] }

Update a domain

Renames an existing domain.

PATCH /api/v1/apps/[APP_ID]/domains/[DOMAIN_NAME]

curl -X PATCH https://hatchbox.io/api/v1/apps/[APP_ID]/domains/example.com \
  -H "Authorization: Bearer [TOKEN]" \
  -H "Content-Type: application/json" \
  -d '{"domain": {"name": "www.example.com"}}'

Returns 200 OK with the updated domain.

Remove a domain

DELETE /api/v1/apps/[APP_ID]/domains/[DOMAIN_NAME]

Returns 200 OK with an empty body.

Processes

A process is a long-running command Hatchbox runs for your app as a systemd service — your web server, background workers, and anything else that needs to stay up. Processes are identified by their numeric ID; use List processes to find it.

Every write here is queued and runs in the background, so a successful response means the change was saved, not that it has reached your servers yet. Each one returns the id of a log you can follow.

The process object

{
  "id": 15,
  "name": "web",
  "start_command": "bin/rails server",
  "stop_command": "",
  "reload_command": "",
  "restart_on_deploy": true,
  "server_id": 6,
  "socket": false,
  "systemd_type": "simple",
  "active": true,
  "roles": ["web"],
  "appsignal": false,
  "appsignal_options": null,
  "created_at": "2026-07-02T17:08:01.887Z",
  "updated_at": "2026-07-02T17:08:01.887Z"
}

{ "errors": ["Appsignal monitoring requires connecting AppSignal to this app first"] }

List processes

GET /api/v1/apps/[APP_ID]/processes

curl https://hatchbox.io/api/v1/apps/[APP_ID]/processes \
  -H "Authorization: Bearer [TOKEN]"

Returns an array of process objects.

Get a process

GET /api/v1/apps/[APP_ID]/processes/[PROCESS_ID]

curl https://hatchbox.io/api/v1/apps/[APP_ID]/processes/[PROCESS_ID] \
  -H "Authorization: Bearer [TOKEN]"

Returns a single process object. A process that isn't on this app returns 404 {"error": "Process not found"}.

Create a process

POST /api/v1/apps/[APP_ID]/processes

curl -X POST https://hatchbox.io/api/v1/apps/[APP_ID]/processes \
  -H "Authorization: Bearer [TOKEN]" \
  -H "Content-Type: application/json" \
  -d '{"process": {"name": "worker", "start_command": "bundle exec sidekiq", "roles": ["worker"]}}'

Returns 201 Created with the process object plus the id of the log for installing it on your servers:

{
  "id": 16,
  "name": "worker",
  "...": "...",
  "log_id": 4330
}

Validation failures return 422 with errors — a duplicate name on the same app, a missing start_command, or both roles and server_id set at once:

{ "errors": ["Only one option can be selected between roles and server"] }

Update a process

Accepts the same parameters as create; send only the fields you're changing. To enable or disable a process, use the endpoints below rather than sending active.

PATCH /api/v1/apps/[APP_ID]/processes/[PROCESS_ID]

curl -X PATCH https://hatchbox.io/api/v1/apps/[APP_ID]/processes/[PROCESS_ID] \
  -H "Authorization: Bearer [TOKEN]" \
  -H "Content-Type: application/json" \
  -d '{"process": {"start_command": "bundle exec sidekiq -c 10"}}'

Returns 200 OK with the updated process object and a log_id for applying the change.

Renaming a process changes the name of its systemd unit. Hatchbox removes the old unit as part of the same operation, so a rename doesn't leave a stray service behind — but the process is stopped and restarted under its new name, so expect a brief interruption.

Delete a process

Stops the process, removes its systemd unit from every server it runs on, and deletes the record. If this was the app's last active web process, the app's Caddy configuration is rewritten too.

DELETE /api/v1/apps/[APP_ID]/processes/[PROCESS_ID]

curl -X DELETE https://hatchbox.io/api/v1/apps/[APP_ID]/processes/[PROCESS_ID] \
  -H "Authorization: Bearer [TOKEN]"

{ "id": 4331 }

The returned id is the log for the removal. The process record still exists at the moment you get this response and is deleted once the job has torn down the units.

Restart a process

POST /api/v1/apps/[APP_ID]/processes/[PROCESS_ID]/restart

curl -X POST https://hatchbox.io/api/v1/apps/[APP_ID]/processes/[PROCESS_ID]/restart \
  -H "Authorization: Bearer [TOKEN]"

{ "id": 4332 }

The returned id is the log for the restart.

Enable a process

Enables the process and starts its systemd unit on every server it runs on.

POST /api/v1/apps/[APP_ID]/processes/[PROCESS_ID]/activation

curl -X POST https://hatchbox.io/api/v1/apps/[APP_ID]/processes/[PROCESS_ID]/activation \
  -H "Authorization: Bearer [TOKEN]"

Returns 200 OK with the process object (active now true) and a log_id:

{
  "id": 15,
  "name": "web",
  "active": true,
  "...": "...",
  "log_id": 4333
}

Safe to repeat. Enabling a process that is already enabled changes nothing, queues nothing, and returns "log_id": null — it will not restart a healthy process.

Disable a process

Stops the process and disables its systemd unit, leaving the record in place so it can be re-enabled later.

DELETE /api/v1/apps/[APP_ID]/processes/[PROCESS_ID]/activation

curl -X DELETE https://hatchbox.io/api/v1/apps/[APP_ID]/processes/[PROCESS_ID]/activation \
  -H "Authorization: Bearer [TOKEN]"

Returns 200 OK with the process object (active now false) and a log_id. As with enabling, disabling an already-disabled process is a no-op and returns "log_id": null.

Cron jobs

Cron jobs are scheduled commands that run inside your app's current deploy, on every server in the cluster carrying the cron role.

Hatchbox writes all of an app's cron jobs into a single crontab file on those servers, so every change here rewrites the whole file. That rewrite is queued and runs in the background — a successful response means the change was saved, not that it has reached the servers yet.

An app whose cluster has no active cron server can't schedule anything, so creating or updating returns 422:

{ "error": "No active servers with the cron role in this cluster" }

Deleting is still allowed in that case, so a cluster that lost its cron server can be tidied up.

The cron job object

{
  "id": 17,
  "app_id": 1,
  "name": "Nightly sync",
  "run_at": "0 0 * * *",
  "command": "bin/rails sync:nightly",
  "appsignal": false,
  "honeybadger_checkin_id": null,
  "created_at": "2026-08-10T09:14:02.000Z",
  "updated_at": "2026-08-10T09:14:02.000Z"
}

{ "errors": ["Appsignal monitoring requires connecting AppSignal to this app first"] }

honeybadger_checkin_id has no such requirement — create a check-in and pass its ID.

List cron jobs

GET /api/v1/apps/[APP_ID]/cron_jobs

curl https://hatchbox.io/api/v1/apps/[APP_ID]/cron_jobs \
  -H "Authorization: Bearer [TOKEN]"

Returns an array of cron job objects.

Get a cron job

GET /api/v1/apps/[APP_ID]/cron_jobs/[CRON_JOB_ID]

curl https://hatchbox.io/api/v1/apps/[APP_ID]/cron_jobs/[CRON_JOB_ID] \
  -H "Authorization: Bearer [TOKEN]"

Returns a single cron job object. A cron job belonging to a different app returns 404 {"error": "Cron job not found"}.

Create a cron job

POST /api/v1/apps/[APP_ID]/cron_jobs

curl -X POST https://hatchbox.io/api/v1/apps/[APP_ID]/cron_jobs \
  -H "Authorization: Bearer [TOKEN]" \
  -H "Content-Type: application/json" \
  -d '{"cron_job": {"name": "Nightly sync", "run_at": "0 0 * * *", "command": "bin/rails sync:nightly"}}'

Returns 201 Created with the cron job. An unparseable schedule returns 422:

{ "errors": ["Run at must be a valid cron expression"] }

Update a cron job

PATCH /api/v1/apps/[APP_ID]/cron_jobs/[CRON_JOB_ID]

Accepts the same parameters as create; send only the fields you're changing.

curl -X PATCH https://hatchbox.io/api/v1/apps/[APP_ID]/cron_jobs/[CRON_JOB_ID] \
  -H "Authorization: Bearer [TOKEN]" \
  -H "Content-Type: application/json" \
  -d '{"cron_job": {"run_at": "@daily"}}'

Returns the updated cron job.

Delete a cron job

DELETE /api/v1/apps/[APP_ID]/cron_jobs/[CRON_JOB_ID]

curl -X DELETE https://hatchbox.io/api/v1/apps/[APP_ID]/cron_jobs/[CRON_JOB_ID] \
  -H "Authorization: Bearer [TOKEN]"

Returns 200 OK with an empty body.

Clusters

List clusters

Returns the clusters for a single account, sorted by name.

GET /api/v1/accounts/[ACCOUNT_ID]/clusters

curl https://hatchbox.io/api/v1/accounts/[ACCOUNT_ID]/clusters \
  -H "Authorization: Bearer [TOKEN]"

[
  {
    "id": 12,
    "name": "my-cluster",
    "provider": "digitalocean",
    "region": "nyc3",
    "servers_count": 2
  }
]

An account you're not a member of returns 404 {"error": "Account not found"}.

Get a cluster

Returns a single cluster with its servers included, so you can render a cluster in one request. See the server object for the shape of each entry.

GET /api/v1/clusters/[CLUSTER_ID]

curl https://hatchbox.io/api/v1/clusters/[CLUSTER_ID] \
  -H "Authorization: Bearer [TOKEN]"

{
  "id": 12,
  "name": "my-cluster",
  "provider": "digitalocean",
  "region": "nyc3",
  "servers_count": 2,
  "servers": [
    {
      "id": 34,
      "name": "web-1",
      "state": "active",
      "roles": ["web", "worker"],
      "cluster_id": 12,
      "provider_id": "405177344",
      "public_ip": "203.0.113.10",
      "public_ipv6": null,
      "private_ip": "10.0.0.5",
      "ssh_port": 22,
      "size": "s-2vcpu-4gb",
      "ubuntu_version": "noble",
      "last_configured_at": "2026-07-14T09:12:44.000Z"
    }
  ]
}

The servers array is sorted by name and contains every server in the cluster. A cluster on an account you're not a member of returns 404 {"error": "Cluster not found"}.

Servers

A server is one machine in a cluster. Its roles determine what runs on it — your app's web, worker, and cron processes, a load balancer, and/or a database engine.

Servers are included in Get a cluster, so you usually don't need these endpoints to list them. Use them when you want a single server on its own.

The server object

{
  "id": 34,
  "name": "web-1",
  "state": "active",
  "roles": ["web", "worker"],
  "cluster_id": 12,
  "provider_id": "405177344",
  "public_ip": "203.0.113.10",
  "public_ipv6": null,
  "private_ip": "10.0.0.5",
  "ssh_port": 22,
  "size": "s-2vcpu-4gb",
  "ubuntu_version": "noble",
  "last_configured_at": "2026-07-14T09:12:44.000Z"
}

List servers

Returns every server in a cluster, sorted by name.

GET /api/v1/clusters/[CLUSTER_ID]/servers

curl https://hatchbox.io/api/v1/clusters/[CLUSTER_ID]/servers \
  -H "Authorization: Bearer [TOKEN]"

Returns an array of server objects. A cluster on an account you're not a member of returns 404 {"error": "Cluster not found"}.

Get a server

GET /api/v1/clusters/[CLUSTER_ID]/servers/[SERVER_ID]

curl https://hatchbox.io/api/v1/clusters/[CLUSTER_ID]/servers/[SERVER_ID] \
  -H "Authorization: Bearer [TOKEN]"

Returns a single server object. A server that exists but lives in a different cluster returns 404 {"error": "Server not found"} — the ID has to match the cluster in the path.

Update server roles

Sets which roles a server carries. This is a desired-state endpoint: send the complete list of roles the server should end up with, and Hatchbox works out what to add and what to remove. Roles you leave out are removed.

PATCH /api/v1/clusters/[CLUSTER_ID]/servers/[SERVER_ID]/roles

curl -X PATCH https://hatchbox.io/api/v1/clusters/[CLUSTER_ID]/servers/[SERVER_ID]/roles \
  -H "Authorization: Bearer [TOKEN]" \
  -H "Content-Type: application/json" \
  -d '{"server": {"roles": ["web", "worker", "cron"]}}'

Returns 200 OK with what changed and the logs for applying it:

{
  "added_roles": ["cron"],
  "removed_roles": ["load_balancer"],
  "logs": [
    { "id": 4340, "name": "Servers::AddRoles" },
    { "id": 4341, "name": "Servers::RemoveRoles" }
  ]
}

Additions and removals run as separate operations, so a request that does both returns two logs. A request that changes nothing returns empty arrays and an empty logs array.

Adding an app code role (app, web, worker, cron) triggers a deploy of every app in the cluster, so the server comes up running current code.

An unrecognized role returns 422 and nothing is queued:

{ "error": "Unknown roles: databse. Assignable roles are app, cron, elasticsearch, load_balancer, memcached, mysql, postgresql, redis, web, worker" }

Destructive changes. Removing a database engine role uninstalls that engine from the machine and destroys the database clusters running on it. Dropping the last app code role also destroys the server's SQLite database clusters — so removing cron alone can take data with it even though cron itself is harmless.

When a request would do either, it's refused with 409 and a description of what would be lost:

{
  "error": "This change destroys data. Resend with confirm_destructive: true to proceed.",
  "destructive_changes": {
    "roles": ["postgresql"],
    "database_clusters": [
      { "id": 8, "name": "my-database-cluster", "engine": "postgresql" }
    ]
  }
}

Resend the identical request with "confirm_destructive": true at the top level of the body to proceed:

curl -X PATCH https://hatchbox.io/api/v1/clusters/[CLUSTER_ID]/servers/[SERVER_ID]/roles \
  -H "Authorization: Bearer [TOKEN]" \
  -H "Content-Type: application/json" \
  -d '{"server": {"roles": ["web"]}, "confirm_destructive": true}'

An engine removal is treated as destructive even when no database clusters are on it, because the engine is still uninstalled from the machine.

If the server is still being created, or is in the middle of provisioning, the response is 409:

{ "error": "Server is currently being created" }

{ "error": "Server is currently being provisioned" }

These are checked before the destructive-change prompt, so a destructive request against a server in either state reports the state rather than the confirmation.

If the server has no address to connect to, the response is 422:

{ "error": "Server has no IP address to connect to" }

Provision a server

Re-runs provisioning on a server that already exists: applies configuration updates, reinstalls the dependencies its roles require, and brings it in line with the current Hatchbox setup. This is the Update button on a server's page in the dashboard.

POST /api/v1/clusters/[CLUSTER_ID]/servers/[SERVER_ID]/provision

curl -X POST https://hatchbox.io/api/v1/clusters/[CLUSTER_ID]/servers/[SERVER_ID]/provision \
  -H "Authorization: Bearer [TOKEN]"

{ "id": 4310 }

The returned id is the log for the run. Provisioning is queued and takes several minutes, so a successful response means the work was accepted, not that it finished — fetch the log to follow along.

Processes may restart while updates are applied, which can cause brief downtime. Prefer running this during low-traffic periods.

If the server is still being created, the response is 409:

{ "error": "Server is currently being created" }

If provisioning is already running for the server, the response is 409:

{ "error": "Provisioning is already running for this server" }

If the server record exists but hasn't been created at your cloud provider yet, the response is 422:

{ "error": "This server has not been created on its cloud provider yet" }

This endpoint only re-provisions servers that already exist. Creating the underlying machine at your provider isn't available through the API — do that from the dashboard first.

Reboot a server

Restarts the machine. Your apps are unavailable until it comes back up.

POST /api/v1/clusters/[CLUSTER_ID]/servers/[SERVER_ID]/reboot

curl -X POST https://hatchbox.io/api/v1/clusters/[CLUSTER_ID]/servers/[SERVER_ID]/reboot \
  -H "Authorization: Bearer [TOKEN]"

{ "id": 4311 }

The returned id is the log for the reboot.

If the server is still being created, or is in the middle of provisioning, the response is 409:

{ "error": "Server is currently being created" }

{ "error": "Server is currently being provisioned" }

Rebooting during provisioning is refused because interrupting a package install can leave the server needing manual repair. Wait for the provisioning log to finish, then retry.

If the server has no address to connect to, the response is 422:

{ "error": "Server has no IP address to connect to" }

The firewall rule object

Firewall rules control which traffic reaches a server. Each one is a single ufw rule: an action, a port, and optionally an address the rule applies to.

Hatchbox adds rules of its own while provisioning — SSH on every server, ports 80 and 443 on web and load balancer servers, and the database engine ports for the private IPs of app servers in the same cluster. Those are marked "removable": false.

{
  "id": 91,
  "server_id": 34,
  "port": 5432,
  "action": "allow",
  "from": "10.0.0.5",
  "description": "App server",
  "removable": true,
  "created_at": "2026-08-27T15:02:11.000Z",
  "updated_at": "2026-08-27T15:02:11.000Z"
}

List firewall rules

Returns every firewall rule on a server, lowest port first.

Paginated — see Pagination.

GET /api/v1/clusters/[CLUSTER_ID]/servers/[SERVER_ID]/firewall_rules

curl https://hatchbox.io/api/v1/clusters/[CLUSTER_ID]/servers/[SERVER_ID]/firewall_rules \
  -H "Authorization: Bearer [TOKEN]"

Returns an array of firewall rule objects.

Get a firewall rule

GET /api/v1/clusters/[CLUSTER_ID]/servers/[SERVER_ID]/firewall_rules/[RULE_ID]

curl https://hatchbox.io/api/v1/clusters/[CLUSTER_ID]/servers/[SERVER_ID]/firewall_rules/[RULE_ID] \
  -H "Authorization: Bearer [TOKEN]"

Returns a single firewall rule object. A rule that belongs to a different server returns 404 {"error": "Firewall rule not found"}.

Add a firewall rule

POST /api/v1/clusters/[CLUSTER_ID]/servers/[SERVER_ID]/firewall_rules

curl -X POST https://hatchbox.io/api/v1/clusters/[CLUSTER_ID]/servers/[SERVER_ID]/firewall_rules \
  -H "Authorization: Bearer [TOKEN]" \
  -H "Content-Type: application/json" \
  -d '{"firewall_rule": {"port": 9000, "action": "allow", "from": "203.0.113.0/24", "description": "Metrics scraper"}}'

Returns 201 Created with the rule and the log for applying it:

{
  "id": 92,
  "server_id": 34,
  "port": 9000,
  "action": "allow",
  "from": "203.0.113.0/24",
  "description": "Metrics scraper",
  "removable": true,
  "created_at": "2026-08-28T10:41:03.000Z",
  "updated_at": "2026-08-28T10:41:03.000Z",
  "log_id": 4412
}

The rule is saved immediately, but it only reaches the server's firewall when the queued operation runs. Fetch log_id to confirm it was applied.

You can add rules to a server that hasn't been created at your provider yet. They're recorded now and applied the next time the server is provisioned.

A rule duplicating one that already exists — same port, action, and from — returns 422:

{ "errors": ["Port has already been taken"] }

Other validation failures return 422 the same way, listing what was wrong:

{ "errors": ["From must be an IP address or range"] }

Remove a firewall rule

DELETE /api/v1/clusters/[CLUSTER_ID]/servers/[SERVER_ID]/firewall_rules/[RULE_ID]

curl -X DELETE https://hatchbox.io/api/v1/clusters/[CLUSTER_ID]/servers/[SERVER_ID]/firewall_rules/[RULE_ID] \
  -H "Authorization: Bearer [TOKEN]"

Returns 202 Accepted:

{ "id": 4413 }

The returned id is the log for the removal. The rule is deleted only after ufw accepts the change on the server, so it keeps appearing in List firewall rules until that finishes. A 202 means the removal was queued, not that it's done — fetch the log to be sure, and treat a failed log as a rule that's still in force.

Rules Hatchbox manages itself can't be removed. Those return 422:

{ "error": "This firewall rule is managed by Hatchbox and cannot be removed" }

If the server has no address to connect to, the removal can't reach ufw and the response is 422:

{ "error": "Server has no IP address to connect to" }

Git providers

Git providers are the connected git accounts (GitHub, GitLab, Bitbucket) for one of your accounts. Use one's id as connected_account_id when creating an app.

List git providers

Lists the git providers for a single account.

GET /api/v1/accounts/[ACCOUNT_ID]/git_providers

curl https://hatchbox.io/api/v1/accounts/[ACCOUNT_ID]/git_providers \
  -H "Authorization: Bearer [TOKEN]"

[
  { "id": 5, "provider": "github", "name": "my-org" }
]

An account you're not a member of returns 404 {"error": "Account not found"}.

Database clusters

A database cluster is the database server your individual databases live on — either one Hatchbox installed on your own server (unmanaged) or one hosted by your provider (managed).

List database clusters

Returns the database clusters for a single account, sorted by name.

GET /api/v1/accounts/[ACCOUNT_ID]/database_clusters

curl https://hatchbox.io/api/v1/accounts/[ACCOUNT_ID]/database_clusters \
  -H "Authorization: Bearer [TOKEN]"

[
  {
    "id": 8,
    "name": "my-database-cluster",
    "engine": "postgresql",
    "version": "17",
    "region": "nyc3",
    "managed": true,
    "active": true,
    "databases_count": 3
  }
]

Databases

A database lives on a database cluster and can be attached to any number of apps.

These responses contain live credentials. Every database on a networked engine includes its username, password, and fully-formed connection URIs. Treat them the way you'd treat any other secret — don't log them, and don't cache them anywhere you wouldn't cache a password.

The database object

{
  "id": 42,
  "name": "my_app_production",
  "engine": "postgresql",
  "database_cluster_id": 8,
  "username": "my_app",
  "password": "sup3rs3cret",
  "private_connection_uri": "postgresql://my_app:sup3rs3cret@10.0.0.5:5432/my_app_production",
  "public_connection_uri": "postgresql://my_app:sup3rs3cret@203.0.113.10:5432/my_app_production",
  "app_attachments": [
    { "app_id": 1, "env_var": "DATABASE_URL" },
    { "app_id": 4, "env_var": "RED_DATABASE_URL" }
  ]
}

SQLite databases

A SQLite database is a file on one of your servers rather than a networked service, so its object is shaped differently — path instead of credentials and connection URIs:

{
  "id": 51,
  "name": "my-app-production",
  "engine": "sqlite",
  "database_cluster_id": 12,
  "path": "/home/deploy/my-app-production.sqlite3",
  "app_attachments": [
    { "app_id": 1, "env_var": "DATABASE_PATH" }
  ]
}

Everything else works the same way: they're listed and read through the same endpoints, attached and detached the same way, and backed up the same way. The differences worth knowing:

• path is required when you create one. Both name and path can be changed afterwards — SQLite databases are the only ones the API lets you update at all.
• Attaching one sets DATABASE_PATH to the file path instead of a connection URI.
• There's nothing to provision, so a new SQLite database is usable immediately rather than after a background job.

List databases

Returns every database on a database cluster, sorted by name — attached to an app or not.

GET /api/v1/database_clusters/[DATABASE_CLUSTER_ID]/databases

curl https://hatchbox.io/api/v1/database_clusters/[DATABASE_CLUSTER_ID]/databases \
  -H "Authorization: Bearer [TOKEN]"

Returns an array of database objects. A cluster on an account you're not a member of returns 404 {"error": "Database cluster not found"}.

Get a database

GET /api/v1/database_clusters/[DATABASE_CLUSTER_ID]/databases/[DATABASE_ID]

curl https://hatchbox.io/api/v1/database_clusters/[DATABASE_CLUSTER_ID]/databases/[DATABASE_ID] \
  -H "Authorization: Bearer [TOKEN]"

Returns a single database object. A database that exists but lives on a different cluster returns 404 {"error": "Database not found"} — the ID has to match the cluster in the path.

Create a database

Creates a database on a cluster. Creating and attaching are separate steps: a new database isn't connected to any app until you attach it.

POST /api/v1/database_clusters/[DATABASE_CLUSTER_ID]/databases

curl -X POST https://hatchbox.io/api/v1/database_clusters/[DATABASE_CLUSTER_ID]/databases \
  -H "Authorization: Bearer [TOKEN]" \
  -H "Content-Type: application/json" \
  -d '{"database": {"name": "my_app_production"}}'

The body is optional — curl -X POST ... -H "Authorization: Bearer [TOKEN]" on its own creates a database with a generated name, username, and password. On a SQLite cluster the body is required, since path has no default.

Returns 201 Created with the database object, including its credentials and connection URIs. The database is created on your server in the background, so it may take a moment before it accepts connections. SQLite databases are the exception — nothing is provisioned, so they're ready as soon as the call returns.

A cluster on an account you're not a member of returns 404 {"error": "Database cluster not found"}. A managed cluster that's still provisioning returns 422 {"error": "Database cluster is not active yet"} — wait until the cluster reports "active": true. Validation failures return 422 with errors, including a missing or relative path on a SQLite cluster.

Update a database

SQLite databases only. Every other engine returns 422 {"error": "Only SQLite databases can be updated"} — their names and credentials are fixed once created.

PATCH /api/v1/database_clusters/[DATABASE_CLUSTER_ID]/databases/[DATABASE_ID]

curl -X PATCH https://hatchbox.io/api/v1/database_clusters/[DATABASE_CLUSTER_ID]/databases/[DATABASE_ID] \
  -H "Authorization: Bearer [TOKEN]" \
  -H "Content-Type: application/json" \
  -d '{"database": {"path": "/home/deploy/moved.sqlite3"}}'

Returns 200 OK with the updated database object.

Changing path rewrites the environment variable on every app the database is attached to, and writes it out to the servers of any app that has deployed before — so attached apps follow the file rather than breaking. If the database has backups enabled, its backup configuration is rewritten on the server too.

Note that this changes where Hatchbox looks for the file; it doesn't move the file for you. Move it on the server yourself, or point the path at a file that already exists.

Validation failures return 422 with errors — a path has to be absolute and can't be blank.

List an app's databases

Returns the databases currently attached to an app, sorted by name. This is the app-side view of the same objects: the cluster endpoints above list everything on a cluster whether or not it's attached to anything, while these two are limited to what the app can actually reach.

GET /api/v1/apps/[APP_ID]/databases

curl https://hatchbox.io/api/v1/apps/[APP_ID]/databases \
  -H "Authorization: Bearer [TOKEN]"

Returns an array of database objects — the same shape as the database object. An app you can't access returns 404 {"error": "App not found"}.

Get an app's database

GET /api/v1/apps/[APP_ID]/databases/[DATABASE_ID]

curl https://hatchbox.io/api/v1/apps/[APP_ID]/databases/[DATABASE_ID] \
  -H "Authorization: Bearer [TOKEN]"

Returns a single database object. A database that isn't attached to this app returns 404 {"error": "Database not found"}, even when you can read that same database through its cluster — this endpoint answers "is this database attached to this app," so an unattached one is indistinguishable from one that doesn't exist.

Attach a database to an app

Attaching a database sets an environment variable on the app holding the connection URI. The app picks up the new variable on its next deploy; if it has deployed before, Hatchbox also writes the variable to your servers right away.

POST /api/v1/apps/[APP_ID]/databases/[DATABASE_ID]/attachment

The database has to belong to the same account as the app, but it does not have to be on the same cluster.

curl -X POST https://hatchbox.io/api/v1/apps/[APP_ID]/databases/[DATABASE_ID]/attachment \
  -H "Authorization: Bearer [TOKEN]" \
  -H "Content-Type: application/json" \
  -d '{"env_var": "REPORTING_DATABASE_URL"}'

Returns 201 Created with the database object. Read app_attachments in the response to learn the variable you actually got — the two names behave differently when one is already in use:

• Without **env\_var**, a default name that's taken gets a colour prefix instead of failing, so a second DATABASE_URL becomes RED_DATABASE_URL, then BLUE_DATABASE_URL. This is what lets an app hold connections to several databases at once.
• With **env\_var**, a name that's already taken on the app returns 422 {"errors": ["Name has already been taken"]}. A name you asked for is never silently changed.

Names must match [A-Z_][A-Z0-9_]*; anything else returns 422 with errors. A database on another account returns 404 {"error": "Database not found"}, and an app you can't access returns 404 {"error": "App not found"}.

Detach a database from an app

Removes the environment variable (or variables) connecting the database to the app, and updates the app's servers. The database itself is untouched and stays on its cluster.

DELETE /api/v1/apps/[APP_ID]/databases/[DATABASE_ID]/attachment

curl -X DELETE https://hatchbox.io/api/v1/apps/[APP_ID]/databases/[DATABASE_ID]/attachment \
  -H "Authorization: Bearer [TOKEN]"

Returns 200 OK. If the database is attached to the app more than once — say as both DATABASE_URL and REPORTING_DATABASE_URL — this removes every one of those attachments. Detaching a database that isn't attached also returns 200 OK, so the call is safe to repeat.

The backup endpoints below are addressed by database ID alone, without the cluster.

The backup configuration object

Backups are configured per database. Managed databases are backed up by your hosting provider, so these endpoints only apply to unmanaged databases running on your own servers.

{
  "database_id": 88,
  "backup_enabled": true,
  "backup_provider": "s3",
  "backup_region": "us-east-1",
  "backup_bucket": "my-backups",
  "backup_endpoint": null,
  "backup_frequency": "@daily",
  "backup_retention_period": "7d",
  "backup_credentials_set": true,
  "appsignal": false,
  "honeybadger_checkin_id": null,
  "last_backup_at": "2026-08-11T03:00:00.000Z"
}

Get the backup configuration

GET /api/v1/databases/[DATABASE_ID]/backup_configuration

curl https://hatchbox.io/api/v1/databases/[DATABASE_ID]/backup_configuration \
  -H "Authorization: Bearer [TOKEN]"

Returns a backup configuration object. A database that has never had backups set up returns the object with backup_enabled: false and empty fields.

A managed database returns 422 {"error": "Managed databases should be backed up on your hosting provider"}.

Enable or update backups

Sets the backup configuration and enables backups in one call. Only the fields you send are changed, so you can adjust a single setting without resending the rest — but every request enables backups, so a partial payload against a database that was never configured fails validation and tells you what's missing.

PATCH /api/v1/databases/[DATABASE_ID]/backup_configuration

curl -X PATCH https://hatchbox.io/api/v1/databases/[DATABASE_ID]/backup_configuration \
  -H "Authorization: Bearer [TOKEN]" \
  -H "Content-Type: application/json" \
  -d '{
    "backup_configuration": {
      "backup_provider": "s3",
      "backup_region": "us-east-1",
      "backup_bucket": "my-backups",
      "backup_access_key_id": "[ACCESS_KEY_ID]",
      "backup_secret_access_key": "[SECRET_ACCESS_KEY]",
      "backup_frequency": "@daily",
      "backup_retention_period": "7d"
    }
  }'

{
  "database_id": 88,
  "backup_enabled": true,
  "backup_provider": "s3",
  "...": "...",
  "log_id": 4288
}

Applying the configuration is queued, so a successful response means it was accepted — fetch the log to confirm the schedule actually landed on the server.

Changing a single setting works the same way:

curl -X PATCH https://hatchbox.io/api/v1/databases/[DATABASE_ID]/backup_configuration \
  -H "Authorization: Bearer [TOKEN]" \
  -H "Content-Type: application/json" \
  -d '{"backup_configuration": {"backup_frequency": "@hourly"}}'

Invalid settings return 422 with the problems listed:

{ "errors": ["Backup bucket can't be blank", "Backup region can't be blank"] }

An unrecognized provider returns 422:

{ "error": "Unknown backup provider: dropbox. Valid providers are local, s3, azureblob, r2, spaces, gcs, wasabi, other" }

Disable backups

Turns backups off and clears the stored provider settings and credentials. The retention period and monitoring settings are kept.

DELETE /api/v1/databases/[DATABASE_ID]/backup_configuration

curl -X DELETE https://hatchbox.io/api/v1/databases/[DATABASE_ID]/backup_configuration \
  -H "Authorization: Bearer [TOKEN]"

Returns 202 with the cleared configuration and a log_id for removing the schedule from the server. If backups were already disabled, returns 200 with the configuration and no log_id — disabling twice is not an error.

Test the backup connection

Uploads a small test file to your configured bucket so you can verify credentials without waiting for a real backup to run.

POST /api/v1/databases/[DATABASE_ID]/backups/test_connection

curl -X POST https://hatchbox.io/api/v1/databases/[DATABASE_ID]/backups/test_connection \
  -H "Authorization: Bearer [TOKEN]"

{ "id": 4289 }

The returned id is the log for the test. The log records whether the upload succeeded, so fetch it to see the result.

Backups have to be enabled and stored remotely. A local provider returns 422:

{ "error": "Local backups have no remote connection to test" }

Trigger a backup

Queues a new backup of the database.

POST /api/v1/databases/[DATABASE_ID]/backups

curl -X POST https://hatchbox.io/api/v1/databases/[DATABASE_ID]/backups \
  -H "Authorization: Bearer [TOKEN]"

{ "id": 4214 }

The returned id is the log for this backup. Backups are queued, so a successful response means it was accepted, not that it finished — fetch the log to find out whether it did.

If a backup is already running for this database, the response is 409:

{ "error": "A backup is already running for this database" }

If backups aren't enabled, or the database is managed, the response is 422:

{ "error": "Backups are not enabled for this database" }

{ "error": "Managed databases should be backed up on your hosting provider" }

Download the latest backup

Returns a temporary, presigned URL to the most recent backup. Fetch the URL to download the backup directly from your storage provider; it expires a few minutes after it's issued.

GET /api/v1/databases/[DATABASE_ID]/backups/latest

curl https://hatchbox.io/api/v1/databases/[DATABASE_ID]/backups/latest \
  -H "Authorization: Bearer [TOKEN]"

{
  "url": "https://your-bucket.s3.amazonaws.com/...",
  "last_backup_at": "2026-07-16T03:00:00.000Z"
}

Download it with the returned URL: curl -o backup.tar.gz "[URL]".

Along with the two 422 messages above, this endpoint returns 422 when there's nothing to download yet, or when the backup lives somewhere we can't generate a link for:

{ "error": "No backup has completed for this database yet" }

{ "error": "Downloading backups is only supported for S3 and S3-compatible providers" }

If the backup can't be reached at your storage provider (for example, expired credentials), the response is 502:

{ "error": "Could not generate a download URL from your backup provider" }

Logs

Every queued operation writes a log. Deploy an app, Restart an app, Delete an app, Restart a process, Delete a process, Provision a server, Reboot a server, Trigger a backup, and Test the backup connection each return the id of the log they created as id. Create a process, Update a process, Enable a process, Disable a process, Enable or update backups, and Disable backups return theirs as log_id alongside the resource. Update server roles returns a logs array, because a single request can queue both an addition and a removal.

Either way, the log is how you find out whether the work actually succeeded — those endpoints return as soon as the job is accepted, long before it finishes.

Operations started outside the API — an auto-deploy from a git push, or a deploy someone ran from the dashboard — write logs too. Nothing hands you those ids, so use List an app's logs to find them.

The log object

{
  "id": 4212,
  "name": "Apps::Deploy",
  "description": "Add the logs endpoint",
  "state": "completed",
  "parent_id": null,
  "loggable_type": "App",
  "loggable_id": 91,
  "commit_sha": "0d1e2f3a4b5c6d7e8f90a1b2c3d4e5f6a7b8c9d0",
  "username": "Jane Doe",
  "body": "-----> Starting deployment\n-----> Deploying 0d1e2f3 from main branch\n",
  "created_at": "2026-08-04T20:31:45.000Z",
  "started_at": "2026-08-04T20:31:46.000Z",
  "completed_at": "2026-08-04T20:33:02.000Z",
  "child_logs": []
}

Where the output lives

An operation that touches several servers opens one SSH connection per server and writes that server's output to its own child log. The parent's body holds only the high-level narrative:

-----> Starting deployment
-----> Deploying 0d1e2f3 from main branch as 20260804203145 release
-----> Building on web-1

The actual command output — git, bundle install, asset compilation, and the error when a deploy fails — is in child_logs. If you're reporting why something failed, read the children, not the parent.

Backups are the exception: they run against a single server and write everything to the parent, so child_logs comes back empty.

Each child is a complete log object. Its loggable_type is Server, naming the machine the output came from, and its id works at GET /api/v1/logs/[LOG_ID] if you'd rather fetch one on its own. Logs nest exactly one level, so children carry no child_logs of their own.

Because the children come back with their bodies, a deploy across several servers can be a large response.

Get a log

GET /api/v1/logs/[LOG_ID]

curl https://hatchbox.io/api/v1/logs/[LOG_ID] \
  -H "Authorization: Bearer [TOKEN]"

Returns a single log object with its children embedded.

You can read any log on an account you belong to, including operations a teammate started and auto-deploys triggered by a push. A log on an account you're not a member of returns 404 {"error": "Log not found"}.

Logs belong to the resource that produced them, so a log is removed when that resource is. This matters for Delete an app — see the note there.

List an app's logs

Returns the operations run against an app — deploys, restarts, process changes — newest first. This is how you find a log you weren't handed the id for, such as an auto-deploy triggered by a git push.

GET /api/v1/apps/[APP_ID]/logs

curl https://hatchbox.io/api/v1/apps/[APP_ID]/logs \
  -H "Authorization: Bearer [TOKEN]"

[
  {
    "id": 4212,
    "name": "Apps::Deploy",
    "description": "Fix the retry backoff",
    "state": "failed",
    "parent_id": null,
    "loggable_type": "App",
    "loggable_id": 91,
    "commit_sha": "1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d",
    "username": "octocat",
    "created_at": "2026-08-26T17:41:02.000Z",
    "started_at": "2026-08-26T17:41:03.000Z",
    "completed_at": "2026-08-26T17:42:19.000Z"
  }
]

Paginated — see Pagination. Defaults to the 20 most recent.

Two differences from Get a log:

• No **body**. Listing them would mean returning every deploy's output at once. Fetch a log by id to read it.
• No **child\_logs**. Only the app's own operations are listed, never the per-server children. Their loggable_type is always App and their parent_id always null.

So the usual flow for a failed push-triggered deploy is two requests — list to find the id, then Get a log to read the children that explain the failure:

LOG_ID=$(curl -s https://hatchbox.io/api/v1/apps/[APP_ID]/logs \
  -H "Authorization: Bearer $TOKEN" \
  | jq -r '[.[] | select(.name == "Apps::Deploy" and .state == "failed")][0].id')

curl -s https://hatchbox.io/api/v1/logs/$LOG_ID \
  -H "Authorization: Bearer $TOKEN" | jq -r '.child_logs[].body'

Waiting for an operation to finish

Poll the log until state leaves pending/processing:

LOG_ID=$(curl -sX POST https://hatchbox.io/api/v1/apps/[APP_ID]/deploy \
  -H "Authorization: Bearer $TOKEN" | jq -r .id)

while :; do
  LOG=$(curl -s https://hatchbox.io/api/v1/logs/$LOG_ID -H "Authorization: Bearer $TOKEN")
  STATE=$(echo "$LOG" | jq -r .state)
  case $STATE in
    completed) echo "Deployed."; break ;;
    failed|aborted) echo "$LOG" | jq -r '.child_logs[].body'; exit 1 ;;
    *) sleep 5 ;;
  esac
done