API

The deploydiff API reads a project's environments, capture batches, diff batches, their tasks and its notifications as JSON, and starts capture and diff batches. It answers with the same data the dashboard shows.

The API comes with the paid plans. Each successful call is billed.

API keys

A key belongs to one project. An organization Owner or Admin creates it from the project's API page in the dashboard, which also shows the project id. The key's secret is shown once, when it is created: store it where your tool keeps its secrets.

A key holds a project role, and has that role's rights on its project:

A key never has an organization role: it cannot change settings, members or keys, nor delete anything. A project has at most 25 active keys. Revoking a key takes effect on its next call. See Roles & Permissions.

Authentication

Send the key in the Authorization header of every call:

curl https://deploydiff.com/api/v1/projects/{project_id}/environments \
  -H "Authorization: Bearer dd_…"

The API reads the key from this header only — never from a cookie or the address.

Addresses

Every endpoint is under one project:

https://deploydiff.com/api/v1/projects/{project_id}/…

• Ids are UUIDs.
• An address takes no trailing slash: one with a slash is redirected to the address without it.
• Every GET endpoint also answers HEAD, with the same status and headers and no body.

To see the API at work, follow Capture after a deploy.

Responses

Bodies are JSON. Every object says what it is in an object field ("environment", "capture_batch", …), carries its id, and ends with created_at and updated_at. Dates are ISO 8601 timestamps with their offset. A field with no value is present and null, never left out.

The page of each object in the dashboard shows its JSON, the same as the API returns.

Lists

A list answers one page at a time, newest first:

{
  "object": "list",
  "data": [
    {
      "object": "capture_batch",
      "id": "00000000-0000-0000-0000-000000000002"
    }
  ],
  "next_cursor": "WyIyMDI2LTExLTA2VDEwOjAwOjAwLjMxKzAwOjAwIiwiYTEuLi4iXQ"
}

next_cursor is null on the last page. A cursor does not expire: keep one to read on later from where you stopped. Send it back exactly as you received it: its format is ours and may change.

Errors

An error answers with its HTTP status and a body naming it:

{
  "error": {
    "code": "capture_interval",
    "message": "The organization's plan allows one capture on demand every minute per environment, clicks and calls together.",
    "retry_after": 42
  }
}

code is stable: test it, not the message, which is written for people. Some errors add a field beside them, listed below.

After a 500 or a 504 on a POST, the batch may have been created all the same. Read the environment's latest batches (?limit=1) before sending the call again. A GET can simply be sent again.

Limits

• Captures on demand. An environment takes one capture on demand per interval set by the organization's plan — one a minute on the paid plans — the dashboard's and the API's together. One that comes too soon is answered 429 capture_interval, with the seconds to wait in retry_after and in the Retry-After header. Diff batches have no such interval.
• Request rate. One IP address sends at most 120 requests a minute. Beyond, calls are answered 429 in plain text, without the JSON body or a Retry-After header: wait for the next minute.
• Time. A read answers within 7 seconds, a start within 15, or 504 timeout.
• Body size. A POST body is at most 16 KB.

Billing

Each successful call — a 2xx answer, HEAD included — is billed at the rate on the pricing page, drawn from your plan's included usage like the rest. A call that is refused or fails is not billed. The captures and diffs an API call starts are billed like any others.

Your organization's usage page shows the calls, hour by hour, under API Call.