Deployment.sh

Deployment API for servers, sites and releases

Everything you can do in the Deployment panel you can do over HTTPS. The REST API uses JSON, scoped bearer tokens and predictable resource paths, so you can trigger deploys from CI, roll back from a chat command, sync environment variables from a secrets manager or build your own internal dashboard.

Developer at a dual monitor desk with a mechanical keyboard testing an API with request and response panes

Why a deployment API matters

A panel is great for the first server. By the tenth, teams want deploys triggered from pipelines, servers created from infrastructure scripts and alerts fed into their own tools. Without an API that means screen scraping or SSH scripts with broad keys. A proper deployment api gives each integration exactly the access it needs and nothing more.

Authentication with scoped tokens

Create tokens in the panel under API tokens. Each token has scopes per resource (read or write on servers, sites, deployments, environment, logs, webhooks) and can be limited to chosen sites. A CI token that can only create deployments on one site cannot read variables or delete servers. Send the token as a bearer header on every request.

  • Tokens are shown once at creation and stored hashed
  • Every request made with a token appears in the audit log on Team, Agency and Enterprise
  • Revoke a token instantly from the panel
bash 
curl https://deployment.sh/api/v1/servers \
  -H "Authorization: Bearer $DEPLOYMENT_TOKEN" \
  -H "Accept: application/json"

Resources

ResourcePathMain actions
Servers/api/v1/serversList, create in a cloud account, show status and metrics, delete
Sites/api/v1/sitesList, create, update repository and branch, delete
Deployments/api/v1/sites/{site}/deploymentsCreate, list history, show status and log
Releases/api/v1/sites/{site}/releasesList kept releases on the servers
Rollbacks/api/v1/sites/{site}/rollbacksRoll back to a kept release
Environment/api/v1/sites/{site}/environments/{env}/variablesList keys, set, delete, show diff
Logs/api/v1/sites/{site}/logsRead deploy, application and nginx logs
Webhooks/api/v1/webhooksCreate, list, test and delete outgoing webhooks

Trigger a deploy with curl

Create a deployment for a specific commit and wait for the result. With wait=true the request returns when the deploy succeeds or fails, which makes it easy to fail a CI job on a failed release.

bash 
curl -X POST "https://deployment.sh/api/v1/sites/site_8k2m/deployments?wait=true" \
  -H "Authorization: Bearer $DEPLOYMENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"environment": "production", "commit": "9f2c1e7"}'
json 
{
  "id": "dep_3vq91",
  "site": "site_8k2m",
  "environment": "production",
  "commit": "9f2c1e7",
  "status": "succeeded",
  "release": "20261019-142211",
  "duration_seconds": 48
}

Roll back with Python

A short script that rolls a site back to the release before the current one, handy for a chat command or an incident runbook.

python 
import os
import requests

API = "https://deployment.sh/api/v1"
headers = {"Authorization": f"Bearer {os.environ['DEPLOYMENT_TOKEN']}"}

releases = requests.get(f"{API}/sites/site_8k2m/releases", headers=headers, timeout=30).json()["data"]
previous = releases[1]["id"]

r = requests.post(f"{API}/sites/site_8k2m/rollbacks", headers=headers,
                  json={"release": previous, "reason": "error rate after deploy"}, timeout=30)
r.raise_for_status()
print(r.json()["status"])

Sync environment variables with Node.js

Push variables from your secrets manager before a deploy. The API returns the diff that the next deploy will apply.

javascript 
const API = "https://deployment.sh/api/v1";
const headers = {
  Authorization: `Bearer ${process.env.DEPLOYMENT_TOKEN}`,
  "Content-Type": "application/json",
};

const res = await fetch(`${API}/sites/site_8k2m/environments/production/variables`, {
  method: "PUT",
  headers,
  body: JSON.stringify({ variables: { QUEUE_CONNECTION: "redis", CACHE_TTL: "600" } }),
});
const { diff } = await res.json();
console.log(diff.added, diff.changed, diff.removed);
Developer sketching branch lines on a window with a grease pencil in a cramped loft workspace at night, laptop and bike in the background

Read logs and deploy history

Deploy logs are available for the retention of your plan, from 14 days on Starter to 2 years on Enterprise. Application and nginx logs are read live from your server and support a lines parameter and a since timestamp, so a script can tail recent errors without SSH access.

Outgoing webhooks

Register an HTTPS endpoint and choose events: deployment started, succeeded, failed and rolled back, server provisioned, health check failed, uptime down and recovered, backup completed and failed. Each request carries a timestamp and an HMAC SHA-256 signature header computed with your webhook secret, so your endpoint can reject forged calls. Failed deliveries are retried with backoff. The full event list is on cloud server management integrations.

Limits, errors and pagination

Rate limits are per token and returned in the response headers of every request, so clients can slow down before they hit them. Errors use standard HTTP status codes with a JSON body containing a code and a message. List endpoints are paginated with a cursor and a page size.

CLI built on the same API

The Deployment CLI wraps these endpoints for your terminal and CI jobs, with commands such as deployment deploy, deployment rollback, deployment env pull and deployment logs. It is how teams wire up continuous deployment software without writing HTTP calls, and it follows the same scopes as your token. Setup steps are in the deployment platform docs.

Which plan includes the API

The API, CLI and outgoing webhooks are in every plan. Starter is 49 USD a month or 24 USD billed yearly. Team is 199 USD a month or 99 USD yearly and adds the audit log of token activity. Agency is 499 USD a month or 249 USD yearly. Enterprise is 1 499 USD a month or 749 USD yearly with SSO. Compare plans on PaaS pricing.

See pricing

Is the API versioned?

Yes. All paths start with /api/v1, and breaking changes would ship under a new version while the current one keeps working.

Can a token be limited to one site?

Yes. Choose the sites when creating the token, and requests for any other site return 403.

Is there an SDK?

The CLI covers common tasks. For code, the API is plain JSON over HTTPS and works with any HTTP client, as the curl, Python and Node examples show.

Can I try Deployment before I pay?

Yes, with the free one-time demo on the home page. Plans start at 49 USD a month, or 24 USD a month billed yearly.

Build on the deployment api

Create an account, generate a scoped token and trigger your first deploy from a script.

Prefer to see the platform first? Try the demo.