Mentions

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
GET	/v1/api/mentions	List the caller’s unread mentions
POST	/v1/api/mentions/read	Mark the caller’s mentions read
GET	/v1/api/projects/{projectId}/mention-roster	List who this project’s conversations can mention

List the caller’s unread mentions

GET /v1/api/mentions · operation ID listUnreadMentions

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	MentionInbox	The caller’s own unread mentions, newest first. Read truncated first: when it is true, total is a floor rather than a count.
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.

Mark the caller’s mentions read

POST /v1/api/mentions/read · operation ID markMentionsRead

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

Property	Type	Required	Notes
ids	string[]	yes

Responses

Status	Body	Description
200	MentionReadAck	The ids that actually changed. An id belonging to another person, or one already read, is absent — naming somebody else’s mention does nothing rather than failing.
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.

List who this project’s conversations can mention

GET /v1/api/projects/{projectId}/mention-roster · operation ID getProjectMentionRoster

Parameters

Name	In	Required	Type	Description
projectId	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	MentionRoster	The workspace’s members plus this project’s collaborators, and the project’s agents (the conductor first). email is present only for an agency viewer.
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 project in this workspace — or the caller is a client collaborator with no grant on it.

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.