> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squasher.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Deployments API

> List and create deployment records for release correlation.

Use the Deployments API when a provider or CI/CD pipeline needs to record a deploy that Squasher can correlate with service releases.

Connected Vercel, Railway, and GitHub providers create deployment records automatically when their webhooks arrive. Use the API fallback for other CI/CD systems.

## Operations

| Operation            | Method and path                              | Purpose                                                   |
| -------------------- | -------------------------------------------- | --------------------------------------------------------- |
| `deployments.list`   | `GET /v1/projects/{project_id}/deployments`  | List deployment records with provider or release filters. |
| `deployments.create` | `POST /v1/projects/{project_id}/deployments` | Create or update a deployment record idempotently.        |

`deployments.list` requires `deployments:read`. `deployments.create` requires `deployments:write`, so CI/CD keys can record deploys without broad project mutation access.

## Generic CI/CD webhook

```bash theme={null}
curl -X POST "https://api.squasher.ai/v1/projects/$SQUASHER_PROJECT_ID/deployments" \
  -H "x-squasher-key: $SQUASHER_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "provider": "buildkite",
    "deployment_id": "build-123",
    "service": "api",
    "version": "1.2.3",
    "environment": "production",
    "status": "ready",
    "url": "https://ci.example.com/builds/123",
    "commit_sha": "abc123",
    "branch": "main",
    "finished_at": "2026-05-07T05:00:00.000Z"
  }'
```

Use the same `service` and `version` values your SDK sends as `service.name` and `service.version`. Re-sending the same `provider` + `deployment_id` updates the existing record instead of creating a duplicate.

Related: [Provider capabilities](/api-reference/provider-capabilities), [GitHub integration](/integrations/github), [Vercel integration](/integrations/vercel), [Railway integration](/integrations/railway).