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

# Deployments

> Trigger, monitor, and manage application deployments

Deployments represent the process of shipping an entity version to production infrastructure. Each deployment goes through multiple phases and streams real-time logs.

## Trigger deployment

```bash theme={null}
POST /api/deploy
```

| Parameter         | Type | Required | Description                                             |
| ----------------- | ---- | -------- | ------------------------------------------------------- |
| `productionAppId` | body | Yes      | Production app to deploy to                             |
| `versionId`       | body | No       | Specific version to deploy (defaults to active version) |

Creates a new deployment record and triggers the deployment pipeline.

**Authentication:** Organization member + `entities:deploy` scope + entity publisher.

## List deployments

```bash theme={null}
GET /api/deploys
```

| Parameter         | Type  | Description                  |
| ----------------- | ----- | ---------------------------- |
| `productionAppId` | query | Filter by production app     |
| `status`          | query | Filter by deployment status  |
| `page`            | query | Page number (default: 1)     |
| `pageSize`        | query | Items per page (default: 20) |

**Authentication:** User authentication required.

## Get deployment

```bash theme={null}
GET /api/deploys/{id}
```

Returns deployment details including status, phases, and logs.

**Authentication:** User authentication required.

## Cancel deployment

```bash theme={null}
POST /api/deploys/{id}/cancel
```

Cancels an in-progress deployment. The deployment pipeline receives the cancellation signal and stops processing.

**Authentication:** Organization member + `entities:deploy` scope + entity publisher.

## Deployment phases

Each deployment progresses through the following phases:

| Phase                | Description                        |
| -------------------- | ---------------------------------- |
| `orchestrate`        | Initial deployment orchestration   |
| `download`           | Download entity package            |
| `infra`              | Provision or update infrastructure |
| `build`              | Build the application              |
| `package`            | Package for deployment             |
| `migrate`            | Run database migrations            |
| `service_deploy`     | Deploy to compute infrastructure   |
| `cache_invalidation` | Invalidate CDN caches              |

Each phase has a status: `pending`, `in_progress`, `completed`, or `failed`. The platform streams real-time logs for each phase as the deployment progresses.

## Deployment lifecycle

```
pending → in_progress → completed
                      → failed
                      → cancelled
```

A deployment starts as `pending`, moves to `in_progress` when the pipeline begins processing, and ends as `completed`, `failed`, or `cancelled`.

Failed deployments include an error message. Cancelled deployments stop the pipeline at the current phase.