Deployments

Generated from contract version 1.0.0 — the same document /v1/api/openapi.json 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

Method	Path	Operation
`GET`	`/v1/api/deployments`	List deployments
`POST`	`/v1/api/deployments`	Redeploy a project’s preview, or deploy it to production
`GET`	`/v1/api/deployments/{id}`	Get one deployment
`POST`	`/v1/api/deployments/{id}/touch`	Extend a preview’s time to live
`PUT`	`/v1/api/deployments/custom-domain`	Set the production deployment’s custom domain

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.

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 /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.

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.

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.

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.

API referenceEvery resource in the published contract, and what is deliberately not in it.

API & OpenAPIDownload the contract, generate a client, and read the compatibility policy.

TypeScript SDKAuth, retries, typed errors, uploads and streaming, already built.

CLI referenceThe same operations from a terminal, with a stable JSON envelope.