# Previews

See the [OpenAPI document](/openapi.json) 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

## Operations

| Method | Path | Operation |
| --- | --- | --- |
| `POST` | `/v1/api/previews` | [Rebuild a project's preview](#rebuild-a-projects-preview) |
| `GET` | `/v1/api/previews/sharing` | [Get public preview sharing for a project](#get-public-preview-sharing-for-a-project) |
| `PUT` | `/v1/api/previews/sharing` | [Enable or revoke public preview sharing](#enable-or-revoke-public-preview-sharing) |

## Rebuild a project's preview

`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 public preview sharing for a project

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

## Enable or revoke public preview sharing

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

## If a request fails

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.

## Next steps

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