# Chat

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 |
| --- | --- | --- |
| `POST` | `/v1/api/chat/attachments` | [Store a file for a chat turn to name](#store-a-file-for-a-chat-turn-to-name) |
| `GET` | `/v1/api/chat/messages` | [Read the projectless chat transcript](#read-the-projectless-chat-transcript) |
| `GET` | `/v1/api/chat/sessions` | [List your chat sessions with one agent](#list-your-chat-sessions-with-one-agent) |
| `POST` | `/v1/api/chat/sessions` | [Start a chat session with an agent, or fork one at a message](#start-a-chat-session-with-an-agent-or-fork-one-at-a-message) |
| `GET` | `/v1/api/chat/sessions/{id}/messages` | [Read one chat session's history](#read-one-chat-sessions-history) |
| `POST` | `/v1/api/chat/stop` | [Request cancellation of your exact model turn across replicas](#request-cancellation-of-your-exact-model-turn-across-replicas) |
| `POST` | `/v1/api/chat/turns` | [Send a message to a project and return while the agent works](#send-a-message-to-a-project-and-return-while-the-agent-works) |
| `GET` | `/v1/api/chat/turns/{turnId}` | [Read where a sent message stands and the agent's answer](#read-where-a-sent-message-stands-and-the-agents-answer) |
| `POST` | `/v1/api/chat/urgent` | [Stop only the project's recent work an urgent message contradicts](#stop-only-the-projects-recent-work-an-urgent-message-contradicts) |

## Store a file for a chat turn to name

`POST /v1/api/chat/attachments` · operation ID `uploadChatAttachment`

**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** — `multipart/form-data` (required)

| Property | Type | Required | Notes |
| --- | --- | --- | --- |
| `file` | string (binary) | **yes** |  |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `201` | ChatAttachment | The file is stored. `artifactKey` is what a later turn sends in `attachments`; the agent reads the bytes through its own tool (analyse an image, parse a PDF, analyse a video, transcribe audio). Audio is transcribed on the way in, so `transcript` carries the text the composer should show. |
| `400` | ApiError | The body is not multipart/form-data, or carries no `file` field. |
| `401` | ApiError | No valid session or API key. |
| `402` | ApiError | The workspace is over a spend cap — its free monthly credit, its plan cap, or a limit it set itself. The body names which one and what to do about it. |
| `403` | ApiError | A client collaborator asked to attach a file. The upload is agency-only: an audio attachment is transcribed on arrival, which spends the AGENCY's model budget. |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |
| `413` | ApiError | The file is over the attachment ceiling — 25 MB, or the smaller limit past which a video can no longer be analysed. |
| `415` | ApiError | No agent tool can read a file of that type. The accepted set is the one the reading tools actually handle — a raster image (including HEIC/HEIF and AVIF), a PDF, audio in a transcribable format, or a video. SVG is refused as markup rather than a raster. |
| `502` | ApiError | The file could not be written to object storage. Nothing was recorded and the upload is safe to retry. |

## Read the projectless chat transcript

`GET /v1/api/chat/messages` · operation ID `listChatMessages`

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

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | WireMessage[] | The signed-in user's projectless conversation. The thread is derived from the SESSION exactly as the stream derives it, so no query can point this read at anyone else's. `cycleId` is null throughout — this transcript belongs to no work group. |
| `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. |

## List your chat sessions with one agent

`GET /v1/api/chat/sessions` · operation ID `listChatSessions`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `projectId` | query | no | string | The project whose manager (or, with `agentId`, team agent) the sessions are with. Omitted: your own workspace assistant. |
| `agentId` | query | no | string | The team agent, within `projectId`. |
| `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` | ChatSessionList | Newest first, then the agent's default session (its original conversation). A project agent's sessions are seen by everyone who may see its chat; the workspace assistant's are yours alone. |
| `400` | ValidationError | The query 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 | The project or agent is not reachable by this caller. |

## Start a chat session with an agent, or fork one at a message

`POST /v1/api/chat/sessions` · operation ID `createChatSession`

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

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

| Property | Type | Required | Notes |
| --- | --- | --- | --- |
| `agentId` | string | no | min length 1 |
| `fork` | object | no |  |
| `projectId` | string | no | min length 1 |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `201` | ChatSessionCreated | The new session. With `fork`, it holds the conversation up to and including `messageId` and is already titled; the original is unchanged. |
| `400` | ValidationError \| ApiError | The body failed validation, or `fork` names a conversation with another agent. |
| `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 project, agent, forked conversation or message is not reachable by this caller. |

## Read one chat session's history

`GET /v1/api/chat/sessions/{id}/messages` · operation ID `listChatSessionMessages`

**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` | WireMessage[] | The session's turns, oldest first, in the same shape as every other conversation read. |
| `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 session with that id is reachable by this caller. |

## Request cancellation of your exact model turn across replicas

`POST /v1/api/chat/stop` · operation ID `stopChatTurn`

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

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

| Property | Type | Required | Notes |
| --- | --- | --- | --- |
| `turnId` | string (uuid) | **yes** |  |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | ChatStopResponse | Cancellation requested; does not undo effects of tools already executed |
| `400` | ValidationError \| ApiError | The JSON body failed schema validation (`ValidationError`), or the request named no active organization (`ApiError`). |
| `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. |

## Send a message to a project and return while the agent works

`POST /v1/api/chat/turns` · operation ID `sendChatTurn`

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

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

| Property | Type | Required | Notes |
| --- | --- | --- | --- |
| `activeCycleId` | string (uuid) | no |  |
| `message` | string | **yes** | min length 1, max length 100000 |
| `messageId` | string (uuid) | no |  |
| `projectId` | string (uuid) | **yes** |  |
| `taskId` | string (uuid) | no |  |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `202` | ChatTurnAccepted | The message is stored and, unless it named only people (`delivered: "thread"`), the project's agent is answering it. The turn runs to completion on the server whether or not anyone is watching; read it back with `GET /v1/api/chat/turns/{turnId}`. `messageId` is the retry key: resending it is the same turn, never a second one. |
| `400` | ValidationError \| ApiError | The body failed validation, or a task was named outside the supplied cycle. |
| `401` | ApiError | No valid session or API key. |
| `402` | ApiError | The workspace is over a spend cap — its free monthly credit, its plan cap, or a limit it set itself. The body names which one and what to do about it. |
| `403` | ApiError | Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project. |
| `404` | ApiError | A named project, cycle or task is not reachable by this caller. |
| `409` | ApiError | The conversation is already running a turn, or this `messageId` was used — for different content, or for a turn that has not finished. |

## Read where a sent message stands and the agent's answer

`GET /v1/api/chat/turns/{turnId}` · operation ID `getChatTurn`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `turnId` | path | **yes** | string |  |
| `projectId` | query | **yes** | string | The project the turn was sent to. |
| `activeCycleId` | query | no | string | The cycle, when the turn was sent to one. |
| `taskId` | query | no | string | The task, when the turn was sent to one. |
| `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` | ChatTurnResult | The turn's status and, once it exists, the agent's answer. `delivered` means the message named only people and no agent will answer it. |
| `400` | ValidationError | The query 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 | The conversation is not reachable by this caller, or holds no message with that id. |

## Stop only the project's recent work an urgent message contradicts

`POST /v1/api/chat/urgent` · operation ID `checkUrgentChatMessage`

**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`, `ChatUrgent` (required)

| Property | Type | Required | Notes |
| --- | --- | --- | --- |
| `content` | string | **yes** | min length 1, max length 20000 |
| `projectId` | string (uuid) | **yes** |  |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | ChatUrgentResponse | The cycles stopped because the message contradicts them; empty when it contradicts nothing or the check could not answer. The rest of the project keeps running. |
| `400` | ValidationError \| ApiError | The JSON body failed schema validation (`ValidationError`), or the request named no active organization (`ApiError`). |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | Read-only access to this project. |
| `404` | ApiError | Project not found. |

## 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/)