Previews

Previews operations in the Hlix API.

See the OpenAPI document for schemas and operation IDs.

Prerequisites

Protected operations require an API key in x-api-key or a browser session cookie; some actions require a verified user session
Tenant-scoped operations use X-Organization-Id; browser sessions can use their active workspace. Discovery and personal-workspace bootstrap do not require an active workspace
The base URL for your deployment, https://server.hlix.ai by default

Method	Path	Operation
`POST`	`/v1/api/previews`	Rebuild a project’s preview
`GET`	`/v1/api/previews/sharing`	Get public preview sharing for a project
`PUT`	`/v1/api/previews/sharing`	Enable or revoke public preview sharing

POST /v1/api/previews · operation ID rebuildPreview

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, RebuildPreview (required)

Property	Type	Required	Notes
`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	Previews are switched off for this deployment of hlix.

GET /v1/api/previews/sharing · operation ID getPreviewSharing

Parameters

Name	In	Required	Type	Description
`projectId`	query	yes	string	The project whose preview sharing to read.
`X-Organization-Id`	header	no	string	The workspace (organization) to act in. Omitted, the session’s active organization is used.

Responses

Status	Body	Description
`200`	PreviewSharingSaved	Whether anyone with a preview link can open it.
`400`	ApiError	projectId is required.
`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.
`503`	ApiError	Sharing storage is unavailable.

PUT /v1/api/previews/sharing · operation ID setPreviewSharing

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, PreviewSharing (required)

Property	Type	Required	Notes
`projectId`	string	yes	min length 1
`public`	boolean	yes

Responses

Status	Body	Description
`200`	PreviewSharingSaved	Sharing applies to all retained and future previews. Agency only.
`400`	ValidationError \| ApiError	The body failed validation.
`401`	ApiError	No valid session or API key.
`403`	ApiError	Clients cannot change sharing.
`404`	ApiError	No such project.
`503`	ApiError	Sharing could not be changed.

The response table for each operation lists its documented errors. Common status codes include:

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 — check the resource ID and your access to the selected Workspace.
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.