# Deployments

Generated from contract version `1.0.0` — the same document [`/v1/api/openapi.json`](/api/openapi/) serves.

## Prerequisites

- An API key in `x-api-key`, or a browser session cookie
- `X-Organization-Id` naming the workspace to act in, unless the session already has an active one
- The base URL for your deployment, `https://server.hlix.ai` by default

## Operations

| Method | Path | Operation |
| --- | --- | --- |
| `GET` | `/v1/api/deployments` | [List deployments](#list-deployments) |
| `POST` | `/v1/api/deployments` | [Redeploy a project's preview, or deploy it to production](#redeploy-a-projects-preview-or-deploy-it-to-production) |
| `GET` | `/v1/api/deployments/{id}` | [Get one deployment](#get-one-deployment) |
| `POST` | `/v1/api/deployments/{id}/touch` | [Extend a preview's time to live](#extend-a-previews-time-to-live) |
| `PUT` | `/v1/api/deployments/custom-domain` | [Set the production deployment's custom domain](#set-the-production-deployments-custom-domain) |

## List deployments

`GET /v1/api/deployments` · operation ID `listDeployments`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `projectId` | query | no | string | Only this project's deployments. |
| `kind` | query | no | string | `project` (the canonical preview), `cycle-preview`, or `production`. An unrecognised value is IGNORED, not rejected — the list comes back unfiltered. |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |
| `X-Client-Portal` | header | no | string | Agency organization id for one aggregate client dashboard; server derives only this caller's workspace relationship and owned account seats. Legacy account ids remain narrowly compatible. Real verified user session required for agency context; administration denied. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | Deployment[] | Matching deployments, oldest first. |
| `400` | ApiError | The request named no active organization. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project. |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |

## Redeploy a project's preview, or deploy it to production

`POST /v1/api/deployments` · operation ID `redeployProjectPreview`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Request body** — `application/json`, `RedeployPreview` (required)

| Property | Type | Required | Notes |
| --- | --- | --- | --- |
| `kind` | `project` | `production` | no |  |
| `minInstances` | number | number | no |  |
| `projectId` | string | **yes** | min length 1 |
| `repoId` | string | no | min length 1 |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `202` | DeploymentAccepted | Handed to the pipeline. The row moves through `building` → `deploying` → `live` on its own; poll `GET /deployments/{id}`. |
| `400` | ValidationError \| ApiError | The JSON body failed validation — `projectId` is required — or the request named no active organization. Validation runs as middleware, so a malformed payload is answered 400 even when previews are switched off. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project. |
| `404` | ApiError | No such project, or no such repository on it. |
| `409` | DeploymentRepoAmbiguous | The project is archived, or it builds against several repositories and names no primary. Unarchive it or retry with `repoId` — `repos` is present only in the second case. |
| `503` | ApiError | Preview deployments are switched off for this deployment of hlix. |

## Get one deployment

`GET /v1/api/deployments/{id}` · operation ID `getDeployment`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `id` | path | **yes** | string |  |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |
| `X-Client-Portal` | header | no | string | Agency organization id for one aggregate client dashboard; server derives only this caller's workspace relationship and owned account seats. Legacy account ids remain narrowly compatible. Real verified user session required for agency context; administration denied. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | Deployment | The deployment row. |
| `400` | ApiError | The request named no active organization. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project. |
| `404` | ApiError | No such deployment in this workspace. |

## Extend a preview's time to live

`POST /v1/api/deployments/{id}/touch` · operation ID `touchDeployment`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `id` | path | **yes** | string |  |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |
| `X-Client-Portal` | header | no | string | Agency organization id for one aggregate client dashboard; server derives only this caller's workspace relationship and owned account seats. Legacy account ids remain narrowly compatible. Real verified user session required for agency context; administration denied. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | DeploymentTouched | The TTL was extended. A project's canonical preview has no TTL, and touching it changes nothing. |
| `400` | ApiError | The request named no active organization. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project. |
| `404` | ApiError | No such deployment in this workspace. |

## Set the production deployment's custom domain

`PUT /v1/api/deployments/custom-domain` · operation ID `setProductionCustomDomain`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Request body** — `application/json`, `CustomDomain` (required)

| Property | Type | Required | Notes |
| --- | --- | --- | --- |
| `domain` | string | null | **yes** |  |
| `projectId` | string | **yes** | min length 1 |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | CustomDomainSaved | Stored. It reads as pending DNS until the domain is connected. |
| `400` | ValidationError \| ApiError | The body failed validation. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project. |
| `404` | ApiError | No such project. |

## If a request fails

These apply to every operation on this page.

- `400` — the body failed schema validation, or the request named no active organization. A `ValidationError` body carries the failing fields; an `ApiError` body carries only `error`.
- `401` — no valid session or API key.
- `403` — authenticated, but not a member of the named organization, or a client collaborator without the required access.
- `404` — no such resource **in this workspace**. Absent and not-visible are deliberately the same answer; do not infer cross-tenant existence from it.
- `409` — the expected revision or state is stale, or another operation currently owns the transition.
- `500` — the operation failed server-side. Retry only where an idempotency key makes that safe.

## Next steps

[API reference](/api/reference/)
  [API & OpenAPI](/api/openapi/)
  [TypeScript SDK](/sdk/typescript/)
  [CLI reference](/reference/cli/)