Deployments API

Send one HTTP request from your pipeline and Unhandled records a deployment: who shipped which version of which service, when it started, and how it ended. Charts across the app then show a marker at that moment, so a latency jump or a new issue lines up with the release that caused it.

The unhandled deploy command calls this endpoint for you and fills most fields from your CI environment. It needs Node 24 or later. Call the API yourself from other runtimes, or when you want to control every field. Deployments explains how declared deployments relate to the ones Unhandled detects from telemetry.

Authentication

Every request carries a deploy key in the x-api-key header. An admin creates deploy keys for a project under Settings > Deploy keys. A key starts with dk_, appears once when you create it, and can be revoked from the same page. The key decides the project, so the URL never names one.

Declare a deployment

curl -X POST "https://unhandled.net/api/v1/deployments" \
  -H "content-type: application/json" \
  -H "x-api-key: $UNHANDLED_API_KEY" \
  -d '{
    "service": "shop-api",
    "environment": "production",
    "version": "2026.10.21-1",
    "commitSha": "3f9c2a7e5b1d4c8f0a6e2d9b7c4a1f3e5d8b0c2a",
    "status": "started",
    "externalId": "release-4812",
    "actor": "release-bot",
    "ciUrl": "https://ci.example.com/pipelines/4812",
    "repositoryUrl": "https://github.com/example/shop",
    "metadata": { "region": "eu-west", "ordersMigration": true }
  }'

const response = await fetch('https://unhandled.net/api/v1/deployments', {
  method: 'POST',
  headers: {
    'content-type': 'application/json',
    'x-api-key': process.env.UNHANDLED_API_KEY,
  },
  body: JSON.stringify({
    service: 'shop-api',
    environment: 'production',
    version: '2026.10.21-1',
    commitSha: '3f9c2a7e5b1d4c8f0a6e2d9b7c4a1f3e5d8b0c2a',
    status: 'started',
    externalId: 'release-4812',
    actor: 'release-bot',
    ciUrl: 'https://ci.example.com/pipelines/4812',
    repositoryUrl: 'https://github.com/example/shop',
    metadata: { region: 'eu-west', ordersMigration: true },
  }),
})

if (!response.ok) throw new Error(`unhandled answered ${response.status}`)
const deployment = await response.json()

import json
import os
import urllib.request

payload = {
    "service": "shop-api",
    "environment": "production",
    "version": "2026.10.21-1",
    "commitSha": "3f9c2a7e5b1d4c8f0a6e2d9b7c4a1f3e5d8b0c2a",
    "status": "started",
    "externalId": "release-4812",
    "actor": "release-bot",
    "ciUrl": "https://ci.example.com/pipelines/4812",
    "repositoryUrl": "https://github.com/example/shop",
    "metadata": {"region": "eu-west", "ordersMigration": True},
}

request = urllib.request.Request(
    "https://unhandled.net/api/v1/deployments",
    data=json.dumps(payload).encode(),
    headers={
        "content-type": "application/json",
        "x-api-key": os.environ["UNHANDLED_API_KEY"],
    },
    method="POST",
)

with urllib.request.urlopen(request) as response:
    deployment = json.load(response)

{
  "id": "0b4f7d3e-2c1a-4e8b-9a6f-5d2c7e1b3a90",
  "source": "api",
  "status": "started",
  "merged": false,
  "url": "https://unhandled.example.com/o/acme/projects/shop/deployments/0b4f7d3e-2c1a-4e8b-9a6f-5d2c7e1b3a90"
}

{
  "message": "Deployment is already succeeded and cannot become started"
}

{
  "message": "Unknown environment \"prod\"",
  "environments": ["production", "staging", "development"]
}

Report a rollout in two calls

A request without externalId always creates a new deployment. With one, Unhandled first looks for a deployment in the project with the same externalId and updates it. That lets a pipeline open the deployment before the rollout and close it afterwards.

On an update:

• Fields you leave out keep their previous values.
• startedAt keeps the value from the first request. A later value is ignored.
• finishedAt is set when the deployment reaches succeeded, failed or canceled, unless you send it.

Allowed status changes

Any other change, such as succeeded back to started, returns 409. Reusing an externalId that belongs to a deployment of another service or environment also returns 409.

Merging with detected deployments

Unhandled also detects deployments when a service starts reporting a new version in its spans. A declaration joins a detected deployment of the same service and environment when both hold:

• The detected version was first seen within 60 minutes of startedAt, before or after.
• The version matches, or the commitSha matches.

A declaration that only carries a commit therefore links to the release whose spans reported that commit in vcs.ref.head.revision. A merged declaration returns 201 with "merged": true.

Status codes

A validation failure returns an errors array whose entries carry a field and a message. An unknown environment returns a message and an environments array with the valid values. Every other error returns a message.

Rate limit

Each deploy key can send 60 requests per minute. The 61st request in that minute returns 429 with a retry-after header in seconds. The budget belongs to the key, so pipelines with separate keys never slow each other down.

Chart markers

Deployments with status failed or canceled stay in the history but get no marker on charts.

FAQ

Related