Chat

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

Operations

Method	Path	Operation
POST	/v1/api/chat/attachments	Store a file for a chat turn to name
GET	/v1/api/chat/messages	Read the projectless chat transcript
GET	/v1/api/chat/sessions	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
GET	/v1/api/chat/sessions/{id}/messages	Read one chat session’s history
POST	/v1/api/chat/stop	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
GET	/v1/api/chat/turns/{turnId}	Read where a sent message stands and the agent’s answer
POST	/v1/api/chat/urgent	Stop only the project’s 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 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.