# Overview (/docs)
Nurama is a collaborative asset-review platform: workspaces contain projects, projects contain assets, folders, boards, tasks and chats, and every change fans out to the people watching it in real time. This site documents how to build on it.
## Pick a credential first [#pick-a-credential-first]
Integrations never sign in with a person's email and password. Each way of connecting has its own credential, and the credential decides what the connection can do.
| You are building | Use | Acts as |
| ------------------------------------------------------------ | -------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| An AI assistant integration (Claude, Cursor, any MCP client) | The hosted [MCP server](/docs/guides/mcp) with OAuth sign-in | The person who signed in, limited to the scopes they approved |
| A script or automation that should act as you | A [personal access token](/docs/getting-started/authentication#personal-access-tokens) | You, limited to the scopes on the token |
| A shared service, bot or team automation | A [bot API key](/docs/guides/bots) | A dedicated bot user with its own memberships and scopes |
All three are scoped, revocable and cannot touch billing, account security or token management.
## The surfaces [#the-surfaces]
## Machine-readable sources [#machine-readable-sources]
Everything on this site is generated from documents you can consume directly:
* OpenAPI 3.0: [`/openapi.json`](/openapi.json) or [`/openapi.yaml`](/openapi.yaml)
* AsyncAPI 3.0: [`/asyncapi.json`](/asyncapi.json) or [`/asyncapi.yaml`](/asyncapi.yaml)
* MCP tool catalogue: [`/mcp-tools.json`](/mcp-tools.json)
* This site as text for language models: [`/llms.txt`](/llms.txt) (index) and [`/llms-full.txt`](/llms-full.txt) (everything). Every page also has a Markdown variant, reachable from the copy button at the top of the page.
The [build manifest](/manifest.json) records which platform release the documents were generated from.
# Authentication (/docs/getting-started/authentication)
Every request to the REST API carries a bearer credential:
```
Authorization: Bearer
```
Three credentials are available to integrations. They differ in whose identity actions are attributed to and in which host accepts them.
| Credential | Prefix | Acts as | Obtain it | Use against |
| --------------------- | ---------- | ----------------------- | -------------------------------------------------------------- | ------------------- |
| Personal access token | `nrm_pat_` | The user who created it | Nurama web app, **Settings → Tokens** | `api.nurama.com` |
| Bot API key | `nrm_bot_` | A dedicated bot user | Workspace settings, **Bots** tab (workspace admins) | `bot.nurama.com` |
| MCP OAuth connection | — | The user who signed in | Automatically, when an MCP client connects to `mcp.nurama.com` | The MCP server only |
Email-and-password sessions exist for the Nurama apps and are not part of the public API. The endpoints behind them are not documented here.
## Personal access tokens [#personal-access-tokens]
A personal access token is a long-lived credential that acts as you within the scopes you chose. Create it under **Settings → Tokens** in the web app, name it, pick scopes, and copy the secret once. Revoke it from the same screen. Tokens cannot create or manage other tokens, so a compromised token cannot widen its own access.
Use one for scripts, local automations and CI jobs that should run as you. If several people or a production system will depend on the integration, create a bot instead so it does not stop working when you leave a workspace.
## Bot API keys [#bot-api-keys]
A bot is a user account owned by a workspace. A workspace owner or admin creates it from the workspace's **Bots** tab, choosing its display name and scopes, then adds it to the projects it should see. The key is shown once and can be rotated from the same place. Bots appear in chats under their own name and avatar, and audit trails attribute their actions to the bot.
Bot keys are only accepted on the bot gateway: `bot.nurama.com` for HTTP and `bot-ws.nurama.com` for Socket.IO. See [Building a bot](/docs/guides/bots) for the workflow, and the [SDK guide](/docs/guides/sdk) for `BotClient`.
## MCP connections [#mcp-connections]
When an MCP client such as Claude connects to `https://mcp.nurama.com/mcp`, it is sent through an OAuth 2.1 sign-in in the browser. The person signs in to Nurama, approves a read-only (`nurama.read`) or read-and-write (`nurama.write`) grant, and the client receives a token it uses for that connection. Nothing is copied or stored by hand, and the grant can be revoked from the Nurama account. A personal access token can be used instead of the OAuth flow for headless clients; see the [MCP guide](/docs/guides/mcp).
## Scopes [#scopes]
Personal access tokens and bot keys carry scopes from this list. An MCP grant maps `nurama.read` to the read scopes and `nurama.write` to all of them except `webhooks:manage`, which only a personal access token can carry.
| Scope | Allows |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `workspaces:read` | Read workspace metadata and your own memberships |
| `projects:read` | Read project metadata and membership |
| `assets:read` | Read asset metadata and request signed download URLs |
| `assets:write` | Upload, update, publish and tag assets |
| `chat:read` | Read chats, messages and message attachments |
| `chat:write` | Post messages, edit your own messages, attach files |
| `tasks:read` | Read boards, tasks, task events and task relations |
| `tasks:write` | Create, update, move, assign and link tasks |
| `webhooks:manage` | Create, update, pause and delete webhook subscriptions, rotate their secrets, test and replay deliveries. Personal access tokens only, and the token's owner must be a workspace admin. |
A request to a scope-gated endpoint without the matching scope fails with `403`, even when the underlying user has permission. Scopes are fixed when the credential is created; make a new one to change them. Whatever the scopes, none of the three credentials can reach billing, subscriptions, credits, account security or token management. Those surfaces are reserved for the Nurama apps.
## WebSocket handshake [#websocket-handshake]
Socket.IO connections authenticate with the same personal access token or bot key, passed as `token` in the handshake query. Public release channels (`/public/{token}`) need no credential. Details are in the [WebSocket guide](/docs/guides/websocket).
Treat tokens and bot keys as secrets. Never embed them in client-side code or share one credential between people; each person should hold their own token, and shared automations should run as a bot.
# Conventions (/docs/getting-started/conventions)
## Identifiers [#identifiers]
Resources are identified by UUIDs. Path parameters are named after the resource they identify (`workspaceId`, `projectId`, `chatId`, `messageId`); the schemas in the reference say which are required.
## Visibility tiers [#visibility-tiers]
Projects have three audiences: `creator`, `reviewer` and `public`. Assets, folders, chats and notifications exist per tier, and many list endpoints take the tier as a path segment or query parameter. A caller only sees the tiers their role allows, and reads never cross tiers. When you reply to something, use the tier it came from.
## Pagination [#pagination]
List endpoints return a paginated envelope and accept:
| Parameter | Meaning |
| ---------- | ---------------------------------------------------------------------------------------- |
| `limit` | Page size. Most endpoints cap it at 20. |
| `paginate` | `cursor` (default for streams such as messages and feeds) or `index` (fixed-size lists). |
| `cursor` | Opaque cursor from the previous page, for cursor pagination. |
| `page` | Page number, for index pagination. |
| `sort` | Field and direction, where the endpoint documents it. |
Cursor responses include the cursor for the next page; index responses include total counts. The SDK's `PaginatedResponse` type covers both shapes.
## Errors [#errors]
Errors share one shape:
```json
{
"code": 403,
"message": "forbidden",
"errorKey": "forbidden"
}
```
`errorKey` is stable and is the value to switch on; `message` is for people. Beyond the responses listed for each operation, any authenticated endpoint may return `400` (validation), `401` (missing or expired credential) or `403` (no permission, missing scope, or a feature the workspace's plan does not include). Validation errors describe the offending field in `message`.
## Rate limits [#rate-limits]
Requests are rate limited per credential. Bot keys share one bucket per key (120 requests per minute); user credentials have per-route limits. A `429` response carries a `Retry-After` header.
## File uploads [#file-uploads]
Files are never posted to the API. You create the asset (or message attachment) first, receive pre-signed upload URLs in the response, upload the bytes directly to storage, then call the matching `complete-upload` endpoint. The SDK wraps the whole sequence; see the `asset` namespace in the [SDK reference](/docs/reference/sdk/routes/asset).
## Dates and times [#dates-and-times]
Timestamps are ISO 8601 strings in UTC. Durations and media positions are in milliseconds unless a field says otherwise.
# Quick start (/docs/getting-started)
The fastest way to try the API is a personal access token: a scoped credential that acts as you. Shared or production automations should use a [bot](/docs/guides/bots) instead, and AI assistants should connect through the [MCP server](/docs/guides/mcp).
## Base URLs [#base-urls]
| Purpose | URL |
| ---------------------------------- | --------------------------------------- |
| REST API (personal access tokens) | `https://api.nurama.com/v1` |
| REST API (bot API keys) | `https://bot.nurama.com/v1` |
| WebSocket (personal access tokens) | `https://ws.nurama.com` (Socket.IO) |
| WebSocket (bot API keys) | `https://bot-ws.nurama.com` (Socket.IO) |
| MCP server | `https://mcp.nurama.com/mcp` |
All REST paths in this documentation are relative to the `/v1` prefix. Requests and responses are JSON unless an operation says otherwise.
## 1. Create a token [#1-create-a-token]
In the Nurama web app open **Settings → Tokens → New token**. Give it a name and pick the scopes it needs. For a first look, `workspaces:read` and `projects:read` are enough. The token starts with `nrm_pat_` and is shown once; store it like a password.
## 2. Make a request [#2-make-a-request]
```bash
curl -s https://api.nurama.com/v1/workspaces \
-H "Authorization: Bearer $NURAMA_TOKEN"
```
The response lists the workspaces you belong to. A request outside the token's scopes fails with `403` and the error key `forbidden`; see [Conventions](/docs/getting-started/conventions) for the error shape.
## 3. The same thing with the SDK [#3-the-same-thing-with-the-sdk]
```bash
pnpm add @nurama/sdk
```
```ts
import NuramaClient from '@nurama/sdk';
const client = new NuramaClient('https://api.nurama.com', {
apiKey: process.env.NURAMA_TOKEN,
});
const workspaces = await client.workspace.listWorkspaces();
```
With `apiKey` set, the client sends the token on every request and skips session handling entirely. Continue with the [SDK guide](/docs/guides/sdk).
## Where to go next [#where-to-go-next]
# Building a bot (/docs/guides/bots)
A bot is a workspace-owned user with its own API key. It appears in chats under its own name and avatar, holds project memberships like any member, and is limited by the scopes on its key.
## 1. Create the bot [#1-create-the-bot]
A workspace owner or admin creates the bot from the workspace's **Bots** tab in the Nurama web app, choosing a display name and the scopes the key should carry, then adds it to the projects it should see. The same can be done over the API with `POST /workspaces/{workspaceId}/bots` and the membership endpoints under it. The raw `nrm_bot_…` key is shown once.
## 2. Connect [#2-connect]
```ts
import BotClient from '@nurama/sdk/bot';
const bot = new BotClient(process.env.NURAMA_BOT_API_KEY);
const { user } = await bot.membership.getMyMemberships();
```
`BotClient` targets `bot.nurama.com` and `bot-ws.nurama.com`. It exposes the same namespaces as the user client minus account, billing, device and bot administration.
## 3. Listen for mentions [#3-listen-for-mentions]
Subscribe to the bot's own user channel and react to `chatMention`:
```ts
await bot.socket.subscribe(`/user/${botUserId}`, 'notification', async (event) => {
if (event.type !== 'chatMention') return;
const { chatId, messageId } = event.tokens;
await bot.socket.emit(`/user/${botUserId}`, 'typing:start', { chatId });
const history = await bot.chat.getMessages(chatId, { limit: 20, sort: { createdAt: -1 }, excludeReplies: true });
const reply = await decide(history);
await bot.chat.createMessage(chatId, { content: reply, replyToId: messageId });
await bot.socket.emit(`/user/${botUserId}`, 'typing:stop', { chatId });
});
```
To see every message in a project rather than only mentions, subscribe to `/project/{projectId}/creator` and `/project/{projectId}/reviewer` and handle `chatCreateMessage`. Reply in the tier the message came from.
## Useful methods [#useful-methods]
| Goal | Method |
| ----------------------------- | ------------------------------------------------------------------------------------ |
| Chat the bot was mentioned in | `bot.chat.getChat(chatId)` |
| Recent history | `bot.chat.getMessages(chatId, params)` |
| Post a reply | `bot.chat.createMessage(chatId, { content, replyToId?, assetMentions?, mentions? })` |
| Active assets in a project | `bot.project.getHomeFeed(projectId, visibility, params)` |
| Project members | `bot.membership.getProjectMemberships(projectId, params)` |
| Create a task | `bot.task.createTask(data)` |
The full list with read/mutate flags is the [method index](/docs/reference/sdk/method-index).
## Good behaviour [#good-behaviour]
* Default to read-only methods; only write when that is the bot's purpose.
* Rate limits are per key (120 requests per minute). Batch reads and cache memberships.
* Render asset references as `{{assetMention:UUID}}` tokens and pass the ids in `assetMentions` so they become clickable.
* Never log the API key. Rotate it with `POST /workspaces/{workspaceId}/bots/{botId}/rotate-key` if it leaks.
If your bot is an AI assistant, consider running the [MCP server](/docs/guides/mcp) instead of writing the tool layer yourself.
# MCP server (/docs/guides/mcp)
Nurama runs a hosted [Model Context Protocol](https://modelcontextprotocol.io) server at `https://mcp.nurama.com/mcp`. An assistant connected to it can read projects, chats, assets, boards and tasks, and, when allowed, post messages and create or update tasks, all as the person who signed in and within the scopes they approved.
## Connect [#connect]
Add the server to your client and sign in when the browser opens. Nurama asks whether to grant read-only (`nurama.read`) or read-and-write (`nurama.write`) access.
**Claude Code**
```bash
claude mcp add --transport http nurama https://mcp.nurama.com/mcp
```
**Claude desktop and claude.ai**: add a custom connector with the URL `https://mcp.nurama.com/mcp`.
**Cursor and other clients**: add an entry to the client's MCP configuration.
```json
{
"mcpServers": {
"nurama": { "url": "https://mcp.nurama.com/mcp" }
}
}
```
Ask the assistant which Nurama tools it has to confirm the connection. The [tool catalogue](/docs/reference/mcp) lists every tool with its input schema; the raw list, identical to the server's `tools/list` response, is at [`/mcp-tools.json`](/mcp-tools.json).
## Headless clients [#headless-clients]
Where a browser sign-in is not possible, for example in CI or a server-side agent, send a [personal access token](/docs/getting-started/authentication#personal-access-tokens) as a bearer header instead of using OAuth:
```
Authorization: Bearer nrm_pat_…
```
The connection then acts as the token's owner within the token's scopes. Bot API keys are not accepted by the MCP server; they are a service identity for the REST and WebSocket APIs, not a personal credential for an assistant.
## What the assistant can do [#what-the-assistant-can-do]
Read tools cover memberships, project feeds, chats, messages, boards and tasks. Write tools, such as sending a message or creating a task, are flagged as mutating in the catalogue and only work under a read-and-write grant or a token with the matching write scopes. Nothing the assistant does can reach billing, account security, token management or webhook subscriptions, whatever it is asked.
Grant the narrowest access that does the job: a read-only connection cannot be talked into writing, whatever the prompt says.
## Revoking access [#revoking-access]
Revoke an OAuth grant or a personal access token from your Nurama account settings. Connections using it stop working immediately.
# Using the SDK (/docs/guides/sdk)
`@nurama/sdk` is a TypeScript client for the REST API and the Socket.IO layer. It ships ESM and CommonJS builds for Node 18+ and a browser bundle, and depends on `@nurama/types` for every request and response type.
```bash
pnpm add @nurama/sdk
```
Source and issues live in the public mirror at [github.com/nurama-team/nurama-sdk](https://github.com/nurama-team/nurama-sdk); the package is Apache-2.0.
## Two clients [#two-clients]
| Client | Import | Credential | Reaches |
| -------------- | ----------------- | --------------------------------------- | ---------------------------------------- |
| `NuramaClient` | `@nurama/sdk` | Personal access token (`apiKey` option) | The API, within the token's scopes |
| `BotClient` | `@nurama/sdk/bot` | Bot API key | The bot gateway, within the key's scopes |
```ts
import NuramaClient from '@nurama/sdk';
const client = new NuramaClient('https://api.nurama.com', {
apiKey: process.env.NURAMA_TOKEN, // nrm_pat_…
websocketURL: 'https://ws.nurama.com', // optional, defaults to the API host
});
```
With `apiKey` set, the client sends the token on every request and never touches session handling. The `auth` namespace and the session flow it drives exist for the Nurama apps; integrations should not sign in with a password.
```ts
import BotClient from '@nurama/sdk/bot';
const bot = new BotClient(process.env.NURAMA_BOT_API_KEY);
const memberships = await bot.membership.getMyMemberships();
```
Both expose the same namespaces (`client.chat`, `bot.chat`, …); `BotClient` simply omits the ones a bot key cannot use.
## Conventions [#conventions]
* **Method names repeat the noun.** `asset.getAsset`, `board.createBoard`, `supportTicket.listSupportTickets`. Methods close over the client rather than `this`, so you can destructure a namespace (`const { getAsset, updateAsset } = client.asset`) and names never collide across namespaces.
* **Namespaces follow the URL.** `/tasks/{id}/links` is `task.getTaskLinks`; `/public-download/{token}` is `public.resolvePublicDownload`.
* **Visibility is an argument.** Reads that differ by tier take `visibility: 'creator' | 'reviewer'`, for example `project.getAssets(projectId, 'reviewer')`.
* **Pagination is a params object.** Methods returning `PaginatedResponse` accept `{ limit, paginate: 'cursor' | 'index', cursor?, page? }`.
* **Required identifiers throw when missing**, before any request is made.
The [method index](/docs/reference/sdk/method-index) lists every bot-reachable method grouped by namespace with a read/mutate flag, and the [SDK reference](/docs/reference/sdk) has full signatures and types.
## Real-time events [#real-time-events]
The `socket` namespace manages Socket.IO connections per channel and re-authenticates when a token is refreshed:
```ts
await client.socket.subscribe(`/project/${projectId}/creator`, 'notification', (event) => {
if (event.type === 'chatCreateMessage') {
// event.changes.create[0].resource is the message
}
});
```
Channel names and event payloads are documented under [WebSocket events](/docs/reference/websocket).
## Versioning [#versioning]
The SDK follows semantic versioning. Removed or renamed methods only ship in a major version, and the [changelog](https://github.com/nurama-team/nurama-sdk/releases) on the mirror lists them. Pin a minor range in production.
# Webhooks (/docs/guides/webhooks)
A webhook subscription tells Nurama to `POST` a signed JSON payload to a URL you control whenever a matching event happens in a workspace. Use webhooks when a server you run needs to react to changes without holding a WebSocket connection open.
## Create a subscription [#create-a-subscription]
Workspace admins create subscriptions from the workspace's **Webhooks** tab in the Nurama web app, or over the API with a personal access token that belongs to an admin and carries the `webhooks:manage` scope:
```bash
curl -s https://api.nurama.com/v1/workspaces/$WORKSPACE_ID/webhooks \
-H "Authorization: Bearer $NURAMA_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"name": "Task sync",
"url": "https://example.com/hooks/nurama",
"events": ["task.created", "task.updated"]
}'
```
The response includes `signingSecret`. It is shown once, so store it with your other secrets before you do anything else. Rules:
* The URL must be HTTPS and publicly reachable. Private and loopback addresses are refused.
* Choose events from the [event catalogue](/docs/reference/api/webhook-events). Unknown names are rejected.
* A workspace can hold 25 subscriptions that are not failed out.
* Only the app or a personal access token with `webhooks:manage` can manage subscriptions. Bot API keys and MCP connections cannot, so a compromised bot or a misled assistant can never register a receiver for your events.
* Set `expiresAt` for a temporary integration and the subscription stops delivering after that time.
The same operations are available in the SDK under `client.webhook`: `createWebhook`, `listWebhooks`, `updateWebhook`, `rotateWebhookSecret`, `testWebhook`, `listWebhookDeliveries` and `replayWebhookDelivery`.
## What a delivery looks like [#what-a-delivery-looks-like]
Each delivery is an HTTP `POST` with a JSON body and these headers:
| Header | Meaning |
| -------------------------- | ------------------------------------------------------------------------------ |
| `X-Nurama-Event-Type` | The event name, for example `task.created` |
| `X-Nurama-Event-Id` | Identifies the event. Retries and replays of the same event carry the same id. |
| `X-Nurama-Delivery-Id` | Identifies this attempt. |
| `X-Nurama-Subscription-Id` | The subscription being delivered to. |
| `X-Nurama-Timestamp` | When the request was signed, as Unix seconds. |
| `X-Nurama-Signature-256` | `sha256=`, the signature described below. |
| `User-Agent` | `Nurama-Webhook/1.0` |
The body is an envelope around the same notification the WebSocket API emits:
```json
{
"id": "0192…",
"type": "task.created",
"createdAt": "2026-09-23T10:15:04.512Z",
"workspace": { "id": "…", "slug": "acme" },
"initiatorId": "…",
"initiatorType": "user",
"resourceId": "…",
"resourceType": "task",
"tokens": { "…": "…" },
"changes": { "create": [{ "resourceType": "task", "resource": { "…": "…" } }] }
}
```
`type` is the webhook event name. `tokens` and `changes` are shaped exactly as documented for the underlying notification; the [event catalogue](/docs/reference/api/webhook-events) links each event to those pages. Payloads are at most 256 KB and additive-only: fields may be added over time, never removed or renamed, so ignore fields you do not recognise.
## Respond quickly [#respond-quickly]
Return any `2xx` status within 10 seconds. Redirects are not followed and count as failures. Do the real work after responding, for example by putting the payload on a queue, so a slow downstream never causes retries.
## Verify the signature [#verify-the-signature]
Every request is signed with the subscription's secret using HMAC-SHA256 over the timestamp header, a dot, and the raw request body:
```
signature = HMAC_SHA256(secret, ".")
```
Verify against the raw bytes you received, before parsing JSON, and compare in constant time. Reject requests whose timestamp is more than a few minutes old to defeat replays of captured requests.
```ts
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verifyNuramaWebhook(rawBody: Buffer, headers: Record, secret: string) {
const timestamp = headers['x-nurama-timestamp'];
const received = headers['x-nurama-signature-256'] ?? '';
if (!timestamp || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const expected = 'sha256=' + createHmac('sha256', secret)
.update(`${timestamp}.`)
.update(rawBody)
.digest('hex');
return expected.length === received.length && timingSafeEqual(Buffer.from(expected), Buffer.from(received));
}
```
In Express, mount the handler with `express.raw({ type: 'application/json' })` so the body arrives unparsed.
## Retries, dead letters and pausing [#retries-dead-letters-and-pausing]
A delivery that gets a non-`2xx` response, a redirect or a timeout is retried with increasing delays: 1 minute, 5 minutes, 15 minutes, 1 hour, 6 hours, then 24 hours, for up to 8 attempts in total. After the last failure the delivery is dead-lettered and can be inspected and replayed from the deliveries endpoint.
If 50 consecutive deliveries to one subscription dead-letter, the subscription is automatically paused with status `failedOut`. Fix the receiver, then set the status back to `active` with a `PATCH`; deliveries that were skipped while paused are not sent. You can also pause a subscription yourself by setting status `paused`.
Handle duplicates: a retry or replay carries the same `X-Nurama-Event-Id`, so keep the ids you have processed and skip repeats. Deliveries can arrive out of order.
## Testing and debugging [#testing-and-debugging]
* `POST /workspaces/{workspaceId}/webhooks/{webhookId}/test` queues a `webhook.test` delivery to that subscription, regardless of its event list.
* `GET /workspaces/{workspaceId}/webhooks/{webhookId}/deliveries` lists attempts with their status (`pending`, `inflight`, `succeeded`, `failed`, `dlq`), the response code and any error.
* `POST /workspaces/{workspaceId}/webhooks/{webhookId}/deliveries/{attemptId}/replay` queues a fresh attempt for a past delivery.
## Rotating the secret [#rotating-the-secret]
`POST /workspaces/{workspaceId}/webhooks/{webhookId}/rotate-secret` returns a new secret once. Deliveries signed from that moment use the new secret, including retries of earlier failures, so update the receiver immediately after rotating. Anything that fails verification during the switch is retried on the normal schedule.
## Reference [#reference]
* [Webhook event catalogue](/docs/reference/api/webhook-events)
* [Webhook Subscriptions endpoints](/docs/reference/api/webhook-subscriptions)
* Raw catalogue: [`/webhook-events.json`](/webhook-events.json)
# Real-time events (/docs/guides/websocket)
The WebSocket server is a separate Socket.IO deployment. If a server you run needs to react to changes without holding a connection open, use [webhooks](/docs/guides/webhooks) instead. Connect with a Socket.IO client (the SDK's `socket` namespace, or `socket.io-client` directly), never with a raw WebSocket.
## Channels [#channels]
A channel is a Socket.IO namespace named after the resource you want to watch:
| Address | Delivers |
| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| `/user/{userId}` | Everything addressed to one user: mentions, member chats, task assignments. You may only join your own. |
| `/workspace/{workspaceId}` | Workspace-level changes. |
| `/project/{projectId}` | Project-level changes for the default audience. |
| `/project/{projectId}/{visibility}` | Changes scoped to `creator`, `reviewer` or `public`. Join both `creator` and `reviewer` if your role spans both. |
| `/chat/{chatId}` | One chat's stream, plus the collab relay (cursors, drawing, presenter control). |
| `/asset/{assetId}`, `/task/{taskId}`, `/submission/{submissionId}` | One resource's stream. |
| `/public/{token}` | A public release, authenticated by the token in the address. |
Joining requires the matching `canGet…Notifications` permission, direct or inherited; a refused handshake surfaces as `connect_error` with the message `forbidden`.
## Handshake [#handshake]
Pass your credential as `token` in the handshake query: a personal access token against `ws.nurama.com`, or a bot API key against `bot-ws.nurama.com`. Public channels need no token.
```ts
import { io } from 'socket.io-client';
const socket = io(`https://ws.nurama.com/project/${projectId}/creator`, {
query: { token: process.env.NURAMA_TOKEN },
});
socket.on('notification', (event) => console.log(event.type, event));
```
When a credential is revoked the server emits `tokenEvent` and disconnects shortly after.
## The notification envelope [#the-notification-envelope]
Almost everything arrives as a single event named `notification`. Its `type` field names one of the [notification types](/docs/reference/websocket/notifications); `tokens` carries the identifiers the type documents, and `changes` lists created, updated and deleted resources:
```json
{
"type": "chatCreateMessage",
"initiatorId": "…",
"tokens": { "chatId": "…", "messageId": "…" },
"changes": { "create": [{ "resourceType": "chatMessage", "resource": { "…": "…" } }] }
}
```
Switch on `type` and read the documented payload. Fields marked deprecated in a type's schema will disappear; prefer the `changes` array over legacy token fields.
## Other events [#other-events]
Typing indicators (`typing:start`, `typing:stop`) are emitted by clients and relayed by the server, `ws:probe` checks liveness, and the `collab:*` family relays live-collaboration state on `/chat/{chatId}` namespaces. Each is documented under [Events](/docs/reference/websocket/events) with its direction and payload.
The complete machine-readable description is the AsyncAPI document at [`/asyncapi.json`](/asyncapi.json).
# REST API (/docs/reference/api)
The pages in this section are generated from the platform's OpenAPI 3.0 document, which is itself derived from the API's validation schemas on every release. Each operation page shows the parameters and request body the server accepts, the documented responses, example requests in several languages, and a playground that calls the API with your own credential.
* Base URL: `https://api.nurama.com/v1` (`https://bot.nurama.com/v1` for bot API keys)
* Authentication: `Authorization: Bearer ` with a personal access token or bot API key; see [Authentication](/docs/getting-started/authentication). Endpoints reserved for the Nurama apps (sign-in, billing, account security) are not listed.
* Shared behaviour: [Conventions](/docs/getting-started/conventions)
* Source document: [`/openapi.json`](/openapi.json), [`/openapi.yaml`](/openapi.yaml)
Only success and route-specific error responses are listed per operation. Any authenticated endpoint may also return `400`, `401` or `403` with the common `Error` body.
# Webhook events (/docs/reference/api/webhook-events)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Subscribe to these event names with the [Webhook Subscriptions](/docs/reference/api/webhook-subscriptions) endpoints. Each delivery is a `{ workspace, type, data… }` envelope around the same notification the WebSocket API emits, so the payload fields are documented on the linked notification pages. See the [webhooks guide](/docs/guides/webhooks) for delivery, signatures and retries.
Event names are not versioned. Payloads are additive-only: fields may be added, never removed or renamed. Receivers should ignore unknown fields.
| Event | Built from notification | Notes |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
| `task.created` | [`boardTaskCreate`](/docs/reference/websocket/notifications/boardtaskcreate) | |
| `task.updated` | [`boardTaskUpdate`](/docs/reference/websocket/notifications/boardtaskupdate), [`boardTaskMove`](/docs/reference/websocket/notifications/boardtaskmove), [`boardTaskAssign`](/docs/reference/websocket/notifications/boardtaskassign) | Covers moves between columns, assignment changes and edits to the subject or description. |
| `task.deleted` | [`boardTaskRemove`](/docs/reference/websocket/notifications/boardtaskremove) | |
| `chat.message.created` | [`chatCreateMessage`](/docs/reference/websocket/notifications/chatcreatemessage) | |
| `asset.published` | [`assetStatusUpdate`](/docs/reference/websocket/notifications/assetstatusupdate) | Fires only when an asset becomes active; other status changes are not delivered. |
| `webhook.test` | [`webhookTest`](/docs/reference/websocket/notifications/webhooktest) | Synthetic event sent by the test endpoint to one subscription, regardless of its event list. |
# Read aggregated access activity for one asset (/docs/reference/api/accessactivity/get-assets-assetid-access-activity)
Returns totals per eventType, a top-N breakdown for one dimension,
and a zero-filled daily series for the requested eventType. Gated
by `canGetAccessActivity` — granted to the same roles that hold
`canGetPublicLinks`.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /assets/{assetId}/access-activity
Read aggregated access activity for one asset
Returns totals per eventType, a top-N breakdown for one dimension,
and a zero-filled daily series for the requested eventType. Gated
by `canGetAccessActivity` — granted to the same roles that hold
`canGetPublicLinks`.
# Top-N assets in a project by access count (/docs/reference/api/accessactivity/get-projects-projectid-access-activity-top-assets)
Returns `(assetId, count)` pairs ordered by total count of the
requested `eventType` in the range. Only ids and counts are
returned; fetch names and thumbnails through the asset endpoints.
Requires `canGetAccessActivity`.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /projects/{projectId}/access-activity/top-assets
Top-N assets in a project by access count
Returns `(assetId, count)` pairs ordered by total count of the
requested `eventType` in the range. Only ids and counts are
returned; fetch names and thumbnails through the asset endpoints.
Requires `canGetAccessActivity`.
# Record a play event from an authenticated player (/docs/reference/api/accessactivity/post-assets-assetid-access-activity)
Reports a play event from an authenticated player. Events are
de-duplicated per UTC day per session, so resuming from pause or
replaying a region within one session counts once. `download` and
`embed_resolved` are NOT accepted on this route — those are recorded
by the API automatically to keep the counts authoritative.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /assets/{assetId}/access-activity
Record a play event from an authenticated player
Reports a play event from an authenticated player. Events are
de-duplicated per UTC day per session, so resuming from pause or
replaying a region within one session counts once. `download` and
`embed_resolved` are NOT accepted on this route — those are recorded
by the API automatically to keep the counts authoritative.
# Record a play event from an embedded player (unauthenticated) (/docs/reference/api/accessactivity/post-public-download-token-access-activity)
Reports a play event from an embedded (unauthenticated) player. The
token is the 10-character public-link token and is the only
credential — no bearer token is used. Events on this route are
always recorded with `visibility: 'public'`; the body accepts no
`visibility` field. Only recorded while the link is `active`: a
missing or disabled link is rejected with 404 (deliberately
indistinguishable), an expired one with 410.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /public-download/{token}/access-activity
Record a play event from an embedded player (unauthenticated)
Reports a play event from an embedded (unauthenticated) player. The
token is the 10-character public-link token and is the only
credential — no bearer token is used. Events on this route are
always recorded with `visibility: 'public'`; the body accepts no
`visibility` field. Only recorded while the link is `active`: a
missing or disabled link is rejected with 404 (deliberately
indistinguishable), an expired one with 410.
# Record a play event from an embedded player (unauthenticated) (/docs/reference/api/publicassetlinks/post-public-download-token-access-activity)
Reports a play event from an embedded (unauthenticated) player. The
token is the 10-character public-link token and is the only
credential — no bearer token is used. Events on this route are
always recorded with `visibility: 'public'`; the body accepts no
`visibility` field. Only recorded while the link is `active`: a
missing or disabled link is rejected with 404 (deliberately
indistinguishable), an expired one with 410.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /public-download/{token}/access-activity
Record a play event from an embedded player (unauthenticated)
Reports a play event from an embedded (unauthenticated) player. The
token is the 10-character public-link token and is the only
credential — no bearer token is used. Events on this route are
always recorded with `visibility: 'public'`; the body accepts no
`visibility` field. Only recorded while the link is `active`: a
missing or disabled link is rejected with 404 (deliberately
indistinguishable), an expired one with 410.
# Delete an AI chat topic. (/docs/reference/api/ai/delete-ai-chat-topics-topicid)
Soft-deletes the topic: the topic and every message in its chat move
to `status: pendingDelete`, and an `aiChatTopicUpdate` notification
with a `delete` change is emitted on the caller's user channel. Only
the topic's creator may delete it.
Machine-readable definition: https://docs.nurama.com/openapi.json
## DELETE /ai/chat/topics/{topicId}
Delete an AI chat topic.
Soft-deletes the topic: the topic and every message in its chat move
to `status: pendingDelete`, and an `aiChatTopicUpdate` notification
with a `delete` change is emitted on the caller's user channel. Only
the topic's creator may delete it.
# Get the workspace's current Nurama Credit balance. (/docs/reference/api/ai/get-ai-balance)
Returns the workspace's spendable Nurama Credit balance.
Requires `canGetCreditBalance` on the workspace (workspace owner /
admin, project owner / admin) and an active subscription; no
per-feature gate. The balance is also returned as `balanceAfter` on
every billable AI call, so clients can keep a balance display fresh
without a separate fetch after every call.
`balance` is the spendable total: `planBalance` (monthly plan grant,
does not carry over) + `purchasedBalance` (top-ups, accumulates).
`hasPriorTopUp` reports whether the workspace has ever made a manual
credit purchase — the precondition for enabling auto top-up.
Also available at `GET /credits/balance` (same response).
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /ai/balance
Get the workspace's current Nurama Credit balance.
Returns the workspace's spendable Nurama Credit balance.
Requires `canGetCreditBalance` on the workspace (workspace owner /
admin, project owner / admin) and an active subscription; no
per-feature gate. The balance is also returned as `balanceAfter` on
every billable AI call, so clients can keep a balance display fresh
without a separate fetch after every call.
`balance` is the spendable total: `planBalance` (monthly plan grant,
does not carry over) + `purchasedBalance` (top-ups, accumulates).
`hasPriorTopUp` reports whether the workspace has ever made a manual
credit purchase — the precondition for enabling auto top-up.
Also available at `GET /credits/balance` (same response).
# Get a single AI chat topic. (/docs/reference/api/ai/get-ai-chat-topics-topicid)
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /ai/chat/topics/{topicId}
Get a single AI chat topic.
# List the caller's AI chat topics for a scope. (/docs/reference/api/ai/get-ai-chat-topics)
Returns topics owned by the calling user, scoped to one
workspace / project, or to "social" (personal) chats. Topics are
ordered by `lastMessageAt` desc with nulls last.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /ai/chat/topics
List the caller's AI chat topics for a scope.
Returns topics owned by the calling user, scoped to one
workspace / project, or to "social" (personal) chats. Topics are
ordered by `lastMessageAt` desc with nulls last.
# List polish tones available to the chat composer. (/docs/reference/api/ai/get-ai-tones)
Returns the polish tone catalogue so clients can offer tone choices
without hard-coding them. The list is currently fixed; workspace-scoped
custom tones are planned.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /ai/tones
List polish tones available to the chat composer.
Returns the polish tone catalogue so clients can offer tone choices
without hard-coding them. The list is currently fixed; workspace-scoped
custom tones are planned.
# Aggregated Nurama Credit usage report for a workspace. (/docs/reference/api/ai/get-ai-usage)
Credit spend on AI features (and convos) in a time window, totalled
and broken down by user and by integration point. Defaults to a
rolling 30-day window ending now when no dates are passed. Filters
apply uniformly: `userId` narrows the per-integration breakdown to
that user's calls, and `integrationPoint` narrows the per-user
breakdown to that feature.
Requires `canGetCreditUsageReport` on the workspace (granted to the
same roles as `canGetCreditBalance`) and an active subscription.
Also available at `GET /credits/usage` (same response).
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /ai/usage
Aggregated Nurama Credit usage report for a workspace.
Credit spend on AI features (and convos) in a time window, totalled
and broken down by user and by integration point. Defaults to a
rolling 30-day window ending now when no dates are passed. Filters
apply uniformly: `userId` narrows the per-integration breakdown to
that user's calls, and `integrationPoint` narrows the per-user
breakdown to that feature.
Requires `canGetCreditUsageReport` on the workspace (granted to the
same roles as `canGetCreditBalance`) and an active subscription.
Also available at `GET /credits/usage` (same response).
# Rename, archive, or set the context pins of an AI chat topic. (/docs/reference/api/ai/patch-ai-chat-topics-topicid)
At least one of `title`, `archived`, or `contextItems` must be
provided. Only the topic's creator may update it; any other caller
receives `forbidden`.
## Context pins (`contextItems`)
The items the user has pinned to Nu's Context column for this topic —
assets, folders, people, submissions, and public collections that the
conversation is "about". Persisted here rather than sent per message,
so the column survives a page reload and a new session the way the
conversation does.
Sent and stored as **identity only** (`type` + `id`); the server
normalises away any other field. Names, thumbnails, and content are
never stored, and neither is any access decision.
A pin is a **bookmark, not a grant**. Every entry is re-resolved from
scratch on every turn, under the caller's live permissions:
- an item deleted since it was pinned drops out of that turn;
- an item the caller has since lost access to drops out;
- visibility tiers are re-derived per turn — the stored pin
carries none.
Dropped entries are silently omitted from the model's context rather
than reported, so the assistant never learns that something it cannot
see exists. The stored list is left intact, so regaining access
restores the pin without re-pinning.
Sending `contextItems` replaces the topic's pins wholesale. An empty
array clears them. Only project-scoped topics resolve pins at all;
workspace- and social-scoped topics have no project to resolve
against and ignore them.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PATCH /ai/chat/topics/{topicId}
Rename, archive, or set the context pins of an AI chat topic.
At least one of `title`, `archived`, or `contextItems` must be
provided. Only the topic's creator may update it; any other caller
receives `forbidden`.
## Context pins (`contextItems`)
The items the user has pinned to Nu's Context column for this topic —
assets, folders, people, submissions, and public collections that the
conversation is "about". Persisted here rather than sent per message,
so the column survives a page reload and a new session the way the
conversation does.
Sent and stored as **identity only** (`type` + `id`); the server
normalises away any other field. Names, thumbnails, and content are
never stored, and neither is any access decision.
A pin is a **bookmark, not a grant**. Every entry is re-resolved from
scratch on every turn, under the caller's live permissions:
- an item deleted since it was pinned drops out of that turn;
- an item the caller has since lost access to drops out;
- visibility tiers are re-derived per turn — the stored pin
carries none.
Dropped entries are silently omitted from the model's context rather
than reported, so the assistant never learns that something it cannot
see exists. The stored list is left intact, so regaining access
restores the pin without re-pinning.
Sending `contextItems` replaces the topic's pins wholesale. An empty
array clears them. Only project-scoped topics resolve pins at all;
workspace- and social-scoped topics have no project to resolve
against and ignore them.
# Create a new (empty) AI chat topic. (/docs/reference/api/ai/post-ai-chat-topics)
Creates a new, empty topic. Send the first message through
`POST /v1/chats/{topic.chatId}/new-message`; the assistant's reply
arrives asynchronously as an `aiChatMessageCreate` notification (see
the AI overview). The balance check runs when a message is sent, so
no credits are charged by this endpoint.
The first user/assistant exchange triggers an auto-naming pass; the
resulting title arrives via the `aiChatTopicUpdate` notification.
Requires access to the scope (`canGetProject` / `canGetWorkspace` on
`scopeId`; no check for `social`), an active subscription, the `ai`
capability and `aiChatEnabled`.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /ai/chat/topics
Create a new (empty) AI chat topic.
Creates a new, empty topic. Send the first message through
`POST /v1/chats/{topic.chatId}/new-message`; the assistant's reply
arrives asynchronously as an `aiChatMessageCreate` notification (see
the AI overview). The balance check runs when a message is sent, so
no credits are charged by this endpoint.
The first user/assistant exchange triggers an auto-naming pass; the
resulting title arrives via the `aiChatTopicUpdate` notification.
Requires access to the scope (`canGetProject` / `canGetWorkspace` on
`scopeId`; no check for `social`), an active subscription, the `ai`
capability and `aiChatEnabled`.
# One turn of a Compose-with-Nu drafting conversation. (/docs/reference/api/ai/post-ai-compose)
Nu helps the user draft a message for a specific chat. The client sends
the drafting conversation so far (`messages`, oldest first); the server
reads the target chat for context and tone and returns Nu's commentary
(`text`) plus, when it has one, a `proposal` — the message Nu suggests
posting. Nothing is posted; the user decides whether the proposal
reaches their composer.
Requires `canAiComposeMessage` on the workspace, an active
subscription, the `ai` capability, `aiComposeEnabled` (and
`aiComposeAllowReviewer` for reviewers) and sufficient balance — see
the AI overview. The caller must also be able to read `chatId`, so
you can only compose into a chat you can already read.
Caps: 1–40 turns; each turn's `text` / `proposal` ≤ 4000 characters.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /ai/compose
One turn of a Compose-with-Nu drafting conversation.
Nu helps the user draft a message for a specific chat. The client sends
the drafting conversation so far (`messages`, oldest first); the server
reads the target chat for context and tone and returns Nu's commentary
(`text`) plus, when it has one, a `proposal` — the message Nu suggests
posting. Nothing is posted; the user decides whether the proposal
reaches their composer.
Requires `canAiComposeMessage` on the workspace, an active
subscription, the `ai` capability, `aiComposeEnabled` (and
`aiComposeAllowReviewer` for reviewers) and sufficient balance — see
the AI overview. The caller must also be able to read `chatId`, so
you can only compose into a chat you can already read.
Caps: 1–40 turns; each turn's `text` / `proposal` ≤ 4000 characters.
# Rate one assistant reply (Nu Feedback). (/docs/reference/api/ai/post-ai-feedback)
Records a thumbs-up / thumbs-down on a single assistant reply, together
with a **snapshot of the interaction that produced it**, for the Nurama
team to review.
**What gets stored.** The reply being rated, up to ten preceding turns
of the conversation, and — when the client supplies them — the page
context and pinned Context-column items that were in play at the time.
Each captured message is truncated at 4,000 characters. Tell the user
before submitting that context from the interaction will be shared
with the Nurama team for review.
The interaction is **snapshotted, not referenced**: the record captures
what the assistant actually said at the time, and remains useful if
the chat is later deleted or the topic rewritten.
**Authorisation.** The caller must be able to read `chatId` — the same
check the chat endpoints apply. A user can only rate a reply in a chat
they can already read, so this endpoint cannot be used to capture
someone else's conversation by guessing message ids. Failure is
`403 forbidden`.
This endpoint is **not** subject to the subscription, AI-feature or
credit-balance checks that gate AI use: feedback can be submitted even
when a workspace's AI add-on has been switched off.
A snapshot that cannot be built does not fail the request — the rating is
still recorded, with `context.snapshotError: true`. Losing a thumbs-down
to a transcript read failure would be the wrong trade.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /ai/feedback
Rate one assistant reply (Nu Feedback).
Records a thumbs-up / thumbs-down on a single assistant reply, together
with a **snapshot of the interaction that produced it**, for the Nurama
team to review.
**What gets stored.** The reply being rated, up to ten preceding turns
of the conversation, and — when the client supplies them — the page
context and pinned Context-column items that were in play at the time.
Each captured message is truncated at 4,000 characters. Tell the user
before submitting that context from the interaction will be shared
with the Nurama team for review.
The interaction is **snapshotted, not referenced**: the record captures
what the assistant actually said at the time, and remains useful if
the chat is later deleted or the topic rewritten.
**Authorisation.** The caller must be able to read `chatId` — the same
check the chat endpoints apply. A user can only rate a reply in a chat
they can already read, so this endpoint cannot be used to capture
someone else's conversation by guessing message ids. Failure is
`403 forbidden`.
This endpoint is **not** subject to the subscription, AI-feature or
credit-balance checks that gate AI use: feedback can be submitted even
when a workspace's AI add-on has been switched off.
A snapshot that cannot be built does not fail the request — the rating is
still recorded, with `context.snapshotError: true`. Losing a thumbs-down
to a transcript read failure would be the wrong trade.
# Polish a draft message in the requested tone. (/docs/reference/api/ai/post-ai-polish)
Rewrites the user's draft message according to the requested tone while
preserving meaning, intent, and any technical terms. In the Nurama web
app this backs the chat composer's "Polish with Nu" button.
Returns the rewritten text plus the credits actually billed and the
workspace's balance after deduction.
Caps:
- `text` is capped at 4000 characters (~1000 input tokens).
- Output is capped at ~600 tokens server-side.
If the workspace has an `aiCustomPreprompt` configured it is prepended
as additional system context (workspace-specific guidance to the model).
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /ai/polish
Polish a draft message in the requested tone.
Rewrites the user's draft message according to the requested tone while
preserving meaning, intent, and any technical terms. In the Nurama web
app this backs the chat composer's "Polish with Nu" button.
Returns the rewritten text plus the credits actually billed and the
workspace's balance after deduction.
Caps:
- `text` is capped at 4000 characters (~1000 input tokens).
- Output is capped at ~600 tokens server-side.
If the workspace has an `aiCustomPreprompt` configured it is prepended
as additional system context (workspace-specific guidance to the model).
# Mint a Scratch upload bundle for an image-revision source frame. (/docs/reference/api/ai/post-ai-revisions-source-upload)
Returns signed multipart upload URLs the client uses to upload a
source image (a captured video frame — always JPEG) directly to
storage BEFORE calling `POST /ai/revisions` with `source.scratchId`.
The bytes never pass through the API. After uploading the parts,
complete the upload via `POST /v1/scratch/{scratchId}/complete-upload`.
Same checks as `POST /ai/revisions` minus the balance check (staging
is free): `canAiGenerateImageRevision`, an active subscription, the
`ai` capability and `aiImageRevisionEnabled`.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /ai/revisions/source-upload
Mint a Scratch upload bundle for an image-revision source frame.
Returns signed multipart upload URLs the client uses to upload a
source image (a captured video frame — always JPEG) directly to
storage BEFORE calling `POST /ai/revisions` with `source.scratchId`.
The bytes never pass through the API. After uploading the parts,
complete the upload via `POST /v1/scratch/{scratchId}/complete-upload`.
Same checks as `POST /ai/revisions` minus the balance check (staging
is free): `canAiGenerateImageRevision`, an active subscription, the
`ai` capability and `aiImageRevisionEnabled`.
# Generate an AI image revision. (/docs/reference/api/ai/post-ai-revisions)
Generate a variation of an existing image (or a captured video
frame) guided by a free-text prompt. The result is staged as a
temporary Scratch upload — call `POST /scratch/{id}/promote` to turn
the chosen revision into a real asset on the destination project
(there is no `/ai/revisions/promote` route).
`source` must contain exactly one of `url` (public media URL),
`scratchId` (an upload created via `POST /ai/revisions/source-upload`
— the preferred path for video frames; it must belong to the caller
and workspace and still be active), or `dataUrl` (deprecated legacy
path for video frames).
Requires `canAiGenerateImageRevision` on the workspace, an active
subscription, the `ai` capability, the `aiImageRevisionEnabled`
workspace/project setting (`aiImageRevisionAllowReviewer` for
reviewers) and a worst-case credit pre-check (a flat estimate).
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /ai/revisions
Generate an AI image revision.
Generate a variation of an existing image (or a captured video
frame) guided by a free-text prompt. The result is staged as a
temporary Scratch upload — call `POST /scratch/{id}/promote` to turn
the chosen revision into a real asset on the destination project
(there is no `/ai/revisions/promote` route).
`source` must contain exactly one of `url` (public media URL),
`scratchId` (an upload created via `POST /ai/revisions/source-upload`
— the preferred path for video frames; it must belong to the caller
and workspace and still be active), or `dataUrl` (deprecated legacy
path for video frames).
Requires `canAiGenerateImageRevision` on the workspace, an active
subscription, the `ai` capability, the `aiImageRevisionEnabled`
workspace/project setting (`aiImageRevisionAllowReviewer` for
reviewers) and a worst-case credit pre-check (a flat estimate).
# Convert a chat message into one or more board-task drafts. (/docs/reference/api/ai/post-ai-task-generation)
Generates a list of `{ subject, description }` task drafts from a
chat message. In the Nurama web app this backs the "Generate with Nu"
option in a message's create-task menu; the returned `tasks` array
seeds the task creator's draft list.
**Compound capability requirement.** Unlike Polish, this endpoint
requires BOTH the `boards` capability (checked against the project)
and the `ai` capability (checked against the workspace); both
`workspaceId` and `projectId` must belong to an active subscription.
Either capability missing returns `capabilityNotAvailable`.
**Context window.** `contextMessages` is the preceding chat
thread (oldest first). The server caps at 10 messages and each
entry's `content` at 8000 characters; supply the messages immediately
before the focal one so the model can resolve pronouns and references.
**Permission.** Requires `canAiGenerateTasks` (held by all
workspace/project admins and by the creator, reviewer and
reviewerAdmin roles).
**Pre-prompt.** If the workspace or project has
`aiTaskGenerationPreprompt` configured, it is appended to the
system prompt as an override block (project value wins per-key).
Separate from `aiCustomPreprompt` so admins can tune task style
without affecting Polish or Chat output.
Caps:
- `messageText` is capped at 8000 characters.
- `contextMessages` is capped at 10 entries; each entry's
`content` is capped at 8000 characters and `authorName` at 100.
- At most 10 tasks are returned.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /ai/task-generation
Convert a chat message into one or more board-task drafts.
Generates a list of `{ subject, description }` task drafts from a
chat message. In the Nurama web app this backs the "Generate with Nu"
option in a message's create-task menu; the returned `tasks` array
seeds the task creator's draft list.
**Compound capability requirement.** Unlike Polish, this endpoint
requires BOTH the `boards` capability (checked against the project)
and the `ai` capability (checked against the workspace); both
`workspaceId` and `projectId` must belong to an active subscription.
Either capability missing returns `capabilityNotAvailable`.
**Context window.** `contextMessages` is the preceding chat
thread (oldest first). The server caps at 10 messages and each
entry's `content` at 8000 characters; supply the messages immediately
before the focal one so the model can resolve pronouns and references.
**Permission.** Requires `canAiGenerateTasks` (held by all
workspace/project admins and by the creator, reviewer and
reviewerAdmin roles).
**Pre-prompt.** If the workspace or project has
`aiTaskGenerationPreprompt` configured, it is appended to the
system prompt as an override block (project value wins per-key).
Separate from `aiCustomPreprompt` so admins can tune task style
without affecting Polish or Chat output.
Caps:
- `messageText` is capped at 8000 characters.
- `contextMessages` is capped at 10 entries; each entry's
`content` is capped at 8000 characters and `authorName` at 100.
- At most 10 tasks are returned.
# Remove the custom thumbnail from an asset (/docs/reference/api/assets/delete-assets-assetid-custom-thumbnail)
Soft-deletes every active `customThumbnailOriginal` and `customThumbnail`
file on the asset by setting their status to `inactive`, decrementing the
asset's `sizeInBytes` and storage quota by the bytes that were active.
Clients should fall back to the auto-generated `thumbnail` files.
Broadcasts an `assetFileUpdate` WebSocket event so connected clients can
re-render without a refetch.
Machine-readable definition: https://docs.nurama.com/openapi.json
## DELETE /assets/{assetId}/custom-thumbnail
Remove the custom thumbnail from an asset
Soft-deletes every active `customThumbnailOriginal` and `customThumbnail`
file on the asset by setting their status to `inactive`, decrementing the
asset's `sizeInBytes` and storage quota by the bytes that were active.
Clients should fall back to the auto-generated `thumbnail` files.
Broadcasts an `assetFileUpdate` WebSocket event so connected clients can
re-render without a refetch.
# Mark asset for deletion (/docs/reference/api/assets/delete-assets-assetid)
Mark an asset as deleted.
Machine-readable definition: https://docs.nurama.com/openapi.json
## DELETE /assets/{assetId}
Mark asset for deletion
Mark an asset as deleted.
# Get a signed inline-view URL for a document asset (/docs/reference/api/assets/get-assets-assetid-document-url)
Returns a short-lived signed URL for rendering a `document` asset inline in the
viewer. Serves the processed `media` derivative (an optimised PDF with permission
flags stripped), not the original — downloads of the original go through
`POST /assets/download`. Requires `canGetAsset`.
The asset must be `active`, have `mediaType: 'document'`, and have an active
`media` file (i.e. post-processing finished successfully); otherwise a 400 is
returned and the document cannot be viewed inline.
The `media` PDF is capped at a maximum page count, so `pagesTruncated`,
`truncatedFrom` and `originalPageCount` tell the viewer whether and where pages
are missing.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /assets/{assetId}/document-url
Get a signed inline-view URL for a document asset
Returns a short-lived signed URL for rendering a `document` asset inline in the
viewer. Serves the processed `media` derivative (an optimised PDF with permission
flags stripped), not the original — downloads of the original go through
`POST /assets/download`. Requires `canGetAsset`.
The asset must be `active`, have `mediaType: 'document'`, and have an active
`media` file (i.e. post-processing finished successfully); otherwise a 400 is
returned and the document cannot be viewed inline.
The `media` PDF is capped at a maximum page count, so `pagesTruncated`,
`truncatedFrom` and `originalPageCount` tell the viewer whether and where pages
are missing.
# Get file from asset (/docs/reference/api/assets/get-assets-assetid-file-fileid)
Retrieve a specific file from an asset by asset ID and file ID. Requires `canGetAsset`.
Private fields (`bucketName`, `tags`, `postProcessingTasks`) are stripped from the response.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /assets/{assetId}/file/{fileId}
Get file from asset
Retrieve a specific file from an asset by asset ID and file ID. Requires `canGetAsset`.
Private fields (`bucketName`, `tags`, `postProcessingTasks`) are stripped from the response.
# Get files by function type (/docs/reference/api/assets/get-assets-assetid-function-type-functiontype)
Retrieve all files from an asset filtered by function type. Requires `canGetAsset`.
Private fields (`bucketName`, `tags`, `postProcessingTasks`) are stripped from each file.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /assets/{assetId}/function-type/{functionType}
Get files by function type
Retrieve all files from an asset filtered by function type. Requires `canGetAsset`.
Private fields (`bucketName`, `tags`, `postProcessingTasks`) are stripped from each file.
# List every location an asset is referenced (/docs/reference/api/assets/get-assets-assetid-references)
One asset can be referenced from many places at once — its own folder, the reviewer tree, any submission it was added to, any public release it was shared in. They all point at the same asset, which is why renaming it retitles it everywhere, and why deleting the last reference in its primary file system removes the rest.
PRIMARY references are the asset's home file system; SECONDARY are everything else, grouped by collection. Only collections with at least one reference appear in `counts`.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /assets/{assetId}/references
List every location an asset is referenced
One asset can be referenced from many places at once — its own folder, the reviewer tree, any submission it was added to, any public release it was shared in. They all point at the same asset, which is why renaming it retitles it everywhere, and why deleting the last reference in its primary file system removes the rest.
PRIMARY references are the asset's home file system; SECONDARY are everything else, grouped by collection. Only collections with at least one reference appear in `counts`.
# Get asset information with optional chat data (/docs/reference/api/assets/get-assets-assetid)
Retrieve information for a specific asset by ID. Optionally include chat data by specifying chatVisibility.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /assets/{assetId}
Get asset information with optional chat data
Retrieve information for a specific asset by ID. Optionally include chat data by specifying chatVisibility.
# Get the page an asset would appear on in paginated results. (/docs/reference/api/assets/get-assets-page-assetid)
Returns the 1-based page number the asset would appear on when listing assets of the
same owner resource and media type with the given sort and page size. Requires `canGetAsset`.
The asset must be `active`.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /assets/page/{assetId}
Get the page an asset would appear on in paginated results.
Returns the 1-based page number the asset would appear on when listing assets of the
same owner resource and media type with the given sort and page size. Requires `canGetAsset`.
The asset must be `active`.
# Finalize the multipart upload of a custom thumbnail (/docs/reference/api/assets/post-assets-assetid-custom-thumbnail-complete-upload)
Commits the multipart upload of a custom thumbnail. Background processing
then generates the sized `customThumbnail` files and registers them on the
asset. Unlike `/v1/assets/complete-upload`, this does not register an
original file on the asset and does not trigger media transcoding.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /assets/{assetId}/custom-thumbnail/complete-upload
Finalize the multipart upload of a custom thumbnail
Commits the multipart upload of a custom thumbnail. Background processing
then generates the sized `customThumbnail` files and registers them on the
asset. Unlike `/v1/assets/complete-upload`, this does not register an
original file on the asset and does not trigger media transcoding.
# Mint a signed multipart upload URL for a custom thumbnail (/docs/reference/api/assets/post-assets-assetid-custom-thumbnail-upload-url)
Returns a multipart upload URL set for a user-supplied custom thumbnail
image. Once the upload is finalized via
`POST /assets/{assetId}/custom-thumbnail/complete-upload`, background
processing generates the sized `customThumbnail` files and registers
them on the asset.
Side effect: any prior active `customThumbnailOriginal` / `customThumbnail`
files on the asset are set to `inactive` before the URL is issued so the
new upload replaces them cleanly. If the upload is abandoned, the asset's
auto-generated `thumbnail` files remain and should be displayed instead.
Custom thumbnails are only supported for `video` and `audio` assets.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /assets/{assetId}/custom-thumbnail/upload-url
Mint a signed multipart upload URL for a custom thumbnail
Returns a multipart upload URL set for a user-supplied custom thumbnail
image. Once the upload is finalized via
`POST /assets/{assetId}/custom-thumbnail/complete-upload`, background
processing generates the sized `customThumbnail` files and registers
them on the asset.
Side effect: any prior active `customThumbnailOriginal` / `customThumbnail`
files on the asset are set to `inactive` before the URL is issued so the
new upload replaces them cleanly. If the upload is abandoned, the asset's
auto-generated `thumbnail` files remain and should be displayed instead.
Custom thumbnails are only supported for `video` and `audio` assets.
# Promote a chat-message attachment to a project asset (/docs/reference/api/assets/post-assets-assetid-promote-to-project)
Copies a chat-message attachment (an asset with `ownerResourceType: 'chat'` and
`functionType: 'attachment'`) into the destination project as a new, fully
independent project asset. Deleting either side afterwards has no effect on the other.
Permission is `canCreateAsset` on the destination project (`body.projectId`), which
excludes reviewers. The source chat must live in the same workspace as the
destination project.
Idempotent: promoting the same source into the same project again returns the
existing promoted asset with `deduped: true`. When post-processing is required the
new asset is returned before it is `active`; the usual asset activation notifications
fire when processing completes.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /assets/{assetId}/promote-to-project
Promote a chat-message attachment to a project asset
Copies a chat-message attachment (an asset with `ownerResourceType: 'chat'` and
`functionType: 'attachment'`) into the destination project as a new, fully
independent project asset. Deleting either side afterwards has no effect on the other.
Permission is `canCreateAsset` on the destination project (`body.projectId`), which
excludes reviewers. The source chat must live in the same workspace as the
destination project.
Idempotent: promoting the same source into the same project again returns the
existing promoted asset with `deduped: true`. When post-processing is required the
new asset is returned before it is `active`; the usual asset activation notifications
fire when processing completes.
# Complete multipart upload (/docs/reference/api/assets/post-assets-complete-upload)
Complete a multipart upload for an asset file.
This endpoint finalizes the multipart upload by combining all uploaded parts,
registers the original file on the asset (`assetId` is required) and triggers
asset completion and media post-processing.
**Two-step workflow:**
1. Upload the file parts to the signed URLs returned when the asset was created
2. Call this endpoint with `assetId` to complete the upload and trigger processing
Post-processing failures after the upload has been committed do not fail the
request — they are reported via the optional `warning` field.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /assets/complete-upload
Complete multipart upload
Complete a multipart upload for an asset file.
This endpoint finalizes the multipart upload by combining all uploaded parts,
registers the original file on the asset (`assetId` is required) and triggers
asset completion and media post-processing.
**Two-step workflow:**
1. Upload the file parts to the signed URLs returned when the asset was created
2. Call this endpoint with `assetId` to complete the upload and trigger processing
Post-processing failures after the upload has been committed do not fail the
request — they are reported via the optional `warning` field.
# Download assets (/docs/reference/api/assets/post-assets-download)
Generate download links for the specified assets/files. Requires `canDownloadAssets`.
Side effect: a `download` event is recorded in each asset's access activity
with the `visibility` given in the request body (defaults to `creator`).
Recording the activity never affects the download response.
Note: the request body is currently accepted without validation; the limits
below reflect the intended contract.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /assets/download
Download assets
Generate download links for the specified assets/files. Requires `canDownloadAssets`.
Side effect: a `download` event is recorded in each asset's access activity
with the `visibility` given in the request body (defaults to `creator`).
Recording the activity never affects the download response.
Note: the request body is currently accepted without validation; the limits
below reflect the intended contract.
# Bulk regenerate signed upload links for assets in status pendingUpload. (/docs/reference/api/assets/post-assets-repair)
Marks every existing file on each asset `pendingDelete` and mints a fresh multipart
upload URL set so the client can re-upload the original. Requires `canRepairAssets`.
Per-asset failures are reported inline (`status: 'error'`) rather than failing the request.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /assets/repair
Bulk regenerate signed upload links for assets in status pendingUpload.
Marks every existing file on each asset `pendingDelete` and mints a fresh multipart
upload URL set so the client can re-upload the original. Requires `canRepairAssets`.
Per-asset failures are reported inline (`status: 'error'`) rather than failing the request.
# Add tag to asset (/docs/reference/api/assets/put-assets-assetid-tag)
Add a tag to an asset.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /assets/{assetId}/tag
Add tag to asset
Add a tag to an asset.
# Remove tag from asset (/docs/reference/api/assets/put-assets-assetid-untag)
Remove a tag from an asset.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /assets/{assetId}/untag
Remove tag from asset
Remove a tag from an asset.
# Update asset (/docs/reference/api/assets/put-assets-assetid)
Modify an existing asset (name, meta, sizeInBytes, status). Requires `canUpdateAsset`.
`status` cannot be set to `pendingDelete` here — deletion goes through `DELETE /assets/{assetId}`.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /assets/{assetId}
Update asset
Modify an existing asset (name, meta, sizeInBytes, status). Requires `canUpdateAsset`.
`status` cannot be set to `pendingDelete` here — deletion goes through `DELETE /assets/{assetId}`.
# Delete a column (/docs/reference/api/board-columns/delete-boards-boardid-columns-columnid)
Deletes a column and moves its tasks to `targetColumnId` when given, otherwise to the default column, otherwise to any remaining column. Deleting the last column is rejected (`invalidBoard`).
Machine-readable definition: https://docs.nurama.com/openapi.json
## DELETE /boards/{boardId}/columns/{columnId}
Delete a column
Deletes a column and moves its tasks to `targetColumnId` when given, otherwise to the default column, otherwise to any remaining column. Deleting the last column is rejected (`invalidBoard`).
# Add a column to a board (/docs/reference/api/board-columns/post-boards-boardid-columns)
Adds a new column to the board. If sortOrder is not provided, it is placed after the last column.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /boards/{boardId}/columns
Add a column to a board
Adds a new column to the board. If sortOrder is not provided, it is placed after the last column.
# Update a column (/docs/reference/api/board-columns/put-boards-boardid-columns-columnid)
Update column name, description, color, isDefault, taskStatus, sortOrder, or reviewersCanContribute.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /boards/{boardId}/columns/{columnId}
Update a column
Update column name, description, color, isDefault, taskStatus, sortOrder, or reviewersCanContribute.
# Reorder columns (/docs/reference/api/board-columns/put-boards-boardid-columns-reorder)
Updates the sortOrder of multiple columns at once.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /boards/{boardId}/columns/reorder
Reorder columns
Updates the sortOrder of multiple columns at once.
# Follow a board (/docs/reference/api/board-following/put-boards-boardid-follow)
Add the current user to the board's followers list. Idempotent — following again has no effect. Board followers receive email notifications when new tasks are created.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /boards/{boardId}/follow
Follow a board
Add the current user to the board's followers list. Idempotent — following again has no effect. Board followers receive email notifications when new tasks are created.
# Unfollow a board (/docs/reference/api/board-following/put-boards-boardid-unfollow)
Remove the current user from the board's followers list.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /boards/{boardId}/unfollow
Unfollow a board
Remove the current user from the board's followers list.
# Remove a task from a board (/docs/reference/api/board-tasks/delete-boards-boardid-tasks-taskid)
Unlinks a task from the board by setting boardId and columnId to null. The task itself is not deleted.
Machine-readable definition: https://docs.nurama.com/openapi.json
## DELETE /boards/{boardId}/tasks/{taskId}
Remove a task from a board
Unlinks a task from the board by setting boardId and columnId to null. The task itself is not deleted.
# Get tasks for a board (/docs/reference/api/board-tasks/get-boards-boardid-tasks)
Returns all tasks on a board, optionally filtered by column, status, assignee, search, or tags. Tasks are populated with creator, assignedTo, and project. API tokens need the `tasks:read` scope.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /boards/{boardId}/tasks
Get tasks for a board
Returns all tasks on a board, optionally filtered by column, status, assignee, search, or tags. Tasks are populated with creator, assignedTo, and project. API tokens need the `tasks:read` scope.
# Search tasks across all boards in a project (/docs/reference/api/board-tasks/get-boards-project-projectid-tasks)
Returns paginated tasks across all boards in a project. Supports search,
board/status/assignee/tag filters. By default only tasks that belong to a
board are returned; pass `boardId=unassigned` to get the orphaned (no
board) tasks instead.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /boards/project/{projectId}/tasks
Search tasks across all boards in a project
Returns paginated tasks across all boards in a project. Supports search,
board/status/assignee/tag filters. By default only tasks that belong to a
board are returned; pass `boardId=unassigned` to get the orphaned (no
board) tasks instead.
# Add an existing task to a board (/docs/reference/api/board-tasks/post-boards-boardid-tasks-add)
Links an existing project task to a board column. If the task does not have a taskNumber, one is assigned.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /boards/{boardId}/tasks/add
Add an existing task to a board
Links an existing project task to a board column. If the task does not have a taskNumber, one is assigned.
# Create a task on a board (/docs/reference/api/board-tasks/post-boards-boardid-tasks)
Creates a new task and places it on the board. If no columnId is specified, the task
is placed in the default column. Auto-assigns an incrementing taskNumber. API tokens
need the `tasks:write` scope. Reviewers can only create tasks in columns flagged
`reviewersCanContribute` (403 `reviewerCannotContributeHere`); an assignee who cannot
see the board's visibility is rejected (400 `invalidAssignee`).
When `announce` is provided, an assistant reply carrying the new task is posted in
`announce.chatId` as a reply to `announce.messageId`; announce failures never fail
the request.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /boards/{boardId}/tasks
Create a task on a board
Creates a new task and places it on the board. If no columnId is specified, the task
is placed in the default column. Auto-assigns an incrementing taskNumber. API tokens
need the `tasks:write` scope. Reviewers can only create tasks in columns flagged
`reviewersCanContribute` (403 `reviewerCannotContributeHere`); an assignee who cannot
see the board's visibility is rejected (400 `invalidAssignee`).
When `announce` is provided, an assistant reply carrying the new task is posted in
`announce.chatId` as a reply to `announce.messageId`; announce failures never fail
the request.
# Move a task to a different column (or board) (/docs/reference/api/board-tasks/put-boards-boardid-tasks-taskid-move)
Moves a task to a new column and optionally sets its position. Pass `targetBoardId`
to move the task onto another board in the same project; `columnId` then defaults to
the target board's default column and the caller must also hold `canMove*BoardTask`
for the target board's visibility (403 otherwise). Without `targetBoardId`,
`columnId` is required.
If the destination column has a `taskStatus`, the task's `status` is set to that
value; otherwise the status is left unchanged.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /boards/{boardId}/tasks/{taskId}/move
Move a task to a different column (or board)
Moves a task to a new column and optionally sets its position. Pass `targetBoardId`
to move the task onto another board in the same project; `columnId` then defaults to
the target board's default column and the caller must also hold `canMove*BoardTask`
for the target board's visibility (403 otherwise). Without `targetBoardId`,
`columnId` is required.
If the destination column has a `taskStatus`, the task's `status` is set to that
value; otherwise the status is left unchanged.
# Delete a board (/docs/reference/api/boards/delete-boards-boardid)
Deletes a board and its columns. The optional body controls what happens
to tasks on the board:
- `unassign` (default) — set `boardId` and `columnId` to null on each task. Tasks are kept.
- `delete` — delete every task on the board, plus its TaskRelation, TaskLink, and TaskEvent rows.
- `reassign` — move tasks to `targetBoardId` / `targetColumnId` (defaults to the target's default column). If the target column has a `taskStatus`, the task's `status` is updated to match.
For `reassign`, the caller must also have Update access on the target board's tasks
(`targetBoardRequired` when `targetBoardId` is missing, `targetBoardSameAsSource`
when it equals the board being deleted). Requires `canDelete{Creator|Reviewer}Board`.
Machine-readable definition: https://docs.nurama.com/openapi.json
## DELETE /boards/{boardId}
Delete a board
Deletes a board and its columns. The optional body controls what happens
to tasks on the board:
- `unassign` (default) — set `boardId` and `columnId` to null on each task. Tasks are kept.
- `delete` — delete every task on the board, plus its TaskRelation, TaskLink, and TaskEvent rows.
- `reassign` — move tasks to `targetBoardId` / `targetColumnId` (defaults to the target's default column). If the target column has a `taskStatus`, the task's `status` is updated to match.
For `reassign`, the caller must also have Update access on the target board's tasks
(`targetBoardRequired` when `targetBoardId` is missing, `targetBoardSameAsSource`
when it equals the board being deleted). Requires `canDelete{Creator|Reviewer}Board`.
# Get a board with columns and tasks (/docs/reference/api/boards/get-boards-boardid)
Returns a board with all its columns and tasks grouped by column. Tasks are populated with creator, assignedTo, and project.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /boards/{boardId}
Get a board with columns and tasks
Returns a board with all its columns and tasks grouped by column. Tasks are populated with creator, assignedTo, and project.
# Get boards for a project (/docs/reference/api/boards/get-boards-project-projectid)
Returns all active boards for a project, filtered by the user's visibility role. Each board includes its columns. Optional search and tags filters.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /boards/project/{projectId}
Get boards for a project
Returns all active boards for a project, filtered by the user's visibility role. Each board includes its columns. Optional search and tags filters.
# Create a new board (/docs/reference/api/boards/post-boards)
Creates a new kanban board for a project with default or custom columns. Default columns are Backlog, To Do, In Progress, In Review, and Done.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /boards
Create a new board
Creates a new kanban board for a project with default or custom columns. Default columns are Backlog, To Do, In Progress, In Review, and Done.
# Tag a board (/docs/reference/api/boards/put-boards-boardid-tag)
Add a project tag to a board. Idempotent — tagging again has no effect.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /boards/{boardId}/tag
Tag a board
Add a project tag to a board. Idempotent — tagging again has no effect.
# Untag a board (/docs/reference/api/boards/put-boards-boardid-untag)
Remove a project tag from a board.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /boards/{boardId}/untag
Untag a board
Remove a project tag from a board.
# Update a board (/docs/reference/api/boards/put-boards-boardid)
Update board name, description, visibility, status, or sort order. Requires
`canUpdate{Creator|Reviewer}Board` for the board's visibility.
Narrowing `visibility` when tasks, assignees or task relations depend on the
removed tier returns 409 `boardVisibilityChangeBlocked`. Re-issue the request with
`cascade: true` to apply the cleanup automatically (re-stamp tasks, unassign blocked
assignees, delete blocked relations); the applied cleanup is reported in the
response's `cascade` field.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /boards/{boardId}
Update a board
Update board name, description, visibility, status, or sort order. Requires
`canUpdate{Creator|Reviewer}Board` for the board's visibility.
Narrowing `visibility` when tasks, assignees or task relations depend on the
removed tier returns 409 `boardVisibilityChangeBlocked`. Re-issue the request with
`cascade: true` to apply the cleanup automatically (re-stamp tasks, unassign blocked
assignees, delete blocked relations); the applied cleanup is reported in the
response's `cascade` field.
# Remove the bot from a project (/docs/reference/api/bots/delete-workspaces-workspaceid-bots-botid-memberships-project-projectid)
Machine-readable definition: https://docs.nurama.com/openapi.json
## DELETE /workspaces/{workspaceId}/bots/{botId}/memberships/project/{projectId}
Remove the bot from a project
# Delete a bot user (/docs/reference/api/bots/delete-workspaces-workspaceid-bots-botid)
Revokes all API keys for the bot, removes the workspace membership, and marks the user `inactive`.
Machine-readable definition: https://docs.nurama.com/openapi.json
## DELETE /workspaces/{workspaceId}/bots/{botId}
Delete a bot user
Revokes all API keys for the bot, removes the workspace membership, and marks the user `inactive`.
# List the bot's project memberships (/docs/reference/api/bots/get-workspaces-workspaceid-bots-botid-memberships)
Project memberships of the bot, limited to projects that belong to this workspace.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /workspaces/{workspaceId}/bots/{botId}/memberships
List the bot's project memberships
Project memberships of the bot, limited to projects that belong to this workspace.
# Get a single bot user (/docs/reference/api/bots/get-workspaces-workspaceid-bots-botid)
Returns bot profile, workspace roles, and API key metadata (no secrets).
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /workspaces/{workspaceId}/bots/{botId}
Get a single bot user
Returns bot profile, workspace roles, and API key metadata (no secrets).
# List bot users in a workspace (/docs/reference/api/bots/get-workspaces-workspaceid-bots)
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /workspaces/{workspaceId}/bots
List bot users in a workspace
# Set the bot's avatar (/docs/reference/api/bots/post-workspaces-workspaceid-bots-botid-avatar)
Creates an avatar asset for the bot and returns signed multipart upload URLs; the caller then uploads the image bytes directly to those URLs. The returned `user` carries the new (still `pendingUpload`) avatar asset so the client can render it optimistically; the processed thumbnail arrives via the `userAvatarUpdate` WebSocket event.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /workspaces/{workspaceId}/bots/{botId}/avatar
Set the bot's avatar
Creates an avatar asset for the bot and returns signed multipart upload URLs; the caller then uploads the image bytes directly to those URLs. The returned `user` carries the new (still `pendingUpload`) avatar asset so the client can render it optimistically; the processed thumbnail arrives via the `userAvatarUpdate` WebSocket event.
# Rotate the bot's API key (/docs/reference/api/bots/post-workspaces-workspaceid-bots-botid-rotate-key)
Revokes the bot's current active API key and issues a new one. The new raw key is returned once.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /workspaces/{workspaceId}/bots/{botId}/rotate-key
Rotate the bot's API key
Revokes the bot's current active API key and issues a new one. The new raw key is returned once.
# Create a bot user in a workspace (/docs/reference/api/bots/post-workspaces-workspaceid-bots)
Creates a bot user, assigns workspace membership with the supplied roles, and issues a single API key. The raw key is returned **once** in the response and is never retrievable again — store it immediately.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /workspaces/{workspaceId}/bots
Create a bot user in a workspace
Creates a bot user, assigns workspace membership with the supplied roles, and issues a single API key. The raw key is returned **once** in the response and is never retrievable again — store it immediately.
# Add the bot to a project or replace its project roles (/docs/reference/api/bots/put-workspaces-workspaceid-bots-botid-memberships-project-projectid)
Upserts the bot's membership on the project. If a membership already exists its role list is replaced. `projectOwner` and `reviewerAdmin` cannot be granted to bots.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /workspaces/{workspaceId}/bots/{botId}/memberships/project/{projectId}
Add the bot to a project or replace its project roles
Upserts the bot's membership on the project. If a membership already exists its role list is replaced. `projectOwner` and `reviewerAdmin` cannot be granted to bots.
# Update a bot user (/docs/reference/api/bots/put-workspaces-workspaceid-bots-botid)
Update the bot's display name and/or color. At least one field must be supplied.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /workspaces/{workspaceId}/bots/{botId}
Update a bot user
Update the bot's display name and/or color. At least one field must be supplied.
# Mark chat for deletion. Only chat creators may delete a chat. (/docs/reference/api/chats/delete-chats-chatid)
Machine-readable definition: https://docs.nurama.com/openapi.json
## DELETE /chats/{chatId}
Mark chat for deletion. Only chat creators may delete a chat.
# Mark member chat for deletion. From the user's perspective the chat will have been deleted. Only chat creators may delete a chat. (/docs/reference/api/chats/delete-chats-member-chatid)
Machine-readable definition: https://docs.nurama.com/openapi.json
## DELETE /chats/member/{chatId}
Mark member chat for deletion. From the user's perspective the chat will have been deleted. Only chat creators may delete a chat.
# Delete an array of members from a member chat by user ID. (/docs/reference/api/chats/delete-chats-member-members-chatid)
Machine-readable definition: https://docs.nurama.com/openapi.json
## DELETE /chats/member/members/{chatId}
Delete an array of members from a member chat by user ID.
# Remove an attachment from a message (/docs/reference/api/chats/delete-chats-message-messageid-attachment-assetid)
Removes the asset from the message's attachments and marks the asset for deletion. If the message has no content and no attachments left afterwards, the message itself is marked for deletion and the deleted message is returned.
Machine-readable definition: https://docs.nurama.com/openapi.json
## DELETE /chats/message/{messageId}/attachment/{assetId}
Remove an attachment from a message
Removes the asset from the message's attachments and marks the asset for deletion. If the message has no content and no attachments left afterwards, the message itself is marked for deletion and the deleted message is returned.
# Remove a user's reaction from a chat message (/docs/reference/api/chats/delete-chats-message-messageid-reaction)
Removes the authenticated user's reaction from the specified chat message. Only the user who created the reaction can remove it.
Machine-readable definition: https://docs.nurama.com/openapi.json
## DELETE /chats/message/{messageId}/reaction
Remove a user's reaction from a chat message
Removes the authenticated user's reaction from the specified chat message. Only the user who created the reaction can remove it.
# Delete a message (/docs/reference/api/chats/delete-chats-message-messageid)
Marks the message for deletion. It is removed later by the cleanup service.
Machine-readable definition: https://docs.nurama.com/openapi.json
## DELETE /chats/message/{messageId}
Delete a message
Marks the message for deletion. It is removed later by the cleanup service.
# Get mentionable assets for a chat with pagination (/docs/reference/api/chats/get-chats-chatid-mentionable-assets)
Returns a paginated list of assets that can be mentioned in the specified chat. The assets returned depend on the chat type:
- **Topic chat about a project**: Returns assets from that project with matching visibility
- **Topic chat about an asset**: Returns assets from the asset's owner project with matching visibility
- **Member chat with project scope**: Returns all assets from that project (all visibilities)
- **Submission chat**: Returns all assets from the project (all visibilities)
- **AI chat (Nu Chat)**: Returns assets from the topic's project, filtered to the
**caller's own** visibility tiers. A workspace- or social-scoped topic has no
project to resolve against and returns an empty array.
Unlike every other chat type above, an AI chat has no meaningful visibility of
its own to inherit — its backing `Chat` row is created with a fixed `creator`
placeholder, identical for every user — so tiers are derived from the caller's
inherited permissions instead. Owning the topic is not on its own evidence of
creator-tier access to the project.
- **Member chat with workspace/social scope**: Returns empty array (no assets are mentionable)
Only active assets are returned. Supports both cursor-based and index-based pagination, plus name filtering.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /chats/{chatId}/mentionable/assets
Get mentionable assets for a chat with pagination
Returns a paginated list of assets that can be mentioned in the specified chat. The assets returned depend on the chat type:
- **Topic chat about a project**: Returns assets from that project with matching visibility
- **Topic chat about an asset**: Returns assets from the asset's owner project with matching visibility
- **Member chat with project scope**: Returns all assets from that project (all visibilities)
- **Submission chat**: Returns all assets from the project (all visibilities)
- **AI chat (Nu Chat)**: Returns assets from the topic's project, filtered to the
**caller's own** visibility tiers. A workspace- or social-scoped topic has no
project to resolve against and returns an empty array.
Unlike every other chat type above, an AI chat has no meaningful visibility of
its own to inherit — its backing `Chat` row is created with a fixed `creator`
placeholder, identical for every user — so tiers are derived from the caller's
inherited permissions instead. Owning the topic is not on its own evidence of
creator-tier access to the project.
- **Member chat with workspace/social scope**: Returns empty array (no assets are mentionable)
Only active assets are returned. Supports both cursor-based and index-based pagination, plus name filtering.
# Get mentionable folders for a chat with pagination (/docs/reference/api/chats/get-chats-chatid-mentionable-folders)
Returns a paginated list of folders that can be mentioned in the specified chat. The folders returned depend on the chat type:
- **Topic chat about a project**: Returns folders from that project with matching visibility
- **Topic chat about an asset**: Returns folders from the asset's owner project with matching visibility
- **Member chat with project scope**: Returns all folders from that project (all visibilities)
- **Submission chat**: Returns reviewer-visibility folders from the project
- **AI chat (Nu Chat)**: Returns folders from the topic's project, filtered to the
**caller's own** visibility tiers. A workspace- or social-scoped topic has no
project to resolve against and returns an empty array.
Unlike every other chat type above, an AI chat has no meaningful visibility of
its own to inherit — its backing `Chat` row is created with a fixed `creator`
placeholder, identical for every user — so tiers are derived from the caller's
inherited permissions instead. Owning the topic is not on its own evidence of
creator-tier access to the project.
- **Member chat with workspace/social scope**: Returns empty array (no folders are mentionable)
Only active folders are returned. Supports both cursor-based and index-based pagination, plus name filtering.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /chats/{chatId}/mentionable/folders
Get mentionable folders for a chat with pagination
Returns a paginated list of folders that can be mentioned in the specified chat. The folders returned depend on the chat type:
- **Topic chat about a project**: Returns folders from that project with matching visibility
- **Topic chat about an asset**: Returns folders from the asset's owner project with matching visibility
- **Member chat with project scope**: Returns all folders from that project (all visibilities)
- **Submission chat**: Returns reviewer-visibility folders from the project
- **AI chat (Nu Chat)**: Returns folders from the topic's project, filtered to the
**caller's own** visibility tiers. A workspace- or social-scoped topic has no
project to resolve against and returns an empty array.
Unlike every other chat type above, an AI chat has no meaningful visibility of
its own to inherit — its backing `Chat` row is created with a fixed `creator`
placeholder, identical for every user — so tiers are derived from the caller's
inherited permissions instead. Owning the topic is not on its own evidence of
creator-tier access to the project.
- **Member chat with workspace/social scope**: Returns empty array (no folders are mentionable)
Only active folders are returned. Supports both cursor-based and index-based pagination, plus name filtering.
# Get mentionable public releases for a chat (/docs/reference/api/chats/get-chats-chatid-mentionable-publics)
Returns a paginated list of active public releases (share links) owned by the chat's project that can be mentioned with
`{{publicMention:token}}` tokens. The project is resolved from the chat the same way as for mentionable submissions.
Chats without a project scope return an empty page. Index pagination only.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /chats/{chatId}/mentionable/publics
Get mentionable public releases for a chat
Returns a paginated list of active public releases (share links) owned by the chat's project that can be mentioned with
`{{publicMention:token}}` tokens. The project is resolved from the chat the same way as for mentionable submissions.
Chats without a project scope return an empty page. Index pagination only.
# Get mentionable submissions for a chat (/docs/reference/api/chats/get-chats-chatid-mentionable-submissions)
Returns a paginated list of active submissions in the chat's project that can be mentioned with `{{submissionMention:submissionId}}` tokens.
The project is resolved from the chat (project/asset/task topic chats, project-scoped member chats, submission chats and project-scoped AI chats).
Chats without a project scope return an empty page. Index pagination only.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /chats/{chatId}/mentionable/submissions
Get mentionable submissions for a chat
Returns a paginated list of active submissions in the chat's project that can be mentioned with `{{submissionMention:submissionId}}` tokens.
The project is resolved from the chat (project/asset/task topic chats, project-scoped member chats, submission chats and project-scoped AI chats).
Chats without a project scope return an empty page. Index pagination only.
# Get mentionable board tasks for a chat with pagination (/docs/reference/api/chats/get-chats-chatid-mentionable-tasks)
Returns a paginated list of board tasks that can be mentioned in the specified chat. Requires the workspace to have the `boards` capability.
Scope/visibility rules:
- **Topic chat about a project**: Tasks in that project on boards whose `visibility` array includes the chat's visibility.
- **Topic chat about an asset**: Tasks in the asset's owner project on boards whose `visibility` array includes the chat's visibility.
- **Topic chat about a task**: Sibling tasks in the parent task's project on boards whose `visibility` array includes the chat's visibility.
- **Member chat with project scope**: All board tasks in that project (no visibility filter — mirrors asset/folder mention behaviour for this chat type).
- **Submission chat**: Tasks in the submission's project on boards whose `visibility` array includes `'reviewer'`.
- **Member chat with workspace/social scope**: Empty result — no tasks are mentionable.
Legacy mention-only tasks (`boardId === null`) are never returned. The `nameSearch` query is OR-matched across `subject` substring, exact `taskNumber` (when numeric), and exact `id` (when a UUID).
Returns `capabilityNotAvailable` / 403 when the workspace lacks the `boards` capability.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /chats/{chatId}/mentionable/tasks
Get mentionable board tasks for a chat with pagination
Returns a paginated list of board tasks that can be mentioned in the specified chat. Requires the workspace to have the `boards` capability.
Scope/visibility rules:
- **Topic chat about a project**: Tasks in that project on boards whose `visibility` array includes the chat's visibility.
- **Topic chat about an asset**: Tasks in the asset's owner project on boards whose `visibility` array includes the chat's visibility.
- **Topic chat about a task**: Sibling tasks in the parent task's project on boards whose `visibility` array includes the chat's visibility.
- **Member chat with project scope**: All board tasks in that project (no visibility filter — mirrors asset/folder mention behaviour for this chat type).
- **Submission chat**: Tasks in the submission's project on boards whose `visibility` array includes `'reviewer'`.
- **Member chat with workspace/social scope**: Empty result — no tasks are mentionable.
Legacy mention-only tasks (`boardId === null`) are never returned. The `nameSearch` query is OR-matched across `subject` substring, exact `taskNumber` (when numeric), and exact `id` (when a UUID).
Returns `capabilityNotAvailable` / 403 when the workspace lacks the `boards` capability.
# Get messages for a chat (/docs/reference/api/chats/get-chats-chatid-messages)
Returns active messages for a chat with recent replies and populated attachments/mentions. API tokens require the `chat:read` scope (`tokenScopeMissing` / 403 otherwise). `createdBefore` / `createdAfter` are only accepted with index pagination.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /chats/{chatId}/messages
Get messages for a chat
Returns active messages for a chat with recent replies and populated attachments/mentions. API tokens require the `chat:read` scope (`tokenScopeMissing` / 403 otherwise). `createdBefore` / `createdAfter` are only accepted with index pagination.
# Get topic chat by id. (/docs/reference/api/chats/get-chats-chatid)
Returns a topic chat (project/asset/task/public) without messages. Member chats are served by `GET /chats/member/{chatId}`.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /chats/{chatId}
Get topic chat by id.
Returns a topic chat (project/asset/task/public) without messages. Member chats are served by `GET /chats/member/{chatId}`.
# Get members addable to a NEW member chat, by scope, before the chat exists. (/docs/reference/api/chats/get-chats-member-addable)
Populates the create-chat member picker. Unlike the raw membership-list endpoints, this is not admin-gated — any user permitted to create a member chat in the scope (including a plain workspaceChatMember) may call it, and only chat-eligible members are returned.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /chats/member/addable
Get members addable to a NEW member chat, by scope, before the chat exists.
Populates the create-chat member picker. Unlike the raw membership-list endpoints, this is not admin-gated — any user permitted to create a member chat in the scope (including a plain workspaceChatMember) may call it, and only chat-eligible members are returned.
# Get member chat by id. (/docs/reference/api/chats/get-chats-member-chatid)
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /chats/member/{chatId}
Get member chat by id.
# Get a list of addable members to a member chat based on the chats scope and the users role in that scope. (/docs/reference/api/chats/get-chats-member-members-chatid)
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /chats/member/members/{chatId}
Get a list of addable members to a member chat based on the chats scope and the users role in that scope.
# Get a paginated list of member chats the user has created or is part of. (/docs/reference/api/chats/get-chats-member)
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /chats/member
Get a paginated list of member chats the user has created or is part of.
# Get messages where the user was mentioned (/docs/reference/api/chats/get-chats-mentions)
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /chats/mentions
Get messages where the user was mentioned
# Get replies for a message (/docs/reference/api/chats/get-chats-message-messageid-replies)
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /chats/message/{messageId}/replies
Get replies for a message
# Get message by ID (/docs/reference/api/chats/get-chats-message-messageid)
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /chats/message/{messageId}
Get message by ID
# Get chat by Topic ID (/docs/reference/api/chats/get-chats-topic-topicid)
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /chats/topic/{topicId}
Get chat by Topic ID
# Get every project topic chat the user can access in a workspace (/docs/reference/api/chats/get-chats-workspace-workspaceid-project-chats)
Returns the creator/reviewer project topic chats across all projects in the workspace that the caller can read, with the latest message and message count for each. Access is derived per project from the caller's inherited permissions (`canGetCreatorChat` / `canGetReviewerChat`). Requires `canGetWorkspace` on the workspace. Results are ordered by most recent activity.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /chats/workspace/{workspaceId}/project-chats
Get every project topic chat the user can access in a workspace
Returns the creator/reviewer project topic chats across all projects in the workspace that the caller can read, with the latest message and message count for each. Access is derived per project from the caller's inherited permissions (`canGetCreatorChat` / `canGetReviewerChat`). Requires `canGetWorkspace` on the workspace. Results are ordered by most recent activity.
# Create a new message in an asset chat, creating the chat if it doesn't exist (/docs/reference/api/chats/post-chats-asset-assetid-visibility-new-message)
Creates a new message in an asset chat. If the chat doesn't exist for the specified visibility, it will be created automatically. Only works with media assets.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /chats/asset/{assetId}/{visibility}/new-message
Create a new message in an asset chat, creating the chat if it doesn't exist
Creates a new message in an asset chat. If the chat doesn't exist for the specified visibility, it will be created automatically. Only works with media assets.
# Create a new message in the specified chat (/docs/reference/api/chats/post-chats-chatid-new-message)
Creates a message in any chat type (topic, member, submission, AI, support). Either `content` or at least one attachment must be provided. API tokens require the `chat:write` scope (`tokenScopeMissing` / 403 otherwise). Mentioning users in topic/member/submission chats creates tasks and notifications for them.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /chats/{chatId}/new-message
Create a new message in the specified chat
Creates a message in any chat type (topic, member, submission, AI, support). Either `content` or at least one attachment must be provided. API tokens require the `chat:write` scope (`tokenScopeMissing` / 403 otherwise). Mentioning users in topic/member/submission chats creates tasks and notifications for them.
# Create a new member chat. (/docs/reference/api/chats/post-chats-member)
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /chats/member
Create a new member chat.
# Attach a file to a message. (/docs/reference/api/chats/post-chats-message-messageid-attachment)
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /chats/message/{messageId}/attachment
Attach a file to a message.
# Create or update a reaction on a chat message (/docs/reference/api/chats/post-chats-message-messageid-reaction)
Creates a new reaction or replaces an existing reaction from the same user on a chat message. Each user can only have one reaction per message.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /chats/message/{messageId}/reaction
Create or update a reaction on a chat message
Creates a new reaction or replaces an existing reaction from the same user on a chat message. Each user can only have one reaction per message.
# Create a new topic chat (/docs/reference/api/chats/post-chats-topic)
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /chats/topic
Create a new topic chat
# Follow a chat to receive updates (/docs/reference/api/chats/put-chats-chatid-follow)
Add the authenticated user to the chat's following list. Users in the following list receive notifications about new messages and updates. Works with all chat types (topic, member, submission). Following a chat multiple times is idempotent.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /chats/{chatId}/follow
Follow a chat to receive updates
Add the authenticated user to the chat's following list. Users in the following list receive notifications about new messages and updates. Works with all chat types (topic, member, submission). Following a chat multiple times is idempotent.
# Unfollow a chat to stop receiving updates (/docs/reference/api/chats/put-chats-chatid-unfollow)
Remove the authenticated user from the chat's following list. Users can unfollow a chat even if they no longer have access to it, allowing them to stop receiving notifications. Works with all chat types (topic, member, submission). Unfollowing a chat you're not following is idempotent.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /chats/{chatId}/unfollow
Unfollow a chat to stop receiving updates
Remove the authenticated user from the chat's following list. Users can unfollow a chat even if they no longer have access to it, allowing them to stop receiving notifications. Works with all chat types (topic, member, submission). Unfollowing a chat you're not following is idempotent.
# Update chat subject. (/docs/reference/api/chats/put-chats-chatid)
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /chats/{chatId}
Update chat subject.
# Archive a member chat for the current user. (/docs/reference/api/chats/put-chats-member-chatid-archive)
Adds the current user's ID to the chat's archivedBy array. Per-user archiving does not affect other members' view of the chat.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /chats/member/{chatId}/archive
Archive a member chat for the current user.
Adds the current user's ID to the chat's archivedBy array. Per-user archiving does not affect other members' view of the chat.
# Upload and set member chat icon. (/docs/reference/api/chats/put-chats-member-chatid-icon)
Creates an icon asset for the member chat and returns signed upload links for it. Any existing icon is marked for deletion. Requires member-chat management permission (`canManageMemberChat`).
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /chats/member/{chatId}/icon
Upload and set member chat icon.
Creates an icon asset for the member chat and returns signed upload links for it. Any existing icon is marked for deletion. Requires member-chat management permission (`canManageMemberChat`).
# Unarchive a member chat for the current user. (/docs/reference/api/chats/put-chats-member-chatid-unarchive)
Removes the current user's ID from the chat's archivedBy array.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /chats/member/{chatId}/unarchive
Unarchive a member chat for the current user.
Removes the current user's ID from the chat's archivedBy array.
# Update member chat subject and/or color. (/docs/reference/api/chats/put-chats-member-chatid)
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /chats/member/{chatId}
Update member chat subject and/or color.
# Add an array of members to a member chat by user ID. (/docs/reference/api/chats/put-chats-member-members-chatid)
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /chats/member/members/{chatId}
Add an array of members to a member chat by user ID.
# Highlight a chat message (/docs/reference/api/chats/put-chats-message-messageid-highlight)
Sets `highlighted = true` on the message and records the highlighter. For project and asset topic chats a system message is posted in the project chat of the same visibility, a `chatHighlightMessage` notification is sent and project members are emailed. Requires the `canHighlightMessage` permission on the chat.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /chats/message/{messageId}/highlight
Highlight a chat message
Sets `highlighted = true` on the message and records the highlighter. For project and asset topic chats a system message is posted in the project chat of the same visibility, a `chatHighlightMessage` notification is sent and project members are emailed. Requires the `canHighlightMessage` permission on the chat.
# Remove the highlight from a chat message (/docs/reference/api/chats/put-chats-message-messageid-unhighlight)
Sets `highlighted = false`, clears the highlighter fields and removes the associated system messages and notification. Requires the `canHighlightMessage` permission on the chat.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /chats/message/{messageId}/unhighlight
Remove the highlight from a chat message
Sets `highlighted = false`, clears the highlighter fields and removes the associated system messages and notification. Requires the `canHighlightMessage` permission on the chat.
# Revise message by ID (/docs/reference/api/chats/put-chats-message-messageid)
Revise a message by ID. If annotations are provided, they will replace current annotations not merged. If no annotations are provided, current annotations will be preserved. If an empty array is provided, all annotations will be removed.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /chats/message/{messageId}
Revise message by ID
Revise a message by ID. If annotations are provided, they will replace current annotations not merged. If no annotations are provided, current annotations will be preserved. If an empty array is provided, all annotations will be removed.
# Get current platform configuration. (/docs/reference/api/config/get-config)
Returns the current platform configuration: validation limits, approved colours, roles and their permissions, billable roles, supported / restricted file types, supported media types per asset function, and feature flags for convos and link previews. Public — no authentication required.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /config
Get current platform configuration.
Returns the current platform configuration: validation limits, approved colours, roles and their permissions, billable roles, supported / restricted file types, supported media types per asset function, and feature flags for convos and link previews. Public — no authentication required.
# Cancel/delete a convo (/docs/reference/api/convos/delete-convos-convoid)
Marks the convo as `cancelled`, clears the chat's active convo and posts a system message.
Only the user who started the convo can delete it.
Machine-readable definition: https://docs.nurama.com/openapi.json
## DELETE /convos/{convoId}
Cancel/delete a convo
Marks the convo as `cancelled`, clears the chat's active convo and posts a system message.
Only the user who started the convo can delete it.
# Get all convos for a chat (/docs/reference/api/convos/get-chats-chatid-convos)
Retrieve all convos (active, completed, or cancelled) for a specific chat.
Results are sorted by creation time in descending order (newest first).
Optionally filter by status. Requires read access to the chat (`canGetChat`) and an active workspace subscription.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /chats/{chatId}/convos
Get all convos for a chat
Retrieve all convos (active, completed, or cancelled) for a specific chat.
Results are sorted by creation time in descending order (newest first).
Optionally filter by status. Requires read access to the chat (`canGetChat`) and an active workspace subscription.
# Get convo details (/docs/reference/api/convos/get-convos-convoid)
Retrieve a convo with populated participants, starter, chat and scope. A convo that is still marked active but whose Daily.co room has gone is reaped on read and returned as `completed`. Requires read access to the convo's chat.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /convos/{convoId}
Get convo details
Retrieve a convo with populated participants, starter, chat and scope. A convo that is still marked active but whose Daily.co room has gone is reaped on read and returned as `completed`. Requires read access to the convo's chat.
# Get convos for a project scope (paginated) (/docs/reference/api/convos/get-convos-scope-scopeid)
Returns convos across all chats in a project, filtered to the requested chat visibilities. The caller must hold the
chat-read permission for **every** requested visibility (`canGetCreatorChat` / `canGetReviewerChat`).
Active convos are listed first, then newest first. `search` matches participant names and convo type and is applied
to the current page after the query.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /convos/scope/{scopeId}
Get convos for a project scope (paginated)
Returns convos across all chats in a project, filtered to the requested chat visibilities. The caller must hold the
chat-read permission for **every** requested visibility (`canGetCreatorChat` / `canGetReviewerChat`).
Active convos are listed first, then newest first. `search` matches participant names and convo type and is applied
to the current page after the query.
# Get all convos for a project (Convos drawer) (/docs/reference/api/convos/get-projects-projectid-convos)
Retrieve all convos across all chats within a project.
Results are sorted by creation time in descending order (newest first).
Optionally filter by visibility (creator/reviewer) and status.
This endpoint is used for the "Convos drawer" feature to show all project convos in one place.
Requires `canGetProject` and an active workspace subscription.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /projects/{projectId}/convos
Get all convos for a project (Convos drawer)
Retrieve all convos across all chats within a project.
Results are sorted by creation time in descending order (newest first).
Optionally filter by visibility (creator/reviewer) and status.
This endpoint is used for the "Convos drawer" feature to show all project convos in one place.
Requires `canGetProject` and an active workspace subscription.
# Update a convo's subject and/or notes (/docs/reference/api/convos/patch-convos-convoid)
Updates `subject` and/or `notes`. Allowed regardless of convo status so notes can be added after the call ends. Only the user who started the convo can update it. At least one field must be provided.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PATCH /convos/{convoId}
Update a convo's subject and/or notes
Updates `subject` and/or `notes`. Allowed regardless of convo status so notes can be added after the call ends. Only the user who started the convo can update it. At least one field must be provided.
# Start a new convo (/docs/reference/api/convos/post-convos)
Start a new video or audio convo in a chat. If the chat already has an active convo it is auto-completed
before the new one is created. Creates a Daily.co room and posts a system message in the chat.
The starter automatically joins as an active participant and receives a meeting token.
Gates (in order): convos feature flag (403 `featureDisabled`), active workspace subscription
(400 `subscriptionNotActive`), the workspace `convos` capability (403 `capabilityNotAvailable`),
a positive credit balance (400 `creditBalanceInsufficient`) and the same chat permission required to post a message
in the chat (`canStartConvo`).
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /convos
Start a new convo
Start a new video or audio convo in a chat. If the chat already has an active convo it is auto-completed
before the new one is created. Creates a Daily.co room and posts a system message in the chat.
The starter automatically joins as an active participant and receives a meeting token.
Gates (in order): convos feature flag (403 `featureDisabled`), active workspace subscription
(400 `subscriptionNotActive`), the workspace `convos` capability (403 `capabilityNotAvailable`),
a positive credit balance (400 `creditBalanceInsufficient`) and the same chat permission required to post a message
in the chat (`canStartConvo`).
# Complete a convo (/docs/reference/api/convos/put-convos-convoid-complete)
Mark a convo as completed. Only the user who started the convo can complete it.
Calculates `durationMinutes`, sets `endedAt` and creates a system message indicating the convo was completed.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /convos/{convoId}/complete
Complete a convo
Mark a convo as completed. Only the user who started the convo can complete it.
Calculates `durationMinutes`, sets `endedAt` and creates a system message indicating the convo was completed.
# Join an active convo (/docs/reference/api/convos/put-convos-convoid-join)
Join an active convo. User must have access to the chat and the convo must be in active status.
Returns a Daily.co meeting token for the user to join the room.
User is added to both activeParticipants and allParticipants arrays.
**Cross-device handover:** If the user is already an active participant (e.g. joining from a second device),
the join still succeeds and returns a new meeting token. A `convoHandover` WebSocket notification is sent
to the user's personal channel (`user/{userId}`) so the old device can close its convo window.
The user is not duplicated in activeParticipants.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /convos/{convoId}/join
Join an active convo
Join an active convo. User must have access to the chat and the convo must be in active status.
Returns a Daily.co meeting token for the user to join the room.
User is added to both activeParticipants and allParticipants arrays.
**Cross-device handover:** If the user is already an active participant (e.g. joining from a second device),
the join still succeeds and returns a new meeting token. A `convoHandover` WebSocket notification is sent
to the user's personal channel (`user/{userId}`) so the old device can close its convo window.
The user is not duplicated in activeParticipants.
# Leave an active convo (/docs/reference/api/convos/put-convos-convoid-leave)
Leave an active convo. User must be an active participant.
User is removed from activeParticipants but remains in allParticipants.
Creates a system message indicating the user left the convo. If the last active participant leaves,
the convo is auto-completed and returned with `status: completed`.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /convos/{convoId}/leave
Leave an active convo
Leave an active convo. User must be an active participant.
User is removed from activeParticipants but remains in allParticipants.
Creates a system message indicating the user left the convo. If the last active participant leaves,
the convo is auto-completed and returned with `status: completed`.
# Rejoin a convo (page refresh / reconnect) (/docs/reference/api/convos/put-convos-convoid-rejoin)
Rejoin an active convo after a page refresh or reconnect.
Only generates a new Daily.co meeting token if the user is already an active participant.
No notifications are sent. This is a silent reconnect.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /convos/{convoId}/rejoin
Rejoin a convo (page refresh / reconnect)
Rejoin an active convo after a page refresh or reconnect.
Only generates a new Daily.co meeting token if the user is already an active participant.
No notifications are sent. This is a silent reconnect.
# Get assets in a folder (not implemented) (/docs/reference/api/folders/get-folders-folderid-assets)
Deprecated placeholder — this route is not implemented. Every request currently fails with `500 unknownError`; if it were reachable it would respond `501 Not Implemented`. Use `GET /projects/{projectId}/files/{visibility}/{path}` to list a folder's contents.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /folders/{folderId}/assets (deprecated)
Get assets in a folder (not implemented)
Deprecated placeholder — this route is not implemented. Every request currently fails with `500 unknownError`; if it were reachable it would respond `501 Not Implemented`. Use `GET /projects/{projectId}/files/{visibility}/{path}` to list a folder's contents.
# Get folder details (/docs/reference/api/folders/get-folders-folderid)
Returns a folder by ID. When the folder has an icon, the icon asset is populated on `icon`. Requires `canGetFolder` on the folder and a live subscription on the owning workspace.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /folders/{folderId}
Get folder details
Returns a folder by ID. When the folder has an icon, the icon asset is populated on `icon`. Requires `canGetFolder` on the folder and a live subscription on the owning workspace.
# Update folder icon (/docs/reference/api/folders/put-folders-folderid-icon)
Creates an icon asset for the folder and returns multipart upload URLs for it, mirroring the asset upload flow. Any existing icon asset is marked `pendingDelete`. Requires `canUpdateFolder` and a live subscription on the owning workspace.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /folders/{folderId}/icon
Update folder icon
Creates an icon asset for the folder and returns multipart upload URLs for it, mirroring the asset upload flow. Any existing icon asset is marked `pendingDelete`. Requires `canUpdateFolder` and a live subscription on the owning workspace.
# Add a tag to a folder (/docs/reference/api/folders/put-folders-folderid-tag)
Adds a project tag to a folder. The tag must belong to the project the folder inherits from, otherwise 404 `tagNotFound`. Requires `canTagFolder` and a live subscription on the owning workspace.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /folders/{folderId}/tag
Add a tag to a folder
Adds a project tag to a folder. The tag must belong to the project the folder inherits from, otherwise 404 `tagNotFound`. Requires `canTagFolder` and a live subscription on the owning workspace.
# Remove a tag from a folder (/docs/reference/api/folders/put-folders-folderid-untag)
Removes a tag from a folder. Requires `canUntagFolder` and a live subscription on the owning workspace.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /folders/{folderId}/untag
Remove a tag from a folder
Removes a tag from a folder. Requires `canUntagFolder` and a live subscription on the owning workspace.
# Update folder name or colour (/docs/reference/api/folders/put-folders-folderid)
Renames a folder, or updates its colour. The required permission depends on the collection the folder lives in, taken from its `ownerResourceType`: a project-owned folder (the creator and reviewer trees) needs `canUpdateFolder`; one owned by a submission needs `canAddSubmittionItems`; one owned by a public release needs `canUpdatePublicFileSystem`. A creator holds the first but not the latter two, matching the path-scoped routes for those collections. Requires a live subscription on the owning workspace.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /folders/{folderId}
Update folder name or colour
Renames a folder, or updates its colour. The required permission depends on the collection the folder lives in, taken from its `ownerResourceType`: a project-owned folder (the creator and reviewer trees) needs `canUpdateFolder`; one owned by a submission needs `canAddSubmittionItems`; one owned by a public release needs `canUpdatePublicFileSystem`. A creator holds the first but not the latter two, matching the path-scoped routes for those collections. Requires a live subscription on the owning workspace.
# Accept an invitation to join a resource (deprecated alias; use POST) (/docs/reference/api/invites/acceptInvite)
Joins the caller to the invited resource with the invite's role(s). Requires `canAcceptInvite` (the invite must be addressed to the caller's email). Existing members receive a member-join push; a billable role also triggers a subscription-update email to the workspace owner.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /invites/accept/{inviteId} (deprecated)
Accept an invitation to join a resource (deprecated alias; use POST)
Joins the caller to the invited resource with the invite's role(s). Requires `canAcceptInvite` (the invite must be addressed to the caller's email). Existing members receive a member-join push; a billable role also triggers a subscription-update email to the workspace owner.
# Cancel invite (/docs/reference/api/invites/cancelInvite)
Marks the invite `cancelled`. Requires `canDeleteInvite` on the invite's resource. Returns the cancelled invite record.
Machine-readable definition: https://docs.nurama.com/openapi.json
## DELETE /invites/{inviteId}
Cancel invite
Marks the invite `cancelled`. Requires `canDeleteInvite` on the invite's resource. Returns the cancelled invite record.
# Get invites for a specific resource (/docs/reference/api/invites/get-invites-resource-resourceid)
Requires the `canGetInvite` right on the resource; otherwise 403.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /invites/resource/{resourceId}
Get invites for a specific resource
Requires the `canGetInvite` right on the resource; otherwise 403.
# Get specific invite (public) (/docs/reference/api/invites/getInvite)
Public route — no authentication. Used by the invite landing page before the invitee has an account. Returns the invite with `inviter`, `invitee` and `resource` populated. An unknown id returns an empty body (the record is simply not found; no 404 is raised).
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /invites/{inviteId}
Get specific invite (public)
Public route — no authentication. Used by the invite landing page before the invitee has an account. Returns the invite with `inviter`, `invitee` and `resource` populated. An unknown id returns an empty body (the record is simply not found; no 404 is raised).
# Get user's invites (/docs/reference/api/invites/getUsersInvites)
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /invites
Get user's invites
# Invite a user to a resource (/docs/reference/api/invites/inviteUserToResource)
Creates an invite and emails the invitee. Requires the right to grant `role` (and every `additionalRoles` entry) on the resource — `canCreateInviteToResource`; otherwise 403. If the invitee already has an account the `inviteCreate` notification is also pushed to their user channel.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /invites
Invite a user to a resource
Creates an invite and emails the invitee. Requires the right to grant `role` (and every `additionalRoles` entry) on the resource — `canCreateInviteToResource`; otherwise 403. If the invitee already has an account the `inviteCreate` notification is also pushed to their user channel.
# Resend an invite email to the invitee. (deprecated alias; use POST) (/docs/reference/api/invites/resendInvite)
Re-sends the invitation email and refreshes the invite's expiry. Requires `canResendInvite` on the invite. Responds with an empty 200 body.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /invites/resend/{inviteId} (deprecated)
Resend an invite email to the invitee. (deprecated alias; use POST)
Re-sends the invitation email and refreshes the invite's expiry. Requires `canResendInvite` on the invite. Responds with an empty 200 body.
# Fetch link previews for one or more URLs. (/docs/reference/api/link-preview/post-link-preview)
Accepts an array of URLs and returns Open Graph / meta tag preview data for each.
Each preview is signed with an HMAC-SHA256 signature that must be included when
the preview is submitted with a chat message. Nurama verifies the signature
when the message is created, to prevent spoofed preview data.
Duplicate URLs are collapsed and URLs that fail validation, fetching or
SSRF checks are silently omitted from `previews`, so the array may be
shorter than the input. Rate limited to 30 requests per minute per IP.
Requires authentication.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /link-preview
Fetch link previews for one or more URLs.
Accepts an array of URLs and returns Open Graph / meta tag preview data for each.
Each preview is signed with an HMAC-SHA256 signature that must be included when
the preview is submitted with a chat message. Nurama verifies the signature
when the message is created, to prevent spoofed preview data.
Duplicate URLs are collapsed and URLs that fail validation, fetching or
SSRF checks are silently omitted from `previews`, so the array may be
shorter than the input. Rate limited to 30 requests per minute per IP.
Requires authentication.
# Add role to membership record (/docs/reference/api/membership/addRoleToMembership)
Requires `canAddMembershipRole` for the role on the membership's resource. Adding an additive role (e.g. `reviewerBoardManager`) auto-pairs its parent role. A billable role triggers a subscription-update email.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /memberships/add-role
Add role to membership record
Requires `canAddMembershipRole` for the role on the membership's resource. Adding an additive role (e.g. `reviewerBoardManager`) auto-pairs its parent role. A billable role triggers a subscription-update email.
# User may delete their own membership record on a resource unless they are a resource owner. (/docs/reference/api/membership/delete-memberships-leave-resourceid)
Machine-readable definition: https://docs.nurama.com/openapi.json
## DELETE /memberships/leave/{resourceId}
User may delete their own membership record on a resource unless they are a resource owner.
# Delete membership record (/docs/reference/api/membership/delete-memberships-membershipid)
Removes a member from a resource. Requires `canDeleteMember`. Owner records cannot be deleted. Responds with an empty 200 body.
Machine-readable definition: https://docs.nurama.com/openapi.json
## DELETE /memberships/{membershipId}
Delete membership record
Removes a member from a resource. Requires `canDeleteMember`. Owner records cannot be deleted. Responds with an empty 200 body.
# Get mentionable users for a project based on visibility (/docs/reference/api/membership/get-memberships-mentionable-project-projectid-visibility)
Requires `canGetProjectMentionableUsers`. Workspace admins of the parent workspace are always included; project roles included depend on `visibility`. Users appearing under several memberships are merged with their roles concatenated.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /memberships/mentionable/project/{projectId}/{visibility}
Get mentionable users for a project based on visibility
Requires `canGetProjectMentionableUsers`. Workspace admins of the parent workspace are always included; project roles included depend on `visibility`. Users appearing under several memberships are merged with their roles concatenated.
# Return membership of a project. Membership retrieved are determined by a user's role in the project. For example, reviewers can only see reviewers. (/docs/reference/api/membership/get-memberships-project-projectid)
Returns a paginated, per-user membership report for the project (same shape as the workspace report). Requires `canGetProjectMembership`; the roles visible depend on the caller's inherited permissions in the project. Only one of the name sorts may be used at a time.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /memberships/project/{projectId}
Return membership of a project. Membership retrieved are determined by a user's role in the project. For example, reviewers can only see reviewers.
Returns a paginated, per-user membership report for the project (same shape as the workspace report). Requires `canGetProjectMembership`; the roles visible depend on the caller's inherited permissions in the project. Only one of the name sorts may be used at a time.
# Return membership of a workspace. User must have a workspace admin role to retrieve membership records. (/docs/reference/api/membership/get-memberships-workspace-workspaceid)
Returns a paginated, per-user membership report covering the workspace and all of its active projects. Requires the `canGetWorkspaceMembers` right. `isBillable=true` restricts to billable roles. Only one of the name sorts (`firstName`, `lastName`, `displayName`) may be used at a time.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /memberships/workspace/{workspaceId}
Return membership of a workspace. User must have a workspace admin role to retrieve membership records.
Returns a paginated, per-user membership report covering the workspace and all of its active projects. Requires the `canGetWorkspaceMembers` right. `isBillable=true` restricts to billable roles. Only one of the name sorts (`firstName`, `lastName`, `displayName`) may be used at a time.
# Get logged-in user's memberships (/docs/reference/api/membership/getUsersMemberships)
Returns every membership record of the caller with `resource` (workspace or project) and public `user` populated. Ordered workspaces first, newest first.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /memberships
Get logged-in user's memberships
Returns every membership record of the caller with `resource` (workspace or project) and public `user` populated. Ordered workspaces first, newest first.
# Get resource-specific last seen timestamps for multiple users in a project (/docs/reference/api/membership/post-memberships-project-projectid-last-seen)
Returns last seen data for specified users within a project. Requires `canGetProjectMembership`. Unknown user ids are silently omitted from `results`; known users with no record get a null `lastSeen`.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /memberships/project/{projectId}/last-seen
Get resource-specific last seen timestamps for multiple users in a project
Returns last seen data for specified users within a project. Requires `canGetProjectMembership`. Unknown user ids are silently omitted from `results`; known users with no record get a null `lastSeen`.
# Get resource-specific last seen timestamps for multiple users in a workspace (/docs/reference/api/membership/post-memberships-workspace-workspaceid-last-seen)
Returns last seen data for specified users within a workspace. Requires the `canGetWorkspaceMembers` right. Unknown user ids are silently omitted from `results`; known users with no record get a null `lastSeen`.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /memberships/workspace/{workspaceId}/last-seen
Get resource-specific last seen timestamps for multiple users in a workspace
Returns last seen data for specified users within a workspace. Requires the `canGetWorkspaceMembers` right. Unknown user ids are silently omitted from `results`; known users with no record get a null `lastSeen`.
# Remove role from membership record (/docs/reference/api/membership/removeRoleFromMembership)
Requires `canRemoveMembershipRole`. Removing a parent role also strips its additive child roles.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /memberships/remove-role
Remove role from membership record
Requires `canRemoveMembershipRole`. Removing a parent role also strips its additive child roles.
# Get bulk count of new notifications for specified channels and types (/docs/reference/api/notifications/post-notifications-count-bulk)
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /notifications/count/bulk
Get bulk count of new notifications for specified channels and types
# Get count of new notifications for specified channels and types. (/docs/reference/api/notifications/post-notifications-count)
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /notifications/count
Get count of new notifications for specified channels and types.
# Get user's last seen records for specified channels and types. (/docs/reference/api/notifications/post-notifications-last-seen)
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /notifications/last-seen
Get user's last seen records for specified channels and types.
# Get new notifications with pagination support (/docs/reference/api/notifications/post-notifications-new)
Retrieves new notifications with support for both cursor and index-based pagination, optionally updating last seen records. Note that if a cursor is submitted this is essentially the same as calling the /notifications endpoint. Also, if a cursor is submitted you probably want to set the updateLastSeen to false.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /notifications/new
Get new notifications with pagination support
Retrieves new notifications with support for both cursor and index-based pagination, optionally updating last seen records. Note that if a cursor is submitted this is essentially the same as calling the /notifications endpoint. Also, if a cursor is submitted you probably want to set the updateLastSeen to false.
# Get paginated notifications for specified channels and types (/docs/reference/api/notifications/post-notifications)
Retrieves notifications with support for both cursor and index-based pagination
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /notifications
Get paginated notifications for specified channels and types
Retrieves notifications with support for both cursor and index-based pagination
# Update user's last seen records for specified channels and types. (/docs/reference/api/notifications/put-notifications-last-seen)
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /notifications/last-seen
Update user's last seen records for specified channels and types.
# Delete items at specified paths within a project (deprecated alias; use PUT) (/docs/reference/api/projects/delete-projects-projectid-files-visibility-delete)
Paths are relative to `project/{projectId}/{visibility}`. Requires `canDeleteCreatorItems` for `creator` and `canDeleteReviewerItems` for `reviewer`. Use `delete-preview` first to learn which secondary references the cascade will remove.
Machine-readable definition: https://docs.nurama.com/openapi.json
## DELETE /projects/{projectId}/files/{visibility}/delete (deprecated)
Delete items at specified paths within a project (deprecated alias; use PUT)
Paths are relative to `project/{projectId}/{visibility}`. Requires `canDeleteCreatorItems` for `creator` and `canDeleteReviewerItems` for `reviewer`. Use `delete-preview` first to learn which secondary references the cascade will remove.
# Delete a public file system (/docs/reference/api/projects/delete-projects-projectid-public-publicid)
Permanently deletes a public file system, its copied file-system entries and its inheritance node, and invalidates its access token. Requires `canDeletePublicFileSystem`; the record must belong to `projectId`.
Machine-readable definition: https://docs.nurama.com/openapi.json
## DELETE /projects/{projectId}/public/{publicId}
Delete a public file system
Permanently deletes a public file system, its copied file-system entries and its inheritance node, and invalidates its access token. Requires `canDeletePublicFileSystem`; the record must belong to `projectId`.
# Mark a project for deletion. (/docs/reference/api/projects/delete-projects-projectid)
Requires `canDeleteProject`. Holders are identical to `canUpdateProject` — which is what this route used to check — so no caller's access changed; the right that names the operation is now the one that gates it, so revoking it from a role actually blocks deletion.
Machine-readable definition: https://docs.nurama.com/openapi.json
## DELETE /projects/{projectId}
Mark a project for deletion.
Requires `canDeleteProject`. Holders are identical to `canUpdateProject` — which is what this route used to check — so no caller's access changed; the right that names the operation is now the one that gates it, so revoking it from a role actually blocks deletion.
# Get assets for a project with specified visibility (/docs/reference/api/projects/get-projects-projectid-assets-visibility)
Retrieves assets for a project filtered by visibility level, optionally with their chats, with support for both cursor and index-based pagination. Requires `canGetCreatorAssets` for `creator` and `canGetReviewerAssets` for `reviewer`. Cursor-only parameters are rejected with index pagination, and `page`, `createdBefore`, `createdAfter` are rejected with cursor pagination.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /projects/{projectId}/assets/{visibility}
Get assets for a project with specified visibility
Retrieves assets for a project filtered by visibility level, optionally with their chats, with support for both cursor and index-based pagination. Requires `canGetCreatorAssets` for `creator` and `canGetReviewerAssets` for `reviewer`. Cursor-only parameters are rejected with index pagination, and `page`, `createdBefore`, `createdAfter` are rejected with cursor pagination.
# Get highlighted messages across the project's creator-visible chats (/docs/reference/api/projects/get-projects-projectid-creator-highlighted-messages)
Cursor-paginated list of active chat messages flagged `highlighted` whose scope is this project and whose scope visibility includes `creator`. Each message is populated (author, attachments, etc.) and carries its parent `chat`. Requires `canGetCreatorHighlights`.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /projects/{projectId}/creator/highlighted-messages
Get highlighted messages across the project's creator-visible chats
Cursor-paginated list of active chat messages flagged `highlighted` whose scope is this project and whose scope visibility includes `creator`. Each message is populated (author, attachments, etc.) and carries its parent `chat`. Requires `canGetCreatorHighlights`.
# Get project feed with assets and chats (/docs/reference/api/projects/get-projects-projectid-feed-visibility)
Retrieves a paginated feed of assets and their associated chats for a project. Requires `canGetCreatorAssets` for `creator` and `canGetReviewerAssets` for `reviewer`. Index pagination is the default; pass `paginate=cursor` for cursor pagination. Cursor-only parameters (`cursor`, `paginateReverse`, `includeCounts`, `includeCursorRecord`, `startAt`, `includeStartAtRecord`) are rejected with index pagination, and `page`, `createdBefore`, `createdAfter` are rejected with cursor pagination.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /projects/{projectId}/feed/{visibility}
Get project feed with assets and chats
Retrieves a paginated feed of assets and their associated chats for a project. Requires `canGetCreatorAssets` for `creator` and `canGetReviewerAssets` for `reviewer`. Index pagination is the default; pass `paginate=cursor` for cursor pagination. Cursor-only parameters (`cursor`, `paginateReverse`, `includeCounts`, `includeCursorRecord`, `startAt`, `includeStartAtRecord`) are rejected with index pagination, and `page`, `createdBefore`, `createdAfter` are rejected with cursor pagination.
# Get items at a specific path within a project (/docs/reference/api/projects/get-projects-projectid-files-visibility-path)
Same as the root listing, scoped to a folder path. Path segments may be folder slugs or IDs (IDs are resolved to slugs; an unknown segment returns `fileSystemPathNotFound`, 404). Virtual paths are supported: `Public` and `Submission` list one synthesized sub-folder per release / submission the caller may read (`canGetPublicFileSystem` / `canGetSubmission`), and `Public/{token}/...`, `Submission/{id}/...` and `Review/...` are translated to the underlying tree. Requires `canGetCreatorItems` for `creator` and `canGetReviewerItems` for `reviewer`.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /projects/{projectId}/files/{visibility}/{path}
Get items at a specific path within a project
Same as the root listing, scoped to a folder path. Path segments may be folder slugs or IDs (IDs are resolved to slugs; an unknown segment returns `fileSystemPathNotFound`, 404). Virtual paths are supported: `Public` and `Submission` list one synthesized sub-folder per release / submission the caller may read (`canGetPublicFileSystem` / `canGetSubmission`), and `Public/{token}/...`, `Submission/{id}/...` and `Review/...` are translated to the underlying tree. Requires `canGetCreatorItems` for `creator` and `canGetReviewerItems` for `reviewer`.
# Get items at the root path of a project (/docs/reference/api/projects/get-projects-projectid-files-visibility)
Lists the items directly under `project/{projectId}/{visibility}`. Requires `canGetCreatorItems` for `creator` and `canGetReviewerItems` for `reviewer`. On the first page of an unfiltered listing the synthesized virtual roots (`Review`, `Public`, `Submission`) the caller may read are prepended to `results`. Index pagination is the default; pass `paginate=cursor` for cursor pagination (cursor-only parameters are rejected with index pagination and `page` is rejected with cursor pagination). `resourceIds` and `resourceSlugs` may not both be set (`invalidItemSearchParams`, 400).
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /projects/{projectId}/files/{visibility}
Get items at the root path of a project
Lists the items directly under `project/{projectId}/{visibility}`. Requires `canGetCreatorItems` for `creator` and `canGetReviewerItems` for `reviewer`. On the first page of an unfiltered listing the synthesized virtual roots (`Review`, `Public`, `Submission`) the caller may read are prepended to `results`. Index pagination is the default; pass `paginate=cursor` for cursor pagination (cursor-only parameters are rejected with index pagination and `page` is rejected with cursor pagination). `resourceIds` and `resourceSlugs` may not both be set (`invalidItemSearchParams`, 400).
# Get the public audit report for a project (/docs/reference/api/projects/get-projects-projectid-public-audit)
Returns a paginated list of project assets that are or have been publicly exposed —
either via a `PublicAssetLink` (direct download link) or via membership in a `Public`
file system. Requires `canGetPublicAudit` (project/workspace owners and admins).
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /projects/{projectId}/public-audit
Get the public audit report for a project
Returns a paginated list of project assets that are or have been publicly exposed —
either via a `PublicAssetLink` (direct download link) or via membership in a `Public`
file system. Requires `canGetPublicAudit` (project/workspace owners and admins).
# Get public file system details (/docs/reference/api/projects/get-projects-projectid-public-publicid)
Retrieves detailed information about a specific public file system by its ID. Requires `canGetPublicFileSystem`. The record must belong to `projectId`; a foreign or unknown id returns `publicFileSystemNotFound` (404).
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /projects/{projectId}/public/{publicId}
Get public file system details
Retrieves detailed information about a specific public file system by its ID. Requires `canGetPublicFileSystem`. The record must belong to `projectId`; a foreign or unknown id returns `publicFileSystemNotFound` (404).
# Get public asset with chat (authenticated management) (/docs/reference/api/projects/get-projects-projectid-public-token-assets-assetid)
Retrieves an asset along with its public chat in the context of this public file system.
The chat is returned in `chats.public` and will be null if no chat has been created yet.
Unlike the unauthenticated `/public/{token}/assets/{assetId}` endpoint, this does NOT
check token expiration. Requires `canGetPublicFileSystem` permission.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /projects/{projectId}/public/{token}/assets/{assetId}
Get public asset with chat (authenticated management)
Retrieves an asset along with its public chat in the context of this public file system.
The chat is returned in `chats.public` and will be null if no chat has been created yet.
Unlike the unauthenticated `/public/{token}/assets/{assetId}` endpoint, this does NOT
check token expiration. Requires `canGetPublicFileSystem` permission.
# Get public chat messages (authenticated management) (/docs/reference/api/projects/get-projects-projectid-public-token-chat-chatid-messages)
Retrieves paginated messages for a public chat (the release's main topic chat or
one of its asset chats). Unlike the unauthenticated
`/public/{token}/chat/{chatId}/messages` endpoint, this does NOT check token
expiration. Requires `canGetPublicFileSystem` permission. A chat that does not
belong to this release returns 403.
Results are always cursor-paginated; `paginate=index` and `page` are accepted
but have no effect.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /projects/{projectId}/public/{token}/chat/{chatId}/messages
Get public chat messages (authenticated management)
Retrieves paginated messages for a public chat (the release's main topic chat or
one of its asset chats). Unlike the unauthenticated
`/public/{token}/chat/{chatId}/messages` endpoint, this does NOT check token
expiration. Requires `canGetPublicFileSystem` permission. A chat that does not
belong to this release returns 403.
Results are always cursor-paginated; `paginate=index` and `page` are accepted
but have no effect.
# Get main public chat (authenticated management) (/docs/reference/api/projects/get-projects-projectid-public-token-chat)
Retrieves the main topic chat for a public file system.
Returns null if no main chat has been created yet (lazy creation pattern).
Unlike the unauthenticated `/public/{token}/chat` endpoint, this does NOT check
token expiration. Requires `canGetPublicFileSystem` permission.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /projects/{projectId}/public/{token}/chat
Get main public chat (authenticated management)
Retrieves the main topic chat for a public file system.
Returns null if no main chat has been created yet (lazy creation pattern).
Unlike the unauthenticated `/public/{token}/chat` endpoint, this does NOT check
token expiration. Requires `canGetPublicFileSystem` permission.
# Get items at a path within a public file system (authenticated management) (/docs/reference/api/projects/get-projects-projectid-public-token-files-path)
Same as the root listing, scoped to a folder path inside the release. Path segments may be folder slugs or IDs (IDs are resolved to slugs; an unknown segment returns `fileSystemPathNotFound`, 404). Requires `canGetPublicFileSystem`; does NOT check token expiration.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /projects/{projectId}/public/{token}/files/{path}
Get items at a path within a public file system (authenticated management)
Same as the root listing, scoped to a folder path inside the release. Path segments may be folder slugs or IDs (IDs are resolved to slugs; an unknown segment returns `fileSystemPathNotFound`, 404). Requires `canGetPublicFileSystem`; does NOT check token expiration.
# Get items at the root of a public file system (authenticated management) (/docs/reference/api/projects/get-projects-projectid-public-token-files)
Lists the items directly under `public/{publicId}` for the release identified by `token`. This is the authenticated management view: unlike the unauthenticated `/public/{token}/files` endpoint it does NOT check token expiration or status, and it never populates chats. Requires `canGetPublicFileSystem`. The token must belong to `projectId`; otherwise `resourceNotFound` (400). Index pagination is the default; pass `paginate=cursor` for cursor pagination (cursor-only parameters are rejected with index pagination and `page` is rejected with cursor pagination).
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /projects/{projectId}/public/{token}/files
Get items at the root of a public file system (authenticated management)
Lists the items directly under `public/{publicId}` for the release identified by `token`. This is the authenticated management view: unlike the unauthenticated `/public/{token}/files` endpoint it does NOT check token expiration or status, and it never populates chats. Requires `canGetPublicFileSystem`. The token must belong to `projectId`; otherwise `resourceNotFound` (400). Index pagination is the default; pass `paginate=cursor` for cursor pagination (cursor-only parameters are rejected with index pagination and `page` is rejected with cursor pagination).
# Get public file systems for a project (/docs/reference/api/projects/get-projects-projectid-public)
Retrieves a paginated list of public file systems for a project with support for search, filtering, and both cursor and index-based pagination. Requires `canGetPublicFileSystem`. Cursor-only parameters are rejected with index pagination and `page` is rejected with cursor pagination.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /projects/{projectId}/public
Get public file systems for a project
Retrieves a paginated list of public file systems for a project with support for search, filtering, and both cursor and index-based pagination. Requires `canGetPublicFileSystem`. Cursor-only parameters are rejected with index pagination and `page` is rejected with cursor pagination.
# Get highlighted messages across the project's reviewer-visible chats (/docs/reference/api/projects/get-projects-projectid-reviewer-highlighted-messages)
Cursor-paginated list of active chat messages flagged `highlighted` whose scope is this project and whose scope visibility includes `reviewer`. Each message is populated (author, attachments, etc.) and carries its parent `chat`. Requires `canGetReviewerHighlights`.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /projects/{projectId}/reviewer/highlighted-messages
Get highlighted messages across the project's reviewer-visible chats
Cursor-paginated list of active chat messages flagged `highlighted` whose scope is this project and whose scope visibility includes `reviewer`. Each message is populated (author, attachments, etc.) and carries its parent `chat`. Requires `canGetReviewerHighlights`.
# Get file system items at a path within a submission (/docs/reference/api/projects/get-projects-projectid-submission-submissionid-files-path)
Same as the root listing, scoped to a folder path inside the submission. Path segments may be folder slugs or IDs (IDs are resolved to slugs; an unknown segment returns `fileSystemPathNotFound`, 404). Requires `canGetSubmission`; the submission must belong to `projectId`.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /projects/{projectId}/submission/{submissionId}/files/{path}
Get file system items at a path within a submission
Same as the root listing, scoped to a folder path inside the submission. Path segments may be folder slugs or IDs (IDs are resolved to slugs; an unknown segment returns `fileSystemPathNotFound`, 404). Requires `canGetSubmission`; the submission must belong to `projectId`.
# Get file system items at the root of a submission (/docs/reference/api/projects/get-projects-projectid-submission-submissionid-files)
Lists the items directly under `submission/{submissionId}`. Requires `canGetSubmission`; the submission must belong to `projectId`. Each item carries its populated `resource` and, for assets, the reviewer chat. Index pagination is the default; pass `paginate=cursor` for cursor pagination (cursor-only parameters are rejected with index pagination and `page` is rejected with cursor pagination). `resourceIds` and `resourceSlugs` may not both be set (`invalidItemSearchParams`, 400).
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /projects/{projectId}/submission/{submissionId}/files
Get file system items at the root of a submission
Lists the items directly under `submission/{submissionId}`. Requires `canGetSubmission`; the submission must belong to `projectId`. Each item carries its populated `resource` and, for assets, the reviewer chat. Index pagination is the default; pass `paginate=cursor` for cursor pagination (cursor-only parameters are rejected with index pagination and `page` is rejected with cursor pagination). `resourceIds` and `resourceSlugs` may not both be set (`invalidItemSearchParams`, 400).
# Get a specific submission for a project with recent messages. (/docs/reference/api/projects/get-projects-projectid-submission-submissionid)
Note, submissions are a Chat model. Requires `canGetSubmission`. The submission must belong to `projectId`; a foreign or unknown id returns `submissionNotFound` (404).
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /projects/{projectId}/submission/{submissionId}
Get a specific submission for a project with recent messages.
Note, submissions are a Chat model. Requires `canGetSubmission`. The submission must belong to `projectId`; a foreign or unknown id returns `submissionNotFound` (404).
# Get submissions for a project (/docs/reference/api/projects/get-projects-projectid-submission)
Requires `canGetSubmission`. Callers holding `canCreateSubmission` also see staged `unreleased` submissions; everyone else sees only `active` ones. Index pagination is the default; pass `paginate=cursor` for cursor pagination (cursor-only parameters are rejected with index pagination, and `page`, `createdBefore`, `createdAfter` are rejected with cursor pagination).
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /projects/{projectId}/submission
Get submissions for a project
Requires `canGetSubmission`. Callers holding `canCreateSubmission` also see staged `unreleased` submissions; everyone else sees only `active` ones. Index pagination is the default; pass `paginate=cursor` for cursor pagination (cursor-only parameters are rejected with index pagination, and `page`, `createdBefore`, `createdAfter` are rejected with cursor pagination).
# Get project details (/docs/reference/api/projects/get-projects-projectid)
Requires `canGetProject`. The caller's roles on the project are attached to the response.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /projects/{projectId}
Get project details
Requires `canGetProject`. The caller's roles on the project are attached to the response.
# Get projects for the authenticated user (/docs/reference/api/projects/get-projects)
Returns every active project the caller is a member of, with the caller's role attached to each project.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /projects
Get projects for the authenticated user
Returns every active project the caller is a member of, with the caller's role attached to each project.
# Get project topic chat (creator or reviewer). (/docs/reference/api/projects/getProjectChat)
Returns the project's topic chat for the given visibility with its most recent messages and replies. Requires `canGetCreatorChat` for `creator` and `canGetReviewerChat` for `reviewer`.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /projects/{projectId}/chat/{visibility}
Get project topic chat (creator or reviewer).
Returns the project's topic chat for the given visibility with its most recent messages and replies. Requires `canGetCreatorChat` for `creator` and `canGetReviewerChat` for `reviewer`.
# Update a single project setting (/docs/reference/api/projects/patch-projects-projectid-settings-name)
Updates one key of the project's `settings` JSON column. Mirrors the
workspace settings endpoint. Requires `canManageProjectSettings`
(no subscription check on this route).
At the project level every setting accepts `null`, meaning "inherit the
workspace's value". Otherwise the type of `value` depends on `name`:
- `allowAiFeatures`, `aiPolishEnabled`, `aiComposeEnabled`, `aiChatEnabled`,
`aiAssistEnabled`, `aiTaskGenerationEnabled`, `aiImageRevisionEnabled`,
`aiPolishAllowReviewer`, `aiComposeAllowReviewer`, `aiChatAllowReviewer`,
`aiAssistAllowReviewer`, `aiTaskGenerationAllowReviewer`,
`aiImageRevisionAllowReviewer` — boolean.
- `aiAssistFollowUpWindow` — integer, 0–30.
- `aiCustomPreprompt`, `aiTaskGenerationPreprompt` — string (may be empty; empty means "no preprompt", null means inherit).
- `aiChatTools`, `aiAssistTools` — object mapping tool names (`^[a-z][a-z0-9_]*$`) to boolean or null.
A `value` of the wrong type for the setting is a validation error (400).
Machine-readable definition: https://docs.nurama.com/openapi.json
## PATCH /projects/{projectId}/settings/{name}
Update a single project setting
Updates one key of the project's `settings` JSON column. Mirrors the
workspace settings endpoint. Requires `canManageProjectSettings`
(no subscription check on this route).
At the project level every setting accepts `null`, meaning "inherit the
workspace's value". Otherwise the type of `value` depends on `name`:
- `allowAiFeatures`, `aiPolishEnabled`, `aiComposeEnabled`, `aiChatEnabled`,
`aiAssistEnabled`, `aiTaskGenerationEnabled`, `aiImageRevisionEnabled`,
`aiPolishAllowReviewer`, `aiComposeAllowReviewer`, `aiChatAllowReviewer`,
`aiAssistAllowReviewer`, `aiTaskGenerationAllowReviewer`,
`aiImageRevisionAllowReviewer` — boolean.
- `aiAssistFollowUpWindow` — integer, 0–30.
- `aiCustomPreprompt`, `aiTaskGenerationPreprompt` — string (may be empty; empty means "no preprompt", null means inherit).
- `aiChatTools`, `aiAssistTools` — object mapping tool names (`^[a-z][a-z0-9_]*$`) to boolean or null.
A `value` of the wrong type for the setting is a validation error (400).
# Create a new folder in a project (/docs/reference/api/projects/post-projects-projectid-files-visibility-create-folder)
Creates a folder in the creator or reviewer tree. The required permission depends on `visibility`, as it does for move and copy: `creator` needs `canCreateFolder`; `reviewer` needs `canCreateReviewerFolder`, which only the workspace and project admin tiers hold. A creator can publish into the reviewer tree but not create folders there directly, matching the fact that they hold no reviewer move or copy right. Reserved names (`Review`, `Public`, `Submission`) are rejected (`reservedFolderName`, 400), as are base paths inside a virtual folder (`protectedBasePath`, 400). A `basePath` that does not exist returns `basePathNotFound` (404).
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /projects/{projectId}/files/{visibility}/create-folder
Create a new folder in a project
Creates a folder in the creator or reviewer tree. The required permission depends on `visibility`, as it does for move and copy: `creator` needs `canCreateFolder`; `reviewer` needs `canCreateReviewerFolder`, which only the workspace and project admin tiers hold. A creator can publish into the reviewer tree but not create folders there directly, matching the fact that they hold no reviewer move or copy right. Reserved names (`Review`, `Public`, `Submission`) are rejected (`reservedFolderName`, 400), as are base paths inside a virtual folder (`protectedBasePath`, 400). A `basePath` that does not exist returns `basePathNotFound` (404).
# Preview what deleting items at these paths would reach (/docs/reference/api/projects/post-projects-projectid-files-visibility-delete-preview)
Answers what a delete would remove beyond the rows named, without deleting anything. Takes the same body the delete takes and resolves it through the same cascade, so the preview cannot disagree with the outcome.
Only SECONDARY references come back — the reviewer, submission and public-release copies that would go with the selection — not the rows the caller listed.
Costs the same right as the delete itself (`canDeleteCreatorItems` / `canDeleteReviewerItems`). A cheaper preview would hand out the labels of submissions and public releases the caller cannot otherwise see.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /projects/{projectId}/files/{visibility}/delete-preview
Preview what deleting items at these paths would reach
Answers what a delete would remove beyond the rows named, without deleting anything. Takes the same body the delete takes and resolves it through the same cascade, so the preview cannot disagree with the outcome.
Only SECONDARY references come back — the reviewer, submission and public-release copies that would go with the selection — not the rows the caller listed.
Costs the same right as the delete itself (`canDeleteCreatorItems` / `canDeleteReviewerItems`). A cheaper preview would hand out the labels of submissions and public releases the caller cannot otherwise see.
# Get items at a specific path within a project (filters in the body) (/docs/reference/api/projects/post-projects-projectid-files-visibility-path)
Identical to the GET listing at a path, but the query options are sent as a JSON body instead of query-string parameters. Same permissions and response shapes as the GET.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /projects/{projectId}/files/{visibility}/{path}
Get items at a specific path within a project (filters in the body)
Identical to the GET listing at a path, but the query options are sent as a JSON body instead of query-string parameters. Same permissions and response shapes as the GET.
# Get items at the root path of a project (filters in the body) (/docs/reference/api/projects/post-projects-projectid-files-visibility)
Identical to the GET listing, but the query options are sent as a JSON body instead of query-string parameters — useful when the filter set (for example a long `resourceIds` list) would not fit in a URL. Same permissions and response shapes as the GET.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /projects/{projectId}/files/{visibility}
Get items at the root path of a project (filters in the body)
Identical to the GET listing, but the query options are sent as a JSON body instead of query-string parameters — useful when the filter set (for example a long `resourceIds` list) would not fit in a URL. Same permissions and response shapes as the GET.
# Create or update project logo. (deprecated alias; use PUT) (/docs/reference/api/projects/post-projects-projectid-logo)
Creates the logo asset and returns its signed upload link(s). POST and PUT run the same operation. Requires `canUpdateProject`. Returns `uploadRequestExceedsSubscription` (400) when the file would exceed the workspace's subscribed storage.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /projects/{projectId}/logo (deprecated)
Create or update project logo. (deprecated alias; use PUT)
Creates the logo asset and returns its signed upload link(s). POST and PUT run the same operation. Requires `canUpdateProject`. Returns `uploadRequestExceedsSubscription` (400) when the file would exceed the workspace's subscribed storage.
# Add items to public file system (/docs/reference/api/projects/post-projects-projectid-public-publicid-add)
Copies additional creator-tree items (assets or folders) into an existing public file system, marks the assets public and recomputes the release inventory. `itemPaths` are relative to `project/{projectId}/creator`. Requires `canAddPubicFileSystemItems`; the record must belong to `projectId`.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /projects/{projectId}/public/{publicId}/add
Add items to public file system
Copies additional creator-tree items (assets or folders) into an existing public file system, marks the assets public and recomputes the release inventory. `itemPaths` are relative to `project/{projectId}/creator`. Requires `canAddPubicFileSystemItems`; the record must belong to `projectId`.
# Release a staged (unreleased) public file system (/docs/reference/api/projects/post-projects-projectid-public-publicid-release)
Flips a public file system's status from `unreleased` to `active`, making it externally accessible via its public token and recomputing the `hasActivePublicFileSystem` flag on its assets. Requires `canUpdatePublicFileSystem`. Returns `publicNotUnreleased` (400) if the record isn't in the `unreleased` state.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /projects/{projectId}/public/{publicId}/release
Release a staged (unreleased) public file system
Flips a public file system's status from `unreleased` to `active`, making it externally accessible via its public token and recomputing the `hasActivePublicFileSystem` flag on its assets. Requires `canUpdatePublicFileSystem`. Returns `publicNotUnreleased` (400) if the record isn't in the `unreleased` state.
# Create public asset chat message with lazy creation (authenticated management) (/docs/reference/api/projects/post-projects-projectid-public-token-assets-assetid-messages)
Creates a message on an asset's public chat. If no public chat exists for the asset
in this public file system, one is created automatically (lazy creation).
Unlike the unauthenticated `/public/{token}/assets/{assetId}/messages` endpoint, this does
NOT check token expiration. Use this for internal management of public file systems.
Requires `canGetPublicFileSystem` permission. Attachments, mentions, asset mentions
and quotes are not supported in public chats and are rejected.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /projects/{projectId}/public/{token}/assets/{assetId}/messages
Create public asset chat message with lazy creation (authenticated management)
Creates a message on an asset's public chat. If no public chat exists for the asset
in this public file system, one is created automatically (lazy creation).
Unlike the unauthenticated `/public/{token}/assets/{assetId}/messages` endpoint, this does
NOT check token expiration. Use this for internal management of public file systems.
Requires `canGetPublicFileSystem` permission. Attachments, mentions, asset mentions
and quotes are not supported in public chats and are rejected.
# Create public chat message (authenticated management) (/docs/reference/api/projects/post-projects-projectid-public-token-chat-chatid-messages)
Creates a message in an existing public chat.
Unlike the unauthenticated `/public/{token}/chat/{chatId}/messages` endpoint, this does
NOT check token expiration. Use this for internal management of public file systems.
Requires `canGetPublicFileSystem` permission. A chat that does not belong to this
release returns 403. Attachments, mentions, asset mentions and quotes are not
supported in public chats and are rejected.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /projects/{projectId}/public/{token}/chat/{chatId}/messages
Create public chat message (authenticated management)
Creates a message in an existing public chat.
Unlike the unauthenticated `/public/{token}/chat/{chatId}/messages` endpoint, this does
NOT check token expiration. Use this for internal management of public file systems.
Requires `canGetPublicFileSystem` permission. A chat that does not belong to this
release returns 403. Attachments, mentions, asset mentions and quotes are not
supported in public chats and are rejected.
# Create public topic chat message with lazy creation (authenticated management) (/docs/reference/api/projects/post-projects-projectid-public-token-chat-messages)
Creates a message on the main public topic chat. If no main chat exists for this
public file system, one is created automatically (lazy creation).
Unlike the unauthenticated `/public/{token}/chat/messages` endpoint, this does
NOT check token expiration. Use this for internal management of public file systems.
Requires `canGetPublicFileSystem` permission. Attachments, mentions, asset mentions
and quotes are not supported in public chats and are rejected.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /projects/{projectId}/public/{token}/chat/messages
Create public topic chat message with lazy creation (authenticated management)
Creates a message on the main public topic chat. If no main chat exists for this
public file system, one is created automatically (lazy creation).
Unlike the unauthenticated `/public/{token}/chat/messages` endpoint, this does
NOT check token expiration. Use this for internal management of public file systems.
Requires `canGetPublicFileSystem` permission. Attachments, mentions, asset mentions
and quotes are not supported in public chats and are rejected.
# Create a folder inside a public file system (/docs/reference/api/projects/post-projects-projectid-public-token-files-create-folder)
Creates a folder at `public/{publicId}/{basePath}` (or the release root when `basePath` is omitted) and recomputes the release inventory. Requires `canCreatePublicFileSystemFolder`; the token must belong to `projectId`. A `basePath` that does not exist in the release returns `basePathNotFound` (404); a folder with the same name already at that address returns `folderExistsAtPath` (409). Does NOT check token expiration.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /projects/{projectId}/public/{token}/files/create-folder
Create a folder inside a public file system
Creates a folder at `public/{publicId}/{basePath}` (or the release root when `basePath` is omitted) and recomputes the release inventory. Requires `canCreatePublicFileSystemFolder`; the token must belong to `projectId`. A `basePath` that does not exist in the release returns `basePathNotFound` (404); a folder with the same name already at that address returns `folderExistsAtPath` (409). Does NOT check token expiration.
# Create a public file system (/docs/reference/api/projects/post-projects-projectid-public)
Creates a public file system (a "release") with a secure token for sharing project assets publicly without authentication. `itemPaths` are relative to `project/{projectId}/creator`. Requires `canCreatePublicFileSystem`.
Gated by the `publicSharing` workspace capability — granted by every paid base plan and intentionally withheld from the Demo plan. Requests from workspaces without the capability return 403 `capabilityNotAvailable` with `errorData.capability = "publicSharing"`; clients can use this to prompt the user to upgrade their plan.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /projects/{projectId}/public
Create a public file system
Creates a public file system (a "release") with a secure token for sharing project assets publicly without authentication. `itemPaths` are relative to `project/{projectId}/creator`. Requires `canCreatePublicFileSystem`.
Gated by the `publicSharing` workspace capability — granted by every paid base plan and intentionally withheld from the Demo plan. Requests from workspaces without the capability return 403 `capabilityNotAvailable` with `errorData.capability = "publicSharing"`; clients can use this to prompt the user to upgrade their plan.
# Publish assets (/docs/reference/api/projects/post-projects-projectid-publish)
Bulk publish an array of file-system items (assets or folders) into the project's reviewer tree. The caller must hold `canPublishItem` on every listed resource; otherwise 403 with the offending ids in `errorData`. Fires per-item and project-level publish notifications, system messages in the creator and reviewer chats and, when `sendEmailNotification` is true, the published-items email.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /projects/{projectId}/publish
Publish assets
Bulk publish an array of file-system items (assets or folders) into the project's reviewer tree. The caller must hold `canPublishItem` on every listed resource; otherwise 403 with the offending ids in `errorData`. Fires per-item and project-level publish notifications, system messages in the creator and reviewer chats and, when `sendEmailNotification` is true, the published-items email.
# Add reviewer-tree items to an existing submission (/docs/reference/api/projects/post-projects-projectid-submission-submissionid-add)
Copies items from the project's reviewer tree into the submission. `itemPaths` are relative to `project/{projectId}/reviewer` and `destinationPath` is relative to `submission/{submissionId}` (omit it to add at the submission root; a destination folder that does not exist returns 404). Marks the copied assets as belonging to the submission and recomputes its inventory. Requires `canAddSubmittionItems`; the submission must belong to `projectId`.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /projects/{projectId}/submission/{submissionId}/add
Add reviewer-tree items to an existing submission
Copies items from the project's reviewer tree into the submission. `itemPaths` are relative to `project/{projectId}/reviewer` and `destinationPath` is relative to `submission/{submissionId}` (omit it to add at the submission root; a destination folder that does not exist returns 404). Marks the copied assets as belonging to the submission and recomputes its inventory. Requires `canAddSubmittionItems`; the submission must belong to `projectId`.
# Create a new folder within a submission (/docs/reference/api/projects/post-projects-projectid-submission-submissionid-files-create-folder)
Requires `canCreateSubmissionFolder`; the submission must belong to `projectId`. Reserved names return `reservedFolderName` (400), a `basePath` inside a virtual folder returns `protectedBasePath` (400), and a `basePath` that does not exist in the submission returns `basePathNotFound` (404). Recomputes the submission's inventory.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /projects/{projectId}/submission/{submissionId}/files/create-folder
Create a new folder within a submission
Requires `canCreateSubmissionFolder`; the submission must belong to `projectId`. Reserved names return `reservedFolderName` (400), a `basePath` inside a virtual folder returns `protectedBasePath` (400), and a `basePath` that does not exist in the submission returns `basePathNotFound` (404). Recomputes the submission's inventory.
# Re-release an already-released submission's side effects (/docs/reference/api/projects/post-projects-projectid-submission-submissionid-release-update)
The "Release Update" action for a live (`active`) submission. Re-fires the reviewer-facing side effects — the submission-update email template, a `submissionUpdate` notification, and system messages in the creator + reviewer project chats — to announce that a released submission has changed. Does NOT change the submission's status. Requires `canUpdateSubmission`. Returns `submissionNotFound` if no active submission matches.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /projects/{projectId}/submission/{submissionId}/release-update
Re-release an already-released submission's side effects
The "Release Update" action for a live (`active`) submission. Re-fires the reviewer-facing side effects — the submission-update email template, a `submissionUpdate` notification, and system messages in the creator + reviewer project chats — to announce that a released submission has changed. Does NOT change the submission's status. Requires `canUpdateSubmission`. Returns `submissionNotFound` if no active submission matches.
# Release a staged (unreleased) submission (/docs/reference/api/projects/post-projects-projectid-submission-submissionid-release)
Flips a submission's status from `unreleased` to `active`, making it visible to reviewers and firing the deferred "new submission" side effects (project-member email, notification, push summary, and system messages in the creator + reviewer project chats). Requires `canUpdateSubmission`. Returns `submissionNotUnreleased` (400) if the submission isn't in the `unreleased` state.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /projects/{projectId}/submission/{submissionId}/release
Release a staged (unreleased) submission
Flips a submission's status from `unreleased` to `active`, making it visible to reviewers and firing the deferred "new submission" side effects (project-member email, notification, push summary, and system messages in the creator + reviewer project chats). Requires `canUpdateSubmission`. Returns `submissionNotUnreleased` (400) if the submission isn't in the `unreleased` state.
# Add a tag to a submission (deprecated alias; use PUT) (/docs/reference/api/projects/post-projects-projectid-submission-submissionid-tag)
Requires `canTagSubmission`. The submission must belong to `projectId`.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /projects/{projectId}/submission/{submissionId}/tag (deprecated)
Add a tag to a submission (deprecated alias; use PUT)
Requires `canTagSubmission`. The submission must belong to `projectId`.
# Remove a tag from a submission (deprecated alias; use PUT) (/docs/reference/api/projects/post-projects-projectid-submission-submissionid-untag)
Requires `canUntagSubmission`. The submission must belong to `projectId`.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /projects/{projectId}/submission/{submissionId}/untag (deprecated)
Remove a tag from a submission (deprecated alias; use PUT)
Requires `canUntagSubmission`. The submission must belong to `projectId`.
# Create a new submission for a project (/docs/reference/api/projects/post-projects-projectid-submission)
Note, submissions are a Chat model. Items are taken from the project's reviewer tree (`itemPaths` are relative to `project/{projectId}/reviewer`; already-prefixed paths are accepted as-is). Requires `canCreateSubmission`.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /projects/{projectId}/submission
Create a new submission for a project
Note, submissions are a Chat model. Items are taken from the project's reviewer tree (`itemPaths` are relative to `project/{projectId}/reviewer`; already-prefixed paths are accepted as-is). Requires `canCreateSubmission`.
# Unpublish assets (/docs/reference/api/projects/post-projects-projectid-unpublish)
Bulk unpublish an array of assets, removing their reviewer-tree references. Only assets can be unpublished (a folder is removed from the reviewer surface by deleting it there). The caller must hold `canUnpublishItem` on every listed resource; otherwise 403 with the offending ids in `errorData`.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /projects/{projectId}/unpublish
Unpublish assets
Bulk unpublish an array of assets, removing their reviewer-tree references. Only assets can be unpublished (a folder is removed from the reviewer surface by deleting it there). The caller must hold `canUnpublishItem` on every listed resource; otherwise 403 with the offending ids in `errorData`.
# Create assets and signed upload links for a project. (/docs/reference/api/projects/post-projects-projectid)
Creates assets in the project's creator tree and returns signed upload links. Requires `canCreateAsset`. When a submitted file's checksum matches an asset already in the project, no bytes are transferred: the platform adds another FileSystem reference to the existing asset and reports `status: success` with `referencesExistingAsset: true` and no signed URLs.
In that case the response's `name` is the EXISTING asset's name, because that is what the new reference carries — `FileSystem.resourceName` is a denormalized copy of `Asset.name`, so the submitted name never lands. The submitted name is returned as `originalName`. Correlate results with requests positionally or by your own upload id, not by `name`.
Returns `uploadRequestExceedsSubscription` (400) when the request would exceed the workspace's subscribed storage.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /projects/{projectId}
Create assets and signed upload links for a project.
Creates assets in the project's creator tree and returns signed upload links. Requires `canCreateAsset`. When a submitted file's checksum matches an asset already in the project, no bytes are transferred: the platform adds another FileSystem reference to the existing asset and reports `status: success` with `referencesExistingAsset: true` and no signed URLs.
In that case the response's `name` is the EXISTING asset's name, because that is what the new reference carries — `FileSystem.resourceName` is a denormalized copy of `Asset.name`, so the submitted name never lands. The submitted name is returned as `originalName`. Correlate results with requests positionally or by your own upload id, not by `name`.
Returns `uploadRequestExceedsSubscription` (400) when the request would exceed the workspace's subscribed storage.
# Create a new project and topic chats with for both reviewers and creators. (/docs/reference/api/projects/post-projects)
Requires `canCreateProject` on the target workspace and an active workspace subscription. Returns `maxProjectsPerWorkspace` (400) when the workspace has reached its plan's project cap and `projectNameTaken` (400) when a project with the same slug already exists in the workspace.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /projects
Create a new project and topic chats with for both reviewers and creators.
Requires `canCreateProject` on the target workspace and an active workspace subscription. Returns `maxProjectsPerWorkspace` (400) when the workspace has reached its plan's project cap and `projectNameTaken` (400) when a project with the same slug already exists in the workspace.
# Copy items to a new path within a project (/docs/reference/api/projects/put-projects-projectid-files-visibility-copy)
Paths are relative to `project/{projectId}/{visibility}`. Requires `canCopyCreatorItems` for `creator` and `canCopyReviewerItems` for `reviewer`.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /projects/{projectId}/files/{visibility}/copy
Copy items to a new path within a project
Paths are relative to `project/{projectId}/{visibility}`. Requires `canCopyCreatorItems` for `creator` and `canCopyReviewerItems` for `reviewer`.
# Delete items at specified paths within a project (/docs/reference/api/projects/put-projects-projectid-files-visibility-delete)
Paths are relative to `project/{projectId}/{visibility}`. Requires `canDeleteCreatorItems` for `creator` and `canDeleteReviewerItems` for `reviewer`. Use `delete-preview` first to learn which secondary references the cascade will remove.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /projects/{projectId}/files/{visibility}/delete
Delete items at specified paths within a project
Paths are relative to `project/{projectId}/{visibility}`. Requires `canDeleteCreatorItems` for `creator` and `canDeleteReviewerItems` for `reviewer`. Use `delete-preview` first to learn which secondary references the cascade will remove.
# Move items to a new path within a project (/docs/reference/api/projects/put-projects-projectid-files-visibility-move)
Paths are relative to `project/{projectId}/{visibility}`. Requires `canMoveCreatorItems` for `creator` and `canMoveReviewerItems` for `reviewer`. Items already in the destination folder are skipped (`count` may be 0).
A destination inside a virtual folder is a copy, not a move, and costs the right of the matching add route: `Public/{token}/...` requires `canAddPubicFileSystemItems`, `Submission/{id}/...` requires `canAddSubmittionItems`, and dropping onto `Review/...` publishes the items (requires `canPublishAsset`). Those responses carry `virtualDestination: true` (and `published: true` plus `errors` for `Review/`).
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /projects/{projectId}/files/{visibility}/move
Move items to a new path within a project
Paths are relative to `project/{projectId}/{visibility}`. Requires `canMoveCreatorItems` for `creator` and `canMoveReviewerItems` for `reviewer`. Items already in the destination folder are skipped (`count` may be 0).
A destination inside a virtual folder is a copy, not a move, and costs the right of the matching add route: `Public/{token}/...` requires `canAddPubicFileSystemItems`, `Submission/{id}/...` requires `canAddSubmittionItems`, and dropping onto `Review/...` publishes the items (requires `canPublishAsset`). Those responses carry `virtualDestination: true` (and `published: true` plus `errors` for `Review/`).
# Create or update project logo. (/docs/reference/api/projects/put-projects-projectid-logo)
Identical to `POST /projects/{projectId}/logo`. Requires `canUpdateProject`.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /projects/{projectId}/logo
Create or update project logo.
Identical to `POST /projects/{projectId}/logo`. Requires `canUpdateProject`.
# Update public file system details (/docs/reference/api/projects/put-projects-projectid-public-publicid)
Updates the title, description, validity and sharing flags of an existing public file system. Requires `canUpdatePublicFileSystem`; the record must belong to `projectId`.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /projects/{projectId}/public/{publicId}
Update public file system details
Updates the title, description, validity and sharing flags of an existing public file system. Requires `canUpdatePublicFileSystem`; the record must belong to `projectId`.
# Copy items within public file system (/docs/reference/api/projects/put-projects-projectid-public-token-files-copy)
Copies items to a new location within the public file system and recomputes the release inventory. Paths are relative to `public/{publicId}`. Requires `canCopyPublicFileSystemItems`; the token must belong to `projectId`. Does NOT check token expiration.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /projects/{projectId}/public/{token}/files/copy
Copy items within public file system
Copies items to a new location within the public file system and recomputes the release inventory. Paths are relative to `public/{publicId}`. Requires `canCopyPublicFileSystemItems`; the token must belong to `projectId`. Does NOT check token expiration.
# Delete items from public file system (/docs/reference/api/projects/put-projects-projectid-public-token-files-delete)
Deletes items from the public file system. Paths are relative to `public/{publicId}`. Requires `canDeletePublicFileSystemItems`; the token must belong to `projectId`. Does NOT check token expiration.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /projects/{projectId}/public/{token}/files/delete
Delete items from public file system
Deletes items from the public file system. Paths are relative to `public/{publicId}`. Requires `canDeletePublicFileSystemItems`; the token must belong to `projectId`. Does NOT check token expiration.
# Move items within public file system (/docs/reference/api/projects/put-projects-projectid-public-token-files-move)
Moves items to a new location within the public file system. Paths are relative to `public/{publicId}`. Items already in the destination folder are skipped (`count` may be 0). Requires `canMovePublicFileSystemItems`; the token must belong to `projectId`. Does NOT check token expiration.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /projects/{projectId}/public/{token}/files/move
Move items within public file system
Moves items to a new location within the public file system. Paths are relative to `public/{publicId}`. Items already in the destination folder are skipped (`count` may be 0). Requires `canMovePublicFileSystemItems`; the token must belong to `projectId`. Does NOT check token expiration.
# Copy items within a submission (/docs/reference/api/projects/put-projects-projectid-submission-submissionid-files-copy)
Paths are relative to `submission/{submissionId}`. Requires `canCopySubmissionItems`; the submission must belong to `projectId`. Recomputes the submission's inventory.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /projects/{projectId}/submission/{submissionId}/files/copy
Copy items within a submission
Paths are relative to `submission/{submissionId}`. Requires `canCopySubmissionItems`; the submission must belong to `projectId`. Recomputes the submission's inventory.
# Delete items within a submission (/docs/reference/api/projects/put-projects-projectid-submission-submissionid-files-delete)
Paths are relative to `submission/{submissionId}`. Requires `canDeleteSubmissionItems`; the submission must belong to `projectId`. Recomputes the submission's inventory.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /projects/{projectId}/submission/{submissionId}/files/delete
Delete items within a submission
Paths are relative to `submission/{submissionId}`. Requires `canDeleteSubmissionItems`; the submission must belong to `projectId`. Recomputes the submission's inventory.
# Move items within a submission (/docs/reference/api/projects/put-projects-projectid-submission-submissionid-files-move)
Paths are relative to `submission/{submissionId}`. Items already in the destination folder are skipped (`count` may be 0). Requires `canMoveSubmissionItems`; the submission must belong to `projectId`.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /projects/{projectId}/submission/{submissionId}/files/move
Move items within a submission
Paths are relative to `submission/{submissionId}`. Items already in the destination folder are skipped (`count` may be 0). Requires `canMoveSubmissionItems`; the submission must belong to `projectId`.
# Add a tag to a submission (/docs/reference/api/projects/put-projects-projectid-submission-submissionid-tag)
Requires `canTagSubmission`. The submission must belong to `projectId`.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /projects/{projectId}/submission/{submissionId}/tag
Add a tag to a submission
Requires `canTagSubmission`. The submission must belong to `projectId`.
# Remove a tag from a submission (/docs/reference/api/projects/put-projects-projectid-submission-submissionid-untag)
Requires `canUntagSubmission`. The submission must belong to `projectId`.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /projects/{projectId}/submission/{submissionId}/untag
Remove a tag from a submission
Requires `canUntagSubmission`. The submission must belong to `projectId`.
# Update a submission (/docs/reference/api/projects/put-projects-projectid-submission-submissionid)
Requires `canUpdateSubmission`. The submission must belong to `projectId`.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /projects/{projectId}/submission/{submissionId}
Update a submission
Requires `canUpdateSubmission`. The submission must belong to `projectId`.
# Update project details (/docs/reference/api/projects/put-projects-projectid)
Requires `canUpdateProject`. A `projectUpdate` notification is emitted only when the name actually changes.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /projects/{projectId}
Update project details
Requires `canUpdateProject`. A `projectUpdate` notification is emitted only when the name actually changes.
# Full-text search across project content. (/docs/reference/api/projects/searchProject)
Searches across assets, chat messages, and tasks within a project using full-text search. The query uses web-search syntax: unquoted words must all match, `"quoted text"` matches a phrase, `OR` matches either side and a leading `-` excludes a word. Results are ranked by relevance and respect the caller's visibility (creator / reviewer) permissions. Each hit includes a populated `record` shaped per the content type's native list view. Requires `canGetProject`.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /projects/{projectId}/search
Full-text search across project content.
Searches across assets, chat messages, and tasks within a project using full-text search. The query uses web-search syntax: unquoted words must all match, `"quoted text"` matches a phrase, `OR` matches either side and a leading `-` excludes a word. Results are ranked by relevance and respect the caller's visibility (creator / reviewer) permissions. Each hit includes a populated `record` shaped per the content type's native list view. Requires `canGetProject`.
# Get asset with public chat (/docs/reference/api/public/get-public-token-assets-assetid)
Retrieves an asset along with its public chat in the context of this public file system.
The chat is returned in `chats.public` and will be null if no chat has been created yet.
No authentication required for read access.
When the release was created with `hideCreators: true`, the asset's creator fields are omitted.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /public/{token}/assets/{assetId}
Get asset with public chat
Retrieves an asset along with its public chat in the context of this public file system.
The chat is returned in `chats.public` and will be null if no chat has been created yet.
No authentication required for read access.
When the release was created with `hideCreators: true`, the asset's creator fields are omitted.
# Get public chat messages (/docs/reference/api/public/get-public-token-chat-chatid-messages)
Retrieves paginated messages for a public chat. The chat must be the
release's main topic chat or one of its asset public chats, otherwise
403 `forbidden` is returned.
No authentication required for read access.
Messages are always returned cursor-paginated. `paginate=index` and
`page` are accepted by validation but are ignored by the handler.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /public/{token}/chat/{chatId}/messages
Get public chat messages
Retrieves paginated messages for a public chat. The chat must be the
release's main topic chat or one of its asset public chats, otherwise
403 `forbidden` is returned.
No authentication required for read access.
Messages are always returned cursor-paginated. `paginate=index` and
`page` are accepted by validation but are ignored by the handler.
# Get main public file system chat (/docs/reference/api/public/get-public-token-chat)
Retrieves the main topic chat for a public file system.
Returns null if no main chat has been created yet (lazy creation pattern).
No authentication required for read access.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /public/{token}/chat
Get main public file system chat
Retrieves the main topic chat for a public file system.
Returns null if no main chat has been created yet (lazy creation pattern).
No authentication required for read access.
# Get public file system items at path (/docs/reference/api/public/get-public-token-files-path)
Retrieves items (assets and folders) from a public file system at a specific folder path. No authentication required. Accepts the same query parameters as `GET /public/{token}/files`. When the release was created with `hideCreators: true`, each item's creator fields are omitted.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /public/{token}/files/{path}
Get public file system items at path
Retrieves items (assets and folders) from a public file system at a specific folder path. No authentication required. Accepts the same query parameters as `GET /public/{token}/files`. When the release was created with `hideCreators: true`, each item's creator fields are omitted.
# Get public file system items (/docs/reference/api/public/get-public-token-files)
Retrieves items (assets and folders) from a public file system at the root level. No authentication required. Supports index pagination (default) or cursor pagination via `paginate=cursor`; the cursor-only options are rejected with 400 when `paginate` is `index`, and `page` is rejected when `paginate` is `cursor`. Populated resources are reduced to the public allowlist before being returned. When the release was created with `hideCreators: true`, each item's `creator` / `resourceCreator` / `resourceCreatorId` fields are omitted.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /public/{token}/files
Get public file system items
Retrieves items (assets and folders) from a public file system at the root level. No authentication required. Supports index pagination (default) or cursor pagination via `paginate=cursor`; the cursor-only options are rejected with 400 when `paginate` is `index`, and `page` is rejected when `paginate` is `cursor`. Populated resources are reduced to the public allowlist before being returned. When the release was created with `hideCreators: true`, each item's `creator` / `resourceCreator` / `resourceCreatorId` fields are omitted.
# Get public file system details (/docs/reference/api/public/get-public-token)
Retrieves detailed information about a public file system using its access token. No authentication required. The token must resolve to an `active`, unexpired release. When the release was created with `hideCreators: true`, the `creator` and `creatorId` fields ("Shared by") are omitted from the response.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /public/{token}
Get public file system details
Retrieves detailed information about a public file system using its access token. No authentication required. The token must resolve to an `active`, unexpired release. When the release was created with `hideCreators: true`, the `creator` and `creatorId` fields ("Shared by") are omitted from the response.
# Create message on asset's public chat (lazy creation) (/docs/reference/api/public/post-public-token-assets-assetid-messages)
Creates a message on an asset's public chat. If no public chat exists for this asset
in this public file system, one is created automatically (lazy creation pattern).
**Authentication is optional.** A signed-in user posts with their real
identity (`authorId`); an unauthenticated visitor may post anonymously by
supplying `guestName` when the release has `allowAnonymousComments` enabled.
See the `guestId` / `guestColor` notes on `POST /public/{token}/chat/{chatId}/messages`.
Attachments, mentions, asset mentions and quotes are not supported in
public chats and are rejected with 400.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /public/{token}/assets/{assetId}/messages
Create message on asset's public chat (lazy creation)
Creates a message on an asset's public chat. If no public chat exists for this asset
in this public file system, one is created automatically (lazy creation pattern).
**Authentication is optional.** A signed-in user posts with their real
identity (`authorId`); an unauthenticated visitor may post anonymously by
supplying `guestName` when the release has `allowAnonymousComments` enabled.
See the `guestId` / `guestColor` notes on `POST /public/{token}/chat/{chatId}/messages`.
Attachments, mentions, asset mentions and quotes are not supported in
public chats and are rejected with 400.
# Create message in public chat (/docs/reference/api/public/post-public-token-chat-chatid-messages)
Creates a new message in an existing public chat. The chat must be the
release's main topic chat or one of its asset public chats.
**Authentication is optional.** A signed-in user posts with their real
identity (`authorId`). An unauthenticated visitor may post anonymously by
supplying a display name (`guestName`) — but only when the release has
`allowAnonymousComments` enabled. The client should also send a stable
`guestId` (a UUID it persists in localStorage per token) so two guests who
type the same name stay distinct, plus an optional `guestColor`. Guest
fields are ignored when the caller is authenticated.
Attachments, mentions, asset mentions and quotes are not supported in
public chats and are rejected with 400.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /public/{token}/chat/{chatId}/messages
Create message in public chat
Creates a new message in an existing public chat. The chat must be the
release's main topic chat or one of its asset public chats.
**Authentication is optional.** A signed-in user posts with their real
identity (`authorId`). An unauthenticated visitor may post anonymously by
supplying a display name (`guestName`) — but only when the release has
`allowAnonymousComments` enabled. The client should also send a stable
`guestId` (a UUID it persists in localStorage per token) so two guests who
type the same name stay distinct, plus an optional `guestColor`. Guest
fields are ignored when the caller is authenticated.
Attachments, mentions, asset mentions and quotes are not supported in
public chats and are rejected with 400.
# Create message on the main public chat (lazy creation) (/docs/reference/api/public/post-public-token-chat-messages)
Creates a message on the public file system's main topic chat. If the
main chat does not exist yet it is created automatically (lazy creation
pattern), using the release title as its subject.
**Authentication is optional.** A signed-in user posts with their real
identity (`authorId`); an unauthenticated visitor may post anonymously by
supplying `guestName` when the release has `allowAnonymousComments` enabled.
See the `guestId` / `guestColor` notes on `POST /public/{token}/chat/{chatId}/messages`.
Attachments, mentions, asset mentions and quotes are not supported in
public chats and are rejected with 400.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /public/{token}/chat/messages
Create message on the main public chat (lazy creation)
Creates a message on the public file system's main topic chat. If the
main chat does not exist yet it is created automatically (lazy creation
pattern), using the release title as its subject.
**Authentication is optional.** A signed-in user posts with their real
identity (`authorId`); an unauthenticated visitor may post anonymously by
supplying `guestName` when the release has `allowAnonymousComments` enabled.
See the `guestId` / `guestColor` notes on `POST /public/{token}/chat/{chatId}/messages`.
Attachments, mentions, asset mentions and quotes are not supported in
public chats and are rejected with 400.
# Generate download links for assets (/docs/reference/api/public/post-public-token-download)
Generates signed download URLs for the original files of assets in a public file system. No authentication required. Every requested asset must exist within the release's file-system path, otherwise the whole request is rejected with 400 `assetNotFound`. One result object is returned per requested asset; an individual entry may carry `status: fail` (with an `error` code) when its original file could not be signed.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /public/{token}/download
Generate download links for assets
Generates signed download URLs for the original files of assets in a public file system. No authentication required. Every requested asset must exist within the release's file-system path, otherwise the whole request is rejected with 400 `assetNotFound`. One result object is returned per requested asset; an individual entry may carry `status: fail` (with an `error` code) when its original file could not be signed.
# List all public download links for an asset (/docs/reference/api/publicassetlinks/get-assets-assetid-public-links)
Returns all public download links for an asset, including active, disabled, and expired links.
Requires canGetPublicLinks permission.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /assets/{assetId}/public-links
List all public download links for an asset
Returns all public download links for an asset, including active, disabled, and expired links.
Requires canGetPublicLinks permission.
# List all public download links for an asset (/docs/reference/api/assets/get-assets-assetid-public-links)
Returns all public download links for an asset, including active, disabled, and expired links.
Requires canGetPublicLinks permission.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /assets/{assetId}/public-links
List all public download links for an asset
Returns all public download links for an asset, including active, disabled, and expired links.
Requires canGetPublicLinks permission.
# Get a signed download URL for a public download token (/docs/reference/api/publicassetlinks/get-public-download-token-download)
Generates a signed download URL for the asset's original file.
No authentication required. The URL is temporary and expires.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /public-download/{token}/download
Get a signed download URL for a public download token
Generates a signed download URL for the asset's original file.
No authentication required. The URL is temporary and expires.
# Resolve a public asset link to embed-player file paths (/docs/reference/api/publicassetlinks/get-public-download-token-embed-files)
Returns the HLS streaming manifest keyPath and a fallback original-media keyPath
for the asset behind a public download token. This is what the embeddable
player at `/public/{token}/embed` uses.
Resolve keyPaths against the base media URL. Play the `.m3u8` manifest with an
HLS-capable player when `streamKeyPath` is present, falling back to the original
media file otherwise. Only `video` and `audio` assets are meant to be embedded;
the response still returns paths for other media types, but they should not be
embedded.
No authentication required. Returns minimal file info — never the full asset
record (no `id`, `files`, `creatorId`, etc.).
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /public-download/{token}/embed-files
Resolve a public asset link to embed-player file paths
Returns the HLS streaming manifest keyPath and a fallback original-media keyPath
for the asset behind a public download token. This is what the embeddable
player at `/public/{token}/embed` uses.
Resolve keyPaths against the base media URL. Play the `.m3u8` manifest with an
HLS-capable player when `streamKeyPath` is present, falling back to the original
media file otherwise. Only `video` and `audio` assets are meant to be embedded;
the response still returns paths for other media types, but they should not be
embedded.
No authentication required. Returns minimal file info — never the full asset
record (no `id`, `files`, `creatorId`, etc.).
# Resolve a public download token (/docs/reference/api/publicassetlinks/get-public-download-token)
Resolves a public download token to minimal file information for the download page.
No authentication required. Returns fileName, mediaType, status, the link mode,
and (for image assets) a `previewKeyPath` so the page can render an inline preview.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /public-download/{token}
Resolve a public download token
Resolves a public download token to minimal file information for the download page.
No authentication required. Returns fileName, mediaType, status, the link mode,
and (for image assets) a `previewKeyPath` so the page can render an inline preview.
# Create a public download link for an asset (/docs/reference/api/publicassetlinks/post-assets-assetid-public-links)
Creates a temporary public download link for an asset. The link can optionally have
an expiration. Requires the `canCreatePublicLink` permission (project/workspace admin roles)
AND the `publicSharing` workspace capability — granted by every paid base plan and
intentionally withheld from the Demo plan. Workspaces without the capability receive
403 `capabilityNotAvailable` with `errorData.capability = "publicSharing"`, which
clients can use to prompt for an upgrade.
Sets `hasActivePublicLink`, `everPublic`, and `publicAssetLinkIds` on the asset.
Sends a notification and email to workspace admins if the creator is a project-level admin.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /assets/{assetId}/public-links
Create a public download link for an asset
Creates a temporary public download link for an asset. The link can optionally have
an expiration. Requires the `canCreatePublicLink` permission (project/workspace admin roles)
AND the `publicSharing` workspace capability — granted by every paid base plan and
intentionally withheld from the Demo plan. Workspaces without the capability receive
403 `capabilityNotAvailable` with `errorData.capability = "publicSharing"`, which
clients can use to prompt for an upgrade.
Sets `hasActivePublicLink`, `everPublic`, and `publicAssetLinkIds` on the asset.
Sends a notification and email to workspace admins if the creator is a project-level admin.
# Create a public download link for an asset (/docs/reference/api/assets/post-assets-assetid-public-links)
Creates a temporary public download link for an asset. The link can optionally have
an expiration. Requires the `canCreatePublicLink` permission (project/workspace admin roles)
AND the `publicSharing` workspace capability — granted by every paid base plan and
intentionally withheld from the Demo plan. Workspaces without the capability receive
403 `capabilityNotAvailable` with `errorData.capability = "publicSharing"`, which
clients can use to prompt for an upgrade.
Sets `hasActivePublicLink`, `everPublic`, and `publicAssetLinkIds` on the asset.
Sends a notification and email to workspace admins if the creator is a project-level admin.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /assets/{assetId}/public-links
Create a public download link for an asset
Creates a temporary public download link for an asset. The link can optionally have
an expiration. Requires the `canCreatePublicLink` permission (project/workspace admin roles)
AND the `publicSharing` workspace capability — granted by every paid base plan and
intentionally withheld from the Demo plan. Workspaces without the capability receive
403 `capabilityNotAvailable` with `errorData.capability = "publicSharing"`, which
clients can use to prompt for an upgrade.
Sets `hasActivePublicLink`, `everPublic`, and `publicAssetLinkIds` on the asset.
Sends a notification and email to workspace admins if the creator is a project-level admin.
# Disable a public download link (/docs/reference/api/publicassetlinks/put-assets-assetid-public-links-linkid-disable)
Sets the link status to 'disabled'. The link can no longer be used for downloads.
Updates hasActivePublicLink on the asset. Requires canUpdatePublicLink permission.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /assets/{assetId}/public-links/{linkId}/disable
Disable a public download link
Sets the link status to 'disabled'. The link can no longer be used for downloads.
Updates hasActivePublicLink on the asset. Requires canUpdatePublicLink permission.
# Reactivate a disabled or expired public download link (/docs/reference/api/publicassetlinks/put-assets-assetid-public-links-linkid-reactivate)
Sets the link status back to 'active' with an optional new expiration.
Updates hasActivePublicLink on the asset. Requires canUpdatePublicLink permission.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /assets/{assetId}/public-links/{linkId}/reactivate
Reactivate a disabled or expired public download link
Sets the link status back to 'active' with an optional new expiration.
Updates hasActivePublicLink on the asset. Requires canUpdatePublicLink permission.
# Update a public download link (/docs/reference/api/publicassetlinks/put-assets-assetid-public-links-linkid)
Update a public link's expiration or status. At least one field must be provided.
Requires canUpdatePublicLink permission.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /assets/{assetId}/public-links/{linkId}
Update a public download link
Update a public link's expiration or status. At least one field must be provided.
Requires canUpdatePublicLink permission.
# Finish a multipart upload for a scratch object. (/docs/reference/api/scratch/post-scratch-scratchid-complete-upload)
Same body as `POST /v1/assets/complete-upload`. Commits the
multipart upload, records the final object size against the
workspace's storage usage, and moves the scratch object to
`active`. Only the user who created the scratch object may call
this (403 otherwise). Idempotent: calling it on an
already-`active` object returns the same `{ id, url }` without
changing anything.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /scratch/{scratchId}/complete-upload
Finish a multipart upload for a scratch object.
Same body as `POST /v1/assets/complete-upload`. Commits the
multipart upload, records the final object size against the
workspace's storage usage, and moves the scratch object to
`active`. Only the user who created the scratch object may call
this (403 otherwise). Idempotent: calling it on an
already-`active` object returns the same `{ id, url }` without
changing anything.
# Promote a scratch object to a real Asset. (/docs/reference/api/scratch/post-scratch-scratchid-promote)
Materialises an `active` scratch object as an Asset
(`functionType: media`) in the workspace or project the scratch
object was created in. The destination is derived from the scratch
object itself — a project asset when it was created within a
project, otherwise a workspace asset — and is **not** accepted from
the request body, so a client cannot claim a scratch object belongs
to a different workspace or project.
Only the user who created the scratch object may promote it, and
they must also hold `canCreateAsset` on the destination workspace
or project.
Idempotent: promoting an object that was already promoted returns
the existing asset with `alreadyPromoted: true`, so a client can
tell "freshly added" from "already added". To attach a scratch
object to a chat message instead, pass it as a `{ scratchId, name? }`
attachment when sending the message
(`POST /v1/chats/{chatId}/messages`).
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /scratch/{scratchId}/promote
Promote a scratch object to a real Asset.
Materialises an `active` scratch object as an Asset
(`functionType: media`) in the workspace or project the scratch
object was created in. The destination is derived from the scratch
object itself — a project asset when it was created within a
project, otherwise a workspace asset — and is **not** accepted from
the request body, so a client cannot claim a scratch object belongs
to a different workspace or project.
Only the user who created the scratch object may promote it, and
they must also hold `canCreateAsset` on the destination workspace
or project.
Idempotent: promoting an object that was already promoted returns
the existing asset with `alreadyPromoted: true`, so a client can
tell "freshly added" from "already added". To attach a scratch
object to a chat message instead, pass it as a `{ scratchId, name? }`
attachment when sending the message
(`POST /v1/chats/{chatId}/messages`).
# Reset resource settings (/docs/reference/api/settings/delete-settings-resourcetype-resourceid)
Remove all setting overrides for this resource
Machine-readable definition: https://docs.nurama.com/openapi.json
## DELETE /settings/{resourceType}/{resourceId}
Reset resource settings
Remove all setting overrides for this resource
# Get effective settings for a resource (/docs/reference/api/settings/get-settings-resourcetype-resourceid-effective)
Returns resolved settings with cascade from global (user preferences) → workspace → project. Only the caller's own settings are resolved.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /settings/{resourceType}/{resourceId}/effective
Get effective settings for a resource
Returns resolved settings with cascade from global (user preferences) → workspace → project. Only the caller's own settings are resolved.
# Get raw resource settings (/docs/reference/api/settings/get-settings-resourcetype-resourceid)
Returns only the caller's overrides for this specific resource (not cascaded). When no overrides exist a `{ message }` object is returned instead (still 200).
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /settings/{resourceType}/{resourceId}
Get raw resource settings
Returns only the caller's overrides for this specific resource (not cascaded). When no overrides exist a `{ message }` object is returned instead (still 200).
# Get all resource settings (/docs/reference/api/settings/get-settings)
Returns all resource-specific setting overrides for the current user
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /settings
Get all resource settings
Returns all resource-specific setting overrides for the current user
# Update resource settings (/docs/reference/api/settings/put-settings-resourcetype-resourceid)
Create or update the caller's setting overrides for a specific resource. Each supplied category is shallow-merged into the existing overrides for that resource; at least one category is required. No check is made that the caller is a member of the resource.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /settings/{resourceType}/{resourceId}
Update resource settings
Create or update the caller's setting overrides for a specific resource. Each supplied category is shallow-merged into the existing overrides for that resource; at least one category is required. No check is made that the caller is a member of the resource.
# Resolve a short link (/docs/reference/api/shortlinks/get-shortlink-code)
Resolves a short link code to its full deep link. This endpoint is publicly accessible
and does not require authentication. The deep link can be used to navigate directly to
a resource in the Nurama web app.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /shortlink/{code}
Resolve a short link
Resolves a short link code to its full deep link. This endpoint is publicly accessible
and does not require authentication. The deep link can be used to navigate directly to
a resource in the Nurama web app.
# Create a short link for an asset (/docs/reference/api/shortlinks/post-assets-assetid-shortlink)
Creates a short link for an asset. If a short link already exists for the asset
with the same visibility setting, the existing short link is returned.
Requires `canGetAsset` on the asset.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /assets/{assetId}/shortlink
Create a short link for an asset
Creates a short link for an asset. If a short link already exists for the asset
with the same visibility setting, the existing short link is returned.
Requires `canGetAsset` on the asset.
# Create a short link for an asset (/docs/reference/api/assets/post-assets-assetid-shortlink)
Creates a short link for an asset. If a short link already exists for the asset
with the same visibility setting, the existing short link is returned.
Requires `canGetAsset` on the asset.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /assets/{assetId}/shortlink
Create a short link for an asset
Creates a short link for an asset. If a short link already exists for the asset
with the same visibility setting, the existing short link is returned.
Requires `canGetAsset` on the asset.
# Create a short link for a chat message (/docs/reference/api/shortlinks/post-chats-message-messageid-shortlink)
Creates a short link for a chat message. If a short link already exists for the message,
the existing short link is returned. Visibility is automatically inherited from the
parent chat (e.g., 'creator' or 'reviewer' for topic chats, null for member chats).
Requires `canCreateMessageShortLink` (read access to the message's chat).
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /chats/message/{messageId}/shortlink
Create a short link for a chat message
Creates a short link for a chat message. If a short link already exists for the message,
the existing short link is returned. Visibility is automatically inherited from the
parent chat (e.g., 'creator' or 'reviewer' for topic chats, null for member chats).
Requires `canCreateMessageShortLink` (read access to the message's chat).
# Create a short link for a chat message (/docs/reference/api/chats/post-chats-message-messageid-shortlink)
Creates a short link for a chat message. If a short link already exists for the message,
the existing short link is returned. Visibility is automatically inherited from the
parent chat (e.g., 'creator' or 'reviewer' for topic chats, null for member chats).
Requires `canCreateMessageShortLink` (read access to the message's chat).
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /chats/message/{messageId}/shortlink
Create a short link for a chat message
Creates a short link for a chat message. If a short link already exists for the message,
the existing short link is returned. Visibility is automatically inherited from the
parent chat (e.g., 'creator' or 'reviewer' for topic chats, null for member chats).
Requires `canCreateMessageShortLink` (read access to the message's chat).
# Get storage chart data (/docs/reference/api/storage/getStorageChart)
Returns the average `sizeInBytes` of a resource's storage records per aggregation period between `startDate` and `endDate`, with missing periods filled from the previous value. Allowed when requesting your own user storage, or when you hold `canGet{ResourceType}Storage` (e.g. `canGetWorkspaceStorage`) on the resource.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /storage/chart/{resourceType}/{resourceId}
Get storage chart data
Returns the average `sizeInBytes` of a resource's storage records per aggregation period between `startDate` and `endDate`, with missing periods filled from the previous value. Allowed when requesting your own user storage, or when you hold `canGet{ResourceType}Storage` (e.g. `canGetWorkspaceStorage`) on the resource.
# Get storage record (/docs/reference/api/storage/getStorageRecord)
Returns the most recent storage record for a resource. Allowed when requesting your own user storage, or when you hold `canGet{ResourceType}Storage` on the resource.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /storage/{resourceType}/{resourceId}
Get storage record
Returns the most recent storage record for a resource. Allowed when requesting your own user storage, or when you hold `canGet{ResourceType}Storage` on the resource.
# Delete a tag (/docs/reference/api/tags/delete-tags-tagid)
Permanently deletes a tag. This action cannot be undone. Requires `canDeleteTag`.
Machine-readable definition: https://docs.nurama.com/openapi.json
## DELETE /tags/{tagId}
Delete a tag
Permanently deletes a tag. This action cannot be undone. Requires `canDeleteTag`.
# Get tags for a resource (/docs/reference/api/tags/get-tags-ownerresourcetype-ownerresourceid)
Retrieves all tags owned by a specific resource. Requires `canGetTags` on `ownerResourceId`. Currently only `ownerResourceType: project` is accepted.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /tags/{ownerResourceType}/{ownerResourceId}
Get tags for a resource
Retrieves all tags owned by a specific resource. Requires `canGetTags` on `ownerResourceId`. Currently only `ownerResourceType: project` is accepted.
# Create a new tag (/docs/reference/api/tags/post-tags)
Creates a new project-scoped tag. Tags can then be applied to the project's assets, folders, submissions, boards and tasks via their `/tag` endpoints. Requires `canCreateTag` on `ownerResourceId`. Currently only `ownerResourceType: project` is accepted. Tag names must be unique per owner (400 `tagSlugExists`).
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /tags
Create a new tag
Creates a new project-scoped tag. Tags can then be applied to the project's assets, folders, submissions, boards and tasks via their `/tag` endpoints. Requires `canCreateTag` on `ownerResourceId`. Currently only `ownerResourceType: project` is accepted. Tag names must be unique per owner (400 `tagSlugExists`).
# Update a tag (/docs/reference/api/tags/put-tags-tagid)
Updates an existing tag's name and/or color. When the name is changed, the slug is automatically regenerated. Requires `canUpdateTag`.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /tags/{tagId}
Update a tag
Updates an existing tag's name and/or color. When the name is changed, the slug is automatically regenerated. Requires `canUpdateTag`.
# Update task details (/docs/reference/api/task-details/put-tasks-taskid-details)
Update a task's subject, description, or assignee. Used for editing task content outside of board column operations.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /tasks/{taskId}/details
Update task details
Update a task's subject, description, or assignee. Used for editing task content outside of board column operations.
# Unlink two tasks (/docs/reference/api/task-links/delete-tasks-taskid-links-linkedtaskid)
Removes the link between two tasks in both directions.
Machine-readable definition: https://docs.nurama.com/openapi.json
## DELETE /tasks/{taskId}/links/{linkedTaskId}
Unlink two tasks
Removes the link between two tasks in both directions.
# Get links for a task (/docs/reference/api/task-links/get-tasks-taskid-links)
Returns all links for a task in both directions. Link types are normalized relative to the queried task (e.g., blocks/blockedBy are flipped when the task is in the linkedTaskId position).
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /tasks/{taskId}/links
Get links for a task
Returns all links for a task in both directions. Link types are normalized relative to the queried task (e.g., blocks/blockedBy are flipped when the task is in the linkedTaskId position).
# Link two tasks (/docs/reference/api/task-links/post-tasks-taskid-links)
Creates a relationship link between two tasks. Duplicate links are rejected.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /tasks/{taskId}/links
Link two tasks
Creates a relationship link between two tasks. Duplicate links are rejected.
# Remove a task relation (/docs/reference/api/task-relations/delete-tasks-taskid-relations-relationid)
Deletes the relation and notifies the board's project channels. Requires update access on the task's board.
Machine-readable definition: https://docs.nurama.com/openapi.json
## DELETE /tasks/{taskId}/relations/{relationId}
Remove a task relation
Deletes the relation and notifies the board's project channels. Requires update access on the task's board.
# List task relations for a chat message (/docs/reference/api/task-relations/get-chat-messages-messageid-relations)
Returns a page of relations whose resource is this chat message, populated like `GET /tasks/{taskId}/relations`. Requires read access to the message's chat.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /chat-messages/{messageId}/relations
List task relations for a chat message
Returns a page of relations whose resource is this chat message, populated like `GET /tasks/{taskId}/relations`. Requires read access to the message's chat.
# List task relations for a chat (/docs/reference/api/task-relations/get-chats-chatid-relations)
Returns a page of relations whose resource is this chat, populated like `GET /tasks/{taskId}/relations`. Requires read access to the chat.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /chats/{chatId}/relations
List task relations for a chat
Returns a page of relations whose resource is this chat, populated like `GET /tasks/{taskId}/relations`. Requires read access to the chat.
# List task relations (/docs/reference/api/task-relations/get-tasks-taskid-relations)
Returns a page of "Related To" entries for a task, populated with chat / message / asset / submission / public-link context and the user who created each relation. Rows whose chat the caller cannot read are filtered out (`totalResults` reflects the filtered page). Requires read access to the task's board.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /tasks/{taskId}/relations
List task relations
Returns a page of "Related To" entries for a task, populated with chat / message / asset / submission / public-link context and the user who created each relation. Rows whose chat the caller cannot read are filtered out (`totalResults` reflects the filtered page). Requires read access to the task's board.
# Relate a chat or chat message to a task (/docs/reference/api/task-relations/post-tasks-taskid-relations)
Creates a relation between a task and either a Chat or a single ChatMessage. The task must be on a board.
Visibility rules are enforced server-side:
- Submission and public chats can attach to any task.
- Creator chats only attach to tasks on creator-visibility boards.
- Reviewer chats only attach to tasks on reviewer-visibility boards.
For chat messages the visibility is derived from the message's parent chat.
Requires update access on the task's board plus read access to the chat / message being attached.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /tasks/{taskId}/relations
Relate a chat or chat message to a task
Creates a relation between a task and either a Chat or a single ChatMessage. The task must be on a board.
Visibility rules are enforced server-side:
- Submission and public chats can attach to any task.
- Creator chats only attach to tasks on creator-visibility boards.
- Reviewer chats only attach to tasks on reviewer-visibility boards.
For chat messages the visibility is derived from the message's parent chat.
Requires update access on the task's board plus read access to the chat / message being attached.
# Delete a task (/docs/reference/api/tasks/delete-tasks-taskid)
Permanently removes a single task. Requires `canRemove{Creator|Reviewer}BoardTask` for
at least one visibility tier of the task's parent board, plus the `boards` workspace
capability. Logs a `taskDeleted` event.
Machine-readable definition: https://docs.nurama.com/openapi.json
## DELETE /tasks/{taskId}
Delete a task
Permanently removes a single task. Requires `canRemove{Creator|Reviewer}BoardTask` for
at least one visibility tier of the task's parent board, plus the `boards` workspace
capability. Logs a `taskDeleted` event.
# Get task event log (/docs/reference/api/tasks/get-tasks-taskid-events)
Returns a paginated activity log for a task. Each event includes the actor (public user with avatar) and a structured `detail` object with the context needed to render a human-readable message.
Event types: created, addedToBoard, moved, assigned, unassigned, updated, removedFromBoard, linked, unlinked, followed, unfollowed.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /tasks/{taskId}/events
Get task event log
Returns a paginated activity log for a task. Each event includes the actor (public user with avatar) and a structured `detail` object with the context needed to render a human-readable message.
Event types: created, addedToBoard, moved, assigned, unassigned, updated, removedFromBoard, linked, unlinked, followed, unfollowed.
# Get count of unacknowledged tasks for a project. (/docs/reference/api/tasks/get-tasks-unacknowledged-projectid)
Counts the authenticated user's unacknowledged tasks in the project, split by visibility.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /tasks/unacknowledged/{projectId}
Get count of unacknowledged tasks for a project.
Counts the authenticated user's unacknowledged tasks in the project, split by visibility.
# Get paginated list of tasks assigned to a user. (/docs/reference/api/tasks/get-tasks)
Returns tasks where `assignedToId` is the authenticated user. Supports index (default) or cursor pagination; the cursor-only and index-only parameters are mutually exclusive with the other `paginate` mode.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /tasks
Get paginated list of tasks assigned to a user.
Returns tasks where `assignedToId` is the authenticated user. Supports index (default) or cursor pagination; the cursor-only and index-only parameters are mutually exclusive with the other `paginate` mode.
# Create several board tasks in one request (/docs/reference/api/tasks/post-tasks-bulk-create)
Single round-trip replacement for creating tasks one at a time. Every draft is
created in order; per-draft failures are reported inline (`status: 'error'`) and do
not abort the batch, so the response is always 200 once validation passes.
Any logged-in user may call this; the per-board `canCreate{Creator|Reviewer}BoardTask`
permission is checked for each draft (`no_permission`), as is that the board is
active and belongs to `projectId` (`board_not_found`). Requires the `boards`
workspace capability.
Each created task gets the same side effects as `POST /boards/{boardId}/tasks`
(event log, notification, `created` task event, topic chat) and, when `tagIds` is
supplied, the tags are applied inline. When `announce` is provided and at least one
task was created, a single assistant reply carrying every new task is posted in the
source chat as a reply to `messageId`; announce failures never fail the request.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /tasks/bulk-create
Create several board tasks in one request
Single round-trip replacement for creating tasks one at a time. Every draft is
created in order; per-draft failures are reported inline (`status: 'error'`) and do
not abort the batch, so the response is always 200 once validation passes.
Any logged-in user may call this; the per-board `canCreate{Creator|Reviewer}BoardTask`
permission is checked for each draft (`no_permission`), as is that the board is
active and belongs to `projectId` (`board_not_found`). Requires the `boards`
workspace capability.
Each created task gets the same side effects as `POST /boards/{boardId}/tasks`
(event log, notification, `created` task event, topic chat) and, when `tagIds` is
supplied, the tags are applied inline. When `announce` is provided and at least one
task was created, a single assistant reply carrying every new task is posted in the
source chat as a reply to `messageId`; announce failures never fail the request.
# Acknowledge all of the current user's unacknowledged mention-tasks in a project. (/docs/reference/api/tasks/put-tasks-acknowledge-all-projectid)
Sets `acknowledged: true` on every unacknowledged mention-task assigned to the authenticated user in the project. Idempotent — already-acknowledged tasks are left as-is and never re-counted. Scoped to the caller's own tasks; other users' tasks are untouched.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /tasks/acknowledge-all/{projectId}
Acknowledge all of the current user's unacknowledged mention-tasks in a project.
Sets `acknowledged: true` on every unacknowledged mention-task assigned to the authenticated user in the project. Idempotent — already-acknowledged tasks are left as-is and never re-counted. Scoped to the caller's own tasks; other users' tasks are untouched.
# Toggle acknowledgement of a task. (/docs/reference/api/tasks/put-tasks-acknowledge-taskid)
Flips the task's `acknowledged` flag. Requires `canUpdateOwnTaskStatus`.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /tasks/acknowledge/{taskId}
Toggle acknowledgement of a task.
Flips the task's `acknowledged` flag. Requires `canUpdateOwnTaskStatus`.
# Follow a task (/docs/reference/api/tasks/put-tasks-taskid-follow)
Add the current user to the task's followers list. Idempotent — following again has no effect.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /tasks/{taskId}/follow
Follow a task
Add the current user to the task's followers list. Idempotent — following again has no effect.
# Tag a task (/docs/reference/api/tasks/put-tasks-taskid-tag)
Add a project tag to a task. Idempotent — tagging again has no effect.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /tasks/{taskId}/tag
Tag a task
Add a project tag to a task. Idempotent — tagging again has no effect.
# Unfollow a task (/docs/reference/api/tasks/put-tasks-taskid-unfollow)
Remove the current user from the task's followers list.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /tasks/{taskId}/unfollow
Unfollow a task
Remove the current user from the task's followers list.
# Untag a task (/docs/reference/api/tasks/put-tasks-taskid-untag)
Remove a project tag from a task.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /tasks/{taskId}/untag
Untag a task
Remove a project tag from a task.
# Update status of task. (/docs/reference/api/tasks/put-tasks-taskid)
Requires `canUpdateOwnTaskStatus` (the task must be assigned to the caller, or the caller must hold an elevated task permission).
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /tasks/{taskId}
Update status of task.
Requires `canUpdateOwnTaskStatus` (the task must be assigned to the caller, or the caller must hold an elevated task permission).
# Get public information about a user with shared membership. (/docs/reference/api/users/get-users-userid)
Returns the public profile of a user who shares at least one workspace/project membership with the caller (or the caller's own public profile).
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /users/{userId}
Get public information about a user with shared membership.
Returns the public profile of a user who shares at least one workspace/project membership with the caller (or the caller's own public profile).
# Get logged in user's details. (/docs/reference/api/users/get-users)
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /users
Get logged in user's details.
# Update the logged-in user's preferences. (/docs/reference/api/users/patch-users-preferences)
Patch-merges the supplied fields into the user's `preferences` JSON.
Omitted keys are left untouched. Used for notification settings, sound
preferences, hide flags, and onboarding-Todo dismissals. Unknown keys
(at any level) are rejected with 400.
`dismissed.*` groups per-user UX opt-outs (todos, workspace-setup
prompts, etc). The `dismissed` object is merged one level deep, so
writing one inner key preserves the others. For todos, unknown ids and
ids of Todos that are not dismissible (such as `verifyEmail`) are
ignored.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PATCH /users/preferences
Update the logged-in user's preferences.
Patch-merges the supplied fields into the user's `preferences` JSON.
Omitted keys are left untouched. Used for notification settings, sound
preferences, hide flags, and onboarding-Todo dismissals. Unknown keys
(at any level) are rejected with 400.
`dismissed.*` groups per-user UX opt-outs (todos, workspace-setup
prompts, etc). The `dismissed` object is merged one level deep, so
writing one inner key preserves the others. For todos, unknown ids and
ids of Todos that are not dismissible (such as `verifyEmail`) are
ignored.
# Create or update an avatar. (/docs/reference/api/users/post-users-avatar)
Creates the avatar asset and returns signed upload links for it. Any existing avatar asset is marked `pendingDelete`. POST and PUT are identical.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /users/avatar
Create or update an avatar.
Creates the avatar asset and returns signed upload links for it. Any existing avatar asset is marked `pendingDelete`. POST and PUT are identical.
# Create or update an avatar. (/docs/reference/api/users/put-users-avatar)
Creates the avatar asset and returns signed upload links for it. Any existing avatar asset is marked `pendingDelete`. POST and PUT are identical.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /users/avatar
Create or update an avatar.
Creates the avatar asset and returns signed upload links for it. Any existing avatar asset is marked `pendingDelete`. POST and PUT are identical.
# Get the latest git commit hash (/docs/reference/api/version/get-version-commit)
Returns the latest git commit hash and build timestamp of the deployed application. Public — no authentication required. The commit is injected during the build process, so accurate values are only available on deployed builds.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /version/commit
Get the latest git commit hash
Returns the latest git commit hash and build timestamp of the deployed application. Public — no authentication required. The commit is injected during the build process, so accurate values are only available on deployed builds.
# Delete a webhook subscription (/docs/reference/api/webhook-subscriptions/delete-workspaces-workspaceid-webhooks-webhookid)
Permanently removes the subscription and its delivery attempts.
Machine-readable definition: https://docs.nurama.com/openapi.json
## DELETE /workspaces/{workspaceId}/webhooks/{webhookId}
Delete a webhook subscription
Permanently removes the subscription and its delivery attempts.
# List delivery attempts (/docs/reference/api/webhook-subscriptions/get-workspaces-workspaceid-webhooks-webhookid-deliveries)
Cursor-paginated delivery log, newest first. Each retry of a notification is its own attempt. Pass the returned `nextCursor` back as `cursor` to fetch the next page.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /workspaces/{workspaceId}/webhooks/{webhookId}/deliveries
List delivery attempts
Cursor-paginated delivery log, newest first. Each retry of a notification is its own attempt. Pass the returned `nextCursor` back as `cursor` to fetch the next page.
# Get a webhook subscription (/docs/reference/api/webhook-subscriptions/get-workspaces-workspaceid-webhooks-webhookid)
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /workspaces/{workspaceId}/webhooks/{webhookId}
Get a webhook subscription
# List the workspace's webhook subscriptions (/docs/reference/api/webhook-subscriptions/get-workspaces-workspaceid-webhooks)
Newest first. Secrets are never included.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /workspaces/{workspaceId}/webhooks
List the workspace's webhook subscriptions
Newest first. Secrets are never included.
# Update a webhook subscription (/docs/reference/api/webhook-subscriptions/patch-workspaces-workspaceid-webhooks-webhookid)
Partial update; at least one field is required. `status` accepts only the admin-controllable transitions `active` and `paused` — setting `active` on a `failedOut` subscription re-enables it and clears `failedOutAt` / `failedOutReason`. Pass `expiresAt: null` to clear an expiry. URL and event changes go through the same checks as create.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PATCH /workspaces/{workspaceId}/webhooks/{webhookId}
Update a webhook subscription
Partial update; at least one field is required. `status` accepts only the admin-controllable transitions `active` and `paused` — setting `active` on a `failedOut` subscription re-enables it and clears `failedOutAt` / `failedOutReason`. Pass `expiresAt: null` to clear an expiry. URL and event changes go through the same checks as create.
# Replay a delivery (/docs/reference/api/webhook-subscriptions/post-workspaces-workspaceid-webhooks-webhookid-deliveries-attemptid-replay)
Re-queues the attempt's notification for delivery. A NEW attempt is created (the original is kept for the audit trail) and the notification is queued for delivery again.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /workspaces/{workspaceId}/webhooks/{webhookId}/deliveries/{attemptId}/replay
Replay a delivery
Re-queues the attempt's notification for delivery. A NEW attempt is created (the original is kept for the audit trail) and the notification is queued for delivery again.
# Rotate the signing secret (/docs/reference/api/webhook-subscriptions/post-workspaces-workspaceid-webhooks-webhookid-rotate-secret)
Generates a new HMAC signing secret and returns it once. Deliveries signed after this call use the new secret immediately; update the receiver's verification config first if you need zero-downtime rotation.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /workspaces/{workspaceId}/webhooks/{webhookId}/rotate-secret
Rotate the signing secret
Generates a new HMAC signing secret and returns it once. Deliveries signed after this call use the new secret immediately; update the receiver's verification config first if you need zero-downtime rotation.
# Queue a test delivery (/docs/reference/api/webhook-subscriptions/post-workspaces-workspaceid-webhooks-webhookid-test)
Fires a synthetic `webhook.test` event through the normal delivery pipeline. The subscription does not need `webhook.test` in its `events` list. The response only confirms the event was queued — inspect the delivery log (`GET .../deliveries`) for the outcome.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /workspaces/{workspaceId}/webhooks/{webhookId}/test
Queue a test delivery
Fires a synthetic `webhook.test` event through the normal delivery pipeline. The subscription does not need `webhook.test` in its `events` list. The response only confirms the event was queued — inspect the delivery log (`GET .../deliveries`) for the outcome.
# Create a webhook subscription (/docs/reference/api/webhook-subscriptions/post-workspaces-workspaceid-webhooks)
Registers a delivery URL for the given events and returns the new subscription together with its `signingSecret` — the only time the secret is returned other than on rotate. The URL must be `http(s)`, ≤ 2048 chars, and must not point at a private / loopback / link-local address (literal IPs are rejected outright; hostnames are DNS-resolved and checked). Deployments that require HTTPS reject `http://` URLs except for `localhost`.
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /workspaces/{workspaceId}/webhooks
Create a webhook subscription
Registers a delivery URL for the given events and returns the new subscription together with its `signingSecret` — the only time the secret is returned other than on rotate. The URL must be `http(s)`, ≤ 2048 chars, and must not point at a private / loopback / link-local address (literal IPs are rejected outright; hostnames are DNS-resolved and checked). Deployments that require HTTPS reject `http://` URLs except for `localhost`.
# Change a workspace's status to 'pendingDelete' for later cleanup. (/docs/reference/api/workspaces/delete-workspaces-workspaceid)
Requires `canDeleteWorkspace`, which only the workspace OWNER holds — not `canUpdateWorkspace`, which admins also hold. Deleting the workspace is the one way an admin could take it away from its owner, so it costs the owner-only right.
Machine-readable definition: https://docs.nurama.com/openapi.json
## DELETE /workspaces/{workspaceId}
Change a workspace's status to 'pendingDelete' for later cleanup.
Requires `canDeleteWorkspace`, which only the workspace OWNER holds — not `canUpdateWorkspace`, which admins also hold. Deleting the workspace is the one way an admin could take it away from its owner, so it costs the owner-only right.
# Get projects within a specific workspace (/docs/reference/api/workspaces/get-workspaces-workspaceid-projects)
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /workspaces/{workspaceId}/projects
Get projects within a specific workspace
# Get details of a specific workspace (/docs/reference/api/workspaces/get-workspaces-workspaceid)
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /workspaces/{workspaceId}
Get details of a specific workspace
# Get all workspaces for the authenticated user (/docs/reference/api/workspaces/get-workspaces)
Returns every workspace the caller holds a membership in, each stamped with the caller's `roles` and the workspace's `capabilities`. Sort with the `sort` query parameter (deep-object style, e.g. `?sort[name]=1&sort[createdAt]=-1`). A `sort` object in the request body is still accepted as a deprecated alias for one release.
Machine-readable definition: https://docs.nurama.com/openapi.json
## GET /workspaces
Get all workspaces for the authenticated user
Returns every workspace the caller holds a membership in, each stamped with the caller's `roles` and the workspace's `capabilities`. Sort with the `sort` query parameter (deep-object style, e.g. `?sort[name]=1&sort[createdAt]=-1`). A `sort` object in the request body is still accepted as a deprecated alias for one release.
# Create or update workspace icon. (deprecated alias; use PUT) (/docs/reference/api/workspaces/post-workspaces-workspaceid-icon)
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /workspaces/{workspaceId}/icon (deprecated)
Create or update workspace icon. (deprecated alias; use PUT)
# Create or update workspace logo. (deprecated alias; use PUT) (/docs/reference/api/workspaces/post-workspaces-workspaceid-logo)
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /workspaces/{workspaceId}/logo (deprecated)
Create or update workspace logo. (deprecated alias; use PUT)
# Create a new workspace (/docs/reference/api/workspaces/post-workspaces)
Machine-readable definition: https://docs.nurama.com/openapi.json
## POST /workspaces
Create a new workspace
# Create or update workspace icon. (/docs/reference/api/workspaces/put-workspaces-workspaceid-icon)
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /workspaces/{workspaceId}/icon
Create or update workspace icon.
# Create or update workspace logo. (/docs/reference/api/workspaces/put-workspaces-workspaceid-logo)
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /workspaces/{workspaceId}/logo
Create or update workspace logo.
# Update a single workspace setting. (/docs/reference/api/workspaces/put-workspaces-workspaceid-settings-name)
Sets one key of the workspace's `settings` JSON column. The `name` path parameter selects the setting and determines the type `value` must have (booleans for the toggles, bounded integers for the credit budgets, strings for the pre-prompts, `{ toolName: boolean|null }` maps for `aiChatTools` / `aiAssistTools`). Requires `canManageWorkspaceSettings` on the workspace.
Setting-specific behaviour:
- `autoTopUpEnabled: true` is refused with `autoTopUpRequiresPriorTopUp`
until the workspace has made at least one manual credit top-up.
- Flipping `boardsEnabled` true→false schedules every board in the
workspace for deletion after a 48h grace window; flipping it back
within the window restores them.
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /workspaces/{workspaceId}/settings/{name}
Update a single workspace setting.
Sets one key of the workspace's `settings` JSON column. The `name` path parameter selects the setting and determines the type `value` must have (booleans for the toggles, bounded integers for the credit budgets, strings for the pre-prompts, `{ toolName: boolean|null }` maps for `aiChatTools` / `aiAssistTools`). Requires `canManageWorkspaceSettings` on the workspace.
Setting-specific behaviour:
- `autoTopUpEnabled: true` is refused with `autoTopUpRequiresPriorTopUp`
until the workspace has made at least one manual credit top-up.
- Flipping `boardsEnabled` true→false schedules every board in the
workspace for deletion after a 48h grace window; flipping it back
within the window restores them.
# Update details of a specific workspace (/docs/reference/api/workspaces/put-workspaces-workspaceid)
Machine-readable definition: https://docs.nurama.com/openapi.json
## PUT /workspaces/{workspaceId}
Update details of a specific workspace
# WebSocket events (/docs/reference/websocket)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Websocket (Socket.io) events emitted by the websocket server (hosted separately from the REST API).
**Connecting / channels.** Every channel is a Socket.io namespace named `/{resourceType}/{resourceId}[/{visibility}]`, where resourceType is one of workspace, project, user, chat, asset, submission, task or public, resourceId is a UUID (or legacy 24-char hex id) and the optional visibility is creator, reviewer or public. Public release channels are `/public/{token}` (10-character public token, no visibility suffix). Any other namespace is refused. Authenticate by passing `query: { token }` on the handshake: a user JWT, a personal access token or a bot API key (bot keys must connect through a configured bot gateway hostname). `/public/{token}` namespaces need no handshake token (the token in the namespace is validated instead); authenticated users may also join them. Failures surface as `connect_error` with message `forbidden` (invalid credentials or no permission) or `badRequest` (malformed channel / permission lookup error).
**Permissions.** A user may only join their own `/user/{userId}`. `/project/{id}/creator`, `/reviewer` and `/public` require canGetProjectCreatorNotifications, canGetProjectReviewerNotifications and canGetProjectPublicNotifications respectively; every other channel requires canGet\{ResourceType}Notifications (direct or inherited).
**Server -> client events:** `notification` (every notification event documented below, emitted on each channel in the notification's channels list; the payload `type` selects the schema), `tokenEvent`, `typing:start` / `typing:stop` and the `collab:*` events (only on `/chat/{chatId}` namespaces). **Client -> server events:** `ws:probe`, `typing:start` / `typing:stop`, `collab:*`. Sockets whose JWT expired or was blacklisted, or whose bot key was revoked, receive `tokenEvent` and are disconnected shortly after.
Each event type below is documented using 'get' to represent the emitted event payload under the '200' response schema. **Keys marked with (\*) will be deprecated in a future release and should not be used for new development and should be replaced with values and objects in the changes key in existing implementations.**
## Servers [#servers]
| Server | URL | Notes |
| ------------ | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `production` | `wss://ws.nurama.com/socket.io` | WebSocket server for user credentials (JWT or personal access token). Socket.IO transport: connect a Socket.IO client to the channel address, not a raw WebSocket. |
| `bots` | `wss://bot-ws.nurama.com/socket.io` | WebSocket server for bot API keys. |
## Channels [#channels]
Channels are Socket.IO namespaces. Connect a Socket.IO client to the namespace address; do not open a raw WebSocket.
### Resource namespace [#resource-namespace]
Address: `/\{resourceType\}/\{resourceId\}/\{visibility\}`
Notifications for one workspace, project, user, chat, asset, submission or task.
Socket.IO namespace named after the resource. The `/{visibility}` segment is optional: connect to `/{resourceType}/{resourceId}` for the default channel. Requires a handshake `token`. A user may only join their own `/user/{userId}`; `/project/{id}/creator`, `/reviewer` and `/public` require canGetProjectCreatorNotifications, canGetProjectReviewerNotifications and canGetProjectPublicNotifications; every other channel requires canGet\{ResourceType}Notifications (direct or inherited).
| Parameter | Description |
| -------------- | -------------------------------------------------------------------------- |
| `resourceType` | Type of the resource whose events to receive. |
| `resourceId` | UUID (or legacy 24-character hex id) of the resource. |
| `visibility` | Optional visibility sub-channel; omit the segment for the default channel. |
### Public release namespace [#public-release-namespace]
Address: `/public/\{token\}`
Notifications for one public release, authenticated by the token in the namespace name.
No handshake `token` is needed (authenticated users may still send one). No visibility suffix. Typing indicators for chats that belong to the release are relayed here as well.
| Parameter | Description |
| --------- | ----------------------------------------------- |
| `token` | 10-character alphanumeric public release token. |
### Collab session namespace [#collab-session-namespace]
Address: `/chat/\{resourceId\}`
Real-time collaboration relay (cursors, drawing, presenter control) between the sockets of one chat.
The relay runs on namespaces starting with `/chat/`; the same connection also receives the notification events of the resource namespace. Relayed payloads are enriched server-side with the authenticated user identity, so client supplied identity keys are overwritten.
| Parameter | Description |
| ------------ | ----------------- |
| `resourceId` | UUID of the chat. |
## Events [#events]
| Event | Direction | Channel | Summary |
| --------------------------------------------------------------------------------------------------------------- | --------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Receive notification](/docs/reference/websocket/events/receive-notification) | server → client | `resource` | Envelope event on which every notification listed in this section is delivered. The type property tells you which event schema applies. |
| [Receive notification](/docs/reference/websocket/events/receive-public-notification) | server → client | `public` | Envelope event on which every notification listed in this section is delivered. The type property tells you which event schema applies. |
| [Receive tokenEvent](/docs/reference/websocket/events/receive-tokenevent) | server → client | `resource` | Emitted by the server right before it force-disconnects a socket whose credential is no longer valid. |
| [Emit ws:probe](/docs/reference/websocket/events/send-ws-probe) | client → server | `resource` | Client -> server liveness probe. Emit with an acknowledgement callback; the server acks immediately with no payload. |
| [Emit typing:start](/docs/reference/websocket/events/send-typing-start) | client → server | `resource` | Ephemeral typing indicator. Client -> server: emit \{ chatId }. Server -> clients: relayed with the authenticated userId to every other socket on the chat channels. |
| [Receive typing:start](/docs/reference/websocket/events/receive-typing-start) | server → client | `resource` | Ephemeral typing indicator. Client -> server: emit \{ chatId }. Server -> clients: relayed with the authenticated userId to every other socket on the chat channels. |
| [Emit typing:stop](/docs/reference/websocket/events/send-typing-stop) | client → server | `resource` | Ephemeral typing indicator stop. Client -> server: emit \{ chatId }. Server -> clients: relayed with the authenticated userId to every other socket on the chat channels. |
| [Receive typing:stop](/docs/reference/websocket/events/receive-typing-stop) | server → client | `resource` | Ephemeral typing indicator stop. Client -> server: emit \{ chatId }. Server -> clients: relayed with the authenticated userId to every other socket on the chat channels. |
| [Emit collab:join](/docs/reference/websocket/events/send-collab-join) | client → server | `collab` | A user joined the collab session on this chat namespace (broadcast to the other members). |
| [Receive collab:join](/docs/reference/websocket/events/receive-collab-join) | server → client | `collab` | A user joined the collab session on this chat namespace (broadcast to the other members). |
| [Emit collab:leave](/docs/reference/websocket/events/send-collab-leave) | client → server | `collab` | A user left the collab session (explicit collab:leave from the client or socket disconnect). |
| [Receive collab:leave](/docs/reference/websocket/events/receive-collab-leave) | server → client | `collab` | A user left the collab session (explicit collab:leave from the client or socket disconnect). |
| [Emit collab:cursor-move](/docs/reference/websocket/events/send-collab-cursor-move) | client → server | `collab` | Remote cursor position update (percentage coordinates). |
| [Receive collab:cursor-move](/docs/reference/websocket/events/receive-collab-cursor-move) | server → client | `collab` | Remote cursor position update (percentage coordinates). |
| [Emit collab:cursor-hide](/docs/reference/websocket/events/send-collab-cursor-hide) | client → server | `collab` | Remote cursor left the asset area. |
| [Receive collab:cursor-hide](/docs/reference/websocket/events/receive-collab-cursor-hide) | server → client | `collab` | Remote cursor left the asset area. |
| [Emit collab:path-start](/docs/reference/websocket/events/send-collab-path-start) | client → server | `collab` | Pen drawing started. |
| [Receive collab:path-start](/docs/reference/websocket/events/receive-collab-path-start) | server → client | `collab` | Pen drawing started. |
| [Emit collab:path-update](/docs/reference/websocket/events/send-collab-path-update) | client → server | `collab` | Pen drawing continued with additional points. |
| [Receive collab:path-update](/docs/reference/websocket/events/receive-collab-path-update) | server → client | `collab` | Pen drawing continued with additional points. |
| [Emit collab:path-end](/docs/reference/websocket/events/send-collab-path-end) | client → server | `collab` | Pen drawing completed. |
| [Receive collab:path-end](/docs/reference/websocket/events/receive-collab-path-end) | server → client | `collab` | Pen drawing completed. |
| [Emit collab:path-clear](/docs/reference/websocket/events/send-collab-path-clear) | client → server | `collab` | Drawn path(s) cleared. With pathId only that path is cleared, otherwise all paths of the user. |
| [Receive collab:path-clear](/docs/reference/websocket/events/receive-collab-path-clear) | server → client | `collab` | Drawn path(s) cleared. With pathId only that path is cleared, otherwise all paths of the user. |
| [Emit collab:click](/docs/reference/websocket/events/send-collab-click) | client → server | `collab` | Click ripple at percentage coordinates. |
| [Receive collab:click](/docs/reference/websocket/events/receive-collab-click) | server → client | `collab` | Click ripple at percentage coordinates. |
| [Emit collab:color-change](/docs/reference/websocket/events/send-collab-color-change) | client → server | `collab` | User changed their annotation colour. The server stores the new colour on the socket, so subsequent relayed events carry it. |
| [Receive collab:color-change](/docs/reference/websocket/events/receive-collab-color-change) | server → client | `collab` | User changed their annotation colour. The server stores the new colour on the socket, so subsequent relayed events carry it. |
| [Emit collab:region-create](/docs/reference/websocket/events/send-collab-region-create) | client → server | `collab` | Audio/video region created on the waveform/timeline. |
| [Receive collab:region-create](/docs/reference/websocket/events/receive-collab-region-create) | server → client | `collab` | Audio/video region created on the waveform/timeline. |
| [Emit collab:region-remove](/docs/reference/websocket/events/send-collab-region-remove) | client → server | `collab` | Region removed. |
| [Receive collab:region-remove](/docs/reference/websocket/events/receive-collab-region-remove) | server → client | `collab` | Region removed. |
| [Emit collab:zoom-sync](/docs/reference/websocket/events/send-collab-zoom-sync) | client → server | `collab` | Zoom level broadcast (followers of the presenter apply it). |
| [Receive collab:zoom-sync](/docs/reference/websocket/events/receive-collab-zoom-sync) | server → client | `collab` | Zoom level broadcast (followers of the presenter apply it). |
| [Emit collab:playback-sync](/docs/reference/websocket/events/send-collab-playback-sync) | client → server | `collab` | Play/pause/seek state broadcast by the presenter to the other members. |
| [Receive collab:playback-sync](/docs/reference/websocket/events/receive-collab-playback-sync) | server → client | `collab` | Play/pause/seek state broadcast by the presenter to the other members. |
| [Receive collab:playback-sync:rejected](/docs/reference/websocket/events/receive-collab-playback-sync-rejected) | server → client | `collab` | Server -> sender only: the sender is not the presenter, so its collab:playback-sync was dropped. Carries the real presenter and playback position so the client can snap back to follower mode. |
| [Receive collab:presenter-assign](/docs/reference/websocket/events/receive-collab-presenter-assign) | server → client | `collab` | Server -> all sockets in the namespace: a new presenter was assigned. |
| [Receive collab:presenter-state](/docs/reference/websocket/events/receive-collab-presenter-state) | server → client | `collab` | Server -> joining socket: current presenter and playback state when a presenter already exists. |
| [Emit collab:presenter-request](/docs/reference/websocket/events/send-collab-presenter-request) | client → server | `collab` | Request for presenter control. From an admin it is granted immediately (collab:presenter-assign, reason admin-takeover); from a non-admin it is relayed to the current presenter socket only. |
| [Receive collab:presenter-request](/docs/reference/websocket/events/receive-collab-presenter-request) | server → client | `collab` | Request for presenter control. From an admin it is granted immediately (collab:presenter-assign, reason admin-takeover); from a non-admin it is relayed to the current presenter socket only. |
| [Emit collab:presenter-takeover](/docs/reference/websocket/events/send-collab-presenter-takeover) | client → server | `collab` | Client -> server only: an admin or the current presenter hands presenter control to a target user. Results in a collab:presenter-assign (reason admin-takeover) to everyone; nothing is relayed under this name. |
| [Emit collab:state-request](/docs/reference/websocket/events/send-collab-state-request) | client → server | `collab` | Server -> the earliest joined other member: asks it to send its current annotation state to a late joiner (collab:state-response). |
| [Receive collab:state-request](/docs/reference/websocket/events/receive-collab-state-request) | server → client | `collab` | Server -> the earliest joined other member: asks it to send its current annotation state to a late joiner (collab:state-response). |
| [Emit collab:state-response](/docs/reference/websocket/events/send-collab-state-response) | client → server | `collab` | Server -> the requesting socket only: sanitised snapshot of paths, regions and zoom provided by an existing member. |
| [Receive collab:state-response](/docs/reference/websocket/events/receive-collab-state-response) | server → client | `collab` | Server -> the requesting socket only: sanitised snapshot of paths, regions and zoom provided by an existing member. |
| [Receive collab:members](/docs/reference/websocket/events/receive-collab-members) | server → client | `collab` | Server -> joining socket: the members already present in the namespace. |
| [Receive collab:self-color](/docs/reference/websocket/events/receive-collab-self-color) | server → client | `collab` | Server -> joining socket: the annotation colour assigned to it for this session. |
## Notification types [#notification-types]
126 notification types are delivered inside the `notification` envelope. See [Notification types](/docs/reference/websocket/notifications).
# Receive collab:click (/docs/reference/websocket/events/receive-collab-click)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
server → client on the
`collab`
channel. Socket.IO event name:
`collab:click`
.
Click ripple at percentage coordinates.
Client -> server -> all other sockets in the same /chat/\{chatId} namespace. The server spreads the client payload and appends the authenticated user identity (userId, displayName, color, avatarUrl), the annotationColor assigned on collab:join and a timestamp; client supplied values for those keys are overwritten.
## Payload: `collab:click` [#payload-collabclick]
Payload of the 'collab:click' socket event.
| Property | Type | Required | Description |
| ----------------- | ---------------- | -------- | ------------------------------------------------------------------- |
| `x` | `number` | no | |
| `y` | `number` | no | |
| `userId` | `string` | no | Authenticated user ID (server supplied, cannot be spoofed). |
| `displayName` | `string \| null` | no | Display name (falls back to first + last name). |
| `color` | `string \| null` | no | The user's profile colour. |
| `avatarUrl` | `string \| null` | no | keyPath of the user's avatar thumbnail file, if any. |
| `annotationColor` | `string` | no | Annotation colour assigned to this user for the collab session. |
| `timestamp` | `integer` | no | Server time in milliseconds since epoch when the event was relayed. |
# Receive collab:color-change (/docs/reference/websocket/events/receive-collab-color-change)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
server → client on the
`collab`
channel. Socket.IO event name:
`collab:color-change`
.
User changed their annotation colour. The server stores the new colour on the socket, so subsequent relayed events carry it.
Client -> server -> all other sockets in the same /chat/\{chatId} namespace. The server spreads the client payload and appends the authenticated user identity (userId, displayName, color, avatarUrl), the annotationColor assigned on collab:join and a timestamp; client supplied values for those keys are overwritten.
## Payload: `collab:color-change` [#payload-collabcolor-change]
Payload of the 'collab:color-change' socket event.
| Property | Type | Required | Description |
| ----------------- | ---------------- | -------- | ------------------------------------------------------------------- |
| `userId` | `string` | no | Authenticated user ID (server supplied, cannot be spoofed). |
| `displayName` | `string \| null` | no | Display name (falls back to first + last name). |
| `color` | `string \| null` | no | The user's profile colour. |
| `avatarUrl` | `string \| null` | no | keyPath of the user's avatar thumbnail file, if any. |
| `annotationColor` | `string` | no | Annotation colour assigned to this user for the collab session. |
| `timestamp` | `integer` | no | Server time in milliseconds since epoch when the event was relayed. |
# Receive collab:cursor-hide (/docs/reference/websocket/events/receive-collab-cursor-hide)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
server → client on the
`collab`
channel. Socket.IO event name:
`collab:cursor-hide`
.
Remote cursor left the asset area.
Client -> server -> all other sockets in the same /chat/\{chatId} namespace. The server spreads the client payload and appends the authenticated user identity (userId, displayName, color, avatarUrl), the annotationColor assigned on collab:join and a timestamp; client supplied values for those keys are overwritten.
## Payload: `collab:cursor-hide` [#payload-collabcursor-hide]
Payload of the 'collab:cursor-hide' socket event.
| Property | Type | Required | Description |
| ----------------- | ---------------- | -------- | ------------------------------------------------------------------- |
| `userId` | `string` | no | Authenticated user ID (server supplied, cannot be spoofed). |
| `displayName` | `string \| null` | no | Display name (falls back to first + last name). |
| `color` | `string \| null` | no | The user's profile colour. |
| `avatarUrl` | `string \| null` | no | keyPath of the user's avatar thumbnail file, if any. |
| `annotationColor` | `string` | no | Annotation colour assigned to this user for the collab session. |
| `timestamp` | `integer` | no | Server time in milliseconds since epoch when the event was relayed. |
# Receive collab:cursor-move (/docs/reference/websocket/events/receive-collab-cursor-move)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
server → client on the
`collab`
channel. Socket.IO event name:
`collab:cursor-move`
.
Remote cursor position update (percentage coordinates).
Client -> server -> all other sockets in the same /chat/\{chatId} namespace. The server spreads the client payload and appends the authenticated user identity (userId, displayName, color, avatarUrl), the annotationColor assigned on collab:join and a timestamp; client supplied values for those keys are overwritten.
## Payload: `collab:cursor-move` [#payload-collabcursor-move]
Payload of the 'collab:cursor-move' socket event.
| Property | Type | Required | Description |
| ----------------- | ---------------- | -------- | ------------------------------------------------------------------- |
| `x` | `number` | no | Client supplied X position as a percentage of the asset area. |
| `y` | `number` | no | Client supplied Y position as a percentage of the asset area. |
| `visible` | `boolean` | no | Client supplied visibility flag. |
| `userId` | `string` | no | Authenticated user ID (server supplied, cannot be spoofed). |
| `displayName` | `string \| null` | no | Display name (falls back to first + last name). |
| `color` | `string \| null` | no | The user's profile colour. |
| `avatarUrl` | `string \| null` | no | keyPath of the user's avatar thumbnail file, if any. |
| `annotationColor` | `string` | no | Annotation colour assigned to this user for the collab session. |
| `timestamp` | `integer` | no | Server time in milliseconds since epoch when the event was relayed. |
# Receive collab:join (/docs/reference/websocket/events/receive-collab-join)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
server → client on the
`collab`
channel. Socket.IO event name:
`collab:join`
.
A user joined the collab session on this chat namespace (broadcast to the other members).
Client emits collab:join with optional \{ preferredAnnotationColor }. Client -> server -> all other sockets in the same /chat/\{chatId} namespace. The server spreads the client payload and appends the authenticated user identity (userId, displayName, color, avatarUrl), the annotationColor assigned on collab:join and a timestamp; client supplied values for those keys are overwritten. The joining socket additionally receives collab:self-color, collab:members (if others are present) and either collab:presenter-assign (first member) or collab:presenter-state.
## Payload: `collab:join` [#payload-collabjoin]
Payload of the 'collab:join' socket event.
| Property | Type | Required | Description |
| -------------------------- | ---------------- | -------- | ------------------------------------------------------------------- |
| `preferredAnnotationColor` | `string` | no | Echo of the colour the client asked for, if it sent one. |
| `userId` | `string` | no | Authenticated user ID (server supplied, cannot be spoofed). |
| `displayName` | `string \| null` | no | Display name (falls back to first + last name). |
| `color` | `string \| null` | no | The user's profile colour. |
| `avatarUrl` | `string \| null` | no | keyPath of the user's avatar thumbnail file, if any. |
| `annotationColor` | `string` | no | Annotation colour assigned to this user for the collab session. |
| `timestamp` | `integer` | no | Server time in milliseconds since epoch when the event was relayed. |
# Receive collab:leave (/docs/reference/websocket/events/receive-collab-leave)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
server → client on the
`collab`
channel. Socket.IO event name:
`collab:leave`
.
A user left the collab session (explicit collab:leave from the client or socket disconnect).
Client -> server -> all other sockets in the same /chat/\{chatId} namespace. The server spreads the client payload and appends the authenticated user identity (userId, displayName, color, avatarUrl), the annotationColor assigned on collab:join and a timestamp; client supplied values for those keys are overwritten. On disconnect the server emits it on behalf of the leaving socket; if they were the presenter a collab:presenter-assign (reason transfer-on-leave) follows.
## Payload: `collab:leave` [#payload-collableave]
Payload of the 'collab:leave' socket event.
| Property | Type | Required | Description |
| ----------------- | ---------------- | -------- | ------------------------------------------------------------------- |
| `userId` | `string` | no | Authenticated user ID (server supplied, cannot be spoofed). |
| `displayName` | `string \| null` | no | Display name (falls back to first + last name). |
| `color` | `string \| null` | no | The user's profile colour. |
| `avatarUrl` | `string \| null` | no | keyPath of the user's avatar thumbnail file, if any. |
| `annotationColor` | `string` | no | Annotation colour assigned to this user for the collab session. |
| `timestamp` | `integer` | no | Server time in milliseconds since epoch when the event was relayed. |
# Receive collab:members (/docs/reference/websocket/events/receive-collab-members)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
server → client on the
`collab`
channel. Socket.IO event name:
`collab:members`
.
Server -> joining socket: the members already present in the namespace.
Sent right after collab:join when at least one other authenticated member is connected.
## Payload: `collab:members` [#payload-collabmembers]
Payload of the 'collab:members' socket event.
| Property | Type | Required | Description |
| ----------- | ---------- | -------- | ---------------------------------------------------------------------------- |
| `members` | `object[]` | no | Member objects: \{ userId, displayName, color, avatarUrl, annotationColor }. |
| `timestamp` | `integer` | no | |
# Receive collab:path-clear (/docs/reference/websocket/events/receive-collab-path-clear)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
server → client on the
`collab`
channel. Socket.IO event name:
`collab:path-clear`
.
Drawn path(s) cleared. With pathId only that path is cleared, otherwise all paths of the user.
Client -> server -> all other sockets in the same /chat/\{chatId} namespace. The server spreads the client payload and appends the authenticated user identity (userId, displayName, color, avatarUrl), the annotationColor assigned on collab:join and a timestamp; client supplied values for those keys are overwritten.
## Payload: `collab:path-clear` [#payload-collabpath-clear]
Payload of the 'collab:path-clear' socket event.
| Property | Type | Required | Description |
| ----------------- | ---------------- | -------- | ------------------------------------------------------------------- |
| `pathId` | `string \| null` | no | |
| `userId` | `string` | no | Authenticated user ID (server supplied, cannot be spoofed). |
| `displayName` | `string \| null` | no | Display name (falls back to first + last name). |
| `color` | `string \| null` | no | The user's profile colour. |
| `avatarUrl` | `string \| null` | no | keyPath of the user's avatar thumbnail file, if any. |
| `annotationColor` | `string` | no | Annotation colour assigned to this user for the collab session. |
| `timestamp` | `integer` | no | Server time in milliseconds since epoch when the event was relayed. |
# Receive collab:path-end (/docs/reference/websocket/events/receive-collab-path-end)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
server → client on the
`collab`
channel. Socket.IO event name:
`collab:path-end`
.
Pen drawing completed.
Client -> server -> all other sockets in the same /chat/\{chatId} namespace. The server spreads the client payload and appends the authenticated user identity (userId, displayName, color, avatarUrl), the annotationColor assigned on collab:join and a timestamp; client supplied values for those keys are overwritten.
## Payload: `collab:path-end` [#payload-collabpath-end]
Payload of the 'collab:path-end' socket event.
| Property | Type | Required | Description |
| ----------------- | ---------------- | -------- | ------------------------------------------------------------------- |
| `pathId` | `string` | no | |
| `pathData` | `string` | no | Final SVG path data. |
| `fadeDuration` | `number` | no | |
| `userId` | `string` | no | Authenticated user ID (server supplied, cannot be spoofed). |
| `displayName` | `string \| null` | no | Display name (falls back to first + last name). |
| `color` | `string \| null` | no | The user's profile colour. |
| `avatarUrl` | `string \| null` | no | keyPath of the user's avatar thumbnail file, if any. |
| `annotationColor` | `string` | no | Annotation colour assigned to this user for the collab session. |
| `timestamp` | `integer` | no | Server time in milliseconds since epoch when the event was relayed. |
# Receive collab:path-start (/docs/reference/websocket/events/receive-collab-path-start)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
server → client on the
`collab`
channel. Socket.IO event name:
`collab:path-start`
.
Pen drawing started.
Client -> server -> all other sockets in the same /chat/\{chatId} namespace. The server spreads the client payload and appends the authenticated user identity (userId, displayName, color, avatarUrl), the annotationColor assigned on collab:join and a timestamp; client supplied values for those keys are overwritten.
## Payload: `collab:path-start` [#payload-collabpath-start]
Payload of the 'collab:path-start' socket event.
| Property | Type | Required | Description |
| ----------------- | ---------------- | -------- | ------------------------------------------------------------------- |
| `pathId` | `string` | no | Client generated path ID. |
| `strokeColor` | `string` | no | |
| `strokeWidth` | `number` | no | |
| `points` | `object[]` | no | Initial point(s) of the path (client defined shape). |
| `fadeDuration` | `number` | no | Milliseconds after which the path fades (0 = persistent). |
| `userId` | `string` | no | Authenticated user ID (server supplied, cannot be spoofed). |
| `displayName` | `string \| null` | no | Display name (falls back to first + last name). |
| `color` | `string \| null` | no | The user's profile colour. |
| `avatarUrl` | `string \| null` | no | keyPath of the user's avatar thumbnail file, if any. |
| `annotationColor` | `string` | no | Annotation colour assigned to this user for the collab session. |
| `timestamp` | `integer` | no | Server time in milliseconds since epoch when the event was relayed. |
# Receive collab:path-update (/docs/reference/websocket/events/receive-collab-path-update)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
server → client on the
`collab`
channel. Socket.IO event name:
`collab:path-update`
.
Pen drawing continued with additional points.
Client -> server -> all other sockets in the same /chat/\{chatId} namespace. The server spreads the client payload and appends the authenticated user identity (userId, displayName, color, avatarUrl), the annotationColor assigned on collab:join and a timestamp; client supplied values for those keys are overwritten.
## Payload: `collab:path-update` [#payload-collabpath-update]
Payload of the 'collab:path-update' socket event.
| Property | Type | Required | Description |
| ----------------- | ---------------- | -------- | ------------------------------------------------------------------- |
| `pathId` | `string` | no | |
| `points` | `object[]` | no | Additional points appended to the path. |
| `userId` | `string` | no | Authenticated user ID (server supplied, cannot be spoofed). |
| `displayName` | `string \| null` | no | Display name (falls back to first + last name). |
| `color` | `string \| null` | no | The user's profile colour. |
| `avatarUrl` | `string \| null` | no | keyPath of the user's avatar thumbnail file, if any. |
| `annotationColor` | `string` | no | Annotation colour assigned to this user for the collab session. |
| `timestamp` | `integer` | no | Server time in milliseconds since epoch when the event was relayed. |
# Receive collab:playback-sync:rejected (/docs/reference/websocket/events/receive-collab-playback-sync-rejected)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
server → client on the
`collab`
channel. Socket.IO event name:
`collab:playback-sync:rejected`
.
Server -> sender only: the sender is not the presenter, so its collab:playback-sync was dropped. Carries the real presenter and playback position so the client can snap back to follower mode.
Emitted only to the rejected sender.
## Payload: `collab:playback-sync:rejected` [#payload-collabplayback-syncrejected]
Payload of the 'collab:playback-sync:rejected' socket event.
| Property | Type | Required | Description |
| ---------------------- | ----------------- | -------- | -------------------------------------------------------------------- |
| `reason` | `"not-presenter"` | no | |
| `presenterId` | `string \| null` | no | |
| `presenterDisplayName` | `string \| null` | no | |
| `playback` | `object` | no | \{ currentTime: number, playing: boolean } of the current presenter. |
| `timestamp` | `integer` | no | |
# Receive collab:playback-sync (/docs/reference/websocket/events/receive-collab-playback-sync)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
server → client on the
`collab`
channel. Socket.IO event name:
`collab:playback-sync`
.
Play/pause/seek state broadcast by the presenter to the other members.
Only the current presenter socket may broadcast; other senders receive collab:playback-sync:rejected instead and nothing is relayed. Client -> server -> all other sockets in the same /chat/\{chatId} namespace. The server spreads the client payload and appends the authenticated user identity (userId, displayName, color, avatarUrl), the annotationColor assigned on collab:join and a timestamp; client supplied values for those keys are overwritten. The server also stores currentTime/playing as the namespace playback state.
## Payload: `collab:playback-sync` [#payload-collabplayback-sync]
Payload of the 'collab:playback-sync' socket event.
| Property | Type | Required | Description |
| ----------------- | ---------------- | -------- | ------------------------------------------------------------------- |
| `action` | `string` | no | Client supplied action (e.g. 'play', 'pause', 'seek'). |
| `currentTime` | `number` | no | |
| `playing` | `boolean` | no | |
| `duration` | `number` | no | |
| `playbackRate` | `number` | no | |
| `userId` | `string` | no | Authenticated user ID (server supplied, cannot be spoofed). |
| `displayName` | `string \| null` | no | Display name (falls back to first + last name). |
| `color` | `string \| null` | no | The user's profile colour. |
| `avatarUrl` | `string \| null` | no | keyPath of the user's avatar thumbnail file, if any. |
| `annotationColor` | `string` | no | Annotation colour assigned to this user for the collab session. |
| `timestamp` | `integer` | no | Server time in milliseconds since epoch when the event was relayed. |
# Receive collab:presenter-assign (/docs/reference/websocket/events/receive-collab-presenter-assign)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
server → client on the
`collab`
channel. Socket.IO event name:
`collab:presenter-assign`
.
Server -> all sockets in the namespace: a new presenter was assigned.
Emitted when the first member joins (first-join), when an admin takes over or a presenter/admin reassigns via collab:presenter-takeover (admin-takeover), and when the presenter disconnects and control transfers to an admin or the earliest joined member (transfer-on-leave).
## Payload: `collab:presenter-assign` [#payload-collabpresenter-assign]
Payload of the 'collab:presenter-assign' socket event.
| Property | Type | Required | Description |
| ---------------------- | --------------------------------------------------------- | -------- | ----------- |
| `presenterId` | `string` | no | |
| `presenterDisplayName` | `string \| null` | no | |
| `reason` | `"first-join" \| "admin-takeover" \| "transfer-on-leave"` | no | |
| `timestamp` | `integer` | no | |
# Receive collab:presenter-request (/docs/reference/websocket/events/receive-collab-presenter-request)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
server → client on the
`collab`
channel. Socket.IO event name:
`collab:presenter-request`
.
Request for presenter control. From an admin it is granted immediately (collab:presenter-assign, reason admin-takeover); from a non-admin it is relayed to the current presenter socket only.
Client emits collab:presenter-request (any data). Client -> server -> the current presenter socket only. The server spreads the client payload and appends the authenticated user identity (userId, displayName, color, avatarUrl), the annotationColor assigned on collab:join and a timestamp; client supplied values for those keys are overwritten. requesterId / requesterDisplayName duplicate userId / displayName.
## Payload: `collab:presenter-request` [#payload-collabpresenter-request]
Payload of the 'collab:presenter-request' socket event.
| Property | Type | Required | Description |
| ---------------------- | ---------------- | -------- | ------------------------------------------------------------------- |
| `requesterId` | `string` | no | |
| `requesterDisplayName` | `string \| null` | no | |
| `userId` | `string` | no | Authenticated user ID (server supplied, cannot be spoofed). |
| `displayName` | `string \| null` | no | Display name (falls back to first + last name). |
| `color` | `string \| null` | no | The user's profile colour. |
| `avatarUrl` | `string \| null` | no | keyPath of the user's avatar thumbnail file, if any. |
| `annotationColor` | `string` | no | Annotation colour assigned to this user for the collab session. |
| `timestamp` | `integer` | no | Server time in milliseconds since epoch when the event was relayed. |
# Receive collab:presenter-state (/docs/reference/websocket/events/receive-collab-presenter-state)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
server → client on the
`collab`
channel. Socket.IO event name:
`collab:presenter-state`
.
Server -> joining socket: current presenter and playback state when a presenter already exists.
Sent instead of collab:presenter-assign to a socket that joins a namespace that already has a presenter.
## Payload: `collab:presenter-state` [#payload-collabpresenter-state]
Payload of the 'collab:presenter-state' socket event.
| Property | Type | Required | Description |
| ---------------------- | ---------------- | -------- | ------------------------------------------- |
| `presenterId` | `string` | no | |
| `presenterDisplayName` | `string \| null` | no | |
| `playback` | `object` | no | \{ currentTime: number, playing: boolean }. |
| `timestamp` | `integer` | no | |
# Receive collab:region-create (/docs/reference/websocket/events/receive-collab-region-create)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
server → client on the
`collab`
channel. Socket.IO event name:
`collab:region-create`
.
Audio/video region created on the waveform/timeline.
Client -> server -> all other sockets in the same /chat/\{chatId} namespace. The server spreads the client payload and appends the authenticated user identity (userId, displayName, color, avatarUrl), the annotationColor assigned on collab:join and a timestamp; client supplied values for those keys are overwritten.
## Payload: `collab:region-create` [#payload-collabregion-create]
Payload of the 'collab:region-create' socket event.
| Property | Type | Required | Description |
| ----------------- | ---------------- | -------- | ------------------------------------------------------------------- |
| `regionId` | `string` | no | |
| `startTime` | `number` | no | |
| `endTime` | `number` | no | |
| `userId` | `string` | no | Authenticated user ID (server supplied, cannot be spoofed). |
| `displayName` | `string \| null` | no | Display name (falls back to first + last name). |
| `color` | `string \| null` | no | The user's profile colour. |
| `avatarUrl` | `string \| null` | no | keyPath of the user's avatar thumbnail file, if any. |
| `annotationColor` | `string` | no | Annotation colour assigned to this user for the collab session. |
| `timestamp` | `integer` | no | Server time in milliseconds since epoch when the event was relayed. |
# Receive collab:region-remove (/docs/reference/websocket/events/receive-collab-region-remove)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
server → client on the
`collab`
channel. Socket.IO event name:
`collab:region-remove`
.
Region removed.
Client -> server -> all other sockets in the same /chat/\{chatId} namespace. The server spreads the client payload and appends the authenticated user identity (userId, displayName, color, avatarUrl), the annotationColor assigned on collab:join and a timestamp; client supplied values for those keys are overwritten.
## Payload: `collab:region-remove` [#payload-collabregion-remove]
Payload of the 'collab:region-remove' socket event.
| Property | Type | Required | Description |
| ----------------- | ---------------- | -------- | ------------------------------------------------------------------- |
| `regionId` | `string` | no | |
| `userId` | `string` | no | Authenticated user ID (server supplied, cannot be spoofed). |
| `displayName` | `string \| null` | no | Display name (falls back to first + last name). |
| `color` | `string \| null` | no | The user's profile colour. |
| `avatarUrl` | `string \| null` | no | keyPath of the user's avatar thumbnail file, if any. |
| `annotationColor` | `string` | no | Annotation colour assigned to this user for the collab session. |
| `timestamp` | `integer` | no | Server time in milliseconds since epoch when the event was relayed. |
# Receive collab:self-color (/docs/reference/websocket/events/receive-collab-self-color)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
server → client on the
`collab`
channel. Socket.IO event name:
`collab:self-color`
.
Server -> joining socket: the annotation colour assigned to it for this session.
The preferred colour is kept when it is not the default (#FF0000); otherwise the first unused palette colour is assigned.
## Payload: `collab:self-color` [#payload-collabself-color]
Payload of the 'collab:self-color' socket event.
| Property | Type | Required | Description |
| ----------------- | -------- | -------- | ----------- |
| `annotationColor` | `string` | no | |
# Receive collab:state-request (/docs/reference/websocket/events/receive-collab-state-request)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
server → client on the
`collab`
channel. Socket.IO event name:
`collab:state-request`
.
Server -> the earliest joined other member: asks it to send its current annotation state to a late joiner (collab:state-response).
Emitted automatically when a socket joins a namespace with existing members, and again when a client retries by emitting collab:state-request itself.
## Payload: `collab:state-request` [#payload-collabstate-request]
Payload of the 'collab:state-request' socket event.
| Property | Type | Required | Description |
| ------------------- | --------- | -------- | -------------------------------------------------- |
| `requesterId` | `string` | no | User ID of the late joiner. |
| `requesterSocketId` | `string` | no | Socket ID to address the collab:state-response to. |
| `timestamp` | `integer` | no | |
# Receive collab:state-response (/docs/reference/websocket/events/receive-collab-state-response)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
server → client on the
`collab`
channel. Socket.IO event name:
`collab:state-response`
.
Server -> the requesting socket only: sanitised snapshot of paths, regions and zoom provided by an existing member.
Client emits collab:state-response with \{ requesterSocketId, paths, regions, zoom }; the server validates/truncates (max 200 paths and 200 regions, string length limits) and forwards it only to requesterSocketId.
## Payload: `collab:state-response` [#payload-collabstate-response]
Payload of the 'collab:state-response' socket event.
| Property | Type | Required | Description |
| ------------------- | ---------- | -------- | ----------------------------------------------------------------------------------------- |
| `requesterSocketId` | `string` | no | |
| `paths` | `object[]` | no | Path objects: \{ pathId, userId, color, strokeWidth, pathData, fadeDuration, createdAt }. |
| `regions` | `object[]` | no | Region objects: \{ regionId, startTime, endTime, userId, displayName, color, avatarUrl }. |
| `zoom` | `number` | no | Zoom level, omitted when the responder did not supply a number. |
| `timestamp` | `integer` | no | |
# Receive collab:zoom-sync (/docs/reference/websocket/events/receive-collab-zoom-sync)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
server → client on the
`collab`
channel. Socket.IO event name:
`collab:zoom-sync`
.
Zoom level broadcast (followers of the presenter apply it).
Client -> server -> all other sockets in the same /chat/\{chatId} namespace. The server spreads the client payload and appends the authenticated user identity (userId, displayName, color, avatarUrl), the annotationColor assigned on collab:join and a timestamp; client supplied values for those keys are overwritten.
## Payload: `collab:zoom-sync` [#payload-collabzoom-sync]
Payload of the 'collab:zoom-sync' socket event.
| Property | Type | Required | Description |
| ----------------- | ---------------- | -------- | ------------------------------------------------------------------- |
| `zoom` | `number` | no | |
| `userId` | `string` | no | Authenticated user ID (server supplied, cannot be spoofed). |
| `displayName` | `string \| null` | no | Display name (falls back to first + last name). |
| `color` | `string \| null` | no | The user's profile colour. |
| `avatarUrl` | `string \| null` | no | keyPath of the user's avatar thumbnail file, if any. |
| `annotationColor` | `string` | no | Annotation colour assigned to this user for the collab session. |
| `timestamp` | `integer` | no | Server time in milliseconds since epoch when the event was relayed. |
# Receive notification (/docs/reference/websocket/events/receive-notification)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
server → client on the
`resource`
channel.
Envelope event on which every notification listed in this section is delivered. The type property tells you which event schema applies.
Emitted on every channel (namespace) listed in the notification's channels array. Unlike the REST notification objects, the socket payload does NOT include id or channels. tokens and changes are shaped per event type as documented under each event.
## Envelope: `notification` [#envelope-notification]
Payload of the 'notification' socket event.
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | Event specific tokens (see the individual event). |
| `changes` | `object \| null` | no | Event specific create/update/delete arrays (see the individual event). May be null. |
## Notification types [#notification-types]
| `type` | Summary |
| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`test`](/docs/reference/websocket/notifications/test) | Event used for testing websocket connections. |
| [`notificationUpdate`](/docs/reference/websocket/notifications/notificationupdate) | Indicates that a previously delivered, grouped notification has been updated (assetGroupUploadComplete or projectGroupItemPublish). |
| [`workspaceCreate`](/docs/reference/websocket/notifications/workspacecreate) | Fired when a new workspace is created. |
| [`workspaceUpdate`](/docs/reference/websocket/notifications/workspaceupdate) | Fired when a workspace name is changed. |
| [`workspaceDelete`](/docs/reference/websocket/notifications/workspacedelete) | Fired when a workspace is marked for deletion. |
| [`workspaceLogoUpdate`](/docs/reference/websocket/notifications/workspacelogoupdate) | CURRENTLY UNUSED IN FAVOR OF logoUpdate event. Fired when a workspace logo is updated. |
| [`projectCreate`](/docs/reference/websocket/notifications/projectcreate) | Fired when a new project is created. |
| [`projectUpdate`](/docs/reference/websocket/notifications/projectupdate) | Fired when a project name is changed. |
| [`projectDelete`](/docs/reference/websocket/notifications/projectdelete) | Fired when a project is marked for deletion. |
| [`projectLogoUpdate`](/docs/reference/websocket/notifications/projectlogoupdate) | CURRENTLY UNUSED IN FAVOR OF logoUpdate event. Fired when a project logo is updated. Updates the project and returns the new asset object for the logo. Note that the logo will not be 'active' until the actual file is uploaded. So you will need to watch for updates to this asset before replacing the logo locally. |
| [`projectAssetsPublish`](/docs/reference/websocket/notifications/projectassetspublish) | CURRENTLY UNUSED (the event type is still registered but nothing emits it). Fired when assets within a project are published. |
| [`projectAssetsUnpublish`](/docs/reference/websocket/notifications/projectassetsunpublish) | CURRENTLY UNUSED (the event type is still registered but nothing emits it). Fired when assets within a project are unpublished. |
| [`assetNameChange`](/docs/reference/websocket/notifications/assetnamechange) | Fired when an asset's name is changed. |
| [`assetPublish`](/docs/reference/websocket/notifications/assetpublish) | Fired for each individual asset published through the project publish flow (accompanies fileSystemPublish / projectItemsPublish). |
| [`assetUnpublish`](/docs/reference/websocket/notifications/assetunpublish) | Fired for each individual asset unpublished through the project unpublish flow (accompanies fileSystemUnpublish / projectItemsUnpublish). |
| [`assetTag`](/docs/reference/websocket/notifications/assettag) | Fired when a tag is added to an asset. |
| [`assetUntag`](/docs/reference/websocket/notifications/assetuntag) | Fired when a tag is removed from an asset. |
| [`assetDelete`](/docs/reference/websocket/notifications/assetdelete) | Fired when an asset is deleted. |
| [`assetStatusUpdate`](/docs/reference/websocket/notifications/assetstatusupdate) | Fired when an asset's status changes (e.g., during processing). |
| [`assetPostProcessUpdate`](/docs/reference/websocket/notifications/assetpostprocessupdate) | Fired periodically during asset post-processing (e.g., transcoding). |
| [`assetFileUpdate`](/docs/reference/websocket/notifications/assetfileupdate) | Fired when a file associated with an asset is updated or added. |
| [`assetGroupUploadComplete`](/docs/reference/websocket/notifications/assetgroupuploadcomplete) | Fired when an uploaded asset becomes active. Uploads by the same creator into the same resource/visibility within the grouping window (30 min) are accumulated into one notification, which is then re-sent via notificationUpdate. |
| [`chatTopicChatCreate`](/docs/reference/websocket/notifications/chattopicchatcreate) | Fired when a new topic-based chat is created. |
| [`chatMemberChatCreate`](/docs/reference/websocket/notifications/chatmemberchatcreate) | Fired when a new member-based chat (DM/group) is created. |
| [`chatUpdateSubject`](/docs/reference/websocket/notifications/chatupdatesubject) | Fired when the subject of a topic-based chat is updated. |
| [`chatMemberUpdate`](/docs/reference/websocket/notifications/chatmemberupdate) | Fired when a member chat's subject or colour is updated. |
| [`chatDelete`](/docs/reference/websocket/notifications/chatdelete) | Fired when a topic-based chat is deleted. |
| [`chatMemberDelete`](/docs/reference/websocket/notifications/chatmemberdelete) | Fired when a member-based chat is deleted. |
| [`chatCreateMessage`](/docs/reference/websocket/notifications/chatcreatemessage) | Fired when a new message is created in a chat (user messages, public/guest messages, AI assistant replies and system messages). |
| [`chatReviseMessage`](/docs/reference/websocket/notifications/chatrevisemessage) | Fired when a chat message is revised (edited). |
| [`chatRefreshMessage`](/docs/reference/websocket/notifications/chatrefreshmessage) | Provides an updated representation of a system message (e.g. after the assets it references finish processing). |
| [`chatMention`](/docs/reference/websocket/notifications/chatmention) | Fired when user(s) are mentioned in a created or revised chat message. Published only on the mentioned users' channels (user/\{userId}). |
| [`chatDeleteMessage`](/docs/reference/websocket/notifications/chatdeletemessage) | Fired when a chat message is deleted. |
| [`chatRemoveAttachment`](/docs/reference/websocket/notifications/chatremoveattachment) | Fired when an attachment is removed from a chat message. |
| [`folderCreate`](/docs/reference/websocket/notifications/foldercreate) | CURRENTLY UNUSED (the event type is still registered but nothing emits it). Fired when a new folder is created. |
| [`folderUpdate`](/docs/reference/websocket/notifications/folderupdate) | CURRENTLY UNUSED (the event type is still registered but nothing emits it). Fired when a folder is updated. |
| [`folderDelete`](/docs/reference/websocket/notifications/folderdelete) | CURRENTLY UNUSED (the event type is still registered but nothing emits it). Fired when a folder is deleted. |
| [`inviteCreate`](/docs/reference/websocket/notifications/invitecreate) | Fired when a new invitation is created. |
| [`inviteCancel`](/docs/reference/websocket/notifications/invitecancel) | Fired when an invitation is cancelled. |
| [`inviteAccept`](/docs/reference/websocket/notifications/inviteaccept) | Fired when an invitation is accepted. |
| [`membershipDelete`](/docs/reference/websocket/notifications/membershipdelete) | Fired when a user's membership to a resource is deleted (removed). |
| [`membershipAddRole`](/docs/reference/websocket/notifications/membershipaddrole) | Fired when a role is added to a user's membership. |
| [`membershipRemoveRole`](/docs/reference/websocket/notifications/membershipremoverole) | Fired when a role is removed from a user's membership. |
| [`membershipLeaveResource`](/docs/reference/websocket/notifications/membershipleaveresource) | Fired when a user leaves a resource themselves. |
| [`workspaceStorageLimitWarning`](/docs/reference/websocket/notifications/workspacestoragelimitwarning) | Fired when a workspace's storage usage exceeds a threshold. |
| [`userSelfUpdate`](/docs/reference/websocket/notifications/userselfupdate) | Fired when a user updates their own profile information. |
| [`userPublicUpdate`](/docs/reference/websocket/notifications/userpublicupdate) | Fired when a user's public information is updated. |
| [`userDeleted`](/docs/reference/websocket/notifications/userdeleted) | Fired when a user account is deleted. |
| [`userAvatarUpdate`](/docs/reference/websocket/notifications/useravatarupdate) | Fired when a avatars status is set to active. Note that this is an asset event and not a user event so it is fired when the asset's status is set to active not when a user's object is updated. |
| [`logoUpdate`](/docs/reference/websocket/notifications/logoupdate) | Generic event for when a workspace or project logo asset becomes active. Includes the updated owner resource in changes. |
| [`iconUpdate`](/docs/reference/websocket/notifications/iconupdate) | Generic event for when a workspace or project icon asset becomes active. Includes the updated owner resource in changes. |
| [`taskAcknowledged`](/docs/reference/websocket/notifications/taskacknowledged) | Fired when tasks are acknowledged within a project. |
| [`taskStatusUpdate`](/docs/reference/websocket/notifications/taskstatusupdate) | Fired when the status of a task is updated. |
| [`taskCreate`](/docs/reference/websocket/notifications/taskcreate) | Fired when a new task is created within a project. |
| [`notificationUpdateLastSeen`](/docs/reference/websocket/notifications/notificationupdatelastseen) | Fired to update a client's 'last seen' timestamp for notifications. |
| [`submissionCreate`](/docs/reference/websocket/notifications/submissioncreate) | Fired when a submission is released for the first time. Published on project/\{projectId}, project/\{projectId}/creator and project/\{projectId}/reviewer. |
| [`projectItemsPublish`](/docs/reference/websocket/notifications/projectitemspublish) | Fired when multiple items (assets/folders) within a project are published. |
| [`projectItemsUnpublish`](/docs/reference/websocket/notifications/projectitemsunpublish) | Fired when multiple items (assets/folders) within a project are unpublished. |
| [`folderPublish`](/docs/reference/websocket/notifications/folderpublish) | Fired when an individual folder is published. |
| [`folderTag`](/docs/reference/websocket/notifications/foldertag) | Fired when a tag is added to a folder. |
| [`folderUntag`](/docs/reference/websocket/notifications/folderuntag) | Fired when a tag is removed from a folder. |
| [`tagCreate`](/docs/reference/websocket/notifications/tagcreate) | Fired when a new tag is created. |
| [`tagUpdate`](/docs/reference/websocket/notifications/tagupdate) | Fired when a tag is updated. |
| [`tagDelete`](/docs/reference/websocket/notifications/tagdelete) | Fired when a tag is deleted. |
| [`fileSystemCreate`](/docs/reference/websocket/notifications/filesystemcreate) | Fired when items are created at a file system path (folder created, single uploaded asset activated, or items copied into a public release). |
| [`fileSystemMove`](/docs/reference/websocket/notifications/filesystemmove) | Fired when items are moved to a new file system path. |
| [`fileSystemCopy`](/docs/reference/websocket/notifications/filesystemcopy) | Fired when items are copied to a new file system path. |
| [`fileSystemDelete`](/docs/reference/websocket/notifications/filesystemdelete) | Fired when items are deleted from file system paths. |
| [`fileSystemPublish`](/docs/reference/websocket/notifications/filesystempublish) | Fired when multiple items are published at a file system path. |
| [`fileSystemUnpublish`](/docs/reference/websocket/notifications/filesystemunpublish) | Fired when multiple items are unpublished from file system paths. |
| [`subscriptionCreate`](/docs/reference/websocket/notifications/subscriptioncreate) | Fired when a new billing subscription is created for a workspace (Stripe webhook). Published on user/\{ownerId} and \{resourceType}/\{resourceId}. |
| [`subscriptionUpdate`](/docs/reference/websocket/notifications/subscriptionupdate) | Fired when an existing billing subscription is updated, paused, resumed or deleted (Stripe webhook). Published on user/\{ownerId} and \{resourceType}/\{resourceId}. |
| [`projectGroupItemPublish`](/docs/reference/websocket/notifications/projectgroupitempublish) | Grouped notification for items published in a project. Items published by the same user within the grouping window (30 min) are accumulated and re-sent via notificationUpdate. |
| [`publicAssetLinkCreate`](/docs/reference/websocket/notifications/publicassetlinkcreate) | Fired when a public (share) link is created for an asset. Published on project/\{projectId}/creator and workspace/\{workspaceId}. |
| [`uploadPushSummary`](/docs/reference/websocket/notifications/uploadpushsummary) | Delayed push-notification summary of assets uploaded to a project by one user. Primarily used to send a push notification after scheduledSendAt, but also broadcast on the project visibility channels when created. |
| [`publishPushSummary`](/docs/reference/websocket/notifications/publishpushsummary) | Push-notification summary of items published to reviewers. Used to send a push notification; broadcast on project/\{projectId}/reviewer. |
| [`submissionPushSummary`](/docs/reference/websocket/notifications/submissionpushsummary) | Push-notification summary for a newly created submission. Used to send a push notification; broadcast on project/\{projectId}. |
| [`memberJoinPush`](/docs/reference/websocket/notifications/memberjoinpush) | Push-notification record created when a user joins a workspace or project. Used to send a push notification; broadcast on \{resourceType}/\{resourceId}. |
| [`chatMemberArchive`](/docs/reference/websocket/notifications/chatmemberarchive) | Fired when the requesting user archives a member chat for themselves. Published on user/\{userId} only. |
| [`chatMemberUnarchive`](/docs/reference/websocket/notifications/chatmemberunarchive) | Fired when the requesting user un-archives a member chat for themselves. Published on user/\{userId} only. |
| [`chatHighlightMessage`](/docs/reference/websocket/notifications/chathighlightmessage) | Fired when a message in a project-scoped chat is highlighted. Published on project/\{projectId}/\{visibility} of the chat. |
| [`chatFollow`](/docs/reference/websocket/notifications/chatfollow) | Fired when a user follows a chat. Published on the chat channels. |
| [`chatUnfollow`](/docs/reference/websocket/notifications/chatunfollow) | Fired when a user unfollows a chat. Published on the chat channels. |
| [`userEmailVerify`](/docs/reference/websocket/notifications/useremailverify) | Fired when a user's email address is verified. Published on user/\{userId}. |
| [`botCreate`](/docs/reference/websocket/notifications/botcreate) | Fired when a bot user is created in a workspace. Published on workspace/\{workspaceId}. |
| [`webhookTest`](/docs/reference/websocket/notifications/webhooktest) | Synthetic event fired when an admin tests a webhook subscription. Published on workspace/\{workspaceId}; delivered by the webhook dispatcher as webhook.test. |
| [`taskFollow`](/docs/reference/websocket/notifications/taskfollow) | Fired when a user follows a task. |
| [`taskUnfollow`](/docs/reference/websocket/notifications/taskunfollow) | Fired when a user unfollows a task. |
| [`submissionUpdate`](/docs/reference/websocket/notifications/submissionupdate) | Fired when an already-released submission is re-released. Published on project/\{projectId}, project/\{projectId}/creator and project/\{projectId}/reviewer. |
| [`submissionTag`](/docs/reference/websocket/notifications/submissiontag) | Fired when a tag is added to a submission. resourceType is chatSubmission. |
| [`submissionUntag`](/docs/reference/websocket/notifications/submissionuntag) | Fired when a tag is removed from a submission. resourceType is chatSubmission. |
| [`aiChatTopicCreate`](/docs/reference/websocket/notifications/aichattopiccreate) | Fired when an AI chat topic is created. Published on user/\{userId} of the topic owner. |
| [`aiChatTopicUpdate`](/docs/reference/websocket/notifications/aichattopicupdate) | Fired when an AI chat topic is updated (title, archive state, context items, last message preview) or deleted. Published on user/\{userId} of the topic owner. |
| [`aiChatMessageCreate`](/docs/reference/websocket/notifications/aichatmessagecreate) | Fired when the AI assistant posts a message in an AI chat topic. Published on user/\{userId} of the topic owner. |
| [`publicFileSystemCreate`](/docs/reference/websocket/notifications/publicfilesystemcreate) | Fired when a public release (public file system) is created. Published on project/\{projectId}/creator. |
| [`publicFileSystemUpdate`](/docs/reference/websocket/notifications/publicfilesystemupdate) | Fired when a public release is updated (title, description, validity, options). Published on project/\{projectId}/creator. |
| [`publicFileSystemDelete`](/docs/reference/websocket/notifications/publicfilesystemdelete) | Fired when a public release is deleted. Published on project/\{projectId}/creator. |
| [`settingsUpdate`](/docs/reference/websocket/notifications/settingsupdate) | Fired when a user's settings for a resource are updated or reset. Published on user/\{userId} only. |
| [`convoStart`](/docs/reference/websocket/notifications/convostart) | Fired when a convo (call) is started in a chat. Published on the chat channels and user/\{userId} of the starter. |
| [`convoJoin`](/docs/reference/websocket/notifications/convojoin) | Fired when a user joins a convo. |
| [`convoLeave`](/docs/reference/websocket/notifications/convoleave) | Fired when a user leaves a convo. |
| [`convoComplete`](/docs/reference/websocket/notifications/convocomplete) | Fired when a convo is completed (ended by a user or when the last participant leaves). |
| [`convoUpdate`](/docs/reference/websocket/notifications/convoupdate) | Fired when a convo is updated (subject / notes). |
| [`convoDelete`](/docs/reference/websocket/notifications/convodelete) | Fired when a convo is deleted. |
| [`convoParticipantJoined`](/docs/reference/websocket/notifications/convoparticipantjoined) | Fired (from the call-provider webhook) when a participant actually joins the call room. |
| [`convoParticipantLeft`](/docs/reference/websocket/notifications/convoparticipantleft) | Fired (from the call-provider webhook) when a participant leaves the call room. |
| [`convoHandover`](/docs/reference/websocket/notifications/convohandover) | Fired on user/\{userId} when the user joins a convo from a second device, so the previous device can leave the call. |
| [`boardCreate`](/docs/reference/websocket/notifications/boardcreate) | Fired when a kanban board is created. Published on the project visibility channels of the board. |
| [`boardUpdate`](/docs/reference/websocket/notifications/boardupdate) | Fired when a kanban board is updated (name, visibility, options). |
| [`boardDelete`](/docs/reference/websocket/notifications/boarddelete) | Fired when a kanban board is deleted. Cascaded task deletions / reassignments are included in changes. |
| [`boardTaskCreate`](/docs/reference/websocket/notifications/boardtaskcreate) | Fired when a task is created on a board (UI, AI tool or bulk create). Also used for push notifications. |
| [`boardTaskMove`](/docs/reference/websocket/notifications/boardtaskmove) | Fired when a task is moved between columns or boards. Published on the visibility channels of both boards for cross-board moves. |
| [`boardTaskAssign`](/docs/reference/websocket/notifications/boardtaskassign) | Fired when a task is assigned or unassigned. Published on the board visibility channels and user/\{assignedToId}. |
| [`boardColumnAdd`](/docs/reference/websocket/notifications/boardcolumnadd) | Fired when a column is added to a board. |
| [`boardColumnUpdate`](/docs/reference/websocket/notifications/boardcolumnupdate) | Fired when a board column is updated. |
| [`boardColumnDelete`](/docs/reference/websocket/notifications/boardcolumndelete) | Fired when a board column is deleted. |
| [`boardColumnReorder`](/docs/reference/websocket/notifications/boardcolumnreorder) | Fired when the columns of a board are reordered. changes.update contains every column with its new order. |
| [`boardTaskAdd`](/docs/reference/websocket/notifications/boardtaskadd) | Fired when an existing task is added to a board. |
| [`boardTaskRemove`](/docs/reference/websocket/notifications/boardtaskremove) | Fired when a task is removed from a board (the task itself is kept). |
| [`boardTaskUpdate`](/docs/reference/websocket/notifications/boardtaskupdate) | Fired when a task's details are updated (subject, description, priority, dates, etc.). |
| [`boardTaskLink`](/docs/reference/websocket/notifications/boardtasklink) | Fired when two tasks are linked. |
| [`boardTaskUnlink`](/docs/reference/websocket/notifications/boardtaskunlink) | Fired when a task link is removed. |
| [`boardTaskRelationAdd`](/docs/reference/websocket/notifications/boardtaskrelationadd) | Fired when a resource (asset, folder, message, chat, ...) is related to a task. Also used for push notifications. |
| [`boardTaskRelationRemove`](/docs/reference/websocket/notifications/boardtaskrelationremove) | Fired when a task relation is removed (explicitly, or cascaded when a board visibility change removes access). |
| [`boardFollow`](/docs/reference/websocket/notifications/boardfollow) | Fired when a user follows a board. |
| [`boardUnfollow`](/docs/reference/websocket/notifications/boardunfollow) | Fired when a user unfollows a board. |
# Receive notification (/docs/reference/websocket/events/receive-public-notification)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
server → client on the
`public`
channel.
Envelope event on which every notification listed in this section is delivered. The type property tells you which event schema applies.
Emitted on every channel (namespace) listed in the notification's channels array. Unlike the REST notification objects, the socket payload does NOT include id or channels. tokens and changes are shaped per event type as documented under each event.
## Envelope: `notification` [#envelope-notification]
Payload of the 'notification' socket event.
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | Event specific tokens (see the individual event). |
| `changes` | `object \| null` | no | Event specific create/update/delete arrays (see the individual event). May be null. |
## Notification types [#notification-types]
| `type` | Summary |
| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`test`](/docs/reference/websocket/notifications/test) | Event used for testing websocket connections. |
| [`notificationUpdate`](/docs/reference/websocket/notifications/notificationupdate) | Indicates that a previously delivered, grouped notification has been updated (assetGroupUploadComplete or projectGroupItemPublish). |
| [`workspaceCreate`](/docs/reference/websocket/notifications/workspacecreate) | Fired when a new workspace is created. |
| [`workspaceUpdate`](/docs/reference/websocket/notifications/workspaceupdate) | Fired when a workspace name is changed. |
| [`workspaceDelete`](/docs/reference/websocket/notifications/workspacedelete) | Fired when a workspace is marked for deletion. |
| [`workspaceLogoUpdate`](/docs/reference/websocket/notifications/workspacelogoupdate) | CURRENTLY UNUSED IN FAVOR OF logoUpdate event. Fired when a workspace logo is updated. |
| [`projectCreate`](/docs/reference/websocket/notifications/projectcreate) | Fired when a new project is created. |
| [`projectUpdate`](/docs/reference/websocket/notifications/projectupdate) | Fired when a project name is changed. |
| [`projectDelete`](/docs/reference/websocket/notifications/projectdelete) | Fired when a project is marked for deletion. |
| [`projectLogoUpdate`](/docs/reference/websocket/notifications/projectlogoupdate) | CURRENTLY UNUSED IN FAVOR OF logoUpdate event. Fired when a project logo is updated. Updates the project and returns the new asset object for the logo. Note that the logo will not be 'active' until the actual file is uploaded. So you will need to watch for updates to this asset before replacing the logo locally. |
| [`projectAssetsPublish`](/docs/reference/websocket/notifications/projectassetspublish) | CURRENTLY UNUSED (the event type is still registered but nothing emits it). Fired when assets within a project are published. |
| [`projectAssetsUnpublish`](/docs/reference/websocket/notifications/projectassetsunpublish) | CURRENTLY UNUSED (the event type is still registered but nothing emits it). Fired when assets within a project are unpublished. |
| [`assetNameChange`](/docs/reference/websocket/notifications/assetnamechange) | Fired when an asset's name is changed. |
| [`assetPublish`](/docs/reference/websocket/notifications/assetpublish) | Fired for each individual asset published through the project publish flow (accompanies fileSystemPublish / projectItemsPublish). |
| [`assetUnpublish`](/docs/reference/websocket/notifications/assetunpublish) | Fired for each individual asset unpublished through the project unpublish flow (accompanies fileSystemUnpublish / projectItemsUnpublish). |
| [`assetTag`](/docs/reference/websocket/notifications/assettag) | Fired when a tag is added to an asset. |
| [`assetUntag`](/docs/reference/websocket/notifications/assetuntag) | Fired when a tag is removed from an asset. |
| [`assetDelete`](/docs/reference/websocket/notifications/assetdelete) | Fired when an asset is deleted. |
| [`assetStatusUpdate`](/docs/reference/websocket/notifications/assetstatusupdate) | Fired when an asset's status changes (e.g., during processing). |
| [`assetPostProcessUpdate`](/docs/reference/websocket/notifications/assetpostprocessupdate) | Fired periodically during asset post-processing (e.g., transcoding). |
| [`assetFileUpdate`](/docs/reference/websocket/notifications/assetfileupdate) | Fired when a file associated with an asset is updated or added. |
| [`assetGroupUploadComplete`](/docs/reference/websocket/notifications/assetgroupuploadcomplete) | Fired when an uploaded asset becomes active. Uploads by the same creator into the same resource/visibility within the grouping window (30 min) are accumulated into one notification, which is then re-sent via notificationUpdate. |
| [`chatTopicChatCreate`](/docs/reference/websocket/notifications/chattopicchatcreate) | Fired when a new topic-based chat is created. |
| [`chatMemberChatCreate`](/docs/reference/websocket/notifications/chatmemberchatcreate) | Fired when a new member-based chat (DM/group) is created. |
| [`chatUpdateSubject`](/docs/reference/websocket/notifications/chatupdatesubject) | Fired when the subject of a topic-based chat is updated. |
| [`chatMemberUpdate`](/docs/reference/websocket/notifications/chatmemberupdate) | Fired when a member chat's subject or colour is updated. |
| [`chatDelete`](/docs/reference/websocket/notifications/chatdelete) | Fired when a topic-based chat is deleted. |
| [`chatMemberDelete`](/docs/reference/websocket/notifications/chatmemberdelete) | Fired when a member-based chat is deleted. |
| [`chatCreateMessage`](/docs/reference/websocket/notifications/chatcreatemessage) | Fired when a new message is created in a chat (user messages, public/guest messages, AI assistant replies and system messages). |
| [`chatReviseMessage`](/docs/reference/websocket/notifications/chatrevisemessage) | Fired when a chat message is revised (edited). |
| [`chatRefreshMessage`](/docs/reference/websocket/notifications/chatrefreshmessage) | Provides an updated representation of a system message (e.g. after the assets it references finish processing). |
| [`chatMention`](/docs/reference/websocket/notifications/chatmention) | Fired when user(s) are mentioned in a created or revised chat message. Published only on the mentioned users' channels (user/\{userId}). |
| [`chatDeleteMessage`](/docs/reference/websocket/notifications/chatdeletemessage) | Fired when a chat message is deleted. |
| [`chatRemoveAttachment`](/docs/reference/websocket/notifications/chatremoveattachment) | Fired when an attachment is removed from a chat message. |
| [`folderCreate`](/docs/reference/websocket/notifications/foldercreate) | CURRENTLY UNUSED (the event type is still registered but nothing emits it). Fired when a new folder is created. |
| [`folderUpdate`](/docs/reference/websocket/notifications/folderupdate) | CURRENTLY UNUSED (the event type is still registered but nothing emits it). Fired when a folder is updated. |
| [`folderDelete`](/docs/reference/websocket/notifications/folderdelete) | CURRENTLY UNUSED (the event type is still registered but nothing emits it). Fired when a folder is deleted. |
| [`inviteCreate`](/docs/reference/websocket/notifications/invitecreate) | Fired when a new invitation is created. |
| [`inviteCancel`](/docs/reference/websocket/notifications/invitecancel) | Fired when an invitation is cancelled. |
| [`inviteAccept`](/docs/reference/websocket/notifications/inviteaccept) | Fired when an invitation is accepted. |
| [`membershipDelete`](/docs/reference/websocket/notifications/membershipdelete) | Fired when a user's membership to a resource is deleted (removed). |
| [`membershipAddRole`](/docs/reference/websocket/notifications/membershipaddrole) | Fired when a role is added to a user's membership. |
| [`membershipRemoveRole`](/docs/reference/websocket/notifications/membershipremoverole) | Fired when a role is removed from a user's membership. |
| [`membershipLeaveResource`](/docs/reference/websocket/notifications/membershipleaveresource) | Fired when a user leaves a resource themselves. |
| [`workspaceStorageLimitWarning`](/docs/reference/websocket/notifications/workspacestoragelimitwarning) | Fired when a workspace's storage usage exceeds a threshold. |
| [`userSelfUpdate`](/docs/reference/websocket/notifications/userselfupdate) | Fired when a user updates their own profile information. |
| [`userPublicUpdate`](/docs/reference/websocket/notifications/userpublicupdate) | Fired when a user's public information is updated. |
| [`userDeleted`](/docs/reference/websocket/notifications/userdeleted) | Fired when a user account is deleted. |
| [`userAvatarUpdate`](/docs/reference/websocket/notifications/useravatarupdate) | Fired when a avatars status is set to active. Note that this is an asset event and not a user event so it is fired when the asset's status is set to active not when a user's object is updated. |
| [`logoUpdate`](/docs/reference/websocket/notifications/logoupdate) | Generic event for when a workspace or project logo asset becomes active. Includes the updated owner resource in changes. |
| [`iconUpdate`](/docs/reference/websocket/notifications/iconupdate) | Generic event for when a workspace or project icon asset becomes active. Includes the updated owner resource in changes. |
| [`taskAcknowledged`](/docs/reference/websocket/notifications/taskacknowledged) | Fired when tasks are acknowledged within a project. |
| [`taskStatusUpdate`](/docs/reference/websocket/notifications/taskstatusupdate) | Fired when the status of a task is updated. |
| [`taskCreate`](/docs/reference/websocket/notifications/taskcreate) | Fired when a new task is created within a project. |
| [`notificationUpdateLastSeen`](/docs/reference/websocket/notifications/notificationupdatelastseen) | Fired to update a client's 'last seen' timestamp for notifications. |
| [`submissionCreate`](/docs/reference/websocket/notifications/submissioncreate) | Fired when a submission is released for the first time. Published on project/\{projectId}, project/\{projectId}/creator and project/\{projectId}/reviewer. |
| [`projectItemsPublish`](/docs/reference/websocket/notifications/projectitemspublish) | Fired when multiple items (assets/folders) within a project are published. |
| [`projectItemsUnpublish`](/docs/reference/websocket/notifications/projectitemsunpublish) | Fired when multiple items (assets/folders) within a project are unpublished. |
| [`folderPublish`](/docs/reference/websocket/notifications/folderpublish) | Fired when an individual folder is published. |
| [`folderTag`](/docs/reference/websocket/notifications/foldertag) | Fired when a tag is added to a folder. |
| [`folderUntag`](/docs/reference/websocket/notifications/folderuntag) | Fired when a tag is removed from a folder. |
| [`tagCreate`](/docs/reference/websocket/notifications/tagcreate) | Fired when a new tag is created. |
| [`tagUpdate`](/docs/reference/websocket/notifications/tagupdate) | Fired when a tag is updated. |
| [`tagDelete`](/docs/reference/websocket/notifications/tagdelete) | Fired when a tag is deleted. |
| [`fileSystemCreate`](/docs/reference/websocket/notifications/filesystemcreate) | Fired when items are created at a file system path (folder created, single uploaded asset activated, or items copied into a public release). |
| [`fileSystemMove`](/docs/reference/websocket/notifications/filesystemmove) | Fired when items are moved to a new file system path. |
| [`fileSystemCopy`](/docs/reference/websocket/notifications/filesystemcopy) | Fired when items are copied to a new file system path. |
| [`fileSystemDelete`](/docs/reference/websocket/notifications/filesystemdelete) | Fired when items are deleted from file system paths. |
| [`fileSystemPublish`](/docs/reference/websocket/notifications/filesystempublish) | Fired when multiple items are published at a file system path. |
| [`fileSystemUnpublish`](/docs/reference/websocket/notifications/filesystemunpublish) | Fired when multiple items are unpublished from file system paths. |
| [`subscriptionCreate`](/docs/reference/websocket/notifications/subscriptioncreate) | Fired when a new billing subscription is created for a workspace (Stripe webhook). Published on user/\{ownerId} and \{resourceType}/\{resourceId}. |
| [`subscriptionUpdate`](/docs/reference/websocket/notifications/subscriptionupdate) | Fired when an existing billing subscription is updated, paused, resumed or deleted (Stripe webhook). Published on user/\{ownerId} and \{resourceType}/\{resourceId}. |
| [`projectGroupItemPublish`](/docs/reference/websocket/notifications/projectgroupitempublish) | Grouped notification for items published in a project. Items published by the same user within the grouping window (30 min) are accumulated and re-sent via notificationUpdate. |
| [`publicAssetLinkCreate`](/docs/reference/websocket/notifications/publicassetlinkcreate) | Fired when a public (share) link is created for an asset. Published on project/\{projectId}/creator and workspace/\{workspaceId}. |
| [`uploadPushSummary`](/docs/reference/websocket/notifications/uploadpushsummary) | Delayed push-notification summary of assets uploaded to a project by one user. Primarily used to send a push notification after scheduledSendAt, but also broadcast on the project visibility channels when created. |
| [`publishPushSummary`](/docs/reference/websocket/notifications/publishpushsummary) | Push-notification summary of items published to reviewers. Used to send a push notification; broadcast on project/\{projectId}/reviewer. |
| [`submissionPushSummary`](/docs/reference/websocket/notifications/submissionpushsummary) | Push-notification summary for a newly created submission. Used to send a push notification; broadcast on project/\{projectId}. |
| [`memberJoinPush`](/docs/reference/websocket/notifications/memberjoinpush) | Push-notification record created when a user joins a workspace or project. Used to send a push notification; broadcast on \{resourceType}/\{resourceId}. |
| [`chatMemberArchive`](/docs/reference/websocket/notifications/chatmemberarchive) | Fired when the requesting user archives a member chat for themselves. Published on user/\{userId} only. |
| [`chatMemberUnarchive`](/docs/reference/websocket/notifications/chatmemberunarchive) | Fired when the requesting user un-archives a member chat for themselves. Published on user/\{userId} only. |
| [`chatHighlightMessage`](/docs/reference/websocket/notifications/chathighlightmessage) | Fired when a message in a project-scoped chat is highlighted. Published on project/\{projectId}/\{visibility} of the chat. |
| [`chatFollow`](/docs/reference/websocket/notifications/chatfollow) | Fired when a user follows a chat. Published on the chat channels. |
| [`chatUnfollow`](/docs/reference/websocket/notifications/chatunfollow) | Fired when a user unfollows a chat. Published on the chat channels. |
| [`userEmailVerify`](/docs/reference/websocket/notifications/useremailverify) | Fired when a user's email address is verified. Published on user/\{userId}. |
| [`botCreate`](/docs/reference/websocket/notifications/botcreate) | Fired when a bot user is created in a workspace. Published on workspace/\{workspaceId}. |
| [`webhookTest`](/docs/reference/websocket/notifications/webhooktest) | Synthetic event fired when an admin tests a webhook subscription. Published on workspace/\{workspaceId}; delivered by the webhook dispatcher as webhook.test. |
| [`taskFollow`](/docs/reference/websocket/notifications/taskfollow) | Fired when a user follows a task. |
| [`taskUnfollow`](/docs/reference/websocket/notifications/taskunfollow) | Fired when a user unfollows a task. |
| [`submissionUpdate`](/docs/reference/websocket/notifications/submissionupdate) | Fired when an already-released submission is re-released. Published on project/\{projectId}, project/\{projectId}/creator and project/\{projectId}/reviewer. |
| [`submissionTag`](/docs/reference/websocket/notifications/submissiontag) | Fired when a tag is added to a submission. resourceType is chatSubmission. |
| [`submissionUntag`](/docs/reference/websocket/notifications/submissionuntag) | Fired when a tag is removed from a submission. resourceType is chatSubmission. |
| [`aiChatTopicCreate`](/docs/reference/websocket/notifications/aichattopiccreate) | Fired when an AI chat topic is created. Published on user/\{userId} of the topic owner. |
| [`aiChatTopicUpdate`](/docs/reference/websocket/notifications/aichattopicupdate) | Fired when an AI chat topic is updated (title, archive state, context items, last message preview) or deleted. Published on user/\{userId} of the topic owner. |
| [`aiChatMessageCreate`](/docs/reference/websocket/notifications/aichatmessagecreate) | Fired when the AI assistant posts a message in an AI chat topic. Published on user/\{userId} of the topic owner. |
| [`publicFileSystemCreate`](/docs/reference/websocket/notifications/publicfilesystemcreate) | Fired when a public release (public file system) is created. Published on project/\{projectId}/creator. |
| [`publicFileSystemUpdate`](/docs/reference/websocket/notifications/publicfilesystemupdate) | Fired when a public release is updated (title, description, validity, options). Published on project/\{projectId}/creator. |
| [`publicFileSystemDelete`](/docs/reference/websocket/notifications/publicfilesystemdelete) | Fired when a public release is deleted. Published on project/\{projectId}/creator. |
| [`settingsUpdate`](/docs/reference/websocket/notifications/settingsupdate) | Fired when a user's settings for a resource are updated or reset. Published on user/\{userId} only. |
| [`convoStart`](/docs/reference/websocket/notifications/convostart) | Fired when a convo (call) is started in a chat. Published on the chat channels and user/\{userId} of the starter. |
| [`convoJoin`](/docs/reference/websocket/notifications/convojoin) | Fired when a user joins a convo. |
| [`convoLeave`](/docs/reference/websocket/notifications/convoleave) | Fired when a user leaves a convo. |
| [`convoComplete`](/docs/reference/websocket/notifications/convocomplete) | Fired when a convo is completed (ended by a user or when the last participant leaves). |
| [`convoUpdate`](/docs/reference/websocket/notifications/convoupdate) | Fired when a convo is updated (subject / notes). |
| [`convoDelete`](/docs/reference/websocket/notifications/convodelete) | Fired when a convo is deleted. |
| [`convoParticipantJoined`](/docs/reference/websocket/notifications/convoparticipantjoined) | Fired (from the call-provider webhook) when a participant actually joins the call room. |
| [`convoParticipantLeft`](/docs/reference/websocket/notifications/convoparticipantleft) | Fired (from the call-provider webhook) when a participant leaves the call room. |
| [`convoHandover`](/docs/reference/websocket/notifications/convohandover) | Fired on user/\{userId} when the user joins a convo from a second device, so the previous device can leave the call. |
| [`boardCreate`](/docs/reference/websocket/notifications/boardcreate) | Fired when a kanban board is created. Published on the project visibility channels of the board. |
| [`boardUpdate`](/docs/reference/websocket/notifications/boardupdate) | Fired when a kanban board is updated (name, visibility, options). |
| [`boardDelete`](/docs/reference/websocket/notifications/boarddelete) | Fired when a kanban board is deleted. Cascaded task deletions / reassignments are included in changes. |
| [`boardTaskCreate`](/docs/reference/websocket/notifications/boardtaskcreate) | Fired when a task is created on a board (UI, AI tool or bulk create). Also used for push notifications. |
| [`boardTaskMove`](/docs/reference/websocket/notifications/boardtaskmove) | Fired when a task is moved between columns or boards. Published on the visibility channels of both boards for cross-board moves. |
| [`boardTaskAssign`](/docs/reference/websocket/notifications/boardtaskassign) | Fired when a task is assigned or unassigned. Published on the board visibility channels and user/\{assignedToId}. |
| [`boardColumnAdd`](/docs/reference/websocket/notifications/boardcolumnadd) | Fired when a column is added to a board. |
| [`boardColumnUpdate`](/docs/reference/websocket/notifications/boardcolumnupdate) | Fired when a board column is updated. |
| [`boardColumnDelete`](/docs/reference/websocket/notifications/boardcolumndelete) | Fired when a board column is deleted. |
| [`boardColumnReorder`](/docs/reference/websocket/notifications/boardcolumnreorder) | Fired when the columns of a board are reordered. changes.update contains every column with its new order. |
| [`boardTaskAdd`](/docs/reference/websocket/notifications/boardtaskadd) | Fired when an existing task is added to a board. |
| [`boardTaskRemove`](/docs/reference/websocket/notifications/boardtaskremove) | Fired when a task is removed from a board (the task itself is kept). |
| [`boardTaskUpdate`](/docs/reference/websocket/notifications/boardtaskupdate) | Fired when a task's details are updated (subject, description, priority, dates, etc.). |
| [`boardTaskLink`](/docs/reference/websocket/notifications/boardtasklink) | Fired when two tasks are linked. |
| [`boardTaskUnlink`](/docs/reference/websocket/notifications/boardtaskunlink) | Fired when a task link is removed. |
| [`boardTaskRelationAdd`](/docs/reference/websocket/notifications/boardtaskrelationadd) | Fired when a resource (asset, folder, message, chat, ...) is related to a task. Also used for push notifications. |
| [`boardTaskRelationRemove`](/docs/reference/websocket/notifications/boardtaskrelationremove) | Fired when a task relation is removed (explicitly, or cascaded when a board visibility change removes access). |
| [`boardFollow`](/docs/reference/websocket/notifications/boardfollow) | Fired when a user follows a board. |
| [`boardUnfollow`](/docs/reference/websocket/notifications/boardunfollow) | Fired when a user unfollows a board. |
# Receive tokenEvent (/docs/reference/websocket/events/receive-tokenevent)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
server → client on the
`resource`
channel. Socket.IO event name:
`tokenEvent`
.
Emitted by the server right before it force-disconnects a socket whose credential is no longer valid.
Payload is a plain string, not an object. 'TokenExpired' is sent when the JWT exp has passed, 'tokenBlacklisted' when the JWT was blacklisted (logout) or a bot API key was revoked. The socket is disconnected \~1 second later; re-authenticate and reconnect.
## Payload: `tokenEvent` [#payload-tokenevent]
Payload of the 'tokenEvent' socket event.
Type: `"TokenExpired" \| "tokenBlacklisted"`
# Receive typing:start (/docs/reference/websocket/events/receive-typing-start)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
server → client on the
`resource`
channel. Socket.IO event name:
`typing:start`
.
Ephemeral typing indicator. Client -> server: emit \{ chatId }. Server -> clients: relayed with the authenticated userId to every other socket on the chat channels.
Client emits typing:start with \{ chatId: string }. The server resolves the same channels a chatCreateMessage for that chat would use (chat/\{chatId}, project/\{projectId}/\{visibility}, public/\{token}; never user/\* channels) and emits typing:start on each of them to every socket except the sender. Not persisted; not delivered as a 'notification' event.
## Payload: `typing:start` [#payload-typingstart]
Payload of the 'typing:start' socket event.
| Property | Type | Required | Description |
| ----------- | --------------- | -------- | -------------------------------------------------------------------------------------------- |
| `chatId` | `string (uuid)` | no | Chat the typing indicator belongs to. |
| `userId` | `string (uuid)` | no | User who is typing. Equals the AI system user ID when the AI assistant is composing a reply. |
| `timestamp` | `integer` | no | Server time in milliseconds since epoch. |
# Receive typing:stop (/docs/reference/websocket/events/receive-typing-stop)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
server → client on the
`resource`
channel. Socket.IO event name:
`typing:stop`
.
Ephemeral typing indicator stop. Client -> server: emit \{ chatId }. Server -> clients: relayed with the authenticated userId to every other socket on the chat channels.
Same routing and payload as typing:start.
## Payload: `typing:stop` [#payload-typingstop]
Payload of the 'typing:stop' socket event.
| Property | Type | Required | Description |
| ----------- | --------------- | -------- | -------------------------------------------------------------------------------------------- |
| `chatId` | `string (uuid)` | no | Chat the typing indicator belongs to. |
| `userId` | `string (uuid)` | no | User who is typing. Equals the AI system user ID when the AI assistant is composing a reply. |
| `timestamp` | `integer` | no | Server time in milliseconds since epoch. |
# Emit collab:click (/docs/reference/websocket/events/send-collab-click)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
client → server on the
`collab`
channel. Socket.IO event name:
`collab:click`
.
Click ripple at percentage coordinates.
Client -> server -> all other sockets in the same /chat/\{chatId} namespace. The server spreads the client payload and appends the authenticated user identity (userId, displayName, color, avatarUrl), the annotationColor assigned on collab:join and a timestamp; client supplied values for those keys are overwritten.
## Payload: `collab:click` [#payload-collabclick]
Payload of the 'collab:click' socket event.
| Property | Type | Required | Description |
| ----------------- | ---------------- | -------- | ------------------------------------------------------------------- |
| `x` | `number` | no | |
| `y` | `number` | no | |
| `userId` | `string` | no | Authenticated user ID (server supplied, cannot be spoofed). |
| `displayName` | `string \| null` | no | Display name (falls back to first + last name). |
| `color` | `string \| null` | no | The user's profile colour. |
| `avatarUrl` | `string \| null` | no | keyPath of the user's avatar thumbnail file, if any. |
| `annotationColor` | `string` | no | Annotation colour assigned to this user for the collab session. |
| `timestamp` | `integer` | no | Server time in milliseconds since epoch when the event was relayed. |
# Emit collab:color-change (/docs/reference/websocket/events/send-collab-color-change)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
client → server on the
`collab`
channel. Socket.IO event name:
`collab:color-change`
.
User changed their annotation colour. The server stores the new colour on the socket, so subsequent relayed events carry it.
Client -> server -> all other sockets in the same /chat/\{chatId} namespace. The server spreads the client payload and appends the authenticated user identity (userId, displayName, color, avatarUrl), the annotationColor assigned on collab:join and a timestamp; client supplied values for those keys are overwritten.
## Payload: `collab:color-change` [#payload-collabcolor-change]
Payload of the 'collab:color-change' socket event.
| Property | Type | Required | Description |
| ----------------- | ---------------- | -------- | ------------------------------------------------------------------- |
| `userId` | `string` | no | Authenticated user ID (server supplied, cannot be spoofed). |
| `displayName` | `string \| null` | no | Display name (falls back to first + last name). |
| `color` | `string \| null` | no | The user's profile colour. |
| `avatarUrl` | `string \| null` | no | keyPath of the user's avatar thumbnail file, if any. |
| `annotationColor` | `string` | no | Annotation colour assigned to this user for the collab session. |
| `timestamp` | `integer` | no | Server time in milliseconds since epoch when the event was relayed. |
# Emit collab:cursor-hide (/docs/reference/websocket/events/send-collab-cursor-hide)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
client → server on the
`collab`
channel. Socket.IO event name:
`collab:cursor-hide`
.
Remote cursor left the asset area.
Client -> server -> all other sockets in the same /chat/\{chatId} namespace. The server spreads the client payload and appends the authenticated user identity (userId, displayName, color, avatarUrl), the annotationColor assigned on collab:join and a timestamp; client supplied values for those keys are overwritten.
## Payload: `collab:cursor-hide` [#payload-collabcursor-hide]
Payload of the 'collab:cursor-hide' socket event.
| Property | Type | Required | Description |
| ----------------- | ---------------- | -------- | ------------------------------------------------------------------- |
| `userId` | `string` | no | Authenticated user ID (server supplied, cannot be spoofed). |
| `displayName` | `string \| null` | no | Display name (falls back to first + last name). |
| `color` | `string \| null` | no | The user's profile colour. |
| `avatarUrl` | `string \| null` | no | keyPath of the user's avatar thumbnail file, if any. |
| `annotationColor` | `string` | no | Annotation colour assigned to this user for the collab session. |
| `timestamp` | `integer` | no | Server time in milliseconds since epoch when the event was relayed. |
# Emit collab:cursor-move (/docs/reference/websocket/events/send-collab-cursor-move)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
client → server on the
`collab`
channel. Socket.IO event name:
`collab:cursor-move`
.
Remote cursor position update (percentage coordinates).
Client -> server -> all other sockets in the same /chat/\{chatId} namespace. The server spreads the client payload and appends the authenticated user identity (userId, displayName, color, avatarUrl), the annotationColor assigned on collab:join and a timestamp; client supplied values for those keys are overwritten.
## Payload: `collab:cursor-move` [#payload-collabcursor-move]
Payload of the 'collab:cursor-move' socket event.
| Property | Type | Required | Description |
| ----------------- | ---------------- | -------- | ------------------------------------------------------------------- |
| `x` | `number` | no | Client supplied X position as a percentage of the asset area. |
| `y` | `number` | no | Client supplied Y position as a percentage of the asset area. |
| `visible` | `boolean` | no | Client supplied visibility flag. |
| `userId` | `string` | no | Authenticated user ID (server supplied, cannot be spoofed). |
| `displayName` | `string \| null` | no | Display name (falls back to first + last name). |
| `color` | `string \| null` | no | The user's profile colour. |
| `avatarUrl` | `string \| null` | no | keyPath of the user's avatar thumbnail file, if any. |
| `annotationColor` | `string` | no | Annotation colour assigned to this user for the collab session. |
| `timestamp` | `integer` | no | Server time in milliseconds since epoch when the event was relayed. |
# Emit collab:join (/docs/reference/websocket/events/send-collab-join)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
client → server on the
`collab`
channel. Socket.IO event name:
`collab:join`
.
A user joined the collab session on this chat namespace (broadcast to the other members).
Client emits collab:join with optional \{ preferredAnnotationColor }. Client -> server -> all other sockets in the same /chat/\{chatId} namespace. The server spreads the client payload and appends the authenticated user identity (userId, displayName, color, avatarUrl), the annotationColor assigned on collab:join and a timestamp; client supplied values for those keys are overwritten. The joining socket additionally receives collab:self-color, collab:members (if others are present) and either collab:presenter-assign (first member) or collab:presenter-state.
## Payload: `collab:join` [#payload-collabjoin]
Payload of the 'collab:join' socket event.
| Property | Type | Required | Description |
| -------------------------- | ---------------- | -------- | ------------------------------------------------------------------- |
| `preferredAnnotationColor` | `string` | no | Echo of the colour the client asked for, if it sent one. |
| `userId` | `string` | no | Authenticated user ID (server supplied, cannot be spoofed). |
| `displayName` | `string \| null` | no | Display name (falls back to first + last name). |
| `color` | `string \| null` | no | The user's profile colour. |
| `avatarUrl` | `string \| null` | no | keyPath of the user's avatar thumbnail file, if any. |
| `annotationColor` | `string` | no | Annotation colour assigned to this user for the collab session. |
| `timestamp` | `integer` | no | Server time in milliseconds since epoch when the event was relayed. |
# Emit collab:leave (/docs/reference/websocket/events/send-collab-leave)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
client → server on the
`collab`
channel. Socket.IO event name:
`collab:leave`
.
A user left the collab session (explicit collab:leave from the client or socket disconnect).
Client -> server -> all other sockets in the same /chat/\{chatId} namespace. The server spreads the client payload and appends the authenticated user identity (userId, displayName, color, avatarUrl), the annotationColor assigned on collab:join and a timestamp; client supplied values for those keys are overwritten. On disconnect the server emits it on behalf of the leaving socket; if they were the presenter a collab:presenter-assign (reason transfer-on-leave) follows.
## Payload: `collab:leave` [#payload-collableave]
Payload of the 'collab:leave' socket event.
| Property | Type | Required | Description |
| ----------------- | ---------------- | -------- | ------------------------------------------------------------------- |
| `userId` | `string` | no | Authenticated user ID (server supplied, cannot be spoofed). |
| `displayName` | `string \| null` | no | Display name (falls back to first + last name). |
| `color` | `string \| null` | no | The user's profile colour. |
| `avatarUrl` | `string \| null` | no | keyPath of the user's avatar thumbnail file, if any. |
| `annotationColor` | `string` | no | Annotation colour assigned to this user for the collab session. |
| `timestamp` | `integer` | no | Server time in milliseconds since epoch when the event was relayed. |
# Emit collab:path-clear (/docs/reference/websocket/events/send-collab-path-clear)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
client → server on the
`collab`
channel. Socket.IO event name:
`collab:path-clear`
.
Drawn path(s) cleared. With pathId only that path is cleared, otherwise all paths of the user.
Client -> server -> all other sockets in the same /chat/\{chatId} namespace. The server spreads the client payload and appends the authenticated user identity (userId, displayName, color, avatarUrl), the annotationColor assigned on collab:join and a timestamp; client supplied values for those keys are overwritten.
## Payload: `collab:path-clear` [#payload-collabpath-clear]
Payload of the 'collab:path-clear' socket event.
| Property | Type | Required | Description |
| ----------------- | ---------------- | -------- | ------------------------------------------------------------------- |
| `pathId` | `string \| null` | no | |
| `userId` | `string` | no | Authenticated user ID (server supplied, cannot be spoofed). |
| `displayName` | `string \| null` | no | Display name (falls back to first + last name). |
| `color` | `string \| null` | no | The user's profile colour. |
| `avatarUrl` | `string \| null` | no | keyPath of the user's avatar thumbnail file, if any. |
| `annotationColor` | `string` | no | Annotation colour assigned to this user for the collab session. |
| `timestamp` | `integer` | no | Server time in milliseconds since epoch when the event was relayed. |
# Emit collab:path-end (/docs/reference/websocket/events/send-collab-path-end)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
client → server on the
`collab`
channel. Socket.IO event name:
`collab:path-end`
.
Pen drawing completed.
Client -> server -> all other sockets in the same /chat/\{chatId} namespace. The server spreads the client payload and appends the authenticated user identity (userId, displayName, color, avatarUrl), the annotationColor assigned on collab:join and a timestamp; client supplied values for those keys are overwritten.
## Payload: `collab:path-end` [#payload-collabpath-end]
Payload of the 'collab:path-end' socket event.
| Property | Type | Required | Description |
| ----------------- | ---------------- | -------- | ------------------------------------------------------------------- |
| `pathId` | `string` | no | |
| `pathData` | `string` | no | Final SVG path data. |
| `fadeDuration` | `number` | no | |
| `userId` | `string` | no | Authenticated user ID (server supplied, cannot be spoofed). |
| `displayName` | `string \| null` | no | Display name (falls back to first + last name). |
| `color` | `string \| null` | no | The user's profile colour. |
| `avatarUrl` | `string \| null` | no | keyPath of the user's avatar thumbnail file, if any. |
| `annotationColor` | `string` | no | Annotation colour assigned to this user for the collab session. |
| `timestamp` | `integer` | no | Server time in milliseconds since epoch when the event was relayed. |
# Emit collab:path-start (/docs/reference/websocket/events/send-collab-path-start)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
client → server on the
`collab`
channel. Socket.IO event name:
`collab:path-start`
.
Pen drawing started.
Client -> server -> all other sockets in the same /chat/\{chatId} namespace. The server spreads the client payload and appends the authenticated user identity (userId, displayName, color, avatarUrl), the annotationColor assigned on collab:join and a timestamp; client supplied values for those keys are overwritten.
## Payload: `collab:path-start` [#payload-collabpath-start]
Payload of the 'collab:path-start' socket event.
| Property | Type | Required | Description |
| ----------------- | ---------------- | -------- | ------------------------------------------------------------------- |
| `pathId` | `string` | no | Client generated path ID. |
| `strokeColor` | `string` | no | |
| `strokeWidth` | `number` | no | |
| `points` | `object[]` | no | Initial point(s) of the path (client defined shape). |
| `fadeDuration` | `number` | no | Milliseconds after which the path fades (0 = persistent). |
| `userId` | `string` | no | Authenticated user ID (server supplied, cannot be spoofed). |
| `displayName` | `string \| null` | no | Display name (falls back to first + last name). |
| `color` | `string \| null` | no | The user's profile colour. |
| `avatarUrl` | `string \| null` | no | keyPath of the user's avatar thumbnail file, if any. |
| `annotationColor` | `string` | no | Annotation colour assigned to this user for the collab session. |
| `timestamp` | `integer` | no | Server time in milliseconds since epoch when the event was relayed. |
# Emit collab:path-update (/docs/reference/websocket/events/send-collab-path-update)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
client → server on the
`collab`
channel. Socket.IO event name:
`collab:path-update`
.
Pen drawing continued with additional points.
Client -> server -> all other sockets in the same /chat/\{chatId} namespace. The server spreads the client payload and appends the authenticated user identity (userId, displayName, color, avatarUrl), the annotationColor assigned on collab:join and a timestamp; client supplied values for those keys are overwritten.
## Payload: `collab:path-update` [#payload-collabpath-update]
Payload of the 'collab:path-update' socket event.
| Property | Type | Required | Description |
| ----------------- | ---------------- | -------- | ------------------------------------------------------------------- |
| `pathId` | `string` | no | |
| `points` | `object[]` | no | Additional points appended to the path. |
| `userId` | `string` | no | Authenticated user ID (server supplied, cannot be spoofed). |
| `displayName` | `string \| null` | no | Display name (falls back to first + last name). |
| `color` | `string \| null` | no | The user's profile colour. |
| `avatarUrl` | `string \| null` | no | keyPath of the user's avatar thumbnail file, if any. |
| `annotationColor` | `string` | no | Annotation colour assigned to this user for the collab session. |
| `timestamp` | `integer` | no | Server time in milliseconds since epoch when the event was relayed. |
# Emit collab:playback-sync (/docs/reference/websocket/events/send-collab-playback-sync)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
client → server on the
`collab`
channel. Socket.IO event name:
`collab:playback-sync`
.
Play/pause/seek state broadcast by the presenter to the other members.
Only the current presenter socket may broadcast; other senders receive collab:playback-sync:rejected instead and nothing is relayed. Client -> server -> all other sockets in the same /chat/\{chatId} namespace. The server spreads the client payload and appends the authenticated user identity (userId, displayName, color, avatarUrl), the annotationColor assigned on collab:join and a timestamp; client supplied values for those keys are overwritten. The server also stores currentTime/playing as the namespace playback state.
## Payload: `collab:playback-sync` [#payload-collabplayback-sync]
Payload of the 'collab:playback-sync' socket event.
| Property | Type | Required | Description |
| ----------------- | ---------------- | -------- | ------------------------------------------------------------------- |
| `action` | `string` | no | Client supplied action (e.g. 'play', 'pause', 'seek'). |
| `currentTime` | `number` | no | |
| `playing` | `boolean` | no | |
| `duration` | `number` | no | |
| `playbackRate` | `number` | no | |
| `userId` | `string` | no | Authenticated user ID (server supplied, cannot be spoofed). |
| `displayName` | `string \| null` | no | Display name (falls back to first + last name). |
| `color` | `string \| null` | no | The user's profile colour. |
| `avatarUrl` | `string \| null` | no | keyPath of the user's avatar thumbnail file, if any. |
| `annotationColor` | `string` | no | Annotation colour assigned to this user for the collab session. |
| `timestamp` | `integer` | no | Server time in milliseconds since epoch when the event was relayed. |
# Emit collab:presenter-request (/docs/reference/websocket/events/send-collab-presenter-request)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
client → server on the
`collab`
channel. Socket.IO event name:
`collab:presenter-request`
.
Request for presenter control. From an admin it is granted immediately (collab:presenter-assign, reason admin-takeover); from a non-admin it is relayed to the current presenter socket only.
Client emits collab:presenter-request (any data). Client -> server -> the current presenter socket only. The server spreads the client payload and appends the authenticated user identity (userId, displayName, color, avatarUrl), the annotationColor assigned on collab:join and a timestamp; client supplied values for those keys are overwritten. requesterId / requesterDisplayName duplicate userId / displayName.
## Payload: `collab:presenter-request` [#payload-collabpresenter-request]
Payload of the 'collab:presenter-request' socket event.
| Property | Type | Required | Description |
| ---------------------- | ---------------- | -------- | ------------------------------------------------------------------- |
| `requesterId` | `string` | no | |
| `requesterDisplayName` | `string \| null` | no | |
| `userId` | `string` | no | Authenticated user ID (server supplied, cannot be spoofed). |
| `displayName` | `string \| null` | no | Display name (falls back to first + last name). |
| `color` | `string \| null` | no | The user's profile colour. |
| `avatarUrl` | `string \| null` | no | keyPath of the user's avatar thumbnail file, if any. |
| `annotationColor` | `string` | no | Annotation colour assigned to this user for the collab session. |
| `timestamp` | `integer` | no | Server time in milliseconds since epoch when the event was relayed. |
# Emit collab:presenter-takeover (/docs/reference/websocket/events/send-collab-presenter-takeover)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
client → server on the
`collab`
channel. Socket.IO event name:
`collab:presenter-takeover`
.
Client -> server only: an admin or the current presenter hands presenter control to a target user. Results in a collab:presenter-assign (reason admin-takeover) to everyone; nothing is relayed under this name.
Client payload: \{ targetUserId: string, targetDisplayName: string }. Ignored when the sender is neither an admin (workspaceOwner/workspaceAdmin/projectOwner/projectAdmin) nor the current presenter, or when targetUserId is missing.
## Payload: `collab:presenter-takeover` [#payload-collabpresenter-takeover]
Client -> server payload (no server emission under this event name).
| Property | Type | Required | Description |
| ------------------- | -------- | -------- | ----------- |
| `targetUserId` | `string` | no | |
| `targetDisplayName` | `string` | no | |
# Emit collab:region-create (/docs/reference/websocket/events/send-collab-region-create)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
client → server on the
`collab`
channel. Socket.IO event name:
`collab:region-create`
.
Audio/video region created on the waveform/timeline.
Client -> server -> all other sockets in the same /chat/\{chatId} namespace. The server spreads the client payload and appends the authenticated user identity (userId, displayName, color, avatarUrl), the annotationColor assigned on collab:join and a timestamp; client supplied values for those keys are overwritten.
## Payload: `collab:region-create` [#payload-collabregion-create]
Payload of the 'collab:region-create' socket event.
| Property | Type | Required | Description |
| ----------------- | ---------------- | -------- | ------------------------------------------------------------------- |
| `regionId` | `string` | no | |
| `startTime` | `number` | no | |
| `endTime` | `number` | no | |
| `userId` | `string` | no | Authenticated user ID (server supplied, cannot be spoofed). |
| `displayName` | `string \| null` | no | Display name (falls back to first + last name). |
| `color` | `string \| null` | no | The user's profile colour. |
| `avatarUrl` | `string \| null` | no | keyPath of the user's avatar thumbnail file, if any. |
| `annotationColor` | `string` | no | Annotation colour assigned to this user for the collab session. |
| `timestamp` | `integer` | no | Server time in milliseconds since epoch when the event was relayed. |
# Emit collab:region-remove (/docs/reference/websocket/events/send-collab-region-remove)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
client → server on the
`collab`
channel. Socket.IO event name:
`collab:region-remove`
.
Region removed.
Client -> server -> all other sockets in the same /chat/\{chatId} namespace. The server spreads the client payload and appends the authenticated user identity (userId, displayName, color, avatarUrl), the annotationColor assigned on collab:join and a timestamp; client supplied values for those keys are overwritten.
## Payload: `collab:region-remove` [#payload-collabregion-remove]
Payload of the 'collab:region-remove' socket event.
| Property | Type | Required | Description |
| ----------------- | ---------------- | -------- | ------------------------------------------------------------------- |
| `regionId` | `string` | no | |
| `userId` | `string` | no | Authenticated user ID (server supplied, cannot be spoofed). |
| `displayName` | `string \| null` | no | Display name (falls back to first + last name). |
| `color` | `string \| null` | no | The user's profile colour. |
| `avatarUrl` | `string \| null` | no | keyPath of the user's avatar thumbnail file, if any. |
| `annotationColor` | `string` | no | Annotation colour assigned to this user for the collab session. |
| `timestamp` | `integer` | no | Server time in milliseconds since epoch when the event was relayed. |
# Emit collab:state-request (/docs/reference/websocket/events/send-collab-state-request)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
client → server on the
`collab`
channel. Socket.IO event name:
`collab:state-request`
.
Server -> the earliest joined other member: asks it to send its current annotation state to a late joiner (collab:state-response).
Emitted automatically when a socket joins a namespace with existing members, and again when a client retries by emitting collab:state-request itself.
## Payload: `collab:state-request` [#payload-collabstate-request]
Payload of the 'collab:state-request' socket event.
| Property | Type | Required | Description |
| ------------------- | --------- | -------- | -------------------------------------------------- |
| `requesterId` | `string` | no | User ID of the late joiner. |
| `requesterSocketId` | `string` | no | Socket ID to address the collab:state-response to. |
| `timestamp` | `integer` | no | |
# Emit collab:state-response (/docs/reference/websocket/events/send-collab-state-response)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
client → server on the
`collab`
channel. Socket.IO event name:
`collab:state-response`
.
Server -> the requesting socket only: sanitised snapshot of paths, regions and zoom provided by an existing member.
Client emits collab:state-response with \{ requesterSocketId, paths, regions, zoom }; the server validates/truncates (max 200 paths and 200 regions, string length limits) and forwards it only to requesterSocketId.
## Payload: `collab:state-response` [#payload-collabstate-response]
Payload of the 'collab:state-response' socket event.
| Property | Type | Required | Description |
| ------------------- | ---------- | -------- | ----------------------------------------------------------------------------------------- |
| `requesterSocketId` | `string` | no | |
| `paths` | `object[]` | no | Path objects: \{ pathId, userId, color, strokeWidth, pathData, fadeDuration, createdAt }. |
| `regions` | `object[]` | no | Region objects: \{ regionId, startTime, endTime, userId, displayName, color, avatarUrl }. |
| `zoom` | `number` | no | Zoom level, omitted when the responder did not supply a number. |
| `timestamp` | `integer` | no | |
# Emit collab:zoom-sync (/docs/reference/websocket/events/send-collab-zoom-sync)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
client → server on the
`collab`
channel. Socket.IO event name:
`collab:zoom-sync`
.
Zoom level broadcast (followers of the presenter apply it).
Client -> server -> all other sockets in the same /chat/\{chatId} namespace. The server spreads the client payload and appends the authenticated user identity (userId, displayName, color, avatarUrl), the annotationColor assigned on collab:join and a timestamp; client supplied values for those keys are overwritten.
## Payload: `collab:zoom-sync` [#payload-collabzoom-sync]
Payload of the 'collab:zoom-sync' socket event.
| Property | Type | Required | Description |
| ----------------- | ---------------- | -------- | ------------------------------------------------------------------- |
| `zoom` | `number` | no | |
| `userId` | `string` | no | Authenticated user ID (server supplied, cannot be spoofed). |
| `displayName` | `string \| null` | no | Display name (falls back to first + last name). |
| `color` | `string \| null` | no | The user's profile colour. |
| `avatarUrl` | `string \| null` | no | keyPath of the user's avatar thumbnail file, if any. |
| `annotationColor` | `string` | no | Annotation colour assigned to this user for the collab session. |
| `timestamp` | `integer` | no | Server time in milliseconds since epoch when the event was relayed. |
# Emit typing:start (/docs/reference/websocket/events/send-typing-start)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
client → server on the
`resource`
channel. Socket.IO event name:
`typing:start`
.
Ephemeral typing indicator. Client -> server: emit \{ chatId }. Server -> clients: relayed with the authenticated userId to every other socket on the chat channels.
Client emits typing:start with \{ chatId: string }. The server resolves the same channels a chatCreateMessage for that chat would use (chat/\{chatId}, project/\{projectId}/\{visibility}, public/\{token}; never user/\* channels) and emits typing:start on each of them to every socket except the sender. Not persisted; not delivered as a 'notification' event.
## Payload: `typing:start` [#payload-typingstart]
Payload of the 'typing:start' socket event.
| Property | Type | Required | Description |
| ----------- | --------------- | -------- | -------------------------------------------------------------------------------------------- |
| `chatId` | `string (uuid)` | no | Chat the typing indicator belongs to. |
| `userId` | `string (uuid)` | no | User who is typing. Equals the AI system user ID when the AI assistant is composing a reply. |
| `timestamp` | `integer` | no | Server time in milliseconds since epoch. |
# Emit typing:stop (/docs/reference/websocket/events/send-typing-stop)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
client → server on the
`resource`
channel. Socket.IO event name:
`typing:stop`
.
Ephemeral typing indicator stop. Client -> server: emit \{ chatId }. Server -> clients: relayed with the authenticated userId to every other socket on the chat channels.
Same routing and payload as typing:start.
## Payload: `typing:stop` [#payload-typingstop]
Payload of the 'typing:stop' socket event.
| Property | Type | Required | Description |
| ----------- | --------------- | -------- | -------------------------------------------------------------------------------------------- |
| `chatId` | `string (uuid)` | no | Chat the typing indicator belongs to. |
| `userId` | `string (uuid)` | no | User who is typing. Equals the AI system user ID when the AI assistant is composing a reply. |
| `timestamp` | `integer` | no | Server time in milliseconds since epoch. |
# Emit ws:probe (/docs/reference/websocket/events/send-ws-probe)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
client → server on the
`resource`
channel. Socket.IO event name:
`ws:probe`
.
Client -> server liveness probe. Emit with an acknowledgement callback; the server acks immediately with no payload.
Client emits ws:probe (any/no data) using socket.io acks, e.g. socket.timeout(2000).emit('ws:probe', null, (err) => ...). A missing ack means the connection is stale and should be torn down. Nothing is emitted by the server other than the ack.
## Payload: `ws:probe` [#payload-wsprobe]
Acknowledgement only; the server sends no payload.
Type: `object`
# aiChatMessageCreate (/docs/reference/websocket/notifications/aichatmessagecreate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`aiChatMessageCreate`
.
Fired when the AI assistant posts a message in an AI chat topic. Published on user/\{userId} of the topic owner.
Payload for the aiChatMessageCreate event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ------------ | --------------- | -------- | -------------------------------------------------------------------- |
| `(*)userId` | `string (uuid)` | no | Deprecated. |
| `(*)topicId` | `string (uuid)` | no | Deprecated. |
| `(*)message` | `object` | no | Deprecated. The assistant message. Use resource from changes.create. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `create` | `object[]` | no | |
**`create`** (items)
| Property | Type | Required | Description |
| -------------- | ----------------- | -------- | ------------------------------ |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"aiChatMessage"` | no | |
| `resource` | `object` | no | The created assistant message. |
# aiChatTopicCreate (/docs/reference/websocket/notifications/aichattopiccreate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`aiChatTopicCreate`
.
Fired when an AI chat topic is created. Published on user/\{userId} of the topic owner.
Payload for the aiChatTopicCreate event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ----------- | --------------- | -------- | ---------------------------------------------------------------- |
| `(*)userId` | `string (uuid)` | no | Deprecated. |
| `(*)topic` | `object` | no | Deprecated. The AI chat topic. Use resource from changes.create. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `create` | `object[]` | no | |
**`create`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ------------------ |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"aiChatTopic"` | no | |
| `resource` | `object` | no | The created topic. |
# aiChatTopicUpdate (/docs/reference/websocket/notifications/aichattopicupdate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`aiChatTopicUpdate`
.
Fired when an AI chat topic is updated (title, archive state, context items, last message preview) or deleted. Published on user/\{userId} of the topic owner.
Payload for the aiChatTopicUpdate event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | changes.update on updates; changes.delete (no resource) when the topic is deleted. |
**`tokens`**
| Property | Type | Required | Description |
| ----------- | --------------- | -------- | ------------------------------------------------------------------ |
| `(*)userId` | `string (uuid)` | no | Deprecated. |
| `(*)topic` | `object` | no | Deprecated. The AI chat topic (status pendingDelete when deleted). |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
| `delete` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ------------------ |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"aiChatTopic"` | no | |
| `resource` | `object` | no | The updated topic. |
**`delete`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"aiChatTopic"` | no | |
# assetDelete (/docs/reference/websocket/notifications/assetdelete)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`assetDelete`
.
Fired when an asset is deleted.
Payload for the asset delete event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ---------------------- | --------------- | -------- | ----------- |
| `(*)requesterId` | `string (uuid)` | no | |
| `(*)requester` | `object` | no | |
| `(*)assetId` | `string (uuid)` | no | |
| `(*)name` | `string` | no | |
| `(*)ownerResourceType` | `string` | no | |
| `(*)ownerResourceId` | `string (uuid)` | no | |
| `(*)visibility` | `string[]` | no | |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `delete` | `object[]` | no | |
**`delete`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
# assetFileUpdate (/docs/reference/websocket/notifications/assetfileupdate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`assetFileUpdate`
.
Fired when a file associated with an asset is updated or added.
Fired when a file associated with an asset is updated or added (e.g., thumbnail generated).
Payload for the asset file update event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | --------------------------------------------------------------- |
| `(*)assetId` | `string (uuid)` | no | |
| `(*)name` | `string` | no | |
| `keyPath` | `string` | yes | The storage key of the new/updated file. |
| `functionType` | `string` | yes | The role of the file (e.g., 'original', 'thumbnail', 'stream'). |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | yes | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"asset"` | no | |
| `resource` | `object` | no | |
# assetGroupUploadComplete (/docs/reference/websocket/notifications/assetgroupuploadcomplete)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`assetGroupUploadComplete`
.
Fired when an uploaded asset becomes active. Uploads by the same creator into the same resource/visibility within the grouping window (30 min) are accumulated into one notification, which is then re-sent via notificationUpdate.
Fired when a group of assets finishes uploading within a defined time window. Subsequent uploads in the window update this notification (tokens.assets and tokens.uploadCount grow) and emit notificationUpdate.
Payload for the assetGroupUploadComplete event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | On the initial notification changes.update contains the first asset; the grouped notification delivered via notificationUpdate is NOT extended with later assets (only tokens are). |
**`tokens`**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ---------------------------------------------------------------------- |
| `(*)creatorId` | `string (uuid)` | no | Deprecated. Use initiatorId. |
| `(*)creator` | `object` | no | Deprecated. Public user object of the uploader. Use initiator. |
| `visibility` | `string[]` | yes | Visibility of the uploaded asset(s). |
| `(*)assets` | `object[]` | no | Deprecated. Uploaded asset objects. Use resources from changes.update. |
| `uploadCount` | `integer` | yes | Number of assets accumulated in this group so far. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"asset"` | no | |
| `resource` | `object` | no | The uploaded asset. |
# assetNameChange (/docs/reference/websocket/notifications/assetnamechange)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`assetNameChange`
.
Fired when an asset's name is changed.
Payload for the asset name change event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ---------------------- | --------------- | -------- | ------------------------- |
| `(*)requesterId` | `string (uuid)` | no | |
| `(*)requester` | `object` | no | |
| `(*)assetId` | `string (uuid)` | no | |
| `(*)ownerResourceType` | `string` | no | |
| `(*)ownerResourceId` | `string (uuid)` | no | |
| `(*)visibility` | `string[]` | no | |
| `oldName` | `string` | yes | |
| `newName` | `string` | yes | |
| `(*)asset` | `object` | no | The updated asset object. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
| `resource` | `object` | no | |
# assetPostProcessUpdate (/docs/reference/websocket/notifications/assetpostprocessupdate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`assetPostProcessUpdate`
.
Fired periodically during asset post-processing (e.g., transcoding).
Payload for the asset post-process update event.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ----------------- | ---------------- | -------- | ----------------------------------------------- |
| `assetId` | `string (uuid)` | yes | |
| `percentComplete` | `number (float)` | yes | |
| `status` | `string` | yes | |
| `meta` | `object` | yes | Additional metadata about the processing state. |
# assetPublish (/docs/reference/websocket/notifications/assetpublish)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`assetPublish`
.
Fired for each individual asset published through the project publish flow (accompanies fileSystemPublish / projectItemsPublish).
Emitted per published asset on the asset's own channel (asset/\{assetId}) plus the project channels. Folders published in the same operation emit folderPublish.
Payload for the assetPublish event.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| -------- | -------- | -------- | ---------------------------- |
| `name` | `string` | yes | Name of the published asset. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | --------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"asset"` | no | |
| `resource` | `object` | no | The published asset object. |
# assetStatusUpdate (/docs/reference/websocket/notifications/assetstatusupdate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`assetStatusUpdate`
.
Fired when an asset's status changes (e.g., during processing).
Payload for the asset status update event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ----------------- | --------------- | -------- | ----------------------------------------- |
| `(*)assetId` | `string (uuid)` | no | |
| `name` | `string` | yes | |
| `oldStatus` | `string` | yes | |
| `newStatus` | `string` | yes | |
| `(*)updatedAsset` | `object` | no | The asset object with the updated status. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | yes | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
| `resource` | `object` | no | |
# assetTag (/docs/reference/websocket/notifications/assettag)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`assetTag`
.
Fired when a tag is added to an asset.
Payload for the assetTag event.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | Not populated for this event (the notification is created without a changes object). |
**`tokens`**
| Property | Type | Required | Description |
| --------- | -------- | -------- | ------------------------------- |
| `name` | `string` | yes | Asset name. |
| `tagName` | `string` | yes | Name of the tag that was added. |
# assetUnpublish (/docs/reference/websocket/notifications/assetunpublish)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`assetUnpublish`
.
Fired for each individual asset unpublished through the project unpublish flow (accompanies fileSystemUnpublish / projectItemsUnpublish).
Emitted per unpublished asset on the asset's own channel (asset/\{assetId}) plus the project channels.
Payload for the assetUnpublish event.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| -------- | -------- | -------- | ------------------------------ |
| `name` | `string` | yes | Name of the unpublished asset. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"asset"` | no | |
| `resource` | `object` | no | The unpublished asset object. |
# assetUntag (/docs/reference/websocket/notifications/assetuntag)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`assetUntag`
.
Fired when a tag is removed from an asset.
Payload for the assetUntag event.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | Not populated for this event (the notification is created without a changes object). |
**`tokens`**
| Property | Type | Required | Description |
| --------- | -------- | -------- | --------------------------------- |
| `name` | `string` | yes | Asset name. |
| `tagName` | `string` | yes | Name of the tag that was removed. |
# boardColumnAdd (/docs/reference/websocket/notifications/boardcolumnadd)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`boardColumnAdd`
.
Fired when a column is added to a board.
Payload for the boardColumnAdd event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | --------------------------------------------- |
| `(*)projectId` | `string (uuid)` | no | Deprecated. |
| `(*)boardId` | `string (uuid)` | no | Deprecated. |
| `boardName` | `string` | yes | |
| `columnName` | `string` | yes | |
| `(*)column` | `object` | no | Deprecated. Use resource from changes.create. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `create` | `object[]` | no | |
**`create`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"boardColumn"` | no | |
| `resource` | `object` | no | The created column. |
# boardColumnDelete (/docs/reference/websocket/notifications/boardcolumndelete)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`boardColumnDelete`
.
Fired when a board column is deleted.
Payload for the boardColumnDelete event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `(*)projectId` | `string (uuid)` | no | Deprecated. |
| `(*)boardId` | `string (uuid)` | no | Deprecated. |
| `boardName` | `string` | yes | |
| `(*)columnId` | `string (uuid)` | no | Deprecated. |
| `columnName` | `string` | yes | |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `delete` | `object[]` | no | |
**`delete`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"boardColumn"` | no | |
# boardColumnReorder (/docs/reference/websocket/notifications/boardcolumnreorder)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`boardColumnReorder`
.
Fired when the columns of a board are reordered. changes.update contains every column with its new order.
Payload for the boardColumnReorder event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `(*)projectId` | `string (uuid)` | no | Deprecated. |
| `(*)boardId` | `string (uuid)` | no | Deprecated. |
| `boardName` | `string` | yes | |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | -------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"boardColumn"` | no | |
| `resource` | `object` | no | A column with its updated order. |
# boardColumnUpdate (/docs/reference/websocket/notifications/boardcolumnupdate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`boardColumnUpdate`
.
Fired when a board column is updated.
Payload for the boardColumnUpdate event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | --------------------------------------------- |
| `(*)projectId` | `string (uuid)` | no | Deprecated. |
| `(*)boardId` | `string (uuid)` | no | Deprecated. |
| `boardName` | `string` | yes | |
| `(*)columnId` | `string (uuid)` | no | Deprecated. |
| `columnName` | `string` | yes | |
| `(*)column` | `object` | no | Deprecated. Use resource from changes.update. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"boardColumn"` | no | |
| `resource` | `object` | no | The updated column. |
# boardCreate (/docs/reference/websocket/notifications/boardcreate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`boardCreate`
.
Fired when a kanban board is created. Published on the project visibility channels of the board.
Payload for the boardCreate event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | --------------------------------------------- |
| `(*)projectId` | `string (uuid)` | no | Deprecated. |
| `boardName` | `string` | yes | |
| `(*)board` | `object` | no | Deprecated. Use resource from changes.create. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `create` | `object[]` | no | |
**`create`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ------------------ |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"board"` | no | |
| `resource` | `object` | no | The created board. |
# boardDelete (/docs/reference/websocket/notifications/boarddelete)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`boardDelete`
.
Fired when a kanban board is deleted. Cascaded task deletions / reassignments are included in changes.
Payload for the boardDelete event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | changes.delete always contains the board plus one entry per task deleted with it; changes.update (present only when tasks were moved to another board) lists the reassigned tasks without a resource object. |
**`tokens`**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `(*)projectId` | `string (uuid)` | no | Deprecated. |
| `boardName` | `string` | yes | |
**`changes`**
| Property | Type | Required | Description |
| -------- | -------------------- | -------- | ----------- |
| `update` | `object[]` | no | |
| `delete` | `object \| object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ------------------------------------------------ |
| `resourceId` | `string (uuid)` | no | ID of a task reassigned to another board/column. |
| `resourceType` | `"task"` | no | |
**`delete`** (items)
One of 2 variants:
**Variant 1**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"board"` | no | |
**Variant 2**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ------------------------------------ |
| `resourceId` | `string (uuid)` | no | ID of a task deleted with the board. |
| `resourceType` | `"task"` | no | |
# boardFollow (/docs/reference/websocket/notifications/boardfollow)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`boardFollow`
.
Fired when a user follows a board.
Payload for the boardFollow event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | --------------------------- |
| `(*)projectId` | `string (uuid)` | no | Deprecated. |
| `(*)boardId` | `string (uuid)` | no | Deprecated. Use resourceId. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | --------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"board"` | no | |
| `resource` | `object` | no | The board with updated followers. |
# boardTaskAdd (/docs/reference/websocket/notifications/boardtaskadd)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`boardTaskAdd`
.
Fired when an existing task is added to a board.
Payload for the boardTaskAdd event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `(*)projectId` | `string (uuid)` | no | Deprecated. |
| `(*)boardId` | `string (uuid)` | no | Deprecated. |
| `boardName` | `string` | yes | |
| `(*)taskId` | `string (uuid)` | no | Deprecated. |
| `taskSubject` | `string` | yes | |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | --------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"task"` | no | |
| `resource` | `object` | no | The task now placed on the board. |
# boardTaskAssign (/docs/reference/websocket/notifications/boardtaskassign)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`boardTaskAssign`
.
Fired when a task is assigned or unassigned. Published on the board visibility channels and user/\{assignedToId}.
Payload for the boardTaskAssign event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| -------------- | ----------------------- | -------- | ----------------------------------- |
| `(*)projectId` | `string (uuid)` | no | Deprecated. |
| `taskNumber` | `integer` | yes | |
| `taskSubject` | `string` | yes | |
| `assignedToId` | `string (uuid) \| null` | yes | New assignee, null when unassigned. |
| `boardName` | `string \| null` | yes | |
| `(*)boardId` | `string (uuid) \| null` | no | Deprecated. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"task"` | no | |
| `resource` | `object` | no | The task with the new assignee. |
# boardTaskCreate (/docs/reference/websocket/notifications/boardtaskcreate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`boardTaskCreate`
.
Fired when a task is created on a board (UI, AI tool or bulk create). Also used for push notifications.
Payload for the boardTaskCreate event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `(*)projectId` | `string (uuid)` | no | Deprecated. |
| `taskNumber` | `integer` | yes | |
| `taskSubject` | `string` | yes | |
| `boardName` | `string` | yes | |
| `(*)boardId` | `string (uuid)` | no | Deprecated. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `create` | `object[]` | no | |
**`create`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"task"` | no | |
| `resource` | `object` | no | The created task. |
# boardTaskLink (/docs/reference/websocket/notifications/boardtasklink)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`boardTaskLink`
.
Fired when two tasks are linked.
Payload for the boardTaskLink event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ----------------- | --------------- | -------- | ---------------------------------- |
| `(*)projectId` | `string (uuid)` | no | Deprecated. |
| `(*)taskId` | `string (uuid)` | no | Deprecated. |
| `(*)linkedTaskId` | `string (uuid)` | no | Deprecated. |
| `linkType` | `string` | yes | Link type (defaults to 'related'). |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `create` | `object[]` | no | |
**`create`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ------------------------ |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"taskLink"` | no | |
| `resource` | `object` | no | The created link record. |
# boardTaskMove (/docs/reference/websocket/notifications/boardtaskmove)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`boardTaskMove`
.
Fired when a task is moved between columns or boards. Published on the visibility channels of both boards for cross-board moves.
Payload for the boardTaskMove event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ---------------- | ----------------------- | -------- | ------------------------------------------------------------------- |
| `(*)projectId` | `string (uuid)` | no | Deprecated. |
| `taskNumber` | `integer` | yes | |
| `taskSubject` | `string` | yes | |
| `fromColumnName` | `string` | yes | |
| `toColumnName` | `string` | yes | |
| `boardName` | `string` | yes | Destination board name. |
| `(*)boardId` | `string (uuid)` | no | Deprecated. Destination board ID. |
| `fromBoardName` | `string \| null` | yes | Source board name for cross-board moves, null for same-board moves. |
| `fromBoardId` | `string (uuid) \| null` | yes | Source board ID for cross-board moves, null for same-board moves. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | --------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"task"` | no | |
| `resource` | `object` | no | The moved task. |
# boardTaskRelationAdd (/docs/reference/websocket/notifications/boardtaskrelationadd)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`boardTaskRelationAdd`
.
Fired when a resource (asset, folder, message, chat, ...) is related to a task. Also used for push notifications.
Payload for the boardTaskRelationAdd event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------------------------- |
| `(*)projectId` | `string (uuid)` | no | Deprecated. |
| `(*)taskId` | `string (uuid)` | no | Deprecated. |
| `resourceId` | `string (uuid)` | yes | ID of the related resource. |
| `resourceType` | `string` | yes | Type of the related resource. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `create` | `object[]` | no | |
**`create`** (items)
| Property | Type | Required | Description |
| -------------- | ---------------- | -------- | ---------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"taskRelation"` | no | |
| `resource` | `object` | no | The created relation record. |
# boardTaskRelationRemove (/docs/reference/websocket/notifications/boardtaskrelationremove)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`boardTaskRelationRemove`
.
Fired when a task relation is removed (explicitly, or cascaded when a board visibility change removes access).
Payload for the boardTaskRelationRemove event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| -------------- | ----------------------- | -------- | --------------------------------------------------------- |
| `(*)projectId` | `string (uuid)` | no | Deprecated. |
| `(*)taskId` | `string (uuid) \| null` | no | Deprecated. Null for cascaded removals. |
| `resourceId` | `string (uuid) \| null` | yes | ID of the related resource. Null for cascaded removals. |
| `resourceType` | `string \| null` | yes | Type of the related resource. Null for cascaded removals. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `delete` | `object[]` | no | |
**`delete`** (items)
| Property | Type | Required | Description |
| -------------- | ---------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"taskRelation"` | no | |
# boardTaskRemove (/docs/reference/websocket/notifications/boardtaskremove)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`boardTaskRemove`
.
Fired when a task is removed from a board (the task itself is kept).
Payload for the boardTaskRemove event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `(*)projectId` | `string (uuid)` | no | Deprecated. |
| `(*)boardId` | `string (uuid)` | no | Deprecated. |
| `boardName` | `string` | yes | |
| `(*)taskId` | `string (uuid)` | no | Deprecated. |
| `taskSubject` | `string` | yes | |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | -------------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"task"` | no | |
| `resource` | `object` | no | The task after removal from the board. |
# boardTaskUnlink (/docs/reference/websocket/notifications/boardtaskunlink)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`boardTaskUnlink`
.
Fired when a task link is removed.
Payload for the boardTaskUnlink event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ----------------- | --------------- | -------- | ----------- |
| `(*)projectId` | `string (uuid)` | no | Deprecated. |
| `(*)taskId` | `string (uuid)` | no | Deprecated. |
| `(*)linkedTaskId` | `string (uuid)` | no | Deprecated. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `delete` | `object[]` | no | |
**`delete`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ------------------------------------------------- |
| `resourceId` | `string (uuid)` | no | Note: the source task ID, not the link record ID. |
| `resourceType` | `"taskLink"` | no | |
# boardTaskUpdate (/docs/reference/websocket/notifications/boardtaskupdate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`boardTaskUpdate`
.
Fired when a task's details are updated (subject, description, priority, dates, etc.).
Payload for the boardTaskUpdate event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `(*)projectId` | `string (uuid)` | no | Deprecated. |
| `(*)boardId` | `string (uuid)` | no | Deprecated. |
| `boardName` | `string` | yes | |
| `(*)taskId` | `string (uuid)` | no | Deprecated. |
| `taskSubject` | `string` | yes | |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"task"` | no | |
| `resource` | `object` | no | The updated task. |
# boardUnfollow (/docs/reference/websocket/notifications/boardunfollow)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`boardUnfollow`
.
Fired when a user unfollows a board.
Payload for the boardUnfollow event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | --------------------------- |
| `(*)projectId` | `string (uuid)` | no | Deprecated. |
| `(*)boardId` | `string (uuid)` | no | Deprecated. Use resourceId. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | --------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"board"` | no | |
| `resource` | `object` | no | The board with updated followers. |
# boardUpdate (/docs/reference/websocket/notifications/boardupdate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`boardUpdate`
.
Fired when a kanban board is updated (name, visibility, options).
Payload for the boardUpdate event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | --------------------------------------------- |
| `(*)projectId` | `string (uuid)` | no | Deprecated. |
| `boardName` | `string` | yes | |
| `(*)board` | `object` | no | Deprecated. Use resource from changes.update. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ------------------ |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"board"` | no | |
| `resource` | `object` | no | The updated board. |
# botCreate (/docs/reference/websocket/notifications/botcreate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`botCreate`
.
Fired when a bot user is created in a workspace. Published on workspace/\{workspaceId}.
Payload for the botCreate event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ---------------- | --------------- | -------- | ------------------------------------------------------------------ |
| `(*)workspaceId` | `string (uuid)` | no | Deprecated. Use resourceId. |
| `(*)bot` | `object` | no | Deprecated. The bot user object. Use resource from changes.create. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `create` | `object[]` | no | |
**`create`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | --------------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"user"` | no | |
| `resource` | `object` | no | The created bot user (accountType bot). |
# chatCreateMessage (/docs/reference/websocket/notifications/chatcreatemessage)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`chatCreateMessage`
.
Fired when a new message is created in a chat (user messages, public/guest messages, AI assistant replies and system messages).
Fired when a new message is created in a chat. Published on chat/\{chatId}, the topic resource channel(s) and user/\{userId} for member chats.
Payload for the chatCreateMessage event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | changes.create holds the message and changes.update the parent chat (lastMessage etc.). When the message creates the chat itself (first message in a new topic chat) the chat entry appears in changes.create instead of changes.update. |
**`tokens`**
| Property | Type | Required | Description |
| ----------------- | --------------- | -------- | ---------------------------------------------------------------------------------------------- |
| `(*)requesterId` | `string (uuid)` | no | Deprecated. Use initiatorId. |
| `(*)requester` | `object` | no | Deprecated. Use initiator. |
| `(*)chatId` | `string (uuid)` | no | Deprecated. |
| `(*)messageId` | `string (uuid)` | no | Deprecated. |
| `(*)resourceType` | `string` | no | Deprecated. Topic/scope resource type of the chat (e.g. 'project', 'asset', 'task', 'public'). |
| `(*)resourceId` | `string (uuid)` | no | Deprecated. |
| `(*)visibility` | `string[]` | no | Deprecated. |
| `(*)mentions` | `object[]` | no | Deprecated. Mentions contained in the message. |
| `(*)message` | `object` | no | Deprecated. The created message object. Use resource from changes.create. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `create` | `object[]` | no | |
| `update` | `object[]` | no | |
**`create`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | -------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"chatMessage"` | no | |
| `resource` | `object` | no | The created message. |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | -------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"chat" \| "chatMember" \| "chatSubmission"` | no | |
| `resource` | `object` | no | The chat the message belongs to (resourceType reflects the chat model: 'chat' for topic chats, 'chatMember' for member chats, 'chatSubmission' for submission chats). |
# chatDelete (/docs/reference/websocket/notifications/chatdelete)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`chatDelete`
.
Fired when a topic-based chat is deleted.
Payload for the topic chat delete event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ---------------- | --------------- | -------- | ----------- |
| `(*)requesterId` | `string (uuid)` | no | |
| `(*)requester` | `object` | no | |
| `(*)chatId` | `string (uuid)` | no | |
| `(*)topicType` | `string` | no | |
| `(*)topicId` | `string (uuid)` | no | |
| `(*)visibility` | `string[]` | no | |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `delete` | `object[]` | no | |
**`delete`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
# chatDeleteMessage (/docs/reference/websocket/notifications/chatdeletemessage)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`chatDeleteMessage`
.
Fired when a chat message is deleted.
Payload for the chatDeleteMessage event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ----------------- | ----------------------- | -------- | ---------------------------------------------------------- |
| `(*)requesterId` | `string (uuid)` | no | Deprecated. Use initiatorId. |
| `(*)requester` | `object` | no | Deprecated. Use initiator. |
| `(*)chatId` | `string (uuid)` | no | Deprecated. |
| `(*)messageId` | `string (uuid)` | no | Deprecated. |
| `(*)resourceType` | `string` | no | Deprecated. |
| `(*)resourceId` | `string (uuid)` | no | Deprecated. |
| `(*)visibility` | `string[]` | no | Deprecated. |
| `(*)replyToId` | `string (uuid) \| null` | no | Deprecated. ID of the message this was a reply to, if any. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
| `delete` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | -------------------------------------------- | -------- | --------------------------------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"chat" \| "chatMember" \| "chatSubmission"` | no | |
| `resource` | `object` | no | The parent chat after the deletion (message counts etc.). |
**`delete`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"chatMessage"` | no | |
# chatFollow (/docs/reference/websocket/notifications/chatfollow)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`chatFollow`
.
Fired when a user follows a chat. Published on the chat channels.
Payload for the chatFollow event.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | Always an empty object for this event. |
| `changes` | `object` | no | |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | -------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"chat"` | no | |
| `resource` | `object` | no | The chat with updated followers. |
# chatHighlightMessage (/docs/reference/websocket/notifications/chathighlightmessage)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`chatHighlightMessage`
.
Fired when a message in a project-scoped chat is highlighted. Published on project/\{projectId}/\{visibility} of the chat.
Payload for the chatHighlightMessage event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ---------------- | --------------- | -------- | ---------------------------- |
| `(*)requesterId` | `string (uuid)` | no | Deprecated. Use initiatorId. |
| `(*)requester` | `object` | no | Deprecated. Use initiator. |
| `(*)chatId` | `string (uuid)` | no | Deprecated. |
| `(*)messageId` | `string (uuid)` | no | Deprecated. |
| `(*)projectId` | `string (uuid)` | no | Deprecated. |
**`changes`**
| Property | Type | Required | Description |
| -------- | -------------------- | -------- | ----------- |
| `update` | `object \| object[]` | no | |
**`update`** (items)
One of 2 variants:
**Variant 1**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | -------------------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"chat"` | no | |
| `resource` | `object` | no | The chat containing the highlighted message. |
**Variant 2**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ------------------------ |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"chatMessage"` | no | |
| `resource` | `object` | no | The highlighted message. |
# chatMemberArchive (/docs/reference/websocket/notifications/chatmemberarchive)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`chatMemberArchive`
.
Fired when the requesting user archives a member chat for themselves. Published on user/\{userId} only.
Payload for the chatMemberArchive event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ----------- | --------------- | -------- | --------------------------- |
| `(*)chatId` | `string (uuid)` | no | Deprecated. Use resourceId. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ------------------------------------------------------ |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"chatMember"` | no | |
| `resource` | `object` | no | The member chat (with the archive state for the user). |
# chatMemberChatCreate (/docs/reference/websocket/notifications/chatmemberchatcreate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`chatMemberChatCreate`
.
Fired when a new member-based chat (DM/group) is created.
Fired when a new member-based chat (direct message/group) is created.
Payload for the member chat create event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ---------------- | --------------- | -------- | ----------- |
| `(*)requesterId` | `string (uuid)` | no | |
| `(*)requester` | `object` | no | |
| `(*)chatId` | `string (uuid)` | no | |
| `(*)scopeType` | `string` | no | |
| `(*)scopeId` | `string (uuid)` | no | |
| `(*)members` | `object[]` | no | |
| `(*)subject` | `string` | no | |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `create` | `object[]` | no | |
**`create`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
| `resource` | `object` | no | |
# chatMemberDelete (/docs/reference/websocket/notifications/chatmemberdelete)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`chatMemberDelete`
.
Fired when a member-based chat is deleted.
Payload for the member chat delete event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ---------------- | --------------- | -------- | ----------- |
| `(*)requesterId` | `string (uuid)` | no | |
| `(*)requester` | `object` | no | |
| `(*)chatId` | `string (uuid)` | no | |
| `(*)scopeType` | `string` | no | |
| `(*)scopeId` | `string (uuid)` | no | |
| `(*)members` | `object[]` | no | |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `delete` | `object[]` | no | |
**`delete`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
# chatMemberUnarchive (/docs/reference/websocket/notifications/chatmemberunarchive)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`chatMemberUnarchive`
.
Fired when the requesting user un-archives a member chat for themselves. Published on user/\{userId} only.
Payload for the chatMemberUnarchive event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ----------- | --------------- | -------- | --------------------------- |
| `(*)chatId` | `string (uuid)` | no | Deprecated. Use resourceId. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ---------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"chatMember"` | no | |
| `resource` | `object` | no | The member chat. |
# chatMemberUpdate (/docs/reference/websocket/notifications/chatmemberupdate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`chatMemberUpdate`
.
Fired when a member chat's subject or colour is updated.
Fired when a member-based chat is updated (subject and/or color). Published on chat/\{chatId} and user/\{memberId} for every member.
Payload for the chatMemberUpdate event.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| -------- | -------- | -------- | ------------------------------------------ |
| `update` | `object` | yes | The submitted update: \{ subject, color }. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ---------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"chatMember"` | no | |
| `resource` | `object` | no | The updated member chat. |
| `oldResource` | `object` | no | The member chat before the update. |
# chatMention (/docs/reference/websocket/notifications/chatmention)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`chatMention`
.
Fired when user(s) are mentioned in a created or revised chat message. Published only on the mentioned users' channels (user/\{userId}).
Fired specifically when a user is mentioned in a chat message. Tokens are the same set as chatCreateMessage / chatReviseMessage.
Payload for the chatMention event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ----------------- | --------------- | -------- | --------------------------------------------------------------------------------- |
| `(*)requesterId` | `string (uuid)` | no | Deprecated. Use initiatorId. |
| `(*)requester` | `object` | no | Deprecated. Use initiator. |
| `(*)chatId` | `string (uuid)` | no | Deprecated. |
| `(*)messageId` | `string (uuid)` | no | Deprecated. |
| `mentions` | `object[]` | yes | Mentions contained in the message. |
| `(*)message` | `object` | no | Deprecated. The message containing the mention. Use resource from changes.update. |
| `(*)resourceType` | `string` | no | Deprecated. Topic/scope resource type of the chat. |
| `(*)resourceId` | `string (uuid)` | no | Deprecated. |
| `(*)visibility` | `string[]` | no | Deprecated. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"chatMessage"` | no | |
| `resource` | `object` | no | The message containing the mention. |
# chatRefreshMessage (/docs/reference/websocket/notifications/chatrefreshmessage)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`chatRefreshMessage`
.
Provides an updated representation of a system message (e.g. after the assets it references finish processing).
Fired by the system to provide an updated representation of a message. initiatorType is always system.
Payload for the chatRefreshMessage event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | --------------------------------------------------------------------------- |
| `(*)chatId` | `string (uuid)` | no | Deprecated. |
| `(*)messageId` | `string (uuid)` | no | Deprecated. |
| `(*)message` | `object` | no | Deprecated. The refreshed message object. Use resource from changes.update. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ---------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"chatMessage"` | no | |
| `resource` | `object` | no | The refreshed message. |
# chatRemoveAttachment (/docs/reference/websocket/notifications/chatremoveattachment)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`chatRemoveAttachment`
.
Fired when an attachment is removed from a chat message.
Payload for the chat remove attachment event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ----------------- | --------------- | -------- | --------------------------------- |
| `(*)requesterId` | `string (uuid)` | no | |
| `(*)requester` | `object` | no | |
| `(*)chatId` | `string (uuid)` | no | |
| `(*)messageId` | `string (uuid)` | no | |
| `(*)assetId` | `string (uuid)` | no | ID of the asset that was removed. |
| `(*)resourceType` | `string` | no | |
| `(*)resourceId` | `string (uuid)` | no | |
| `(*)visibility` | `string[]` | no | |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
| `resource` | `object` | no | |
# chatReviseMessage (/docs/reference/websocket/notifications/chatrevisemessage)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`chatReviseMessage`
.
Fired when a chat message is revised (edited).
Payload for the chatReviseMessage event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ----------------- | --------------- | -------- | ------------------------------------------------------------------------- |
| `(*)requesterId` | `string (uuid)` | no | Deprecated. Use initiatorId. |
| `(*)requester` | `object` | no | Deprecated. Use initiator. |
| `(*)chatId` | `string (uuid)` | no | Deprecated. |
| `(*)messageId` | `string (uuid)` | no | Deprecated. |
| `(*)resourceType` | `string` | no | Deprecated. |
| `(*)resourceId` | `string (uuid)` | no | Deprecated. |
| `(*)visibility` | `string[]` | no | Deprecated. |
| `(*)mentions` | `object[]` | no | Deprecated. |
| `(*)message` | `object` | no | Deprecated. The revised message object. Use resource from changes.update. |
**`changes`**
| Property | Type | Required | Description |
| -------- | -------------------- | -------- | ----------- |
| `update` | `object \| object[]` | no | |
**`update`** (items)
One of 2 variants:
**Variant 1**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | -------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"chatMessage"` | no | |
| `resource` | `object` | no | The revised message. |
| `oldResource` | `object` | no | The message before the revision. |
**Variant 2**
| Property | Type | Required | Description |
| -------------- | -------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"chat" \| "chatMember" \| "chatSubmission"` | no | |
| `resource` | `object` | no | The chat the message belongs to (resourceType reflects the chat model: 'chat' for topic chats, 'chatMember' for member chats, 'chatSubmission' for submission chats). |
# chatTopicChatCreate (/docs/reference/websocket/notifications/chattopicchatcreate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`chatTopicChatCreate`
.
Fired when a new topic-based chat is created.
Fired when a new topic-based chat is created (linked to an asset or project).
Payload for the topic chat create event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ---------------- | --------------- | -------- | ----------- |
| `(*)requesterId` | `string (uuid)` | no | |
| `(*)requester` | `object` | no | |
| `(*)chatId` | `string (uuid)` | no | |
| `(*)topicType` | `string` | no | |
| `(*)topicId` | `string (uuid)` | no | |
| `(*)visibility` | `string[]` | no | |
| `(*)subject` | `string` | no | |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `create` | `object[]` | no | |
**`create`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
| `resource` | `object` | no | |
# chatUnfollow (/docs/reference/websocket/notifications/chatunfollow)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`chatUnfollow`
.
Fired when a user unfollows a chat. Published on the chat channels.
Payload for the chatUnfollow event.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | Always an empty object for this event. |
| `changes` | `object` | no | |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | -------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"chat"` | no | |
| `resource` | `object` | no | The chat with updated followers. |
# chatUpdateSubject (/docs/reference/websocket/notifications/chatupdatesubject)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`chatUpdateSubject`
.
Fired when the subject of a topic-based chat is updated.
Payload for the topic chat subject update event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ---------------- | --------------- | -------- | ----------- |
| `(*)requesterId` | `string (uuid)` | no | |
| `(*)requester` | `object` | no | |
| `(*)chatId` | `string (uuid)` | no | |
| `(*)topicType` | `string` | no | |
| `(*)topicId` | `string (uuid)` | no | |
| `(*)visibility` | `string[]` | no | |
| `oldSubject` | `string` | yes | |
| `newSubject` | `string` | yes | |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
| `resource` | `object` | no | |
| `oldResource` | `object` | no | The chat before the subject change. |
# convoComplete (/docs/reference/websocket/notifications/convocomplete)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`convoComplete`
.
Fired when a convo is completed (ended by a user or when the last participant leaves).
Payload for the convoComplete event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ------------------ | --------------- | -------- | ----------- |
| `(*)convoId` | `string (uuid)` | no | Deprecated. |
| `(*)chatId` | `string (uuid)` | no | Deprecated. |
| `(*)userId` | `string (uuid)` | no | Deprecated. |
| `userName` | `string` | yes | |
| `durationMinutes` | `number` | yes | |
| `participantNames` | `string[]` | yes | |
**`changes`**
| Property | Type | Required | Description |
| -------- | ------------------------------ | -------- | ----------- |
| `update` | `object \| object \| object[]` | no | |
**`update`** (items)
One of 3 variants:
**Variant 1**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"convo"` | no | |
| `resource` | `object` | no | The convo. |
**Variant 2**
| Property | Type | Required | Description |
| -------------- | -------------------------------------------- | -------- | -------------------------------------------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"chat" \| "chatMember" \| "chatSubmission"` | no | |
| `resource` | `object` | no | The chat the convo belongs to (resourceType is the chat model name). |
**Variant 3**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------------------------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"chatMessage"` | no | |
| `resource` | `object` | no | The system message posted to the chat for this event. |
# convoDelete (/docs/reference/websocket/notifications/convodelete)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`convoDelete`
.
Fired when a convo is deleted.
Payload for the convoDelete event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ------------ | -------------------------------------------- | -------- | ----------- |
| `(*)convoId` | `string (uuid)` | no | Deprecated. |
| `(*)chatId` | `string (uuid)` | no | Deprecated. |
| `chatType` | `"chat" \| "chatMember" \| "chatSubmission"` | yes | |
| `(*)userId` | `string (uuid)` | no | Deprecated. |
| `userName` | `string` | yes | |
**`changes`**
| Property | Type | Required | Description |
| -------- | -------------------- | -------- | ----------- |
| `update` | `object \| object[]` | no | |
| `delete` | `object[]` | no | |
**`update`** (items)
One of 2 variants:
**Variant 1**
| Property | Type | Required | Description |
| -------------- | -------------------------------------------- | -------- | ------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"chat" \| "chatMember" \| "chatSubmission"` | no | |
| `resource` | `object` | no | The chat the convo belonged to. |
**Variant 2**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | -------------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"chatMessage"` | no | |
| `resource` | `object` | no | The system message posted to the chat. |
**`delete`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"convo"` | no | |
# convoHandover (/docs/reference/websocket/notifications/convohandover)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`convoHandover`
.
Fired on user/\{userId} when the user joins a convo from a second device, so the previous device can leave the call.
Payload for the convoHandover event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | Not populated for this event (the notification is created without a changes object). |
**`tokens`**
| Property | Type | Required | Description |
| ------------ | --------------- | -------- | ---------------------------- |
| `(*)convoId` | `string (uuid)` | no | Deprecated. Use resourceId. |
| `(*)userId` | `string (uuid)` | no | Deprecated. Use initiatorId. |
# convoJoin (/docs/reference/websocket/notifications/convojoin)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`convoJoin`
.
Fired when a user joins a convo.
Payload for the convoJoin event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ------------ | --------------- | -------- | ----------- |
| `(*)convoId` | `string (uuid)` | no | Deprecated. |
| `(*)userId` | `string (uuid)` | no | Deprecated. |
| `userName` | `string` | yes | |
**`changes`**
| Property | Type | Required | Description |
| -------- | ------------------------------ | -------- | ----------- |
| `update` | `object \| object \| object[]` | no | |
**`update`** (items)
One of 3 variants:
**Variant 1**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"convo"` | no | |
| `resource` | `object` | no | The convo. |
**Variant 2**
| Property | Type | Required | Description |
| -------------- | -------------------------------------------- | -------- | -------------------------------------------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"chat" \| "chatMember" \| "chatSubmission"` | no | |
| `resource` | `object` | no | The chat the convo belongs to (resourceType is the chat model name). |
**Variant 3**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------------------------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"chatMessage"` | no | |
| `resource` | `object` | no | The system message posted to the chat for this event. |
# convoLeave (/docs/reference/websocket/notifications/convoleave)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`convoLeave`
.
Fired when a user leaves a convo.
Payload for the convoLeave event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ------------ | --------------- | -------- | ----------- |
| `(*)convoId` | `string (uuid)` | no | Deprecated. |
| `(*)userId` | `string (uuid)` | no | Deprecated. |
| `userName` | `string` | yes | |
**`changes`**
| Property | Type | Required | Description |
| -------- | ------------------------------ | -------- | ----------- |
| `update` | `object \| object \| object[]` | no | |
**`update`** (items)
One of 3 variants:
**Variant 1**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"convo"` | no | |
| `resource` | `object` | no | The convo. |
**Variant 2**
| Property | Type | Required | Description |
| -------------- | -------------------------------------------- | -------- | -------------------------------------------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"chat" \| "chatMember" \| "chatSubmission"` | no | |
| `resource` | `object` | no | The chat the convo belongs to (resourceType is the chat model name). |
**Variant 3**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------------------------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"chatMessage"` | no | |
| `resource` | `object` | no | The system message posted to the chat for this event. |
# convoParticipantJoined (/docs/reference/websocket/notifications/convoparticipantjoined)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`convoParticipantJoined`
.
Fired (from the call-provider webhook) when a participant actually joins the call room.
Payload for the convoParticipantJoined event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ----------- | --------------- | -------- | ----------- |
| `userName` | `string` | yes | |
| `convoType` | `string` | yes | |
| `(*)chatId` | `string (uuid)` | no | Deprecated. |
**`changes`**
| Property | Type | Required | Description |
| -------- | -------------------- | -------- | ----------- |
| `update` | `object \| object[]` | no | |
**`update`** (items)
One of 2 variants:
**Variant 1**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ------------------------------------ |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"convo"` | no | |
| `resource` | `object` | no | The convo with updated participants. |
**Variant 2**
| Property | Type | Required | Description |
| -------------- | -------------------------------------------- | -------- | ------------------------------ |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"chat" \| "chatMember" \| "chatSubmission"` | no | |
| `resource` | `object` | no | The chat the convo belongs to. |
# convoParticipantLeft (/docs/reference/websocket/notifications/convoparticipantleft)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`convoParticipantLeft`
.
Fired (from the call-provider webhook) when a participant leaves the call room.
Payload for the convoParticipantLeft event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ----------- | --------------- | -------- | ----------- |
| `userName` | `string` | yes | |
| `convoType` | `string` | yes | |
| `(*)chatId` | `string (uuid)` | no | Deprecated. |
**`changes`**
| Property | Type | Required | Description |
| -------- | -------------------- | -------- | ----------- |
| `update` | `object \| object[]` | no | |
**`update`** (items)
One of 2 variants:
**Variant 1**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ------------------------------------ |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"convo"` | no | |
| `resource` | `object` | no | The convo with updated participants. |
**Variant 2**
| Property | Type | Required | Description |
| -------------- | -------------------------------------------- | -------- | ------------------------------ |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"chat" \| "chatMember" \| "chatSubmission"` | no | |
| `resource` | `object` | no | The chat the convo belongs to. |
# convoStart (/docs/reference/websocket/notifications/convostart)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`convoStart`
.
Fired when a convo (call) is started in a chat. Published on the chat channels and user/\{userId} of the starter.
Payload for the convoStart event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ------------ | -------------------------------------------- | -------- | --------------------- |
| `(*)convoId` | `string (uuid)` | no | Deprecated. |
| `(*)chatId` | `string (uuid)` | no | Deprecated. |
| `chatType` | `"chat" \| "chatMember" \| "chatSubmission"` | yes | |
| `convoType` | `string` | yes | |
| `(*)userId` | `string (uuid)` | no | Deprecated. |
| `userName` | `string` | yes | |
| `roomUrl` | `string` | yes | URL of the call room. |
**`changes`**
| Property | Type | Required | Description |
| -------- | -------------------- | -------- | ----------- |
| `create` | `object \| object[]` | no | |
| `update` | `object[]` | no | |
**`create`** (items)
One of 2 variants:
**Variant 1**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ------------------ |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"convo"` | no | |
| `resource` | `object` | no | The started convo. |
**Variant 2**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | -------------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"chatMessage"` | no | |
| `resource` | `object` | no | The system message posted to the chat. |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | -------------------------------------------- | -------- | ------------------------------ |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"chat" \| "chatMember" \| "chatSubmission"` | no | |
| `resource` | `object` | no | The chat the convo belongs to. |
# convoUpdate (/docs/reference/websocket/notifications/convoupdate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`convoUpdate`
.
Fired when a convo is updated (subject / notes).
Payload for the convoUpdate event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ------------ | -------------------------------------------- | -------- | ----------- |
| `(*)convoId` | `string (uuid)` | no | Deprecated. |
| `(*)chatId` | `string (uuid)` | no | Deprecated. |
| `chatType` | `"chat" \| "chatMember" \| "chatSubmission"` | yes | |
| `(*)userId` | `string (uuid)` | no | Deprecated. |
| `userName` | `string` | yes | |
**`changes`**
| Property | Type | Required | Description |
| -------- | ------------------------------ | -------- | ----------- |
| `update` | `object \| object \| object[]` | no | |
**`update`** (items)
One of 3 variants:
**Variant 1**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"convo"` | no | |
| `resource` | `object` | no | The convo. |
**Variant 2**
| Property | Type | Required | Description |
| -------------- | -------------------------------------------- | -------- | -------------------------------------------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"chat" \| "chatMember" \| "chatSubmission"` | no | |
| `resource` | `object` | no | The chat the convo belongs to (resourceType is the chat model name). |
**Variant 3**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------------------------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"chatMessage"` | no | |
| `resource` | `object` | no | The system message posted to the chat for this event. |
# fileSystemCopy (/docs/reference/websocket/notifications/filesystemcopy)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`fileSystemCopy`
.
Fired when items are copied to a new file system path.
Payload for the fileSystemCopy event.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | Not populated for this event (the notification is created without a changes object). |
**`tokens`**
| Property | Type | Required | Description |
| ----------------- | ---------- | -------- | ----------------------------------------------------- |
| `itemsCount` | `integer` | yes | Number of items copied. |
| `itemPaths` | `string[]` | yes | Original file system paths of the copied items. |
| `destinationPath` | `string` | yes | Destination file system path where items were copied. |
# fileSystemCreate (/docs/reference/websocket/notifications/filesystemcreate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`fileSystemCreate`
.
Fired when items are created at a file system path (folder created, single uploaded asset activated, or items copied into a public release).
Signals clients to refresh the destination path. The changes object is usually absent; it is populated only for the single-asset activation (create asset) and public release (update public) cases.
Payload for the fileSystemCreate event.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | Optional. Present only in some code paths (see description). |
**`tokens`**
| Property | Type | Required | Description |
| ----------------- | --------- | -------- | -------------------------------------------------------------------------------------------- |
| `itemsCount` | `integer` | yes | Number of items created. |
| `destinationPath` | `string` | yes | File system path where items were created (e.g. 'project/\{projectId}/creator/\{basePath}'). |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `create` | `object[]` | no | |
| `update` | `object[]` | no | |
**`create`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | --------------------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"asset"` | no | |
| `resource` | `object` | no | The activated asset (upload completion path). |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ---------------------------------------------------------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"public"` | no | |
| `resource` | `object` | no | The public release record with recalculated inventory (add-items-to-release path). |
# fileSystemDelete (/docs/reference/websocket/notifications/filesystemdelete)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`fileSystemDelete`
.
Fired when items are deleted from file system paths.
Payload for the fileSystemDelete event.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | Not populated for this event (the notification is created without a changes object). |
**`tokens`**
| Property | Type | Required | Description |
| ------------ | ---------- | -------- | --------------------------------------- |
| `itemsCount` | `integer` | yes | Number of items deleted. |
| `itemPaths` | `string[]` | yes | File system paths of the deleted items. |
# fileSystemMove (/docs/reference/websocket/notifications/filesystemmove)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`fileSystemMove`
.
Fired when items are moved to a new file system path.
Payload for the fileSystemMove event.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | Not populated for this event (the notification is created without a changes object). |
**`tokens`**
| Property | Type | Required | Description |
| ----------------- | ---------- | -------- | ---------------------------------------------------- |
| `itemsCount` | `integer` | yes | Number of items moved. |
| `itemPaths` | `string[]` | yes | Original file system paths of the moved items. |
| `destinationPath` | `string` | yes | Destination file system path where items were moved. |
# fileSystemPublish (/docs/reference/websocket/notifications/filesystempublish)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`fileSystemPublish`
.
Fired when multiple items are published at a file system path.
Fired when multiple items (assets/folders) are published at a file system path.
Payload for the items published event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| -------------------- | --------- | -------- | -------------------------------------------- |
| `(*)itemsCount` | `integer` | no | Number of items published. |
| `(*)destinationPath` | `string` | no | File system path where items were published. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"asset" \| "folder"` | no | |
| `resource` | `object` | no | |
# fileSystemUnpublish (/docs/reference/websocket/notifications/filesystemunpublish)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`fileSystemUnpublish`
.
Fired when multiple items are unpublished from file system paths.
Fired when multiple items (assets/folders) are unpublished from file system paths.
Payload for the items unpublished event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| --------------- | ---------- | -------- | ------------------------------------------- |
| `(*)itemsCount` | `integer` | no | Number of items unpublished. |
| `(*)itemPaths` | `string[]` | no | File system paths of the unpublished items. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"asset" \| "folder"` | no | |
| `resource` | `object` | no | |
# folderCreate (/docs/reference/websocket/notifications/foldercreate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`folderCreate`
.
CURRENTLY UNUSED (the event type is still registered but nothing emits it). Fired when a new folder is created.
Fired when a new folder is created.
Payload for the folder create event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ---------------- | --------------- | -------- | -------------------------------- |
| `(*)requesterId` | `string (uuid)` | no | |
| `(*)requester` | `object` | no | |
| `(*)folder` | `object` | no | The newly created folder object. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `create` | `object[]` | no | |
**`create`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
| `resource` | `object` | no | |
# folderDelete (/docs/reference/websocket/notifications/folderdelete)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`folderDelete`
.
CURRENTLY UNUSED (the event type is still registered but nothing emits it). Fired when a folder is deleted.
Fired when a folder is deleted.
Payload for the folder delete event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ---------------- | --------------- | -------- | ----------------------------------- |
| `(*)requesterId` | `string (uuid)` | no | |
| `(*)requester` | `object` | no | |
| `(*)folder` | `object` | no | The folder object that was deleted. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `delete` | `object[]` | no | |
**`delete`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
# folderPublish (/docs/reference/websocket/notifications/folderpublish)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`folderPublish`
.
Fired when an individual folder is published.
Payload for the folder publish event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| --------- | -------- | -------- | -------------------------------------- |
| `(*)name` | `string` | no | Name of the folder that was published. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
| `resource` | `object` | no | |
# folderTag (/docs/reference/websocket/notifications/foldertag)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`folderTag`
.
Fired when a tag is added to a folder.
Payload for the folderTag event.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | Not populated for this event (the notification is created without a changes object). |
**`tokens`**
| Property | Type | Required | Description |
| --------- | -------- | -------- | ------------------------------- |
| `name` | `string` | yes | Folder name. |
| `tagName` | `string` | yes | Name of the tag that was added. |
# folderUntag (/docs/reference/websocket/notifications/folderuntag)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`folderUntag`
.
Fired when a tag is removed from a folder.
Payload for the folderUntag event.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | Not populated for this event (the notification is created without a changes object). |
**`tokens`**
| Property | Type | Required | Description |
| --------- | -------- | -------- | --------------------------------- |
| `name` | `string` | yes | Folder name. |
| `tagName` | `string` | yes | Name of the tag that was removed. |
# folderUpdate (/docs/reference/websocket/notifications/folderupdate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`folderUpdate`
.
CURRENTLY UNUSED (the event type is still registered but nothing emits it). Fired when a folder is updated.
Fired when a folder is updated (name, color, etc.).
Payload for the folder update event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ------------------- | --------------- | -------- | ------------------------------------ |
| `(*)requesterId` | `string (uuid)` | no | |
| `(*)requester` | `object` | no | |
| `(*)originalFolder` | `object` | no | The folder object before the update. |
| `(*)updatedFolder` | `object` | no | The folder object after the update. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
| `resource` | `object` | no | |
# iconUpdate (/docs/reference/websocket/notifications/iconupdate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`iconUpdate`
.
Generic event for when a workspace or project icon asset becomes active. Includes the updated owner resource in changes.
Fired by the system when an icon asset's upload completes. changes.update contains the asset and the owning workspace/project.
Payload for the iconUpdate event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ----------------- | -------------------------- | -------- | ------------------------------------------------------- |
| `(*)resourceType` | `"workspace" \| "project"` | no | Deprecated. |
| `(*)resourceId` | `string (uuid)` | no | Deprecated. |
| `(*)asset` | `object` | no | Deprecated. The asset object representing the new icon. |
**`changes`**
| Property | Type | Required | Description |
| -------- | -------------------- | -------- | ----------- |
| `update` | `object \| object[]` | no | |
**`update`** (items)
One of 2 variants:
**Variant 1**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | --------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"asset"` | no | |
| `resource` | `object` | no | The icon asset. |
**Variant 2**
| Property | Type | Required | Description |
| -------------- | -------------------------- | -------- | ---------------------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"workspace" \| "project"` | no | |
| `resource` | `object` | no | The owning resource with the new icon applied. |
# Notification types (/docs/reference/websocket/notifications)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Each notification arrives as a `notification` socket event whose `type` names one of the entries below. Subscribe to `notification` on a channel and switch on `type`.
| `type` | Summary |
| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`test`](/docs/reference/websocket/notifications/test) | Event used for testing websocket connections. |
| [`notificationUpdate`](/docs/reference/websocket/notifications/notificationupdate) | Indicates that a previously delivered, grouped notification has been updated (assetGroupUploadComplete or projectGroupItemPublish). |
| [`workspaceCreate`](/docs/reference/websocket/notifications/workspacecreate) | Fired when a new workspace is created. |
| [`workspaceUpdate`](/docs/reference/websocket/notifications/workspaceupdate) | Fired when a workspace name is changed. |
| [`workspaceDelete`](/docs/reference/websocket/notifications/workspacedelete) | Fired when a workspace is marked for deletion. |
| [`workspaceLogoUpdate`](/docs/reference/websocket/notifications/workspacelogoupdate) | CURRENTLY UNUSED IN FAVOR OF logoUpdate event. Fired when a workspace logo is updated. |
| [`projectCreate`](/docs/reference/websocket/notifications/projectcreate) | Fired when a new project is created. |
| [`projectUpdate`](/docs/reference/websocket/notifications/projectupdate) | Fired when a project name is changed. |
| [`projectDelete`](/docs/reference/websocket/notifications/projectdelete) | Fired when a project is marked for deletion. |
| [`projectLogoUpdate`](/docs/reference/websocket/notifications/projectlogoupdate) | CURRENTLY UNUSED IN FAVOR OF logoUpdate event. Fired when a project logo is updated. Updates the project and returns the new asset object for the logo. Note that the logo will not be 'active' until the actual file is uploaded. So you will need to watch for updates to this asset before replacing the logo locally. |
| [`projectAssetsPublish`](/docs/reference/websocket/notifications/projectassetspublish) | CURRENTLY UNUSED (the event type is still registered but nothing emits it). Fired when assets within a project are published. |
| [`projectAssetsUnpublish`](/docs/reference/websocket/notifications/projectassetsunpublish) | CURRENTLY UNUSED (the event type is still registered but nothing emits it). Fired when assets within a project are unpublished. |
| [`assetNameChange`](/docs/reference/websocket/notifications/assetnamechange) | Fired when an asset's name is changed. |
| [`assetPublish`](/docs/reference/websocket/notifications/assetpublish) | Fired for each individual asset published through the project publish flow (accompanies fileSystemPublish / projectItemsPublish). |
| [`assetUnpublish`](/docs/reference/websocket/notifications/assetunpublish) | Fired for each individual asset unpublished through the project unpublish flow (accompanies fileSystemUnpublish / projectItemsUnpublish). |
| [`assetTag`](/docs/reference/websocket/notifications/assettag) | Fired when a tag is added to an asset. |
| [`assetUntag`](/docs/reference/websocket/notifications/assetuntag) | Fired when a tag is removed from an asset. |
| [`assetDelete`](/docs/reference/websocket/notifications/assetdelete) | Fired when an asset is deleted. |
| [`assetStatusUpdate`](/docs/reference/websocket/notifications/assetstatusupdate) | Fired when an asset's status changes (e.g., during processing). |
| [`assetPostProcessUpdate`](/docs/reference/websocket/notifications/assetpostprocessupdate) | Fired periodically during asset post-processing (e.g., transcoding). |
| [`assetFileUpdate`](/docs/reference/websocket/notifications/assetfileupdate) | Fired when a file associated with an asset is updated or added. |
| [`assetGroupUploadComplete`](/docs/reference/websocket/notifications/assetgroupuploadcomplete) | Fired when an uploaded asset becomes active. Uploads by the same creator into the same resource/visibility within the grouping window (30 min) are accumulated into one notification, which is then re-sent via notificationUpdate. |
| [`chatTopicChatCreate`](/docs/reference/websocket/notifications/chattopicchatcreate) | Fired when a new topic-based chat is created. |
| [`chatMemberChatCreate`](/docs/reference/websocket/notifications/chatmemberchatcreate) | Fired when a new member-based chat (DM/group) is created. |
| [`chatUpdateSubject`](/docs/reference/websocket/notifications/chatupdatesubject) | Fired when the subject of a topic-based chat is updated. |
| [`chatMemberUpdate`](/docs/reference/websocket/notifications/chatmemberupdate) | Fired when a member chat's subject or colour is updated. |
| [`chatDelete`](/docs/reference/websocket/notifications/chatdelete) | Fired when a topic-based chat is deleted. |
| [`chatMemberDelete`](/docs/reference/websocket/notifications/chatmemberdelete) | Fired when a member-based chat is deleted. |
| [`chatCreateMessage`](/docs/reference/websocket/notifications/chatcreatemessage) | Fired when a new message is created in a chat (user messages, public/guest messages, AI assistant replies and system messages). |
| [`chatReviseMessage`](/docs/reference/websocket/notifications/chatrevisemessage) | Fired when a chat message is revised (edited). |
| [`chatRefreshMessage`](/docs/reference/websocket/notifications/chatrefreshmessage) | Provides an updated representation of a system message (e.g. after the assets it references finish processing). |
| [`chatMention`](/docs/reference/websocket/notifications/chatmention) | Fired when user(s) are mentioned in a created or revised chat message. Published only on the mentioned users' channels (user/\{userId}). |
| [`chatDeleteMessage`](/docs/reference/websocket/notifications/chatdeletemessage) | Fired when a chat message is deleted. |
| [`chatRemoveAttachment`](/docs/reference/websocket/notifications/chatremoveattachment) | Fired when an attachment is removed from a chat message. |
| [`folderCreate`](/docs/reference/websocket/notifications/foldercreate) | CURRENTLY UNUSED (the event type is still registered but nothing emits it). Fired when a new folder is created. |
| [`folderUpdate`](/docs/reference/websocket/notifications/folderupdate) | CURRENTLY UNUSED (the event type is still registered but nothing emits it). Fired when a folder is updated. |
| [`folderDelete`](/docs/reference/websocket/notifications/folderdelete) | CURRENTLY UNUSED (the event type is still registered but nothing emits it). Fired when a folder is deleted. |
| [`inviteCreate`](/docs/reference/websocket/notifications/invitecreate) | Fired when a new invitation is created. |
| [`inviteCancel`](/docs/reference/websocket/notifications/invitecancel) | Fired when an invitation is cancelled. |
| [`inviteAccept`](/docs/reference/websocket/notifications/inviteaccept) | Fired when an invitation is accepted. |
| [`membershipDelete`](/docs/reference/websocket/notifications/membershipdelete) | Fired when a user's membership to a resource is deleted (removed). |
| [`membershipAddRole`](/docs/reference/websocket/notifications/membershipaddrole) | Fired when a role is added to a user's membership. |
| [`membershipRemoveRole`](/docs/reference/websocket/notifications/membershipremoverole) | Fired when a role is removed from a user's membership. |
| [`membershipLeaveResource`](/docs/reference/websocket/notifications/membershipleaveresource) | Fired when a user leaves a resource themselves. |
| [`workspaceStorageLimitWarning`](/docs/reference/websocket/notifications/workspacestoragelimitwarning) | Fired when a workspace's storage usage exceeds a threshold. |
| [`userSelfUpdate`](/docs/reference/websocket/notifications/userselfupdate) | Fired when a user updates their own profile information. |
| [`userPublicUpdate`](/docs/reference/websocket/notifications/userpublicupdate) | Fired when a user's public information is updated. |
| [`userDeleted`](/docs/reference/websocket/notifications/userdeleted) | Fired when a user account is deleted. |
| [`userAvatarUpdate`](/docs/reference/websocket/notifications/useravatarupdate) | Fired when a avatars status is set to active. Note that this is an asset event and not a user event so it is fired when the asset's status is set to active not when a user's object is updated. |
| [`logoUpdate`](/docs/reference/websocket/notifications/logoupdate) | Generic event for when a workspace or project logo asset becomes active. Includes the updated owner resource in changes. |
| [`iconUpdate`](/docs/reference/websocket/notifications/iconupdate) | Generic event for when a workspace or project icon asset becomes active. Includes the updated owner resource in changes. |
| [`taskAcknowledged`](/docs/reference/websocket/notifications/taskacknowledged) | Fired when tasks are acknowledged within a project. |
| [`taskStatusUpdate`](/docs/reference/websocket/notifications/taskstatusupdate) | Fired when the status of a task is updated. |
| [`taskCreate`](/docs/reference/websocket/notifications/taskcreate) | Fired when a new task is created within a project. |
| [`notificationUpdateLastSeen`](/docs/reference/websocket/notifications/notificationupdatelastseen) | Fired to update a client's 'last seen' timestamp for notifications. |
| [`submissionCreate`](/docs/reference/websocket/notifications/submissioncreate) | Fired when a submission is released for the first time. Published on project/\{projectId}, project/\{projectId}/creator and project/\{projectId}/reviewer. |
| [`projectItemsPublish`](/docs/reference/websocket/notifications/projectitemspublish) | Fired when multiple items (assets/folders) within a project are published. |
| [`projectItemsUnpublish`](/docs/reference/websocket/notifications/projectitemsunpublish) | Fired when multiple items (assets/folders) within a project are unpublished. |
| [`folderPublish`](/docs/reference/websocket/notifications/folderpublish) | Fired when an individual folder is published. |
| [`folderTag`](/docs/reference/websocket/notifications/foldertag) | Fired when a tag is added to a folder. |
| [`folderUntag`](/docs/reference/websocket/notifications/folderuntag) | Fired when a tag is removed from a folder. |
| [`tagCreate`](/docs/reference/websocket/notifications/tagcreate) | Fired when a new tag is created. |
| [`tagUpdate`](/docs/reference/websocket/notifications/tagupdate) | Fired when a tag is updated. |
| [`tagDelete`](/docs/reference/websocket/notifications/tagdelete) | Fired when a tag is deleted. |
| [`fileSystemCreate`](/docs/reference/websocket/notifications/filesystemcreate) | Fired when items are created at a file system path (folder created, single uploaded asset activated, or items copied into a public release). |
| [`fileSystemMove`](/docs/reference/websocket/notifications/filesystemmove) | Fired when items are moved to a new file system path. |
| [`fileSystemCopy`](/docs/reference/websocket/notifications/filesystemcopy) | Fired when items are copied to a new file system path. |
| [`fileSystemDelete`](/docs/reference/websocket/notifications/filesystemdelete) | Fired when items are deleted from file system paths. |
| [`fileSystemPublish`](/docs/reference/websocket/notifications/filesystempublish) | Fired when multiple items are published at a file system path. |
| [`fileSystemUnpublish`](/docs/reference/websocket/notifications/filesystemunpublish) | Fired when multiple items are unpublished from file system paths. |
| [`subscriptionCreate`](/docs/reference/websocket/notifications/subscriptioncreate) | Fired when a new billing subscription is created for a workspace (Stripe webhook). Published on user/\{ownerId} and \{resourceType}/\{resourceId}. |
| [`subscriptionUpdate`](/docs/reference/websocket/notifications/subscriptionupdate) | Fired when an existing billing subscription is updated, paused, resumed or deleted (Stripe webhook). Published on user/\{ownerId} and \{resourceType}/\{resourceId}. |
| [`projectGroupItemPublish`](/docs/reference/websocket/notifications/projectgroupitempublish) | Grouped notification for items published in a project. Items published by the same user within the grouping window (30 min) are accumulated and re-sent via notificationUpdate. |
| [`publicAssetLinkCreate`](/docs/reference/websocket/notifications/publicassetlinkcreate) | Fired when a public (share) link is created for an asset. Published on project/\{projectId}/creator and workspace/\{workspaceId}. |
| [`uploadPushSummary`](/docs/reference/websocket/notifications/uploadpushsummary) | Delayed push-notification summary of assets uploaded to a project by one user. Primarily used to send a push notification after scheduledSendAt, but also broadcast on the project visibility channels when created. |
| [`publishPushSummary`](/docs/reference/websocket/notifications/publishpushsummary) | Push-notification summary of items published to reviewers. Used to send a push notification; broadcast on project/\{projectId}/reviewer. |
| [`submissionPushSummary`](/docs/reference/websocket/notifications/submissionpushsummary) | Push-notification summary for a newly created submission. Used to send a push notification; broadcast on project/\{projectId}. |
| [`memberJoinPush`](/docs/reference/websocket/notifications/memberjoinpush) | Push-notification record created when a user joins a workspace or project. Used to send a push notification; broadcast on \{resourceType}/\{resourceId}. |
| [`chatMemberArchive`](/docs/reference/websocket/notifications/chatmemberarchive) | Fired when the requesting user archives a member chat for themselves. Published on user/\{userId} only. |
| [`chatMemberUnarchive`](/docs/reference/websocket/notifications/chatmemberunarchive) | Fired when the requesting user un-archives a member chat for themselves. Published on user/\{userId} only. |
| [`chatHighlightMessage`](/docs/reference/websocket/notifications/chathighlightmessage) | Fired when a message in a project-scoped chat is highlighted. Published on project/\{projectId}/\{visibility} of the chat. |
| [`chatFollow`](/docs/reference/websocket/notifications/chatfollow) | Fired when a user follows a chat. Published on the chat channels. |
| [`chatUnfollow`](/docs/reference/websocket/notifications/chatunfollow) | Fired when a user unfollows a chat. Published on the chat channels. |
| [`userEmailVerify`](/docs/reference/websocket/notifications/useremailverify) | Fired when a user's email address is verified. Published on user/\{userId}. |
| [`botCreate`](/docs/reference/websocket/notifications/botcreate) | Fired when a bot user is created in a workspace. Published on workspace/\{workspaceId}. |
| [`webhookTest`](/docs/reference/websocket/notifications/webhooktest) | Synthetic event fired when an admin tests a webhook subscription. Published on workspace/\{workspaceId}; delivered by the webhook dispatcher as webhook.test. |
| [`taskFollow`](/docs/reference/websocket/notifications/taskfollow) | Fired when a user follows a task. |
| [`taskUnfollow`](/docs/reference/websocket/notifications/taskunfollow) | Fired when a user unfollows a task. |
| [`submissionUpdate`](/docs/reference/websocket/notifications/submissionupdate) | Fired when an already-released submission is re-released. Published on project/\{projectId}, project/\{projectId}/creator and project/\{projectId}/reviewer. |
| [`submissionTag`](/docs/reference/websocket/notifications/submissiontag) | Fired when a tag is added to a submission. resourceType is chatSubmission. |
| [`submissionUntag`](/docs/reference/websocket/notifications/submissionuntag) | Fired when a tag is removed from a submission. resourceType is chatSubmission. |
| [`aiChatTopicCreate`](/docs/reference/websocket/notifications/aichattopiccreate) | Fired when an AI chat topic is created. Published on user/\{userId} of the topic owner. |
| [`aiChatTopicUpdate`](/docs/reference/websocket/notifications/aichattopicupdate) | Fired when an AI chat topic is updated (title, archive state, context items, last message preview) or deleted. Published on user/\{userId} of the topic owner. |
| [`aiChatMessageCreate`](/docs/reference/websocket/notifications/aichatmessagecreate) | Fired when the AI assistant posts a message in an AI chat topic. Published on user/\{userId} of the topic owner. |
| [`publicFileSystemCreate`](/docs/reference/websocket/notifications/publicfilesystemcreate) | Fired when a public release (public file system) is created. Published on project/\{projectId}/creator. |
| [`publicFileSystemUpdate`](/docs/reference/websocket/notifications/publicfilesystemupdate) | Fired when a public release is updated (title, description, validity, options). Published on project/\{projectId}/creator. |
| [`publicFileSystemDelete`](/docs/reference/websocket/notifications/publicfilesystemdelete) | Fired when a public release is deleted. Published on project/\{projectId}/creator. |
| [`settingsUpdate`](/docs/reference/websocket/notifications/settingsupdate) | Fired when a user's settings for a resource are updated or reset. Published on user/\{userId} only. |
| [`convoStart`](/docs/reference/websocket/notifications/convostart) | Fired when a convo (call) is started in a chat. Published on the chat channels and user/\{userId} of the starter. |
| [`convoJoin`](/docs/reference/websocket/notifications/convojoin) | Fired when a user joins a convo. |
| [`convoLeave`](/docs/reference/websocket/notifications/convoleave) | Fired when a user leaves a convo. |
| [`convoComplete`](/docs/reference/websocket/notifications/convocomplete) | Fired when a convo is completed (ended by a user or when the last participant leaves). |
| [`convoUpdate`](/docs/reference/websocket/notifications/convoupdate) | Fired when a convo is updated (subject / notes). |
| [`convoDelete`](/docs/reference/websocket/notifications/convodelete) | Fired when a convo is deleted. |
| [`convoParticipantJoined`](/docs/reference/websocket/notifications/convoparticipantjoined) | Fired (from the call-provider webhook) when a participant actually joins the call room. |
| [`convoParticipantLeft`](/docs/reference/websocket/notifications/convoparticipantleft) | Fired (from the call-provider webhook) when a participant leaves the call room. |
| [`convoHandover`](/docs/reference/websocket/notifications/convohandover) | Fired on user/\{userId} when the user joins a convo from a second device, so the previous device can leave the call. |
| [`boardCreate`](/docs/reference/websocket/notifications/boardcreate) | Fired when a kanban board is created. Published on the project visibility channels of the board. |
| [`boardUpdate`](/docs/reference/websocket/notifications/boardupdate) | Fired when a kanban board is updated (name, visibility, options). |
| [`boardDelete`](/docs/reference/websocket/notifications/boarddelete) | Fired when a kanban board is deleted. Cascaded task deletions / reassignments are included in changes. |
| [`boardTaskCreate`](/docs/reference/websocket/notifications/boardtaskcreate) | Fired when a task is created on a board (UI, AI tool or bulk create). Also used for push notifications. |
| [`boardTaskMove`](/docs/reference/websocket/notifications/boardtaskmove) | Fired when a task is moved between columns or boards. Published on the visibility channels of both boards for cross-board moves. |
| [`boardTaskAssign`](/docs/reference/websocket/notifications/boardtaskassign) | Fired when a task is assigned or unassigned. Published on the board visibility channels and user/\{assignedToId}. |
| [`boardColumnAdd`](/docs/reference/websocket/notifications/boardcolumnadd) | Fired when a column is added to a board. |
| [`boardColumnUpdate`](/docs/reference/websocket/notifications/boardcolumnupdate) | Fired when a board column is updated. |
| [`boardColumnDelete`](/docs/reference/websocket/notifications/boardcolumndelete) | Fired when a board column is deleted. |
| [`boardColumnReorder`](/docs/reference/websocket/notifications/boardcolumnreorder) | Fired when the columns of a board are reordered. changes.update contains every column with its new order. |
| [`boardTaskAdd`](/docs/reference/websocket/notifications/boardtaskadd) | Fired when an existing task is added to a board. |
| [`boardTaskRemove`](/docs/reference/websocket/notifications/boardtaskremove) | Fired when a task is removed from a board (the task itself is kept). |
| [`boardTaskUpdate`](/docs/reference/websocket/notifications/boardtaskupdate) | Fired when a task's details are updated (subject, description, priority, dates, etc.). |
| [`boardTaskLink`](/docs/reference/websocket/notifications/boardtasklink) | Fired when two tasks are linked. |
| [`boardTaskUnlink`](/docs/reference/websocket/notifications/boardtaskunlink) | Fired when a task link is removed. |
| [`boardTaskRelationAdd`](/docs/reference/websocket/notifications/boardtaskrelationadd) | Fired when a resource (asset, folder, message, chat, ...) is related to a task. Also used for push notifications. |
| [`boardTaskRelationRemove`](/docs/reference/websocket/notifications/boardtaskrelationremove) | Fired when a task relation is removed (explicitly, or cascaded when a board visibility change removes access). |
| [`boardFollow`](/docs/reference/websocket/notifications/boardfollow) | Fired when a user follows a board. |
| [`boardUnfollow`](/docs/reference/websocket/notifications/boardunfollow) | Fired when a user unfollows a board. |
# inviteAccept (/docs/reference/websocket/notifications/inviteaccept)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`inviteAccept`
.
Fired when an invitation is accepted.
Payload for the inviteAccept event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ----------------- | --------------- | -------- | ------------------------------------------------ |
| `(*)requesterId` | `string (uuid)` | no | Deprecated. Use initiatorId. |
| `(*)requester` | `object` | no | Deprecated. Use initiator. |
| `(*)resourceType` | `string` | no | Deprecated. |
| `(*)resourceId` | `string (uuid)` | no | Deprecated. |
| `(*)role` | `string` | no | Deprecated. |
| `(*)invite` | `object` | no | Deprecated. The invite object that was accepted. |
| `(*)membership` | `object` | no | Deprecated. The newly created membership object. |
**`changes`**
| Property | Type | Required | Description |
| -------- | -------------------- | -------- | ----------- |
| `update` | `object \| object[]` | no | |
**`update`** (items)
One of 2 variants:
**Variant 1**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ------------------------------------------------------------------------------- |
| `resourceId` | `string (uuid)` | no | Note: the ID of the resource the membership belongs to (not the membership ID). |
| `resourceType` | `"membership"` | no | |
| `resource` | `object` | no | The membership created by accepting the invite. |
**Variant 2**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------------------------------------------------------------------- |
| `resourceId` | `string (uuid)` | no | Note: the ID of the resource the invite belongs to (not the invite ID). |
| `resourceType` | `"invite"` | no | |
| `resource` | `object` | no | The accepted invite. |
# inviteCancel (/docs/reference/websocket/notifications/invitecancel)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`inviteCancel`
.
Fired when an invitation is cancelled.
Payload for the invite cancel event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ----------------- | ---------------- | -------- | ------------------------------------- |
| `(*)requesterId` | `string (uuid)` | no | |
| `(*)requester` | `object` | no | |
| `(*)inviteeEmail` | `string (email)` | no | |
| `(*)resourceType` | `string` | no | |
| `(*)resourceId` | `string (uuid)` | no | |
| `(*)role` | `string` | no | |
| `(*)invite` | `object` | no | The invite object that was cancelled. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
| `resource` | `object` | no | |
# inviteCreate (/docs/reference/websocket/notifications/invitecreate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`inviteCreate`
.
Fired when a new invitation is created.
Payload for the invite create event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ----------------- | ---------------- | -------- | ----------- |
| `(*)requesterId` | `string (uuid)` | no | |
| `(*)requester` | `object` | no | |
| `(*)inviteeEmail` | `string (email)` | no | |
| `(*)resourceType` | `string` | no | |
| `(*)resourceId` | `string (uuid)` | no | |
| `(*)role` | `string` | no | |
| `(*)resourceName` | `string` | no | |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `create` | `object[]` | no | |
**`create`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
| `resource` | `object` | no | |
# logoUpdate (/docs/reference/websocket/notifications/logoupdate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`logoUpdate`
.
Generic event for when a workspace or project logo asset becomes active. Includes the updated owner resource in changes.
Fired by the system when a logo asset's upload completes. changes.update contains the asset and the owning workspace/project.
Payload for the logoUpdate event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ----------------- | -------------------------- | -------- | ------------------------------------------------------- |
| `(*)resourceType` | `"workspace" \| "project"` | no | Deprecated. |
| `(*)resourceId` | `string (uuid)` | no | Deprecated. |
| `(*)asset` | `object` | no | Deprecated. The asset object representing the new logo. |
**`changes`**
| Property | Type | Required | Description |
| -------- | -------------------- | -------- | ----------- |
| `update` | `object \| object[]` | no | |
**`update`** (items)
One of 2 variants:
**Variant 1**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | --------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"asset"` | no | |
| `resource` | `object` | no | The logo asset. |
**Variant 2**
| Property | Type | Required | Description |
| -------------- | -------------------------- | -------- | ---------------------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"workspace" \| "project"` | no | |
| `resource` | `object` | no | The owning resource with the new logo applied. |
# memberJoinPush (/docs/reference/websocket/notifications/memberjoinpush)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`memberJoinPush`
.
Push-notification record created when a user joins a workspace or project. Used to send a push notification; broadcast on \{resourceType}/\{resourceId}.
Created directly (bypasses template validation). Not intended for UI rendering.
Payload for the memberJoinPush event.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | Not populated for this event (the notification is created without a changes object). |
**`tokens`**
| Property | Type | Required | Description |
| -------------- | -------------------------- | -------- | -------------------- |
| `userId` | `string` | yes | The user who joined. |
| `resourceId` | `string` | yes | |
| `resourceType` | `"workspace" \| "project"` | yes | |
| `resourceName` | `string` | yes | |
# membershipAddRole (/docs/reference/websocket/notifications/membershipaddrole)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`membershipAddRole`
.
Fired when a role is added to a user's membership.
Fired when a role is added to a user's membership for a resource.
Payload for the membership add role event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ----------------- | --------------- | -------- | ----------- |
| `(*)requesterId` | `string (uuid)` | no | |
| `(*)requester` | `object` | no | |
| `(*)memberId` | `string (uuid)` | no | |
| `member` | `object` | yes | |
| `(*)resourceType` | `string` | no | |
| `(*)resourceId` | `string (uuid)` | no | |
| `resourceName` | `string` | yes | |
| `role` | `string` | yes | |
| `(*)membership` | `object` | no | |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
| `resource` | `object` | no | |
# membershipDelete (/docs/reference/websocket/notifications/membershipdelete)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`membershipDelete`
.
Fired when a user's membership to a resource is deleted (removed).
Payload for the membership delete event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ----------------- | --------------- | -------- | ----------- |
| `(*)requesterId` | `string (uuid)` | no | |
| `(*)requester` | `object` | no | |
| `(*)memberId` | `string (uuid)` | no | |
| `(*)member` | `object` | no | |
| `(*)resourceType` | `string` | no | |
| `(*)resourceId` | `string (uuid)` | no | |
| `resourceName` | `string` | yes | |
| `roles` | `string[]` | yes | |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `delete` | `object[]` | no | |
**`delete`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
# membershipLeaveResource (/docs/reference/websocket/notifications/membershipleaveresource)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`membershipLeaveResource`
.
Fired when a user leaves a resource themselves.
Payload for the membershipLeaveResource event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ----------------- | --------------- | -------- | ---------------------------- |
| `(*)requesterId` | `string (uuid)` | no | Deprecated. Use initiatorId. |
| `(*)requester` | `object` | no | Deprecated. Use initiator. |
| `(*)memberId` | `string (uuid)` | no | Deprecated. |
| `member` | `object` | yes | |
| `(*)resourceType` | `string` | no | Deprecated. |
| `(*)resourceId` | `string (uuid)` | no | Deprecated. |
| `resourceName` | `string` | yes | |
| `roles` | `string[]` | yes | |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `delete` | `object[]` | no | |
**`delete`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ------------------------------------ |
| `resourceId` | `string (uuid)` | no | ID of the deleted membership record. |
| `resourceType` | `"membership"` | no | |
# membershipRemoveRole (/docs/reference/websocket/notifications/membershipremoverole)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`membershipRemoveRole`
.
Fired when a role is removed from a user's membership.
Fired when a role is removed from a user's membership for a resource.
Payload for the membership remove role event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ----------------- | --------------- | -------- | ------------------------------ |
| `(*)requesterId` | `string (uuid)` | no | |
| `(*)requester` | `object` | no | |
| `(*)memberId` | `string (uuid)` | no | |
| `member` | `object` | yes | |
| `(*)resourceType` | `string` | no | |
| `(*)resourceId` | `string (uuid)` | no | |
| `resourceName` | `string` | yes | |
| `role` | `string` | yes | |
| `(*)membership` | `object` | no | The updated membership object. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
| `resource` | `object` | no | |
# notificationUpdate (/docs/reference/websocket/notifications/notificationupdate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`notificationUpdate`
.
Indicates that a previously delivered, grouped notification has been updated (assetGroupUploadComplete or projectGroupItemPublish).
Fired when a grouped notification accumulates another item within its grouping window. The full updated notification is in tokens.updatedNotification; the changes object is not populated for this event.
Payload for the notificationUpdate event.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | Not populated for this event (the notification is created without a changes object). |
**`tokens`**
| Property | Type | Required | Description |
| ---------------------- | --------------- | -------- | ---------------------------------------------------------------------------------------------------- |
| `notificationId` | `string (uuid)` | yes | ID of the notification that was updated. |
| `originalNotification` | `object` | yes | The notification object before the update. |
| `updatedNotification` | `object` | yes | The notification object after the update (tokens.assets / tokens.items and changes.update extended). |
# notificationUpdateLastSeen (/docs/reference/websocket/notifications/notificationupdatelastseen)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`notificationUpdateLastSeen`
.
Fired to update a client's 'last seen' timestamp for notifications.
Fired internally or for specific clients to update their 'last seen' timestamp for certain notification channels/types.
Payload for the notification update last seen event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ------------- | -------------------- | -------- | ----------- |
| `(*)channels` | `string[]` | no | |
| `(*)types` | `string[]` | no | |
| `(*)lastSeen` | `string (date-time)` | no | |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
| `resource` | `object` | no | |
# projectAssetsPublish (/docs/reference/websocket/notifications/projectassetspublish)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`projectAssetsPublish`
.
CURRENTLY UNUSED (the event type is still registered but nothing emits it). Fired when assets within a project are published.
Fired when assets within a project are published.
Payload for the project assets publish event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ---------------- | --------------- | -------- | ---------------------------------------------- |
| `(*)requesterId` | `string (uuid)` | no | |
| `(*)requester` | `object` | no | |
| `(*)assets` | `object[]` | no | Deprecated. Use resources from changes.update. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | yes | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
| `resource` | `object` | no | |
# projectAssetsUnpublish (/docs/reference/websocket/notifications/projectassetsunpublish)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`projectAssetsUnpublish`
.
CURRENTLY UNUSED (the event type is still registered but nothing emits it). Fired when assets within a project are unpublished.
Fired when assets within a project are unpublished.
Payload for the project assets unpublish event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ---------------- | --------------- | -------- | ---------------------------------------------- |
| `(*)requesterId` | `string (uuid)` | no | |
| `(*)requester` | `object` | no | |
| `(*)assets` | `object[]` | no | Deprecated. Use resources from changes.update. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | yes | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
| `resource` | `object` | no | |
# projectCreate (/docs/reference/websocket/notifications/projectcreate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`projectCreate`
.
Fired when a new project is created.
Payload for the project create event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ---------------- | --------------- | -------- | ---------------------------------------------- |
| `(*)requesterId` | `string (uuid)` | no | |
| `(*)requester` | `object` | no | |
| `(*)projectId` | `string (uuid)` | no | |
| `(*)projectName` | `string` | no | |
| `(*)workspaceId` | `string (uuid)` | no | |
| `(*)membership` | `object` | no | The initial membership object for the creator. |
**`changes`**
| Property | Type | Required | Description |
| -------- | -------------------- | -------- | ----------- |
| `create` | `object \| object[]` | no | |
**`create`** (items)
One of 2 variants:
**Variant 1**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
| `resource` | `object` | no | New project object. |
**Variant 2**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ---------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
| `resource` | `object` | no | New membership object. |
# projectDelete (/docs/reference/websocket/notifications/projectdelete)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`projectDelete`
.
Fired when a project is marked for deletion.
Payload for the project delete event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ---------------- | --------------- | -------- | ----------- |
| `(*)requesterId` | `string (uuid)` | no | |
| `(*)requester` | `object` | no | |
| `(*)projectId` | `string (uuid)` | no | |
| `projectName` | `string` | yes | |
| `(*)workspaceId` | `string (uuid)` | no | |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `delete` | `object[]` | no | |
**`delete`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
# projectGroupItemPublish (/docs/reference/websocket/notifications/projectgroupitempublish)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`projectGroupItemPublish`
.
Grouped notification for items published in a project. Items published by the same user within the grouping window (30 min) are accumulated and re-sent via notificationUpdate.
Payload for the projectGroupItemPublish event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ---------- | ---------- | -------- | ------------------------------------------------------------------------------ |
| `(*)items` | `object[]` | no | Deprecated. Published asset/folder objects. Use resources from changes.update. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------------- | -------- | ----------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"asset" \| "folder"` | no | |
| `resource` | `object` | no | A published item. |
# projectItemsPublish (/docs/reference/websocket/notifications/projectitemspublish)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`projectItemsPublish`
.
Fired when multiple items (assets/folders) within a project are published.
Payload for the project items publish event.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"asset" \| "folder"` | no | |
| `resource` | `object` | no | |
# projectItemsUnpublish (/docs/reference/websocket/notifications/projectitemsunpublish)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`projectItemsUnpublish`
.
Fired when multiple items (assets/folders) within a project are unpublished.
Payload for the project items unpublish event.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| -------- | ---- | -------- | ----------- |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"asset" \| "folder"` | no | |
| `resource` | `object` | no | |
# projectLogoUpdate (/docs/reference/websocket/notifications/projectlogoupdate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`projectLogoUpdate`
.
CURRENTLY UNUSED IN FAVOR OF logoUpdate event. Fired when a project logo is updated. Updates the project and returns the new asset object for the logo. Note that the logo will not be 'active' until the actual file is uploaded. So you will need to watch for updates to this asset before replacing the logo locally.
Fired when a project logo is updated. No code path currently emits this event; see logoUpdate.
Payload for the projectLogoUpdate event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ---------- | -------- | -------- | --------------------------------------------------------------------------- |
| `(*)asset` | `object` | no | Deprecated. Use resource from changes.update where resourceType is 'asset'. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `create` | `object[]` | no | |
| `update` | `object[]` | no | |
**`create`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"asset"` | no | |
| `resource` | `object` | no | The new logo asset. |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | -------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"project"` | no | |
| `resource` | `object` | no | The updated project. |
# projectUpdate (/docs/reference/websocket/notifications/projectupdate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`projectUpdate`
.
Fired when a project name is changed.
Payload for the project name change event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ---------------- | --------------- | -------- | ----------- |
| `(*)requesterId` | `string (uuid)` | no | |
| `(*)requester` | `object` | no | |
| `(*)projectId` | `string (uuid)` | no | |
| `oldProjectName` | `string` | yes | |
| `newProjectName` | `string` | yes | |
| `(*)workspaceId` | `string (uuid)` | no | |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ------------------------------ |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
| `resource` | `object` | no | Updated project object. |
| `oldResource` | `object` | no | The project before the update. |
# publicAssetLinkCreate (/docs/reference/websocket/notifications/publicassetlinkcreate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`publicAssetLinkCreate`
.
Fired when a public (share) link is created for an asset. Published on project/\{projectId}/creator and workspace/\{workspaceId}.
Payload for the publicAssetLinkCreate event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| -------------- | ---------------------------- | -------- | --------------------------------------------------------- |
| `assetName` | `string` | yes | |
| `(*)assetId` | `string (uuid)` | no | Deprecated. Use resourceId. |
| `(*)projectId` | `string (uuid)` | no | Deprecated. |
| `projectName` | `string` | yes | |
| `creatorName` | `string` | yes | Display name (or email) of the user who created the link. |
| `expires` | `string (date-time) \| null` | yes | Expiry of the link, null when it does not expire. |
| `deepLink` | `string` | yes | Deep link to the asset in the app. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `create` | `object[]` | no | |
**`create`** (items)
| Property | Type | Required | Description |
| -------------- | ------------------- | -------- | ------------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"publicAssetLink"` | no | |
| `resource` | `object` | no | The created public asset link record. |
# publicFileSystemCreate (/docs/reference/websocket/notifications/publicfilesystemcreate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`publicFileSystemCreate`
.
Fired when a public release (public file system) is created. Published on project/\{projectId}/creator.
Payload for the publicFileSystemCreate event.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ----------- | -------- | -------- | ---------------------------------------------- |
| `title` | `string` | yes | |
| `inventory` | `object` | yes | Inventory summary of the items in the release. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `create` | `object[]` | no | |
**`create`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | -------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"public"` | no | |
| `resource` | `object` | no | The public release record. |
# publicFileSystemDelete (/docs/reference/websocket/notifications/publicfilesystemdelete)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`publicFileSystemDelete`
.
Fired when a public release is deleted. Published on project/\{projectId}/creator.
Payload for the publicFileSystemDelete event.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| -------- | -------- | -------- | ----------- |
| `title` | `string` | yes | |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `delete` | `object[]` | no | |
**`delete`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ---------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"public"` | no | |
| `resource` | `object` | no | The deleted public release record. |
# publicFileSystemUpdate (/docs/reference/websocket/notifications/publicfilesystemupdate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`publicFileSystemUpdate`
.
Fired when a public release is updated (title, description, validity, options). Published on project/\{projectId}/creator.
Payload for the publicFileSystemUpdate event.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| -------- | -------- | -------- | ----------- |
| `title` | `string` | yes | |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ---------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"public"` | no | |
| `resource` | `object` | no | The updated public release record. |
| `oldResource` | `object` | no | The record before the update. |
# publishPushSummary (/docs/reference/websocket/notifications/publishpushsummary)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`publishPushSummary`
.
Push-notification summary of items published to reviewers. Used to send a push notification; broadcast on project/\{projectId}/reviewer.
Created directly (bypasses template validation). Not intended for UI rendering.
Payload for the publishPushSummary event.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | Not populated for this event (the notification is created without a changes object). |
**`tokens`**
| Property | Type | Required | Description |
| ------------- | ---------- | -------- | ---------------------------------------------------------------------- |
| `publisherId` | `string` | yes | |
| `projectId` | `string` | yes | |
| `projectName` | `string` | yes | |
| `items` | `object[]` | yes | Minimal item summaries: \{ \_id, mediaType (null for folders), name }. |
# settingsUpdate (/docs/reference/websocket/notifications/settingsupdate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`settingsUpdate`
.
Fired when a user's settings for a resource are updated or reset. Published on user/\{userId} only.
Payload for the settingsUpdate event.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | changes.update on update, changes.delete on reset. resourceId of the entry is the user ID. |
**`tokens`**
| Property | Type | Required | Description |
| -------------- | -------- | -------- | --------------------------------------------- |
| `resourceType` | `string` | yes | Type of the resource the settings apply to. |
| `resourceId` | `string` | yes | |
| `settings` | `object` | yes | The updated settings (empty object on reset). |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
| `delete` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ---------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"settings"` | no | |
| `resource` | `object` | no | The updated settings object. |
**`delete`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"settings"` | no | |
# submissionCreate (/docs/reference/websocket/notifications/submissioncreate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`submissionCreate`
.
Fired when a submission is released for the first time. Published on project/\{projectId}, project/\{projectId}/creator and project/\{projectId}/reviewer.
Payload for the submissionCreate event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ---------------- | --------------- | -------- | ------------------------------------------------------------------------------------- |
| `(*)requesterId` | `string (uuid)` | no | Deprecated. Use initiatorId. |
| `(*)requester` | `object` | no | Deprecated. Use initiator. |
| `(*)submission` | `object` | no | Deprecated. The submission (chatSubmission) object. Use resource from changes.create. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `create` | `object[]` | no | |
**`create`** (items)
| Property | Type | Required | Description |
| -------------- | ------------------ | -------- | ------------------------ |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"chatSubmission"` | no | |
| `resource` | `object` | no | The released submission. |
# submissionPushSummary (/docs/reference/websocket/notifications/submissionpushsummary)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`submissionPushSummary`
.
Push-notification summary for a newly created submission. Used to send a push notification; broadcast on project/\{projectId}.
Created directly (bypasses template validation). Not intended for UI rendering.
Payload for the submissionPushSummary event.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | Not populated for this event (the notification is created without a changes object). |
**`tokens`**
| Property | Type | Required | Description |
| ------------------- | -------- | -------- | ------------------------------------------------ |
| `publisherId` | `string` | yes | |
| `projectId` | `string` | yes | |
| `projectName` | `string` | yes | |
| `submissionId` | `string` | yes | |
| `submissionSubject` | `string` | yes | |
| `description` | `string` | yes | Submission description (empty string when none). |
# submissionTag (/docs/reference/websocket/notifications/submissiontag)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`submissionTag`
.
Fired when a tag is added to a submission. resourceType is chatSubmission.
Payload for the submissionTag event.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | Not populated for this event (the notification is created without a changes object). |
**`tokens`**
| Property | Type | Required | Description |
| --------- | -------- | -------- | --------------------------------------------- |
| `subject` | `string` | yes | Submission subject ('Submission' when empty). |
| `tagName` | `string` | yes | |
# submissionUntag (/docs/reference/websocket/notifications/submissionuntag)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`submissionUntag`
.
Fired when a tag is removed from a submission. resourceType is chatSubmission.
Payload for the submissionUntag event.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | Not populated for this event (the notification is created without a changes object). |
**`tokens`**
| Property | Type | Required | Description |
| --------- | -------- | -------- | --------------------------------------------- |
| `subject` | `string` | yes | Submission subject ('Submission' when empty). |
| `tagName` | `string` | yes | |
# submissionUpdate (/docs/reference/websocket/notifications/submissionupdate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`submissionUpdate`
.
Fired when an already-released submission is re-released. Published on project/\{projectId}, project/\{projectId}/creator and project/\{projectId}/reviewer.
Payload for the submissionUpdate event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ---------------- | --------------- | -------- | ------------------------------------------------------------------------------------- |
| `(*)requesterId` | `string (uuid)` | no | Deprecated. Use initiatorId. |
| `(*)requester` | `object` | no | Deprecated. Use initiator. |
| `(*)submission` | `object` | no | Deprecated. The submission (chatSubmission) object. Use resource from changes.update. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | ------------------ | -------- | --------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"chatSubmission"` | no | |
| `resource` | `object` | no | The re-released submission. |
# subscriptionCreate (/docs/reference/websocket/notifications/subscriptioncreate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`subscriptionCreate`
.
Fired when a new billing subscription is created for a workspace (Stripe webhook). Published on user/\{ownerId} and \{resourceType}/\{resourceId}.
Payload for the subscriptionCreate event.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | Always an empty object for this event. |
| `changes` | `object` | no | |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `create` | `object[]` | no | |
**`create`** (items)
| Property | Type | Required | Description |
| -------------- | ---------------- | -------- | -------------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"subscription"` | no | |
| `resource` | `object` | no | The newly created subscription object. |
# subscriptionUpdate (/docs/reference/websocket/notifications/subscriptionupdate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`subscriptionUpdate`
.
Fired when an existing billing subscription is updated, paused, resumed or deleted (Stripe webhook). Published on user/\{ownerId} and \{resourceType}/\{resourceId}.
Payload for the subscriptionUpdate event.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | Always an empty object for this event. |
| `changes` | `object` | no | |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | ---------------- | -------- | -------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"subscription"` | no | |
| `resource` | `object` | no | The updated subscription object. |
# tagCreate (/docs/reference/websocket/notifications/tagcreate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`tagCreate`
.
Fired when a new tag is created.
Payload for the tag create event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ------------ | -------- | -------- | ------------------------- |
| `(*)tagName` | `string` | no | Name of the created tag. |
| `(*)color` | `string` | no | Color of the created tag. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `create` | `object[]` | no | |
**`create`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
| `resource` | `object` | no | |
# tagDelete (/docs/reference/websocket/notifications/tagdelete)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`tagDelete`
.
Fired when a tag is deleted.
Payload for the tagDelete event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ------------ | -------- | -------- | ------------------------------------- |
| `(*)tagName` | `string` | no | Deprecated. Name of the deleted tag. |
| `(*)color` | `string` | no | Deprecated. Color of the deleted tag. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `delete` | `object[]` | no | |
**`delete`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"tag"` | no | |
| `resource` | `object` | no | The deleted tag object. |
# tagUpdate (/docs/reference/websocket/notifications/tagupdate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`tagUpdate`
.
Fired when a tag is updated.
Fired when a tag is updated (name or color change).
Payload for the tag update event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| --------------- | -------- | -------- | -------------------------- |
| `(*)oldTagName` | `string` | no | Previous name of the tag. |
| `(*)newTagName` | `string` | no | New name of the tag. |
| `(*)oldColor` | `string` | no | Previous color of the tag. |
| `(*)newColor` | `string` | no | New color of the tag. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
| `resource` | `object` | no | |
# taskAcknowledged (/docs/reference/websocket/notifications/taskacknowledged)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`taskAcknowledged`
.
Fired when tasks are acknowledged within a project.
Payload for the task acknowledged event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ------------------------ | --------------- | -------- | -------------------------------------------- |
| `(*)projectId` | `string (uuid)` | no | |
| `newUnacknowledgedCount` | `integer` | yes | The remaining count of unacknowledged tasks. |
| `(*)acknowledgedTasks` | `object[]` | no | List of tasks that were acknowledged. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
| `resource` | `object` | no | |
# taskCreate (/docs/reference/websocket/notifications/taskcreate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`taskCreate`
.
Fired when a new task is created within a project.
Payload for the task create event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ------------------------------ |
| `(*)projectId` | `string (uuid)` | no | |
| `(*)task` | `object` | no | The newly created task object. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `create` | `object[]` | no | |
**`create`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
| `resource` | `object` | no | |
# taskFollow (/docs/reference/websocket/notifications/taskfollow)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`taskFollow`
.
Fired when a user follows a task.
Payload for the taskFollow event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | --------------------------- |
| `(*)projectId` | `string (uuid)` | no | Deprecated. |
| `(*)taskId` | `string (uuid)` | no | Deprecated. Use resourceId. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | -------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"task"` | no | |
| `resource` | `object` | no | The task with updated followers. |
# taskStatusUpdate (/docs/reference/websocket/notifications/taskstatusupdate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`taskStatusUpdate`
.
Fired when the status of a task is updated.
Payload for the task status update event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ---------------- | --------------- | -------- | ----------- |
| `(*)projectId` | `string (uuid)` | no | |
| `originalStatus` | `string` | yes | |
| `updatedStatus` | `string` | yes | |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
| `resource` | `object` | no | |
# taskUnfollow (/docs/reference/websocket/notifications/taskunfollow)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`taskUnfollow`
.
Fired when a user unfollows a task.
Payload for the taskUnfollow event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | --------------------------- |
| `(*)projectId` | `string (uuid)` | no | Deprecated. |
| `(*)taskId` | `string (uuid)` | no | Deprecated. Use resourceId. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | -------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"task"` | no | |
| `resource` | `object` | no | The task with updated followers. |
# test (/docs/reference/websocket/notifications/test)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`test`
.
Event used for testing websocket connections.
Test event payload. Changes key structure will depend on test scenario.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ---------- | -------- | -------- | -------------------------------- |
| `testData` | `string` | yes | Arbitrary data sent for testing. |
# uploadPushSummary (/docs/reference/websocket/notifications/uploadpushsummary)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`uploadPushSummary`
.
Delayed push-notification summary of assets uploaded to a project by one user. Primarily used to send a push notification after scheduledSendAt, but also broadcast on the project visibility channels when created.
Created directly (bypasses template validation) and grouped per creator/project while pushStatus is pending; later uploads are appended to tokens.assets and the timer is reset. Not intended for UI rendering.
Payload for the uploadPushSummary event.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | Not populated for this event (the notification is created without a changes object). |
**`tokens`**
| Property | Type | Required | Description |
| ------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------ |
| `creatorId` | `string` | yes | ID of the uploader. |
| `creator` | `object` | no | Public user snapshot of the uploader (present in the payload although not part of the template). |
| `projectId` | `string` | yes | |
| `projectName` | `string` | yes | |
| `assets` | `object[]` | yes | Minimal asset summaries: \{ \_id, mediaType, name }. |
# userAvatarUpdate (/docs/reference/websocket/notifications/useravatarupdate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`userAvatarUpdate`
.
Fired when a avatars status is set to active. Note that this is an asset event and not a user event so it is fired when the asset's status is set to active not when a user's object is updated.
Fired when a user updates their avatar.
Payload for the user avatar update event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ----------- | --------------- | -------- | --------------------------------------------- |
| `(*)userId` | `string (uuid)` | no | |
| `(*)asset` | `object` | no | The asset object representing the new avatar. |
**`changes`**
| Property | Type | Required | Description |
| -------- | -------------------- | -------- | ----------- |
| `update` | `object \| object[]` | no | |
**`update`** (items)
One of 2 variants:
**Variant 1**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
| `resource` | `object` | no | |
**Variant 2**
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
| `resource` | `object` | no | |
# userDeleted (/docs/reference/websocket/notifications/userdeleted)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`userDeleted`
.
Fired when a user account is deleted.
Payload for the user deleted event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ------------- | -------- | -------- | ------------------------------------------- |
| `(*)userData` | `object` | no | Information about the user who was deleted. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `delete` | `object[]` | no | |
**`delete`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
# userEmailVerify (/docs/reference/websocket/notifications/useremailverify)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`userEmailVerify`
.
Fired when a user's email address is verified. Published on user/\{userId}.
Payload for the userEmailVerify event.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | Always an empty object for this event. |
| `changes` | `object` | no | |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ------------------------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `"user"` | no | |
| `resource` | `object` | no | The user object (includes isEmailVerified). |
# userPublicUpdate (/docs/reference/websocket/notifications/userpublicupdate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`userPublicUpdate`
.
Fired when a user's public information is updated.
Fired when a user's public information (e.g., display name, avatar) is updated, visible to others.
Payload for the user public update event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ----------- | -------- | -------- | ------------------------------------------------------ |
| `(*)update` | `object` | no | Object containing the public fields that were updated. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
| `resource` | `object` | no | |
# userSelfUpdate (/docs/reference/websocket/notifications/userselfupdate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`userSelfUpdate`
.
Fired when a user updates their own profile information.
Payload for the user self update event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ----------- | -------- | -------- | ----------------------------------------------- |
| `(*)update` | `object` | no | Object containing the fields that were updated. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | no | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
| `resource` | `object` | no | |
# webhookTest (/docs/reference/websocket/notifications/webhooktest)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`webhookTest`
.
Synthetic event fired when an admin tests a webhook subscription. Published on workspace/\{workspaceId}; delivered by the webhook dispatcher as webhook.test.
Payload for the webhookTest event.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | Not populated for this event (the notification is created without a changes object). |
**`tokens`**
| Property | Type | Required | Description |
| ---------------- | --------------- | -------- | ----------------------------------------------------------------------------------------- |
| `triggeredById` | `string (uuid)` | yes | User who triggered the test. |
| `subscriptionId` | `string (uuid)` | yes | Webhook subscription being tested (also resourceId; resourceType is webhookSubscription). |
| `message` | `string` | yes | Human readable banner message. |
# workspaceCreate (/docs/reference/websocket/notifications/workspacecreate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`workspaceCreate`
.
Fired when a new workspace is created.
Payload for the workspace create event. Includes new workspace object in changes.create array.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ----------------- | -------- | -------- | --------------------------------------------- |
| `(*)newWorkspace` | `object` | no | Deprecated. Use resource from changes.create. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `create` | `object[]` | yes | |
**`create`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | --------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
| `resource` | `object` | no | New workspace object. |
# workspaceDelete (/docs/reference/websocket/notifications/workspacedelete)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`workspaceDelete`
.
Fired when a workspace is marked for deletion.
Payload for the workspace delete event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ---------------- | --------------- | -------- | ----------- |
| `(*)requesterId` | `string (uuid)` | no | |
| `(*)requester` | `object` | no | |
| `(*)workspaceId` | `string (uuid)` | no | |
| `workspaceName` | `string` | yes | |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `delete` | `object[]` | yes | |
**`delete`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
# workspaceLogoUpdate (/docs/reference/websocket/notifications/workspacelogoupdate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`workspaceLogoUpdate`
.
CURRENTLY UNUSED IN FAVOR OF logoUpdate event. Fired when a workspace logo is updated.
Fired when a workspace logo is updated.
Payload for the workspace logo update event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ---------- | -------- | -------- | --------------------------------------------------------------------------- |
| `(*)asset` | `object` | no | Deprecated. Use resource from changes.update where resourceType is 'asset'. |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | yes | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ----------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
| `resource` | `object` | no | |
# workspaceStorageLimitWarning (/docs/reference/websocket/notifications/workspacestoragelimitwarning)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`workspaceStorageLimitWarning`
.
Fired when a workspace's storage usage exceeds a threshold.
Fired when a workspace's storage usage exceeds a predefined threshold.
Payload for the workspace storage limit warning event.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| --------------------- | --------------- | -------- | ----------- |
| `workspaceId` | `string (uuid)` | yes | |
| `storageLimitInBytes` | `number` | yes | |
| `storageUsedInBytes` | `number` | yes | |
# workspaceUpdate (/docs/reference/websocket/notifications/workspaceupdate)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Delivered as the
`notification`
socket event with
`type`
set to
`workspaceUpdate`
.
Fired when a workspace name is changed.
Payload for the workspace name change event.
Token keys marked with (\*) will be deprecated in a future release and should not be used for new development; replace them with the values and objects in the `changes` key in existing implementations.
## Payload [#payload]
| Property | Type | Required | Description |
| --------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | yes | The specific type of notification event (matches the top-level key, e.g., 'workspaceCreate'). Every notification type is documented as its own event in this reference. |
| `initiatorId` | `string (uuid)` | no | ID of the user or system that initiated the event. Null if initiatorType is 'system'. |
| `initiatorType` | `"user" \| "system"` | yes | Type of initiator (user or system). |
| `initiator` | `object \| null` | no | Populated initiator user object (if initiatorType is 'user'). |
| `resourceId` | `string (uuid)` | yes | ID of the primary resource this notification pertains to. |
| `resourceType` | `string` | yes | Type of the primary resource this notification pertains to. |
| `channels` | `string[]` | no | The specific channels this notification was published on. Present on notification objects returned by the REST API only; the socket 'notification' payload omits it (and id). |
| `createdAt` | `string (date-time)` | yes | Timestamp when the notification was created. |
| `tokens` | `object` | no | |
| `changes` | `object` | no | |
**`tokens`**
| Property | Type | Required | Description |
| ------------------ | --------------- | -------- | ----------- |
| `(*)requesterId` | `string (uuid)` | no | |
| `(*)requester` | `object` | no | |
| `(*)workspaceId` | `string (uuid)` | no | |
| `oldWorkspaceName` | `string` | yes | |
| `newWorkspaceName` | `string` | yes | |
**`changes`**
| Property | Type | Required | Description |
| -------- | ---------- | -------- | ----------- |
| `update` | `object[]` | yes | |
**`update`** (items)
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ------------------------- |
| `resourceId` | `string (uuid)` | no | |
| `resourceType` | `string` | no | |
| `resource` | `object` | no | Updated workspace object. |
# BotClient (/docs/reference/sdk/BotClient)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
## Classes [#classes]
### default [#default]
Client for interacting with the Nurama API as a bot user.
Authenticates with a long-lived API key (`nrm_bot_...`) instead of a JWT.
Requests must arrive at the bot subdomain (`bot.nurama.com` by default) so
the server can apply bot-specific firewall and rate-limit rules.
Exposes only the namespaces a bot is permitted to use — auth, user profile,
payment, subscription, device, and bot-administration namespaces are omitted.
#### Example [#example]
```ts
import BotClient from '@nurama/sdk/bot';
const bot = new BotClient(process.env.NURAMA_BOT_API_KEY!);
const workspaces = await bot.workspace.listWorkspaces();
```
#### Constructors [#constructors]
##### Constructor [#constructor]
```ts
new default(apiKey, options?): default;
```
###### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | --------------------------------------- | ------------------------------------------------------ |
| `apiKey` | `string` | Bot API key in the format `nrm_bot_{prefix}_{secret}`. |
| `options` | [`BotClientOptions`](#botclientoptions) | Configuration overrides. |
###### Returns [#returns]
[`default`](#default)
#### Properties [#properties]
| Property | Modifier | Type | Description |
| -------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `aiChat` | `readonly` | \{ `createTopic`: `Promise`\<`AiChatCreateTopicResponse`>; `deleteTopic`: `Promise`\<`AiChatGetTopicResponse`>; `getTopic`: `Promise`\<`AiChatGetTopicResponse`>; `listTopics`: `Promise`\<`AiChatListTopicsResponse`>; `updateTopic`: `Promise`\<`AiChatGetTopicResponse`>; } | - |
| `aiChat.createTopic` | `public` | `Promise`\<`AiChatCreateTopicResponse`> | - |
| `aiChat.deleteTopic` | `public` | `Promise`\<`AiChatGetTopicResponse`> | - |
| `aiChat.getTopic` | `public` | `Promise`\<`AiChatGetTopicResponse`> | - |
| `aiChat.listTopics` | `public` | `Promise`\<`AiChatListTopicsResponse`> | - |
| `aiChat.updateTopic` | `public` | `Promise`\<`AiChatGetTopicResponse`> | - |
| `asset` | `readonly` | [`AssetMethods`](/docs/reference/sdk/NuramaClient#assetmethods) | - |
| `board` | `readonly` | \{ `addColumn`: `Promise`\<`BoardColumn`>; `addExistingTaskToBoard`: `Promise`\<`Task`>; `createBoard`: `Promise`\<`Board`>; `createBoardTask`: `Promise`\<`Task`>; `deleteBoard`: `Promise`\<\{ `deletedTaskIds`: `string`\[]; `disposition`: `string`; `message`: `string`; `reassignedTaskIds`: `string`\[]; }>; `deleteColumn`: `Promise`\<`void`>; `followBoard`: `Promise`\<`Board`>; `getBoard`: `Promise`\<`BoardWithTasks`>; `getBoardTasks`: `Promise`\<`Task`\[]>; `getProjectBoards`: `Promise`\<`Board`\[]>; `getProjectTasks`: `Promise`\<`any`>; `moveTask`: `Promise`\<`Task`>; `removeTaskFromBoard`: `Promise`\<`Task`>; `reorderColumns`: `Promise`\<`BoardColumn`\[]>; `tagBoard`: `Promise`\<`Board`>; `unfollowBoard`: `Promise`\<`Board`>; `untagBoard`: `Promise`\<`Board`>; `updateBoard`: `Promise`\<`Board`>; `updateColumn`: `Promise`\<`BoardColumn`>; } | - |
| `board.addColumn` | `public` | `Promise`\<`BoardColumn`> | - |
| `board.addExistingTaskToBoard` | `public` | `Promise`\<`Task`> | - |
| `board.createBoard` | `public` | `Promise`\<`Board`> | - |
| `board.createBoardTask` | `public` | `Promise`\<`Task`> | - |
| `board.deleteBoard` | `public` | `Promise`\<\{ `deletedTaskIds`: `string`\[]; `disposition`: `string`; `message`: `string`; `reassignedTaskIds`: `string`\[]; }> | - |
| `board.deleteColumn` | `public` | `Promise`\<`void`> | - |
| `board.followBoard` | `public` | `Promise`\<`Board`> | - |
| `board.getBoard` | `public` | `Promise`\<`BoardWithTasks`> | - |
| `board.getBoardTasks` | `public` | `Promise`\<`Task`\[]> | - |
| `board.getProjectBoards` | `public` | `Promise`\<`Board`\[]> | - |
| `board.getProjectTasks` | `public` | `Promise`\<`any`> | - |
| `board.moveTask` | `public` | `Promise`\<`Task`> | - |
| `board.removeTaskFromBoard` | `public` | `Promise`\<`Task`> | - |
| `board.reorderColumns` | `public` | `Promise`\<`BoardColumn`\[]> | - |
| `board.tagBoard` | `public` | `Promise`\<`Board`> | - |
| `board.unfollowBoard` | `public` | `Promise`\<`Board`> | - |
| `board.untagBoard` | `public` | `Promise`\<`Board`> | - |
| `board.updateBoard` | `public` | `Promise`\<`Board`> | - |
| `board.updateColumn` | `public` | `Promise`\<`BoardColumn`> | - |
| `chat` | `readonly` | \{ `addAttachments`: `Promise`\<[`AttachmentUploadRecord`](/docs/reference/sdk/routes/chat#attachmentuploadrecord)\[]>; `addMembers`: `Promise`\<`ChatMember`>; `archiveMemberChat`: `Promise`\<`ChatMember`>; `createAssetChatAndMessage`: `Promise`\<`any`>; `createMemberChat`: `Promise`\<`ChatMember`>; `createMessage`: `Promise`\<`ChatMessage`>; `createMessageShortLink`: `Promise`\<\{ `code`: `string`; `shortUrl`: `string`; }>; `createReaction`: `Promise`\<`ChatMessage`>; `createTopicChat`: `Promise`\<`Chat`>; `deleteChat`: `Promise`\<`void`>; `deleteMemberChat`: `Promise`\<`void`>; `deleteMessage`: `Promise`\<`ChatMessage`>; `fetchLinkPreviews`: `Promise`\<[`LinkPreviewResponse`](/docs/reference/sdk/routes/chat#linkpreviewresponse)>; `followChat`: `Promise`\<`void`>; `getAddableMembers`: `Promise`\< \| [`AddableMembersByScope`](/docs/reference/sdk/routes/chat#addablemembersbyscope) \| `Membership`\[]>; `getChat`: `Promise`\<`Chat`>; `getChatByTopicId`: `Promise`\<`Chat`>; `getMemberChat`: `Promise`\<`ChatMember`>; `getMentionableAssets`: `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/chat#paginatedresponse)\<`Asset`>>; `getMentionableFolders`: `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/chat#paginatedresponse)\<`Folder`>>; `getMentionablePublics`: `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/chat#paginatedresponse)\<[`MentionablePublic`](/docs/reference/sdk/routes/chat#mentionablepublic)>>; `getMentionableSubmissions`: `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/chat#paginatedresponse)\<[`MentionableSubmission`](/docs/reference/sdk/routes/chat#mentionablesubmission)>>; `getMentionableTasks`: `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/chat#paginatedresponse)\<`any`>>; `getMentions`: `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/chat#paginatedresponse)\<`ChatMessage`>>; `getMessage`: `Promise`\<`ChatMessage`>; `getMessages`: `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/chat#paginatedresponse)\<`ChatMessage`>>; `getReplies`: `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/chat#paginatedresponse)\<`ChatMessage`>>; `getScopeAddableMembers`: `Promise`\< \| [`AddableMembersByScope`](/docs/reference/sdk/routes/chat#addablemembersbyscope) \| `Membership`\[]>; `getUsersMemberChats`: `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/chat#paginatedresponse)\<`ChatMember`>>; `getWorkspaceProjectChats`: `Promise`\<`any`\[]>; `highlightMessage`: `Promise`\<`ChatMessage`>; `removeAttachment`: `Promise`\<`ChatMessage`>; `removeMembers`: `Promise`\<`ChatMember`>; `removeReaction`: `Promise`\<`ChatMessage`>; `reviseMessage`: `Promise`\<`ChatMessage`>; `unarchiveMemberChat`: `Promise`\<`ChatMember`>; `unfollowChat`: `Promise`\<`void`>; `unhighlightMessage`: `Promise`\<`ChatMessage`>; `updateChatSubject`: `Promise`\<`Chat`>; `updateMemberChat`: `Promise`\<`ChatMember`>; `updateMemberChatIcon`: `Promise`\<\{ `chat`: `ChatMember`; } & [`AttachmentUploadRecord`](/docs/reference/sdk/routes/chat#attachmentuploadrecord)>; } | - |
| `chat.addAttachments` | `public` | `Promise`\<[`AttachmentUploadRecord`](/docs/reference/sdk/routes/chat#attachmentuploadrecord)\[]> | - |
| `chat.addMembers` | `public` | `Promise`\<`ChatMember`> | - |
| `chat.archiveMemberChat` | `public` | `Promise`\<`ChatMember`> | - |
| `chat.createAssetChatAndMessage` | `public` | `Promise`\<`any`> | - |
| `chat.createMemberChat` | `public` | `Promise`\<`ChatMember`> | - |
| `chat.createMessage` | `public` | `Promise`\<`ChatMessage`> | - |
| `chat.createMessageShortLink` | `public` | `Promise`\<\{ `code`: `string`; `shortUrl`: `string`; }> | - |
| `chat.createReaction` | `public` | `Promise`\<`ChatMessage`> | - |
| `chat.createTopicChat` | `public` | `Promise`\<`Chat`> | - |
| `chat.deleteChat` | `public` | `Promise`\<`void`> | - |
| `chat.deleteMemberChat` | `public` | `Promise`\<`void`> | - |
| `chat.deleteMessage` | `public` | `Promise`\<`ChatMessage`> | - |
| `chat.fetchLinkPreviews` | `public` | `Promise`\<[`LinkPreviewResponse`](/docs/reference/sdk/routes/chat#linkpreviewresponse)> | - |
| `chat.followChat` | `public` | `Promise`\<`void`> | - |
| `chat.getAddableMembers` | `public` | `Promise`\< \| [`AddableMembersByScope`](/docs/reference/sdk/routes/chat#addablemembersbyscope) \| `Membership`\[]> | - |
| `chat.getChat` | `public` | `Promise`\<`Chat`> | - |
| `chat.getChatByTopicId` | `public` | `Promise`\<`Chat`> | - |
| `chat.getMemberChat` | `public` | `Promise`\<`ChatMember`> | - |
| `chat.getMentionableAssets` | `public` | `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/chat#paginatedresponse)\<`Asset`>> | - |
| `chat.getMentionableFolders` | `public` | `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/chat#paginatedresponse)\<`Folder`>> | - |
| `chat.getMentionablePublics` | `public` | `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/chat#paginatedresponse)\<[`MentionablePublic`](/docs/reference/sdk/routes/chat#mentionablepublic)>> | - |
| `chat.getMentionableSubmissions` | `public` | `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/chat#paginatedresponse)\<[`MentionableSubmission`](/docs/reference/sdk/routes/chat#mentionablesubmission)>> | - |
| `chat.getMentionableTasks` | `public` | `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/chat#paginatedresponse)\<`any`>> | - |
| `chat.getMentions` | `public` | `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/chat#paginatedresponse)\<`ChatMessage`>> | - |
| `chat.getMessage` | `public` | `Promise`\<`ChatMessage`> | - |
| `chat.getMessages` | `public` | `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/chat#paginatedresponse)\<`ChatMessage`>> | - |
| `chat.getReplies` | `public` | `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/chat#paginatedresponse)\<`ChatMessage`>> | - |
| `chat.getScopeAddableMembers` | `public` | `Promise`\< \| [`AddableMembersByScope`](/docs/reference/sdk/routes/chat#addablemembersbyscope) \| `Membership`\[]> | - |
| `chat.getUsersMemberChats` | `public` | `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/chat#paginatedresponse)\<`ChatMember`>> | - |
| `chat.getWorkspaceProjectChats` | `public` | `Promise`\<`any`\[]> | - |
| `chat.highlightMessage` | `public` | `Promise`\<`ChatMessage`> | - |
| `chat.removeAttachment` | `public` | `Promise`\<`ChatMessage`> | - |
| `chat.removeMembers` | `public` | `Promise`\<`ChatMember`> | - |
| `chat.removeReaction` | `public` | `Promise`\<`ChatMessage`> | - |
| `chat.reviseMessage` | `public` | `Promise`\<`ChatMessage`> | - |
| `chat.unarchiveMemberChat` | `public` | `Promise`\<`ChatMember`> | - |
| `chat.unfollowChat` | `public` | `Promise`\<`void`> | - |
| `chat.unhighlightMessage` | `public` | `Promise`\<`ChatMessage`> | - |
| `chat.updateChatSubject` | `public` | `Promise`\<`Chat`> | - |
| `chat.updateMemberChat` | `public` | `Promise`\<`ChatMember`> | - |
| `chat.updateMemberChatIcon` | `public` | `Promise`\<\{ `chat`: `ChatMember`; } & [`AttachmentUploadRecord`](/docs/reference/sdk/routes/chat#attachmentuploadrecord)> | - |
| `config` | `readonly` | [`ConfigMethods`](/docs/reference/sdk/routes/config#configmethods) | - |
| `convo` | `readonly` | \{ `completeConvo`: `Promise`\<`CompleteConvoResponse`>; `deleteConvo`: `Promise`\<`void`>; `getChatConvos`: `Promise`\<`Convo`\[]>; `getConvo`: `Promise`\<`GetConvoResponse`>; `getProjectConvos`: `Promise`\<`Convo`\[]>; `getScopeConvos`: `Promise`\<`GetScopeConvosResponse`>; `joinConvo`: `Promise`\<`JoinConvoResponse`>; `leaveConvo`: `Promise`\<`LeaveConvoResponse`>; `rejoinConvo`: `Promise`\<`JoinConvoResponse`>; `startConvo`: `Promise`\<`StartConvoResponse`>; `updateConvo`: `Promise`\<`UpdateConvoResponse`>; } | - |
| `convo.completeConvo` | `public` | `Promise`\<`CompleteConvoResponse`> | - |
| `convo.deleteConvo` | `public` | `Promise`\<`void`> | - |
| `convo.getChatConvos` | `public` | `Promise`\<`Convo`\[]> | - |
| `convo.getConvo` | `public` | `Promise`\<`GetConvoResponse`> | - |
| `convo.getProjectConvos` | `public` | `Promise`\<`Convo`\[]> | - |
| `convo.getScopeConvos` | `public` | `Promise`\<`GetScopeConvosResponse`> | - |
| `convo.joinConvo` | `public` | `Promise`\<`JoinConvoResponse`> | - |
| `convo.leaveConvo` | `public` | `Promise`\<`LeaveConvoResponse`> | - |
| `convo.rejoinConvo` | `public` | `Promise`\<`JoinConvoResponse`> | - |
| `convo.startConvo` | `public` | `Promise`\<`StartConvoResponse`> | - |
| `convo.updateConvo` | `public` | `Promise`\<`UpdateConvoResponse`> | - |
| `folder` | `readonly` | \{ `getFolder`: `Promise`\<`Folder`>; `getFoldersAssets`: `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/folder#paginatedresponse)\<`Asset`>>; `tagFolder`: `Promise`\<`Folder`>; `untagFolder`: `Promise`\<`Folder`>; `updateFolder`: `Promise`\<`Folder`>; `updateFolderIcon`: `Promise`\<`any`>; } | - |
| `folder.getFolder` | `public` | `Promise`\<`Folder`> | - |
| `folder.getFoldersAssets` | `public` | `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/folder#paginatedresponse)\<`Asset`>> | - |
| `folder.tagFolder` | `public` | `Promise`\<`Folder`> | - |
| `folder.untagFolder` | `public` | `Promise`\<`Folder`> | - |
| `folder.updateFolder` | `public` | `Promise`\<`Folder`> | - |
| `folder.updateFolderIcon` | `public` | `Promise`\<`any`> | - |
| `invite` | `readonly` | \{ `acceptInvite`: `Promise`\<[`AcceptInviteResponse`](/docs/reference/sdk/routes/invite#acceptinviteresponse)>; `cancelInvite`: `Promise`\<`Invite`>; `getInviteById`: `Promise`\<`Invite`>; `getInvites`: `Promise`\<[`PaginatedInvitesResponse`](/docs/reference/sdk/routes/invite#paginatedinvitesresponse)>; `getInvitesForResource`: `Promise`\<`Invite`\[]>; `inviteUser`: `Promise`\<`Invite`>; `resendInvite`: `Promise`\<`Invite`>; } | - |
| `invite.acceptInvite` | `public` | `Promise`\<[`AcceptInviteResponse`](/docs/reference/sdk/routes/invite#acceptinviteresponse)> | - |
| `invite.cancelInvite` | `public` | `Promise`\<`Invite`> | - |
| `invite.getInviteById` | `public` | `Promise`\<`Invite`> | - |
| `invite.getInvites` | `public` | `Promise`\<[`PaginatedInvitesResponse`](/docs/reference/sdk/routes/invite#paginatedinvitesresponse)> | - |
| `invite.getInvitesForResource` | `public` | `Promise`\<`Invite`\[]> | - |
| `invite.inviteUser` | `public` | `Promise`\<`Invite`> | - |
| `invite.resendInvite` | `public` | `Promise`\<`Invite`> | - |
| `membership` | `readonly` | \{ `addRole`: `Promise`\<`Membership`>; `deleteMembership`: `Promise`\<`void`>; `getMyMemberships`: `Promise`\<`Membership`\[]>; `getProjectLastSeen`: `Promise`\<[`GetLastSeenResponse`](/docs/reference/sdk/routes/membership#getlastseenresponse)>; `getProjectMemberships`: `Promise`\<`MembershipReport`>; `getProjectMentionableUsers`: `Promise`\<`Mentionable`\[]>; `getWorkspaceLastSeen`: `Promise`\<[`GetLastSeenResponse`](/docs/reference/sdk/routes/membership#getlastseenresponse)>; `getWorkspaceMemberships`: `Promise`\<`MembershipReport`>; `leaveResource`: `Promise`\<`void`>; `removeRole`: `Promise`\<`Membership`>; } | - |
| `membership.addRole` | `public` | `Promise`\<`Membership`> | - |
| `membership.deleteMembership` | `public` | `Promise`\<`void`> | - |
| `membership.getMyMemberships` | `public` | `Promise`\<`Membership`\[]> | - |
| `membership.getProjectLastSeen` | `public` | `Promise`\<[`GetLastSeenResponse`](/docs/reference/sdk/routes/membership#getlastseenresponse)> | - |
| `membership.getProjectMemberships` | `public` | `Promise`\<`MembershipReport`> | - |
| `membership.getProjectMentionableUsers` | `public` | `Promise`\<`Mentionable`\[]> | - |
| `membership.getWorkspaceLastSeen` | `public` | `Promise`\<[`GetLastSeenResponse`](/docs/reference/sdk/routes/membership#getlastseenresponse)> | - |
| `membership.getWorkspaceMemberships` | `public` | `Promise`\<`MembershipReport`> | - |
| `membership.leaveResource` | `public` | `Promise`\<`void`> | - |
| `membership.removeRole` | `public` | `Promise`\<`Membership`> | - |
| `notification` | `readonly` | \{ `getNewNotificationCount`: `Promise`\<[`NotificationCountResponse`](/docs/reference/sdk/routes/notification#notificationcountresponse)>; `getNewNotificationCountBulk`: `Promise`\<[`NotificationCountBulkResponse`](/docs/reference/sdk/routes/notification#notificationcountbulkresponse)>; `getNewNotifications`: `Promise`\<[`PaginatedNotificationResponse`](/docs/reference/sdk/routes/notification#paginatednotificationresponse)>; `getNotifications`: `Promise`\<[`PaginatedNotificationResponse`](/docs/reference/sdk/routes/notification#paginatednotificationresponse)>; `getUsersLastNotificationsSeen`: `Promise`\<[`LastSeenResponse`](/docs/reference/sdk/routes/notification#lastseenresponse)>; `updateUsersLastSeen`: `Promise`\<[`LastSeenResponse`](/docs/reference/sdk/routes/notification#lastseenresponse)>; } | - |
| `notification.getNewNotificationCount` | `public` | `Promise`\<[`NotificationCountResponse`](/docs/reference/sdk/routes/notification#notificationcountresponse)> | - |
| `notification.getNewNotificationCountBulk` | `public` | `Promise`\<[`NotificationCountBulkResponse`](/docs/reference/sdk/routes/notification#notificationcountbulkresponse)> | - |
| `notification.getNewNotifications` | `public` | `Promise`\<[`PaginatedNotificationResponse`](/docs/reference/sdk/routes/notification#paginatednotificationresponse)> | - |
| `notification.getNotifications` | `public` | `Promise`\<[`PaginatedNotificationResponse`](/docs/reference/sdk/routes/notification#paginatednotificationresponse)> | - |
| `notification.getUsersLastNotificationsSeen` | `public` | `Promise`\<[`LastSeenResponse`](/docs/reference/sdk/routes/notification#lastseenresponse)> | - |
| `notification.updateUsersLastSeen` | `public` | `Promise`\<[`LastSeenResponse`](/docs/reference/sdk/routes/notification#lastseenresponse)> | - |
| `product` | `readonly` | \{ `getSuggestedCurrency`: `Promise`\<\{ `country`: `string` \| `null`; `currency`: [`SupportedCurrency`](/docs/reference/sdk/routes/product#supportedcurrency); `locked?`: `boolean`; `supported`: [`SupportedCurrency`](/docs/reference/sdk/routes/product#supportedcurrency)\[]; }>; `getWorkspaceProducts`: `Promise`\<`Product`\[]>; `listPlans`: `Promise`\<`Product`\[]>; } | - |
| `product.getSuggestedCurrency` | `public` | `Promise`\<\{ `country`: `string` \| `null`; `currency`: [`SupportedCurrency`](/docs/reference/sdk/routes/product#supportedcurrency); `locked?`: `boolean`; `supported`: [`SupportedCurrency`](/docs/reference/sdk/routes/product#supportedcurrency)\[]; }> | - |
| `product.getWorkspaceProducts` | `public` | `Promise`\<`Product`\[]> | - |
| `product.listPlans` | `public` | `Promise`\<`Product`\[]> | - |
| `project` | `readonly` | [`ProjectMethods`](/docs/reference/sdk/NuramaClient#projectmethods) | - |
| `public` | `readonly` | \{ `createPublicAssetChatMessage`: `Promise`\<`CreatePublicAssetChatMessageResponse`>; `createPublicChatMessage`: `Promise`\<`ChatMessage`>; `createPublicTopicChatMessage`: `Promise`\<`CreatePublicAssetChatMessageResponse`>; `downloadAssets`: `Promise`\<`DownloadSignedUrlData`\[]>; `getPublicAsset`: `Promise`\<`PublicAssetResponse`>; `getPublicChat`: `Promise`\<`Chat` \| `null`>; `getPublicChatMessages`: `Promise`\<`PublicChatMessagesResponse`>; `getPublicDownloadUrl`: `Promise`\<[`PublicDownloadUrlResponse`](/docs/reference/sdk/routes/shortlink#publicdownloadurlresponse)>; `getPublicEmbedFiles`: `Promise`\<[`PublicEmbedFilesResponse`](/docs/reference/sdk/routes/shortlink#publicembedfilesresponse)>; `getPublicFileSystem`: `Promise`\<[`PublicFileSystemDetailsResponse`](/docs/reference/sdk/routes/public#publicfilesystemdetailsresponse)>; `getPublicItems`: `Promise`\<[`PublicFileSystemResponse`](/docs/reference/sdk/routes/public#publicfilesystemresponse)>; `getPublicItemsAtPath`: `Promise`\<[`PublicFileSystemResponse`](/docs/reference/sdk/routes/public#publicfilesystemresponse)>; `recordAccessActivity`: `Promise`\<`void`>; `resolvePublicDownload`: `Promise`\<[`ResolvePublicDownloadResponse`](/docs/reference/sdk/routes/shortlink#resolvepublicdownloadresponse)>; } | - |
| `public.createPublicAssetChatMessage` | `public` | `Promise`\<`CreatePublicAssetChatMessageResponse`> | - |
| `public.createPublicChatMessage` | `public` | `Promise`\<`ChatMessage`> | - |
| `public.createPublicTopicChatMessage` | `public` | `Promise`\<`CreatePublicAssetChatMessageResponse`> | - |
| `public.downloadAssets` | `public` | `Promise`\<`DownloadSignedUrlData`\[]> | - |
| `public.getPublicAsset` | `public` | `Promise`\<`PublicAssetResponse`> | - |
| `public.getPublicChat` | `public` | `Promise`\<`Chat` \| `null`> | - |
| `public.getPublicChatMessages` | `public` | `Promise`\<`PublicChatMessagesResponse`> | - |
| `public.getPublicDownloadUrl` | `public` | `Promise`\<[`PublicDownloadUrlResponse`](/docs/reference/sdk/routes/shortlink#publicdownloadurlresponse)> | - |
| `public.getPublicEmbedFiles` | `public` | `Promise`\<[`PublicEmbedFilesResponse`](/docs/reference/sdk/routes/shortlink#publicembedfilesresponse)> | - |
| `public.getPublicFileSystem` | `public` | `Promise`\<[`PublicFileSystemDetailsResponse`](/docs/reference/sdk/routes/public#publicfilesystemdetailsresponse)> | - |
| `public.getPublicItems` | `public` | `Promise`\<[`PublicFileSystemResponse`](/docs/reference/sdk/routes/public#publicfilesystemresponse)> | - |
| `public.getPublicItemsAtPath` | `public` | `Promise`\<[`PublicFileSystemResponse`](/docs/reference/sdk/routes/public#publicfilesystemresponse)> | - |
| `public.recordAccessActivity` | `public` | `Promise`\<`void`> | - |
| `public.resolvePublicDownload` | `public` | `Promise`\<[`ResolvePublicDownloadResponse`](/docs/reference/sdk/routes/shortlink#resolvepublicdownloadresponse)> | - |
| `settings` | `readonly` | \{ `cleanupOrphanedSettings`: `Promise`\<\{ `message`: `string`; `removedCount`: `number`; }>; `getAllResourceSettings`: `Promise`\<\{ `resourceSettings`: [`ResourceSettings`](/docs/reference/sdk/routes/settings#resourcesettings)\[]; }>; `getEffectiveSettings`: `Promise`\<[`EffectiveSettings`](/docs/reference/sdk/routes/settings#effectivesettings)>; `getResourceSettings`: `Promise`\< \| [`ResourceSettings`](/docs/reference/sdk/routes/settings#resourcesettings) \| \{ `message`: `string`; }>; `resetResourceSettings`: `Promise`\<\{ `message`: `string`; }>; `updateResourceSettings`: `Promise`\<\{ `message`: `string`; `settings`: [`ResourceSettings`](/docs/reference/sdk/routes/settings#resourcesettings); }>; } | - |
| `settings.cleanupOrphanedSettings` | `public` | `Promise`\<\{ `message`: `string`; `removedCount`: `number`; }> | - |
| `settings.getAllResourceSettings` | `public` | `Promise`\<\{ `resourceSettings`: [`ResourceSettings`](/docs/reference/sdk/routes/settings#resourcesettings)\[]; }> | - |
| `settings.getEffectiveSettings` | `public` | `Promise`\<[`EffectiveSettings`](/docs/reference/sdk/routes/settings#effectivesettings)> | - |
| `settings.getResourceSettings` | `public` | `Promise`\< \| [`ResourceSettings`](/docs/reference/sdk/routes/settings#resourcesettings) \| \{ `message`: `string`; }> | - |
| `settings.resetResourceSettings` | `public` | `Promise`\<\{ `message`: `string`; }> | - |
| `settings.updateResourceSettings` | `public` | `Promise`\<\{ `message`: `string`; `settings`: [`ResourceSettings`](/docs/reference/sdk/routes/settings#resourcesettings); }> | - |
| `shortlink` | `readonly` | \{ `resolveShortLink`: `Promise`\<[`ResolveShortLinkResponse`](/docs/reference/sdk/routes/shortlink#resolveshortlinkresponse)>; } | - |
| `shortlink.resolveShortLink` | `public` | `Promise`\<[`ResolveShortLinkResponse`](/docs/reference/sdk/routes/shortlink#resolveshortlinkresponse)> | - |
| `socket` | `readonly` | \{ `connect`: (`channel`, `options`) => `Promise`\<[`SocketChannel`](/docs/reference/sdk/routes/socket#socketchannel)>; `connectPublic`: (`publicToken`, `options`) => `Promise`\<[`SocketChannel`](/docs/reference/sdk/routes/socket#socketchannel)>; `disconnect`: (`channel`) => `Promise`\<`void`>; `disconnectAll`: () => `Promise`\<`void`>; `emit`: (`channel`, `event`, `data?`) => `void`; `emitWithAck`: (`channel`, `event`, `data`, `timeoutMs`) => `Promise`\<`boolean`>; `isConnected`: (`channel`) => `boolean`; `onReconnect`: (`channel`, `callback`) => `void`; `onReconnectFailed`: (`channel`, `callback`) => `void`; `subscribe`: \<`T`>(`channel`, `event`, `callback`) => `Promise`\<`void`>; `subscribePublic`: \<`T`>(`publicToken`, `event`, `callback`) => `Promise`\<`void`>; `unsubscribe`: (`channel`, `event`, `callback?`) => `void`; } | - |
| `socket.connect` | `public` | (`channel`, `options`) => `Promise`\<[`SocketChannel`](/docs/reference/sdk/routes/socket#socketchannel)> | Connect to a socket channel |
| `socket.connectPublic` | `public` | (`publicToken`, `options`) => `Promise`\<[`SocketChannel`](/docs/reference/sdk/routes/socket#socketchannel)> | Connect to a public socket channel without authentication |
| `socket.disconnect` | `public` | (`channel`) => `Promise`\<`void`> | Disconnect from a socket channel |
| `socket.disconnectAll` | `public` | () => `Promise`\<`void`> | Disconnect from all channels |
| `socket.emit` | `public` | (`channel`, `event`, `data?`) => `void` | Emit an event to a connected channel |
| `socket.emitWithAck` | `public` | (`channel`, `event`, `data`, `timeoutMs`) => `Promise`\<`boolean`> | Emit an event with a timeout-bounded server acknowledgement. Resolves `true` if the server acks within `timeoutMs`, `false` on timeout or transport error. Use it to actively verify a channel's liveness when `socket.connected` may be stale — most notably after a backgrounded tab returns to focus, where the flag can remain `true` for up to socket.io's own heartbeat window (\~25–45s) even after the underlying TCP transport has died. Relies on socket.io v4's `socket.timeout(ms).emit(ev, data, cb)` pattern: the server acknowledges the event via its trailing callback; if no ack arrives within `timeoutMs` the callback receives an Error. |
| `socket.isConnected` | `public` | (`channel`) => `boolean` | Check if connected to a channel |
| `socket.onReconnect` | `public` | (`channel`, `callback`) => `void` | Register a callback for when the channel reconnects — a socket.io transport-level reconnect, or the token-refresh reconnect. Use it to recover any gap of server->client messages missed while the connection was down; socket.io does not replay those. Dispatched from the 'reconnect' handler in connect() and from the token-refresh path. |
| `socket.onReconnectFailed` | `public` | (`channel`, `callback`) => `void` | Register a callback for when Socket.IO exhausts all reconnection attempts |
| `socket.subscribe` | `public` | \<`T`>(`channel`, `event`, `callback`) => `Promise`\<`void`> | Subscribe to an event on a channel |
| `socket.subscribePublic` | `public` | \<`T`>(`publicToken`, `event`, `callback`) => `Promise`\<`void`> | Subscribe to an event on a public channel Automatically connects to the public channel if not already connected |
| `socket.unsubscribe` | `public` | (`channel`, `event`, `callback?`) => `void` | Stop listening for an event on a channel. If `callback` is provided, only that specific listener is removed; otherwise every listener for that event is cleared. |
| `storage` | `readonly` | \{ `getStorageChart`: `Promise`\<[`ChartDataResponse`](/docs/reference/sdk/routes/storage#chartdataresponse)>; `getStorageRecord`: `Promise`\<[`StorageRecord`](/docs/reference/sdk/routes/storage#storagerecord)>; } | - |
| `storage.getStorageChart` | `public` | `Promise`\<[`ChartDataResponse`](/docs/reference/sdk/routes/storage#chartdataresponse)> | - |
| `storage.getStorageRecord` | `public` | `Promise`\<[`StorageRecord`](/docs/reference/sdk/routes/storage#storagerecord)> | - |
| `tag` | `readonly` | \{ `createTag`: `Promise`\<`Tag`>; `deleteTag`: `Promise`\<`Tag`>; `getTags`: `Promise`\<[`Tags`](/docs/reference/sdk/routes/tag#tags)>; `updateTag`: `Promise`\<`Tag`>; } | - |
| `tag.createTag` | `public` | `Promise`\<`Tag`> | - |
| `tag.deleteTag` | `public` | `Promise`\<`Tag`> | - |
| `tag.getTags` | `public` | `Promise`\<[`Tags`](/docs/reference/sdk/routes/tag#tags)> | - |
| `tag.updateTag` | `public` | `Promise`\<`Tag`> | - |
| `task` | `readonly` | \{ `acknowledgeAllTasks`: `Promise`\<[`AcknowledgeAllTasksResponse`](/docs/reference/sdk/routes/task#acknowledgealltasksresponse)>; `acknowledgeTask`: `Promise`\<`Task`>; `bulkCreate`: `Promise`\<[`BulkCreateTasksResponse`](/docs/reference/sdk/routes/task#bulkcreatetasksresponse)>; `deleteTask`: `Promise`\<`void`>; `followTask`: `Promise`\<`Task`>; `getMyTasks`: `Promise`\<[`GetTasksResponse`](/docs/reference/sdk/routes/task#gettasksresponse)>; `getTaskEvents`: `Promise`\<[`GetTaskEventsResponse`](/docs/reference/sdk/routes/task#gettaskeventsresponse)>; `getTaskLinks`: `Promise`\<`TaskLink`\[]>; `getUnacknowledgedTaskCount`: `Promise`\<[`UnacknowledgedTaskCountResponse`](/docs/reference/sdk/routes/task#unacknowledgedtaskcountresponse)>; `linkTask`: `Promise`\<`TaskLink`>; `tagTask`: `Promise`\<`Task`>; `unfollowTask`: `Promise`\<`Task`>; `unlinkTask`: `Promise`\<`void`>; `untagTask`: `Promise`\<`Task`>; `updateTaskDetails`: `Promise`\<`Task`>; `updateTaskStatus`: `Promise`\<`Task`>; } | - |
| `task.acknowledgeAllTasks` | `public` | `Promise`\<[`AcknowledgeAllTasksResponse`](/docs/reference/sdk/routes/task#acknowledgealltasksresponse)> | - |
| `task.acknowledgeTask` | `public` | `Promise`\<`Task`> | - |
| `task.bulkCreate` | `public` | `Promise`\<[`BulkCreateTasksResponse`](/docs/reference/sdk/routes/task#bulkcreatetasksresponse)> | - |
| `task.deleteTask` | `public` | `Promise`\<`void`> | - |
| `task.followTask` | `public` | `Promise`\<`Task`> | - |
| `task.getMyTasks` | `public` | `Promise`\<[`GetTasksResponse`](/docs/reference/sdk/routes/task#gettasksresponse)> | - |
| `task.getTaskEvents` | `public` | `Promise`\<[`GetTaskEventsResponse`](/docs/reference/sdk/routes/task#gettaskeventsresponse)> | - |
| `task.getTaskLinks` | `public` | `Promise`\<`TaskLink`\[]> | - |
| `task.getUnacknowledgedTaskCount` | `public` | `Promise`\<[`UnacknowledgedTaskCountResponse`](/docs/reference/sdk/routes/task#unacknowledgedtaskcountresponse)> | - |
| `task.linkTask` | `public` | `Promise`\<`TaskLink`> | - |
| `task.tagTask` | `public` | `Promise`\<`Task`> | - |
| `task.unfollowTask` | `public` | `Promise`\<`Task`> | - |
| `task.unlinkTask` | `public` | `Promise`\<`void`> | - |
| `task.untagTask` | `public` | `Promise`\<`Task`> | - |
| `task.updateTaskDetails` | `public` | `Promise`\<`Task`> | - |
| `task.updateTaskStatus` | `public` | `Promise`\<`Task`> | - |
| `taskRelation` | `readonly` | \{ `createTaskRelation`: `Promise`\<[`TaskRelation`](/docs/reference/sdk/routes/taskRelation#taskrelation)>; `deleteTaskRelation`: `Promise`\<`void`>; `getRelationsForChat`: `Promise`\<[`PaginatedTaskRelations`](/docs/reference/sdk/routes/taskRelation#paginatedtaskrelations)>; `getRelationsForMessage`: `Promise`\<[`PaginatedTaskRelations`](/docs/reference/sdk/routes/taskRelation#paginatedtaskrelations)>; `getTaskRelations`: `Promise`\<[`PaginatedTaskRelations`](/docs/reference/sdk/routes/taskRelation#paginatedtaskrelations)>; } | - |
| `taskRelation.createTaskRelation` | `public` | `Promise`\<[`TaskRelation`](/docs/reference/sdk/routes/taskRelation#taskrelation)> | - |
| `taskRelation.deleteTaskRelation` | `public` | `Promise`\<`void`> | - |
| `taskRelation.getRelationsForChat` | `public` | `Promise`\<[`PaginatedTaskRelations`](/docs/reference/sdk/routes/taskRelation#paginatedtaskrelations)> | - |
| `taskRelation.getRelationsForMessage` | `public` | `Promise`\<[`PaginatedTaskRelations`](/docs/reference/sdk/routes/taskRelation#paginatedtaskrelations)> | - |
| `taskRelation.getTaskRelations` | `public` | `Promise`\<[`PaginatedTaskRelations`](/docs/reference/sdk/routes/taskRelation#paginatedtaskrelations)> | - |
| `version` | `readonly` | \{ `getCommitHash`: `Promise`\<[`CommitResponse`](/docs/reference/sdk/routes/version#commitresponse)>; `getHealth`: `Promise`\<[`HealthStatus`](/docs/reference/sdk/routes/version#healthstatus)>; } | - |
| `version.getCommitHash` | `public` | `Promise`\<[`CommitResponse`](/docs/reference/sdk/routes/version#commitresponse)> | - |
| `version.getHealth` | `public` | `Promise`\<[`HealthStatus`](/docs/reference/sdk/routes/version#healthstatus)> | - |
| `workspace` | `readonly` | [`WorkspaceMethods`](/docs/reference/sdk/NuramaClient#workspacemethods) | - |
## Interfaces [#interfaces]
### BotClientOptions [#botclientoptions]
#### Properties [#properties-1]
| Property | Type | Description |
| ------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `baseURL?` | `string` | Override the default bot API URL ([https://bot.nurama.com](https://bot.nurama.com)). |
| `cacheDurationSeconds?` | `number` | Cache duration in seconds. Default: 5 |
| `debug?` | `boolean` | Enable debug logging. Default: false |
| `enableCache?` | `boolean` | Enable response caching. Default: true |
| `fetch?` | (`input`, `init?`) => `Promise`\<`Response`> | Custom fetch implementation. Defaults to global fetch. |
| `websocketURL?` | `string` | Override the default bot WebSocket URL ([https://bot-ws.nurama.com](https://bot-ws.nurama.com)). |
# NuramaClient (/docs/reference/sdk/NuramaClient)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
## Classes [#classes]
### default [#default]
Client interface for interacting with the Nurama REST API.
#### Constructors [#constructors]
##### Constructor [#constructor]
```ts
new default(baseURL, options?): default;
```
Creates an instance of NuramaClient.
###### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | --------------------------------------------- | -------------------------------- |
| `baseURL` | `string` | The base URL for the Nurama API. |
| `options` | [`NuramaClientOptions`](#nuramaclientoptions) | Configuration options. |
###### Returns [#returns]
[`default`](#default)
#### Properties [#properties]
| Property | Modifier | Type | Default value | Description |
| ---------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ai` | `public` | \{ `composeWithNu`: `Promise`\<[`ComposeWithNuResponse`](/docs/reference/sdk/routes/ai#composewithnuresponse)>; `createRevisionSourceUpload`: `Promise`\<[`CreateRevisionSourceUploadResponse`](/docs/reference/sdk/routes/ai#createrevisionsourceuploadresponse)>; `generateRevision`: `Promise`\<[`GenerateImageRevisionResponse`](/docs/reference/sdk/routes/ai#generateimagerevisionresponse)>; `generateTasks`: `Promise`\<[`GenerateTasksResponse`](/docs/reference/sdk/routes/ai#generatetasksresponse)>; `listTones`: `Promise`\<[`ListTonesResponse`](/docs/reference/sdk/routes/ai#listtonesresponse)>; `polish`: `Promise`\<[`PolishResponse`](/docs/reference/sdk/routes/ai#polishresponse)>; `submitFeedback`: `Promise`\<\{ `id`: `string`; }>; } | `undefined` | - |
| `ai.composeWithNu` | `public` | `Promise`\<[`ComposeWithNuResponse`](/docs/reference/sdk/routes/ai#composewithnuresponse)> | `undefined` | - |
| `ai.createRevisionSourceUpload` | `public` | `Promise`\<[`CreateRevisionSourceUploadResponse`](/docs/reference/sdk/routes/ai#createrevisionsourceuploadresponse)> | `undefined` | - |
| `ai.generateRevision` | `public` | `Promise`\<[`GenerateImageRevisionResponse`](/docs/reference/sdk/routes/ai#generateimagerevisionresponse)> | `undefined` | - |
| `ai.generateTasks` | `public` | `Promise`\<[`GenerateTasksResponse`](/docs/reference/sdk/routes/ai#generatetasksresponse)> | `undefined` | - |
| `ai.listTones` | `public` | `Promise`\<[`ListTonesResponse`](/docs/reference/sdk/routes/ai#listtonesresponse)> | `undefined` | - |
| `ai.polish` | `public` | `Promise`\<[`PolishResponse`](/docs/reference/sdk/routes/ai#polishresponse)> | `undefined` | - |
| `ai.submitFeedback` | `public` | `Promise`\<\{ `id`: `string`; }> | `undefined` | - |
| `aiChat` | `public` | \{ `createTopic`: `Promise`\<`AiChatCreateTopicResponse`>; `deleteTopic`: `Promise`\<`AiChatGetTopicResponse`>; `getTopic`: `Promise`\<`AiChatGetTopicResponse`>; `listTopics`: `Promise`\<`AiChatListTopicsResponse`>; `updateTopic`: `Promise`\<`AiChatGetTopicResponse`>; } | `undefined` | - |
| `aiChat.createTopic` | `public` | `Promise`\<`AiChatCreateTopicResponse`> | `undefined` | - |
| `aiChat.deleteTopic` | `public` | `Promise`\<`AiChatGetTopicResponse`> | `undefined` | - |
| `aiChat.getTopic` | `public` | `Promise`\<`AiChatGetTopicResponse`> | `undefined` | - |
| `aiChat.listTopics` | `public` | `Promise`\<`AiChatListTopicsResponse`> | `undefined` | - |
| `aiChat.updateTopic` | `public` | `Promise`\<`AiChatGetTopicResponse`> | `undefined` | - |
| `asset` | `readonly` | [`AssetMethods`](#assetmethods) | `undefined` | - |
| `auth` | `readonly` | [`AuthMethods`](#authmethods) | `undefined` | - |
| `baseURL` | `readonly` | `string` | `undefined` | - |
| `blogPosts` | `public` | \{ `listBlogPosts`: `Promise`\<`BlogPostListResponse`>; } | `undefined` | - |
| `blogPosts.listBlogPosts` | `public` | `Promise`\<`BlogPostListResponse`> | `undefined` | - |
| `board` | `public` | \{ `addColumn`: `Promise`\<`BoardColumn`>; `addExistingTaskToBoard`: `Promise`\<`Task`>; `createBoard`: `Promise`\<`Board`>; `createBoardTask`: `Promise`\<`Task`>; `deleteBoard`: `Promise`\<\{ `deletedTaskIds`: `string`\[]; `disposition`: `string`; `message`: `string`; `reassignedTaskIds`: `string`\[]; }>; `deleteColumn`: `Promise`\<`void`>; `followBoard`: `Promise`\<`Board`>; `getBoard`: `Promise`\<`BoardWithTasks`>; `getBoardTasks`: `Promise`\<`Task`\[]>; `getProjectBoards`: `Promise`\<`Board`\[]>; `getProjectTasks`: `Promise`\<`any`>; `moveTask`: `Promise`\<`Task`>; `removeTaskFromBoard`: `Promise`\<`Task`>; `reorderColumns`: `Promise`\<`BoardColumn`\[]>; `tagBoard`: `Promise`\<`Board`>; `unfollowBoard`: `Promise`\<`Board`>; `untagBoard`: `Promise`\<`Board`>; `updateBoard`: `Promise`\<`Board`>; `updateColumn`: `Promise`\<`BoardColumn`>; } | `undefined` | - |
| `board.addColumn` | `public` | `Promise`\<`BoardColumn`> | `undefined` | - |
| `board.addExistingTaskToBoard` | `public` | `Promise`\<`Task`> | `undefined` | - |
| `board.createBoard` | `public` | `Promise`\<`Board`> | `undefined` | - |
| `board.createBoardTask` | `public` | `Promise`\<`Task`> | `undefined` | - |
| `board.deleteBoard` | `public` | `Promise`\<\{ `deletedTaskIds`: `string`\[]; `disposition`: `string`; `message`: `string`; `reassignedTaskIds`: `string`\[]; }> | `undefined` | - |
| `board.deleteColumn` | `public` | `Promise`\<`void`> | `undefined` | - |
| `board.followBoard` | `public` | `Promise`\<`Board`> | `undefined` | - |
| `board.getBoard` | `public` | `Promise`\<`BoardWithTasks`> | `undefined` | - |
| `board.getBoardTasks` | `public` | `Promise`\<`Task`\[]> | `undefined` | - |
| `board.getProjectBoards` | `public` | `Promise`\<`Board`\[]> | `undefined` | - |
| `board.getProjectTasks` | `public` | `Promise`\<`any`> | `undefined` | - |
| `board.moveTask` | `public` | `Promise`\<`Task`> | `undefined` | - |
| `board.removeTaskFromBoard` | `public` | `Promise`\<`Task`> | `undefined` | - |
| `board.reorderColumns` | `public` | `Promise`\<`BoardColumn`\[]> | `undefined` | - |
| `board.tagBoard` | `public` | `Promise`\<`Board`> | `undefined` | - |
| `board.unfollowBoard` | `public` | `Promise`\<`Board`> | `undefined` | - |
| `board.untagBoard` | `public` | `Promise`\<`Board`> | `undefined` | - |
| `board.updateBoard` | `public` | `Promise`\<`Board`> | `undefined` | - |
| `board.updateColumn` | `public` | `Promise`\<`BoardColumn`> | `undefined` | - |
| `bot` | `public` | \{ `createBot`: `Promise`\<[`CreateBotResponse`](/docs/reference/sdk/routes/bot#createbotresponse)>; `deleteBot`: `Promise`\<`void`>; `getBot`: `Promise`\<[`Bot`](/docs/reference/sdk/routes/bot#bot)>; `listBots`: `Promise`\<[`Bot`](/docs/reference/sdk/routes/bot#bot)\[]>; `listProjectMemberships`: `Promise`\<[`BotProjectMembership`](/docs/reference/sdk/routes/bot#botprojectmembership)\[]>; `removeProjectMembership`: `Promise`\<`void`>; `rotateBotKey`: `Promise`\<[`RotateBotKeyResponse`](/docs/reference/sdk/routes/bot#rotatebotkeyresponse)>; `setProjectMembership`: `Promise`\<[`BotProjectMembership`](/docs/reference/sdk/routes/bot#botprojectmembership)>; `updateBot`: `Promise`\<[`Bot`](/docs/reference/sdk/routes/bot#bot)>; `updateBotAvatar`: `Promise`\<[`UpdateBotAvatarResponse`](/docs/reference/sdk/routes/bot#updatebotavatarresponse)>; } | `undefined` | - |
| `bot.createBot` | `public` | `Promise`\<[`CreateBotResponse`](/docs/reference/sdk/routes/bot#createbotresponse)> | `undefined` | - |
| `bot.deleteBot` | `public` | `Promise`\<`void`> | `undefined` | - |
| `bot.getBot` | `public` | `Promise`\<[`Bot`](/docs/reference/sdk/routes/bot#bot)> | `undefined` | - |
| `bot.listBots` | `public` | `Promise`\<[`Bot`](/docs/reference/sdk/routes/bot#bot)\[]> | `undefined` | - |
| `bot.listProjectMemberships` | `public` | `Promise`\<[`BotProjectMembership`](/docs/reference/sdk/routes/bot#botprojectmembership)\[]> | `undefined` | - |
| `bot.removeProjectMembership` | `public` | `Promise`\<`void`> | `undefined` | - |
| `bot.rotateBotKey` | `public` | `Promise`\<[`RotateBotKeyResponse`](/docs/reference/sdk/routes/bot#rotatebotkeyresponse)> | `undefined` | - |
| `bot.setProjectMembership` | `public` | `Promise`\<[`BotProjectMembership`](/docs/reference/sdk/routes/bot#botprojectmembership)> | `undefined` | - |
| `bot.updateBot` | `public` | `Promise`\<[`Bot`](/docs/reference/sdk/routes/bot#bot)> | `undefined` | - |
| `bot.updateBotAvatar` | `public` | `Promise`\<[`UpdateBotAvatarResponse`](/docs/reference/sdk/routes/bot#updatebotavatarresponse)> | `undefined` | - |
| `browserMode` | `readonly` | `boolean` | `false` | - |
| `cacheDurationSeconds` | `readonly` | `number` | `undefined` | - |
| `chat` | `public` | \{ `addAttachments`: `Promise`\<[`AttachmentUploadRecord`](/docs/reference/sdk/routes/chat#attachmentuploadrecord)\[]>; `addMembers`: `Promise`\<`ChatMember`>; `archiveMemberChat`: `Promise`\<`ChatMember`>; `createAssetChatAndMessage`: `Promise`\<`any`>; `createMemberChat`: `Promise`\<`ChatMember`>; `createMessage`: `Promise`\<`ChatMessage`>; `createMessageShortLink`: `Promise`\<\{ `code`: `string`; `shortUrl`: `string`; }>; `createReaction`: `Promise`\<`ChatMessage`>; `createTopicChat`: `Promise`\<`Chat`>; `deleteChat`: `Promise`\<`void`>; `deleteMemberChat`: `Promise`\<`void`>; `deleteMessage`: `Promise`\<`ChatMessage`>; `fetchLinkPreviews`: `Promise`\<[`LinkPreviewResponse`](/docs/reference/sdk/routes/chat#linkpreviewresponse)>; `followChat`: `Promise`\<`void`>; `getAddableMembers`: `Promise`\< \| [`AddableMembersByScope`](/docs/reference/sdk/routes/chat#addablemembersbyscope) \| `Membership`\[]>; `getChat`: `Promise`\<`Chat`>; `getChatByTopicId`: `Promise`\<`Chat`>; `getMemberChat`: `Promise`\<`ChatMember`>; `getMentionableAssets`: `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/chat#paginatedresponse)\<`Asset`>>; `getMentionableFolders`: `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/chat#paginatedresponse)\<`Folder`>>; `getMentionablePublics`: `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/chat#paginatedresponse)\<[`MentionablePublic`](/docs/reference/sdk/routes/chat#mentionablepublic)>>; `getMentionableSubmissions`: `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/chat#paginatedresponse)\<[`MentionableSubmission`](/docs/reference/sdk/routes/chat#mentionablesubmission)>>; `getMentionableTasks`: `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/chat#paginatedresponse)\<`any`>>; `getMentions`: `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/chat#paginatedresponse)\<`ChatMessage`>>; `getMessage`: `Promise`\<`ChatMessage`>; `getMessages`: `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/chat#paginatedresponse)\<`ChatMessage`>>; `getReplies`: `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/chat#paginatedresponse)\<`ChatMessage`>>; `getScopeAddableMembers`: `Promise`\< \| [`AddableMembersByScope`](/docs/reference/sdk/routes/chat#addablemembersbyscope) \| `Membership`\[]>; `getUsersMemberChats`: `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/chat#paginatedresponse)\<`ChatMember`>>; `getWorkspaceProjectChats`: `Promise`\<`any`\[]>; `highlightMessage`: `Promise`\<`ChatMessage`>; `removeAttachment`: `Promise`\<`ChatMessage`>; `removeMembers`: `Promise`\<`ChatMember`>; `removeReaction`: `Promise`\<`ChatMessage`>; `reviseMessage`: `Promise`\<`ChatMessage`>; `unarchiveMemberChat`: `Promise`\<`ChatMember`>; `unfollowChat`: `Promise`\<`void`>; `unhighlightMessage`: `Promise`\<`ChatMessage`>; `updateChatSubject`: `Promise`\<`Chat`>; `updateMemberChat`: `Promise`\<`ChatMember`>; `updateMemberChatIcon`: `Promise`\<\{ `chat`: `ChatMember`; } & [`AttachmentUploadRecord`](/docs/reference/sdk/routes/chat#attachmentuploadrecord)>; } | `undefined` | - |
| `chat.addAttachments` | `public` | `Promise`\<[`AttachmentUploadRecord`](/docs/reference/sdk/routes/chat#attachmentuploadrecord)\[]> | `undefined` | - |
| `chat.addMembers` | `public` | `Promise`\<`ChatMember`> | `undefined` | - |
| `chat.archiveMemberChat` | `public` | `Promise`\<`ChatMember`> | `undefined` | - |
| `chat.createAssetChatAndMessage` | `public` | `Promise`\<`any`> | `undefined` | - |
| `chat.createMemberChat` | `public` | `Promise`\<`ChatMember`> | `undefined` | - |
| `chat.createMessage` | `public` | `Promise`\<`ChatMessage`> | `undefined` | - |
| `chat.createMessageShortLink` | `public` | `Promise`\<\{ `code`: `string`; `shortUrl`: `string`; }> | `undefined` | - |
| `chat.createReaction` | `public` | `Promise`\<`ChatMessage`> | `undefined` | - |
| `chat.createTopicChat` | `public` | `Promise`\<`Chat`> | `undefined` | - |
| `chat.deleteChat` | `public` | `Promise`\<`void`> | `undefined` | - |
| `chat.deleteMemberChat` | `public` | `Promise`\<`void`> | `undefined` | - |
| `chat.deleteMessage` | `public` | `Promise`\<`ChatMessage`> | `undefined` | - |
| `chat.fetchLinkPreviews` | `public` | `Promise`\<[`LinkPreviewResponse`](/docs/reference/sdk/routes/chat#linkpreviewresponse)> | `undefined` | - |
| `chat.followChat` | `public` | `Promise`\<`void`> | `undefined` | - |
| `chat.getAddableMembers` | `public` | `Promise`\< \| [`AddableMembersByScope`](/docs/reference/sdk/routes/chat#addablemembersbyscope) \| `Membership`\[]> | `undefined` | - |
| `chat.getChat` | `public` | `Promise`\<`Chat`> | `undefined` | - |
| `chat.getChatByTopicId` | `public` | `Promise`\<`Chat`> | `undefined` | - |
| `chat.getMemberChat` | `public` | `Promise`\<`ChatMember`> | `undefined` | - |
| `chat.getMentionableAssets` | `public` | `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/chat#paginatedresponse)\<`Asset`>> | `undefined` | - |
| `chat.getMentionableFolders` | `public` | `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/chat#paginatedresponse)\<`Folder`>> | `undefined` | - |
| `chat.getMentionablePublics` | `public` | `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/chat#paginatedresponse)\<[`MentionablePublic`](/docs/reference/sdk/routes/chat#mentionablepublic)>> | `undefined` | - |
| `chat.getMentionableSubmissions` | `public` | `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/chat#paginatedresponse)\<[`MentionableSubmission`](/docs/reference/sdk/routes/chat#mentionablesubmission)>> | `undefined` | - |
| `chat.getMentionableTasks` | `public` | `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/chat#paginatedresponse)\<`any`>> | `undefined` | - |
| `chat.getMentions` | `public` | `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/chat#paginatedresponse)\<`ChatMessage`>> | `undefined` | - |
| `chat.getMessage` | `public` | `Promise`\<`ChatMessage`> | `undefined` | - |
| `chat.getMessages` | `public` | `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/chat#paginatedresponse)\<`ChatMessage`>> | `undefined` | - |
| `chat.getReplies` | `public` | `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/chat#paginatedresponse)\<`ChatMessage`>> | `undefined` | - |
| `chat.getScopeAddableMembers` | `public` | `Promise`\< \| [`AddableMembersByScope`](/docs/reference/sdk/routes/chat#addablemembersbyscope) \| `Membership`\[]> | `undefined` | - |
| `chat.getUsersMemberChats` | `public` | `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/chat#paginatedresponse)\<`ChatMember`>> | `undefined` | - |
| `chat.getWorkspaceProjectChats` | `public` | `Promise`\<`any`\[]> | `undefined` | - |
| `chat.highlightMessage` | `public` | `Promise`\<`ChatMessage`> | `undefined` | - |
| `chat.removeAttachment` | `public` | `Promise`\<`ChatMessage`> | `undefined` | - |
| `chat.removeMembers` | `public` | `Promise`\<`ChatMember`> | `undefined` | - |
| `chat.removeReaction` | `public` | `Promise`\<`ChatMessage`> | `undefined` | - |
| `chat.reviseMessage` | `public` | `Promise`\<`ChatMessage`> | `undefined` | - |
| `chat.unarchiveMemberChat` | `public` | `Promise`\<`ChatMember`> | `undefined` | - |
| `chat.unfollowChat` | `public` | `Promise`\<`void`> | `undefined` | - |
| `chat.unhighlightMessage` | `public` | `Promise`\<`ChatMessage`> | `undefined` | - |
| `chat.updateChatSubject` | `public` | `Promise`\<`Chat`> | `undefined` | - |
| `chat.updateMemberChat` | `public` | `Promise`\<`ChatMember`> | `undefined` | - |
| `chat.updateMemberChatIcon` | `public` | `Promise`\<\{ `chat`: `ChatMember`; } & [`AttachmentUploadRecord`](/docs/reference/sdk/routes/chat#attachmentuploadrecord)> | `undefined` | - |
| `config` | `readonly` | [`ConfigMethods`](/docs/reference/sdk/routes/config#configmethods) | `undefined` | - |
| `convo` | `public` | \{ `completeConvo`: `Promise`\<`CompleteConvoResponse`>; `deleteConvo`: `Promise`\<`void`>; `getChatConvos`: `Promise`\<`Convo`\[]>; `getConvo`: `Promise`\<`GetConvoResponse`>; `getProjectConvos`: `Promise`\<`Convo`\[]>; `getScopeConvos`: `Promise`\<`GetScopeConvosResponse`>; `joinConvo`: `Promise`\<`JoinConvoResponse`>; `leaveConvo`: `Promise`\<`LeaveConvoResponse`>; `rejoinConvo`: `Promise`\<`JoinConvoResponse`>; `startConvo`: `Promise`\<`StartConvoResponse`>; `updateConvo`: `Promise`\<`UpdateConvoResponse`>; } | `undefined` | - |
| `convo.completeConvo` | `public` | `Promise`\<`CompleteConvoResponse`> | `undefined` | - |
| `convo.deleteConvo` | `public` | `Promise`\<`void`> | `undefined` | - |
| `convo.getChatConvos` | `public` | `Promise`\<`Convo`\[]> | `undefined` | - |
| `convo.getConvo` | `public` | `Promise`\<`GetConvoResponse`> | `undefined` | - |
| `convo.getProjectConvos` | `public` | `Promise`\<`Convo`\[]> | `undefined` | - |
| `convo.getScopeConvos` | `public` | `Promise`\<`GetScopeConvosResponse`> | `undefined` | - |
| `convo.joinConvo` | `public` | `Promise`\<`JoinConvoResponse`> | `undefined` | - |
| `convo.leaveConvo` | `public` | `Promise`\<`LeaveConvoResponse`> | `undefined` | - |
| `convo.rejoinConvo` | `public` | `Promise`\<`JoinConvoResponse`> | `undefined` | - |
| `convo.startConvo` | `public` | `Promise`\<`StartConvoResponse`> | `undefined` | - |
| `convo.updateConvo` | `public` | `Promise`\<`UpdateConvoResponse`> | `undefined` | - |
| `credits` | `public` | \{ `getBalance`: `Promise`\<[`GetBalanceResponse`](/docs/reference/sdk/routes/credits#getbalanceresponse)>; `getUsageReport`: `Promise`\<[`UsageReportResponse`](/docs/reference/sdk/routes/credits#usagereportresponse)>; } | `undefined` | - |
| `credits.getBalance` | `public` | `Promise`\<[`GetBalanceResponse`](/docs/reference/sdk/routes/credits#getbalanceresponse)> | `undefined` | - |
| `credits.getUsageReport` | `public` | `Promise`\<[`UsageReportResponse`](/docs/reference/sdk/routes/credits#usagereportresponse)> | `undefined` | - |
| `debug` | `readonly` | `boolean` | `undefined` | - |
| `device` | `public` | \{ `deleteDevice`: `Promise`\<`void`>; `getDevice`: `Promise`\<`Device`>; `getUserDevices`: `Promise`\<`Device`\[]>; `registerDevice`: `Promise`\<`Device`>; `updateDevice`: `Promise`\<`Device`>; } | `undefined` | - |
| `device.deleteDevice` | `public` | `Promise`\<`void`> | `undefined` | - |
| `device.getDevice` | `public` | `Promise`\<`Device`> | `undefined` | - |
| `device.getUserDevices` | `public` | `Promise`\<`Device`\[]> | `undefined` | - |
| `device.registerDevice` | `public` | `Promise`\<`Device`> | `undefined` | - |
| `device.updateDevice` | `public` | `Promise`\<`Device`> | `undefined` | - |
| `enableCache` | `readonly` | `boolean` | `undefined` | - |
| `fetch` | `readonly` | (`input`, `init?`) => `Promise`\<`Response`> | `undefined` | - |
| `folder` | `public` | \{ `getFolder`: `Promise`\<`Folder`>; `getFoldersAssets`: `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/folder#paginatedresponse)\<`Asset`>>; `tagFolder`: `Promise`\<`Folder`>; `untagFolder`: `Promise`\<`Folder`>; `updateFolder`: `Promise`\<`Folder`>; `updateFolderIcon`: `Promise`\<`any`>; } | `undefined` | - |
| `folder.getFolder` | `public` | `Promise`\<`Folder`> | `undefined` | - |
| `folder.getFoldersAssets` | `public` | `Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/folder#paginatedresponse)\<`Asset`>> | `undefined` | - |
| `folder.tagFolder` | `public` | `Promise`\<`Folder`> | `undefined` | - |
| `folder.untagFolder` | `public` | `Promise`\<`Folder`> | `undefined` | - |
| `folder.updateFolder` | `public` | `Promise`\<`Folder`> | `undefined` | - |
| `folder.updateFolderIcon` | `public` | `Promise`\<`any`> | `undefined` | - |
| `invalidateCacheOnMutation` | `readonly` | `boolean` | `undefined` | - |
| `invite` | `public` | \{ `acceptInvite`: `Promise`\<[`AcceptInviteResponse`](/docs/reference/sdk/routes/invite#acceptinviteresponse)>; `cancelInvite`: `Promise`\<`Invite`>; `getInviteById`: `Promise`\<`Invite`>; `getInvites`: `Promise`\<[`PaginatedInvitesResponse`](/docs/reference/sdk/routes/invite#paginatedinvitesresponse)>; `getInvitesForResource`: `Promise`\<`Invite`\[]>; `inviteUser`: `Promise`\<`Invite`>; `resendInvite`: `Promise`\<`Invite`>; } | `undefined` | - |
| `invite.acceptInvite` | `public` | `Promise`\<[`AcceptInviteResponse`](/docs/reference/sdk/routes/invite#acceptinviteresponse)> | `undefined` | - |
| `invite.cancelInvite` | `public` | `Promise`\<`Invite`> | `undefined` | - |
| `invite.getInviteById` | `public` | `Promise`\<`Invite`> | `undefined` | - |
| `invite.getInvites` | `public` | `Promise`\<[`PaginatedInvitesResponse`](/docs/reference/sdk/routes/invite#paginatedinvitesresponse)> | `undefined` | - |
| `invite.getInvitesForResource` | `public` | `Promise`\<`Invite`\[]> | `undefined` | - |
| `invite.inviteUser` | `public` | `Promise`\<`Invite`> | `undefined` | - |
| `invite.resendInvite` | `public` | `Promise`\<`Invite`> | `undefined` | - |
| `membership` | `public` | \{ `addRole`: `Promise`\<`Membership`>; `deleteMembership`: `Promise`\<`void`>; `getMyMemberships`: `Promise`\<`Membership`\[]>; `getProjectLastSeen`: `Promise`\<[`GetLastSeenResponse`](/docs/reference/sdk/routes/membership#getlastseenresponse)>; `getProjectMemberships`: `Promise`\<`MembershipReport`>; `getProjectMentionableUsers`: `Promise`\<`Mentionable`\[]>; `getWorkspaceLastSeen`: `Promise`\<[`GetLastSeenResponse`](/docs/reference/sdk/routes/membership#getlastseenresponse)>; `getWorkspaceMemberships`: `Promise`\<`MembershipReport`>; `leaveResource`: `Promise`\<`void`>; `removeRole`: `Promise`\<`Membership`>; } | `undefined` | - |
| `membership.addRole` | `public` | `Promise`\<`Membership`> | `undefined` | - |
| `membership.deleteMembership` | `public` | `Promise`\<`void`> | `undefined` | - |
| `membership.getMyMemberships` | `public` | `Promise`\<`Membership`\[]> | `undefined` | - |
| `membership.getProjectLastSeen` | `public` | `Promise`\<[`GetLastSeenResponse`](/docs/reference/sdk/routes/membership#getlastseenresponse)> | `undefined` | - |
| `membership.getProjectMemberships` | `public` | `Promise`\<`MembershipReport`> | `undefined` | - |
| `membership.getProjectMentionableUsers` | `public` | `Promise`\<`Mentionable`\[]> | `undefined` | - |
| `membership.getWorkspaceLastSeen` | `public` | `Promise`\<[`GetLastSeenResponse`](/docs/reference/sdk/routes/membership#getlastseenresponse)> | `undefined` | - |
| `membership.getWorkspaceMemberships` | `public` | `Promise`\<`MembershipReport`> | `undefined` | - |
| `membership.leaveResource` | `public` | `Promise`\<`void`> | `undefined` | - |
| `membership.removeRole` | `public` | `Promise`\<`Membership`> | `undefined` | - |
| `notification` | `public` | \{ `getNewNotificationCount`: `Promise`\<[`NotificationCountResponse`](/docs/reference/sdk/routes/notification#notificationcountresponse)>; `getNewNotificationCountBulk`: `Promise`\<[`NotificationCountBulkResponse`](/docs/reference/sdk/routes/notification#notificationcountbulkresponse)>; `getNewNotifications`: `Promise`\<[`PaginatedNotificationResponse`](/docs/reference/sdk/routes/notification#paginatednotificationresponse)>; `getNotifications`: `Promise`\<[`PaginatedNotificationResponse`](/docs/reference/sdk/routes/notification#paginatednotificationresponse)>; `getUsersLastNotificationsSeen`: `Promise`\<[`LastSeenResponse`](/docs/reference/sdk/routes/notification#lastseenresponse)>; `updateUsersLastSeen`: `Promise`\<[`LastSeenResponse`](/docs/reference/sdk/routes/notification#lastseenresponse)>; } | `undefined` | - |
| `notification.getNewNotificationCount` | `public` | `Promise`\<[`NotificationCountResponse`](/docs/reference/sdk/routes/notification#notificationcountresponse)> | `undefined` | - |
| `notification.getNewNotificationCountBulk` | `public` | `Promise`\<[`NotificationCountBulkResponse`](/docs/reference/sdk/routes/notification#notificationcountbulkresponse)> | `undefined` | - |
| `notification.getNewNotifications` | `public` | `Promise`\<[`PaginatedNotificationResponse`](/docs/reference/sdk/routes/notification#paginatednotificationresponse)> | `undefined` | - |
| `notification.getNotifications` | `public` | `Promise`\<[`PaginatedNotificationResponse`](/docs/reference/sdk/routes/notification#paginatednotificationresponse)> | `undefined` | - |
| `notification.getUsersLastNotificationsSeen` | `public` | `Promise`\<[`LastSeenResponse`](/docs/reference/sdk/routes/notification#lastseenresponse)> | `undefined` | - |
| `notification.updateUsersLastSeen` | `public` | `Promise`\<[`LastSeenResponse`](/docs/reference/sdk/routes/notification#lastseenresponse)> | `undefined` | - |
| `payment` | `public` | \{ `createManualCheckout`: `Promise`\<`any`>; `createStripeCheckout`: `Promise`\<[`StripeCheckoutResponse`](/docs/reference/sdk/routes/payment#stripecheckoutresponse)>; `createStripeCustomer`: `Promise`\<[`StripeCustomerResponse`](/docs/reference/sdk/routes/payment#stripecustomerresponse)>; `getStripePortalUrl`: `Promise`\<[`StripePortalResponse`](/docs/reference/sdk/routes/payment#stripeportalresponse)>; } | `undefined` | - |
| `payment.createManualCheckout` | `public` | `Promise`\<`any`> | `undefined` | - |
| `payment.createStripeCheckout` | `public` | `Promise`\<[`StripeCheckoutResponse`](/docs/reference/sdk/routes/payment#stripecheckoutresponse)> | `undefined` | - |
| `payment.createStripeCustomer` | `public` | `Promise`\<[`StripeCustomerResponse`](/docs/reference/sdk/routes/payment#stripecustomerresponse)> | `undefined` | - |
| `payment.getStripePortalUrl` | `public` | `Promise`\<[`StripePortalResponse`](/docs/reference/sdk/routes/payment#stripeportalresponse)> | `undefined` | - |
| `product` | `public` | \{ `getSuggestedCurrency`: `Promise`\<\{ `country`: `string` \| `null`; `currency`: [`SupportedCurrency`](/docs/reference/sdk/routes/product#supportedcurrency); `locked?`: `boolean`; `supported`: [`SupportedCurrency`](/docs/reference/sdk/routes/product#supportedcurrency)\[]; }>; `getWorkspaceProducts`: `Promise`\<`Product`\[]>; `listPlans`: `Promise`\<`Product`\[]>; } | `undefined` | - |
| `product.getSuggestedCurrency` | `public` | `Promise`\<\{ `country`: `string` \| `null`; `currency`: [`SupportedCurrency`](/docs/reference/sdk/routes/product#supportedcurrency); `locked?`: `boolean`; `supported`: [`SupportedCurrency`](/docs/reference/sdk/routes/product#supportedcurrency)\[]; }> | `undefined` | - |
| `product.getWorkspaceProducts` | `public` | `Promise`\<`Product`\[]> | `undefined` | - |
| `product.listPlans` | `public` | `Promise`\<`Product`\[]> | `undefined` | - |
| `project` | `readonly` | [`ProjectMethods`](#projectmethods) | `undefined` | - |
| `public` | `public` | \{ `createPublicAssetChatMessage`: `Promise`\<`CreatePublicAssetChatMessageResponse`>; `createPublicChatMessage`: `Promise`\<`ChatMessage`>; `createPublicTopicChatMessage`: `Promise`\<`CreatePublicAssetChatMessageResponse`>; `downloadAssets`: `Promise`\<`DownloadSignedUrlData`\[]>; `getPublicAsset`: `Promise`\<`PublicAssetResponse`>; `getPublicChat`: `Promise`\<`Chat` \| `null`>; `getPublicChatMessages`: `Promise`\<`PublicChatMessagesResponse`>; `getPublicDownloadUrl`: `Promise`\<[`PublicDownloadUrlResponse`](/docs/reference/sdk/routes/shortlink#publicdownloadurlresponse)>; `getPublicEmbedFiles`: `Promise`\<[`PublicEmbedFilesResponse`](/docs/reference/sdk/routes/shortlink#publicembedfilesresponse)>; `getPublicFileSystem`: `Promise`\<[`PublicFileSystemDetailsResponse`](/docs/reference/sdk/routes/public#publicfilesystemdetailsresponse)>; `getPublicItems`: `Promise`\<[`PublicFileSystemResponse`](/docs/reference/sdk/routes/public#publicfilesystemresponse)>; `getPublicItemsAtPath`: `Promise`\<[`PublicFileSystemResponse`](/docs/reference/sdk/routes/public#publicfilesystemresponse)>; `recordAccessActivity`: `Promise`\<`void`>; `resolvePublicDownload`: `Promise`\<[`ResolvePublicDownloadResponse`](/docs/reference/sdk/routes/shortlink#resolvepublicdownloadresponse)>; } | `undefined` | - |
| `public.createPublicAssetChatMessage` | `public` | `Promise`\<`CreatePublicAssetChatMessageResponse`> | `undefined` | - |
| `public.createPublicChatMessage` | `public` | `Promise`\<`ChatMessage`> | `undefined` | - |
| `public.createPublicTopicChatMessage` | `public` | `Promise`\<`CreatePublicAssetChatMessageResponse`> | `undefined` | - |
| `public.downloadAssets` | `public` | `Promise`\<`DownloadSignedUrlData`\[]> | `undefined` | - |
| `public.getPublicAsset` | `public` | `Promise`\<`PublicAssetResponse`> | `undefined` | - |
| `public.getPublicChat` | `public` | `Promise`\<`Chat` \| `null`> | `undefined` | - |
| `public.getPublicChatMessages` | `public` | `Promise`\<`PublicChatMessagesResponse`> | `undefined` | - |
| `public.getPublicDownloadUrl` | `public` | `Promise`\<[`PublicDownloadUrlResponse`](/docs/reference/sdk/routes/shortlink#publicdownloadurlresponse)> | `undefined` | - |
| `public.getPublicEmbedFiles` | `public` | `Promise`\<[`PublicEmbedFilesResponse`](/docs/reference/sdk/routes/shortlink#publicembedfilesresponse)> | `undefined` | - |
| `public.getPublicFileSystem` | `public` | `Promise`\<[`PublicFileSystemDetailsResponse`](/docs/reference/sdk/routes/public#publicfilesystemdetailsresponse)> | `undefined` | - |
| `public.getPublicItems` | `public` | `Promise`\<[`PublicFileSystemResponse`](/docs/reference/sdk/routes/public#publicfilesystemresponse)> | `undefined` | - |
| `public.getPublicItemsAtPath` | `public` | `Promise`\<[`PublicFileSystemResponse`](/docs/reference/sdk/routes/public#publicfilesystemresponse)> | `undefined` | - |
| `public.recordAccessActivity` | `public` | `Promise`\<`void`> | `undefined` | - |
| `public.resolvePublicDownload` | `public` | `Promise`\<[`ResolvePublicDownloadResponse`](/docs/reference/sdk/routes/shortlink#resolvepublicdownloadresponse)> | `undefined` | - |
| `refreshLockTimeoutMs` | `readonly` | `number` | `undefined` | - |
| `refreshTokenStorageKey` | `readonly` | `string` | `undefined` | - |
| `scratch` | `public` | \{ `completeUpload`: `Promise`\<[`CompleteUploadResponse`](/docs/reference/sdk/routes/scratch#completeuploadresponse)>; `promote`: `Promise`\<[`PromoteResponse`](/docs/reference/sdk/routes/scratch#promoteresponse)>; } | `undefined` | - |
| `scratch.completeUpload` | `public` | `Promise`\<[`CompleteUploadResponse`](/docs/reference/sdk/routes/scratch#completeuploadresponse)> | `undefined` | - |
| `scratch.promote` | `public` | `Promise`\<[`PromoteResponse`](/docs/reference/sdk/routes/scratch#promoteresponse)> | `undefined` | - |
| `settings` | `public` | \{ `cleanupOrphanedSettings`: `Promise`\<\{ `message`: `string`; `removedCount`: `number`; }>; `getAllResourceSettings`: `Promise`\<\{ `resourceSettings`: [`ResourceSettings`](/docs/reference/sdk/routes/settings#resourcesettings)\[]; }>; `getEffectiveSettings`: `Promise`\<[`EffectiveSettings`](/docs/reference/sdk/routes/settings#effectivesettings)>; `getResourceSettings`: `Promise`\< \| [`ResourceSettings`](/docs/reference/sdk/routes/settings#resourcesettings) \| \{ `message`: `string`; }>; `resetResourceSettings`: `Promise`\<\{ `message`: `string`; }>; `updateResourceSettings`: `Promise`\<\{ `message`: `string`; `settings`: [`ResourceSettings`](/docs/reference/sdk/routes/settings#resourcesettings); }>; } | `undefined` | - |
| `settings.cleanupOrphanedSettings` | `public` | `Promise`\<\{ `message`: `string`; `removedCount`: `number`; }> | `undefined` | - |
| `settings.getAllResourceSettings` | `public` | `Promise`\<\{ `resourceSettings`: [`ResourceSettings`](/docs/reference/sdk/routes/settings#resourcesettings)\[]; }> | `undefined` | - |
| `settings.getEffectiveSettings` | `public` | `Promise`\<[`EffectiveSettings`](/docs/reference/sdk/routes/settings#effectivesettings)> | `undefined` | - |
| `settings.getResourceSettings` | `public` | `Promise`\< \| [`ResourceSettings`](/docs/reference/sdk/routes/settings#resourcesettings) \| \{ `message`: `string`; }> | `undefined` | - |
| `settings.resetResourceSettings` | `public` | `Promise`\<\{ `message`: `string`; }> | `undefined` | - |
| `settings.updateResourceSettings` | `public` | `Promise`\<\{ `message`: `string`; `settings`: [`ResourceSettings`](/docs/reference/sdk/routes/settings#resourcesettings); }> | `undefined` | - |
| `shortlink` | `public` | \{ `resolveShortLink`: `Promise`\<[`ResolveShortLinkResponse`](/docs/reference/sdk/routes/shortlink#resolveshortlinkresponse)>; } | `undefined` | - |
| `shortlink.resolveShortLink` | `public` | `Promise`\<[`ResolveShortLinkResponse`](/docs/reference/sdk/routes/shortlink#resolveshortlinkresponse)> | `undefined` | - |
| `socket` | `public` | \{ `connect`: (`channel`, `options`) => `Promise`\<[`SocketChannel`](/docs/reference/sdk/routes/socket#socketchannel)>; `connectPublic`: (`publicToken`, `options`) => `Promise`\<[`SocketChannel`](/docs/reference/sdk/routes/socket#socketchannel)>; `disconnect`: (`channel`) => `Promise`\<`void`>; `disconnectAll`: () => `Promise`\<`void`>; `emit`: (`channel`, `event`, `data?`) => `void`; `emitWithAck`: (`channel`, `event`, `data`, `timeoutMs`) => `Promise`\<`boolean`>; `isConnected`: (`channel`) => `boolean`; `onReconnect`: (`channel`, `callback`) => `void`; `onReconnectFailed`: (`channel`, `callback`) => `void`; `subscribe`: \<`T`>(`channel`, `event`, `callback`) => `Promise`\<`void`>; `subscribePublic`: \<`T`>(`publicToken`, `event`, `callback`) => `Promise`\<`void`>; `unsubscribe`: (`channel`, `event`, `callback?`) => `void`; } | `undefined` | - |
| `socket.connect` | `public` | (`channel`, `options`) => `Promise`\<[`SocketChannel`](/docs/reference/sdk/routes/socket#socketchannel)> | `undefined` | Connect to a socket channel |
| `socket.connectPublic` | `public` | (`publicToken`, `options`) => `Promise`\<[`SocketChannel`](/docs/reference/sdk/routes/socket#socketchannel)> | `undefined` | Connect to a public socket channel without authentication |
| `socket.disconnect` | `public` | (`channel`) => `Promise`\<`void`> | `undefined` | Disconnect from a socket channel |
| `socket.disconnectAll` | `public` | () => `Promise`\<`void`> | `undefined` | Disconnect from all channels |
| `socket.emit` | `public` | (`channel`, `event`, `data?`) => `void` | `undefined` | Emit an event to a connected channel |
| `socket.emitWithAck` | `public` | (`channel`, `event`, `data`, `timeoutMs`) => `Promise`\<`boolean`> | `undefined` | Emit an event with a timeout-bounded server acknowledgement. Resolves `true` if the server acks within `timeoutMs`, `false` on timeout or transport error. Use it to actively verify a channel's liveness when `socket.connected` may be stale — most notably after a backgrounded tab returns to focus, where the flag can remain `true` for up to socket.io's own heartbeat window (\~25–45s) even after the underlying TCP transport has died. Relies on socket.io v4's `socket.timeout(ms).emit(ev, data, cb)` pattern: the server acknowledges the event via its trailing callback; if no ack arrives within `timeoutMs` the callback receives an Error. |
| `socket.isConnected` | `public` | (`channel`) => `boolean` | `undefined` | Check if connected to a channel |
| `socket.onReconnect` | `public` | (`channel`, `callback`) => `void` | `undefined` | Register a callback for when the channel reconnects — a socket.io transport-level reconnect, or the token-refresh reconnect. Use it to recover any gap of server->client messages missed while the connection was down; socket.io does not replay those. Dispatched from the 'reconnect' handler in connect() and from the token-refresh path. |
| `socket.onReconnectFailed` | `public` | (`channel`, `callback`) => `void` | `undefined` | Register a callback for when Socket.IO exhausts all reconnection attempts |
| `socket.subscribe` | `public` | \<`T`>(`channel`, `event`, `callback`) => `Promise`\<`void`> | `undefined` | Subscribe to an event on a channel |
| `socket.subscribePublic` | `public` | \<`T`>(`publicToken`, `event`, `callback`) => `Promise`\<`void`> | `undefined` | Subscribe to an event on a public channel Automatically connects to the public channel if not already connected |
| `socket.unsubscribe` | `public` | (`channel`, `event`, `callback?`) => `void` | `undefined` | Stop listening for an event on a channel. If `callback` is provided, only that specific listener is removed; otherwise every listener for that event is cleared. |
| `storage` | `public` | \{ `getStorageChart`: `Promise`\<[`ChartDataResponse`](/docs/reference/sdk/routes/storage#chartdataresponse)>; `getStorageRecord`: `Promise`\<[`StorageRecord`](/docs/reference/sdk/routes/storage#storagerecord)>; } | `undefined` | - |
| `storage.getStorageChart` | `public` | `Promise`\<[`ChartDataResponse`](/docs/reference/sdk/routes/storage#chartdataresponse)> | `undefined` | - |
| `storage.getStorageRecord` | `public` | `Promise`\<[`StorageRecord`](/docs/reference/sdk/routes/storage#storagerecord)> | `undefined` | - |
| `subscription` | `readonly` | [`SubscriptionMethods`](#subscriptionmethods) | `undefined` | - |
| `supportChat` | `public` | \{ `createAttachment`: `Promise`\<`SupportChatCreateAttachmentResponse`>; `getTopic`: `Promise`\<`SupportChatGetTopicResponse`>; } | `undefined` | - |
| `supportChat.createAttachment` | `public` | `Promise`\<`SupportChatCreateAttachmentResponse`> | `undefined` | - |
| `supportChat.getTopic` | `public` | `Promise`\<`SupportChatGetTopicResponse`> | `undefined` | - |
| `supportTicket` | `public` | \{ `createSupportTicket`: `Promise`\<[`SupportTicket`](/docs/reference/sdk/routes/supportTicket#supportticket)>; `getSupportTicket`: `Promise`\<[`SupportTicket`](/docs/reference/sdk/routes/supportTicket#supportticket)>; `getSupportTicketScopeOptions`: `Promise`\<[`SupportTicketScopeOptions`](/docs/reference/sdk/routes/supportTicket#supportticketscopeoptions)>; `listSupportTickets`: `Promise`\<[`SupportTicketListResponse`](/docs/reference/sdk/routes/supportTicket#supportticketlistresponse)>; } | `undefined` | - |
| `supportTicket.createSupportTicket` | `public` | `Promise`\<[`SupportTicket`](/docs/reference/sdk/routes/supportTicket#supportticket)> | `undefined` | - |
| `supportTicket.getSupportTicket` | `public` | `Promise`\<[`SupportTicket`](/docs/reference/sdk/routes/supportTicket#supportticket)> | `undefined` | - |
| `supportTicket.getSupportTicketScopeOptions` | `public` | `Promise`\<[`SupportTicketScopeOptions`](/docs/reference/sdk/routes/supportTicket#supportticketscopeoptions)> | `undefined` | - |
| `supportTicket.listSupportTickets` | `public` | `Promise`\<[`SupportTicketListResponse`](/docs/reference/sdk/routes/supportTicket#supportticketlistresponse)> | `undefined` | - |
| `tag` | `public` | \{ `createTag`: `Promise`\<`Tag`>; `deleteTag`: `Promise`\<`Tag`>; `getTags`: `Promise`\<[`Tags`](/docs/reference/sdk/routes/tag#tags)>; `updateTag`: `Promise`\<`Tag`>; } | `undefined` | - |
| `tag.createTag` | `public` | `Promise`\<`Tag`> | `undefined` | - |
| `tag.deleteTag` | `public` | `Promise`\<`Tag`> | `undefined` | - |
| `tag.getTags` | `public` | `Promise`\<[`Tags`](/docs/reference/sdk/routes/tag#tags)> | `undefined` | - |
| `tag.updateTag` | `public` | `Promise`\<`Tag`> | `undefined` | - |
| `task` | `public` | \{ `acknowledgeAllTasks`: `Promise`\<[`AcknowledgeAllTasksResponse`](/docs/reference/sdk/routes/task#acknowledgealltasksresponse)>; `acknowledgeTask`: `Promise`\<`Task`>; `bulkCreate`: `Promise`\<[`BulkCreateTasksResponse`](/docs/reference/sdk/routes/task#bulkcreatetasksresponse)>; `deleteTask`: `Promise`\<`void`>; `followTask`: `Promise`\<`Task`>; `getMyTasks`: `Promise`\<[`GetTasksResponse`](/docs/reference/sdk/routes/task#gettasksresponse)>; `getTaskEvents`: `Promise`\<[`GetTaskEventsResponse`](/docs/reference/sdk/routes/task#gettaskeventsresponse)>; `getTaskLinks`: `Promise`\<`TaskLink`\[]>; `getUnacknowledgedTaskCount`: `Promise`\<[`UnacknowledgedTaskCountResponse`](/docs/reference/sdk/routes/task#unacknowledgedtaskcountresponse)>; `linkTask`: `Promise`\<`TaskLink`>; `tagTask`: `Promise`\<`Task`>; `unfollowTask`: `Promise`\<`Task`>; `unlinkTask`: `Promise`\<`void`>; `untagTask`: `Promise`\<`Task`>; `updateTaskDetails`: `Promise`\<`Task`>; `updateTaskStatus`: `Promise`\<`Task`>; } | `undefined` | - |
| `task.acknowledgeAllTasks` | `public` | `Promise`\<[`AcknowledgeAllTasksResponse`](/docs/reference/sdk/routes/task#acknowledgealltasksresponse)> | `undefined` | - |
| `task.acknowledgeTask` | `public` | `Promise`\<`Task`> | `undefined` | - |
| `task.bulkCreate` | `public` | `Promise`\<[`BulkCreateTasksResponse`](/docs/reference/sdk/routes/task#bulkcreatetasksresponse)> | `undefined` | - |
| `task.deleteTask` | `public` | `Promise`\<`void`> | `undefined` | - |
| `task.followTask` | `public` | `Promise`\<`Task`> | `undefined` | - |
| `task.getMyTasks` | `public` | `Promise`\<[`GetTasksResponse`](/docs/reference/sdk/routes/task#gettasksresponse)> | `undefined` | - |
| `task.getTaskEvents` | `public` | `Promise`\<[`GetTaskEventsResponse`](/docs/reference/sdk/routes/task#gettaskeventsresponse)> | `undefined` | - |
| `task.getTaskLinks` | `public` | `Promise`\<`TaskLink`\[]> | `undefined` | - |
| `task.getUnacknowledgedTaskCount` | `public` | `Promise`\<[`UnacknowledgedTaskCountResponse`](/docs/reference/sdk/routes/task#unacknowledgedtaskcountresponse)> | `undefined` | - |
| `task.linkTask` | `public` | `Promise`\<`TaskLink`> | `undefined` | - |
| `task.tagTask` | `public` | `Promise`\<`Task`> | `undefined` | - |
| `task.unfollowTask` | `public` | `Promise`\<`Task`> | `undefined` | - |
| `task.unlinkTask` | `public` | `Promise`\<`void`> | `undefined` | - |
| `task.untagTask` | `public` | `Promise`\<`Task`> | `undefined` | - |
| `task.updateTaskDetails` | `public` | `Promise`\<`Task`> | `undefined` | - |
| `task.updateTaskStatus` | `public` | `Promise`\<`Task`> | `undefined` | - |
| `taskRelation` | `public` | \{ `createTaskRelation`: `Promise`\<[`TaskRelation`](/docs/reference/sdk/routes/taskRelation#taskrelation)>; `deleteTaskRelation`: `Promise`\<`void`>; `getRelationsForChat`: `Promise`\<[`PaginatedTaskRelations`](/docs/reference/sdk/routes/taskRelation#paginatedtaskrelations)>; `getRelationsForMessage`: `Promise`\<[`PaginatedTaskRelations`](/docs/reference/sdk/routes/taskRelation#paginatedtaskrelations)>; `getTaskRelations`: `Promise`\<[`PaginatedTaskRelations`](/docs/reference/sdk/routes/taskRelation#paginatedtaskrelations)>; } | `undefined` | - |
| `taskRelation.createTaskRelation` | `public` | `Promise`\<[`TaskRelation`](/docs/reference/sdk/routes/taskRelation#taskrelation)> | `undefined` | - |
| `taskRelation.deleteTaskRelation` | `public` | `Promise`\<`void`> | `undefined` | - |
| `taskRelation.getRelationsForChat` | `public` | `Promise`\<[`PaginatedTaskRelations`](/docs/reference/sdk/routes/taskRelation#paginatedtaskrelations)> | `undefined` | - |
| `taskRelation.getRelationsForMessage` | `public` | `Promise`\<[`PaginatedTaskRelations`](/docs/reference/sdk/routes/taskRelation#paginatedtaskrelations)> | `undefined` | - |
| `taskRelation.getTaskRelations` | `public` | `Promise`\<[`PaginatedTaskRelations`](/docs/reference/sdk/routes/taskRelation#paginatedtaskrelations)> | `undefined` | - |
| `token` | `public` | \{ `createToken`: `Promise`\<[`CreateTokenResponse`](/docs/reference/sdk/routes/token#createtokenresponse)>; `deleteToken`: `Promise`\<`void`>; `listTokens`: `Promise`\<[`TokenSummary`](/docs/reference/sdk/routes/token#tokensummary)\[]>; } | `undefined` | - |
| `token.createToken` | `public` | `Promise`\<[`CreateTokenResponse`](/docs/reference/sdk/routes/token#createtokenresponse)> | `undefined` | - |
| `token.deleteToken` | `public` | `Promise`\<`void`> | `undefined` | - |
| `token.listTokens` | `public` | `Promise`\<[`TokenSummary`](/docs/reference/sdk/routes/token#tokensummary)\[]> | `undefined` | - |
| `tokenExpiryBufferSeconds` | `readonly` | `number` | `undefined` | - |
| `tokenRefreshMaxWaitMs` | `readonly` | `number` | `undefined` | - |
| `tokenRefreshRetryDelayMs` | `readonly` | `number` | `undefined` | - |
| `tokenStorageKey` | `readonly` | `string` | `undefined` | - |
| `user` | `readonly` | [`UserMethods`](#usermethods) | `undefined` | - |
| `version` | `public` | \{ `getCommitHash`: `Promise`\<[`CommitResponse`](/docs/reference/sdk/routes/version#commitresponse)>; `getHealth`: `Promise`\<[`HealthStatus`](/docs/reference/sdk/routes/version#healthstatus)>; } | `undefined` | - |
| `version.getCommitHash` | `public` | `Promise`\<[`CommitResponse`](/docs/reference/sdk/routes/version#commitresponse)> | `undefined` | - |
| `version.getHealth` | `public` | `Promise`\<[`HealthStatus`](/docs/reference/sdk/routes/version#healthstatus)> | `undefined` | - |
| `webhook` | `public` | \{ `createWebhook`: `Promise`\<[`CreateWebhookResponse`](/docs/reference/sdk/routes/webhook#createwebhookresponse)>; `deleteWebhook`: `Promise`\<`void`>; `getWebhook`: `Promise`\<[`WebhookSubscription`](/docs/reference/sdk/routes/webhook#webhooksubscription)>; `listWebhookDeliveries`: `Promise`\<[`ListDeliveriesResponse`](/docs/reference/sdk/routes/webhook#listdeliveriesresponse)>; `listWebhooks`: `Promise`\<[`WebhookSubscription`](/docs/reference/sdk/routes/webhook#webhooksubscription)\[]>; `replayWebhookDelivery`: `Promise`\<\{ `attempt`: [`WebhookAttempt`](/docs/reference/sdk/routes/webhook#webhookattempt); }>; `rotateWebhookSecret`: `Promise`\<[`RotateWebhookSecretResponse`](/docs/reference/sdk/routes/webhook#rotatewebhooksecretresponse)>; `testWebhook`: `Promise`\<[`TestWebhookResponse`](/docs/reference/sdk/routes/webhook#testwebhookresponse)>; `updateWebhook`: `Promise`\<[`WebhookSubscription`](/docs/reference/sdk/routes/webhook#webhooksubscription)>; } | `undefined` | - |
| `webhook.createWebhook` | `public` | `Promise`\<[`CreateWebhookResponse`](/docs/reference/sdk/routes/webhook#createwebhookresponse)> | `undefined` | - |
| `webhook.deleteWebhook` | `public` | `Promise`\<`void`> | `undefined` | - |
| `webhook.getWebhook` | `public` | `Promise`\<[`WebhookSubscription`](/docs/reference/sdk/routes/webhook#webhooksubscription)> | `undefined` | - |
| `webhook.listWebhookDeliveries` | `public` | `Promise`\<[`ListDeliveriesResponse`](/docs/reference/sdk/routes/webhook#listdeliveriesresponse)> | `undefined` | - |
| `webhook.listWebhooks` | `public` | `Promise`\<[`WebhookSubscription`](/docs/reference/sdk/routes/webhook#webhooksubscription)\[]> | `undefined` | - |
| `webhook.replayWebhookDelivery` | `public` | `Promise`\<\{ `attempt`: [`WebhookAttempt`](/docs/reference/sdk/routes/webhook#webhookattempt); }> | `undefined` | - |
| `webhook.rotateWebhookSecret` | `public` | `Promise`\<[`RotateWebhookSecretResponse`](/docs/reference/sdk/routes/webhook#rotatewebhooksecretresponse)> | `undefined` | - |
| `webhook.testWebhook` | `public` | `Promise`\<[`TestWebhookResponse`](/docs/reference/sdk/routes/webhook#testwebhookresponse)> | `undefined` | - |
| `webhook.updateWebhook` | `public` | `Promise`\<[`WebhookSubscription`](/docs/reference/sdk/routes/webhook#webhooksubscription)> | `undefined` | - |
| `websocketURL?` | `readonly` | `string` | `undefined` | - |
| `workspace` | `readonly` | [`WorkspaceMethods`](#workspacemethods) | `undefined` | - |
#### Methods [#methods]
##### \_log() [#_log]
```ts
_log(...args): void;
```
Internal helper for conditional logging. Underscore-prefixed to flag
"internal contract" — accessible from sibling route modules but not
part of the documented public API.
###### Parameters [#parameters-1]
| Parameter | Type | Description |
| --------- | -------- | --------------------------------- |
| ...`args` | `any`\[] | Arguments to pass to console.log. |
###### Returns [#returns-1]
`void`
##### clearCache() [#clearcache]
```ts
clearCache(): void;
```
Clears the response cache.
###### Returns [#returns-2]
`void`
##### getCacheStats() [#getcachestats]
```ts
getCacheStats(): {
entries: {
hasData: boolean;
hasPendingPromise: boolean;
key: string;
timestamp: number;
}[];
size: number;
};
```
Gets cache statistics for debugging.
###### Returns [#returns-3]
```ts
{
entries: {
hasData: boolean;
hasPendingPromise: boolean;
key: string;
timestamp: number;
}[];
size: number;
}
```
Object containing cache statistics.
| Name | Type |
| --------- | ----------------------------------------------------------------------------------------------------- |
| `entries` | \{ `hasData`: `boolean`; `hasPendingPromise`: `boolean`; `key`: `string`; `timestamp`: `number`; }\[] |
| `size` | `number` |
##### getTokenExpiry() [#gettokenexpiry]
```ts
getTokenExpiry(): {
access: string | null;
refresh: string | null;
};
```
Gets the token expiration timestamps.
###### Returns [#returns-4]
```ts
{
access: string | null;
refresh: string | null;
}
```
Object containing access and refresh token expiry ISO timestamps.
| Name | Type |
| --------- | ------------------ |
| `access` | `string` \| `null` |
| `refresh` | `string` \| `null` |
##### getUserId() [#getuserid]
```ts
getUserId(): string | null;
```
Gets the current user's ID from the JWT token.
###### Returns [#returns-5]
`string` | `null`
The user ID if available, null otherwise.
##### getVersion() [#getversion]
```ts
getVersion(): SDKVersionInfo;
```
Gets the SDK version information including build timestamp and hash.
Useful for debugging and verifying which SDK version is in use.
###### Returns [#returns-6]
[`SDKVersionInfo`](#sdkversioninfo)
SDK version, build timestamp, build hash, and git commit
##### tokenValid() [#tokenvalid]
```ts
tokenValid(): boolean;
```
Checks if the current JWT token exists and is valid.
###### Returns [#returns-7]
`boolean`
True if the token exists and is valid, false otherwise.
## Interfaces [#interfaces]
### ApiError [#apierror]
Error thrown by `_request` when the API responds with a non-2xx status.
`status` is the HTTP status and `data` the parsed error body
(`{ type, code, message, errorData? }`). Use `isApiError` to narrow.
#### Extends [#extends]
* `Error`
#### Properties [#properties-1]
| Property | Type | Inherited from |
| ---------------------------- | -------- | --------------- |
| `data?` | `any` | - |
| `message` | `string` | `Error.message` |
| `name` | `string` | `Error.name` |
| `stack?` | `string` | `Error.stack` |
| `status?` | `number` | - |
***
### AssetMethods [#assetmethods]
#### Extends [#extends-1]
* `ReturnType`\<*typeof* [`default`](/docs/reference/sdk/routes/asset#default)>
#### Methods [#methods-1]
##### cleanupUploadSessions() [#cleanupuploadsessions]
```ts
cleanupUploadSessions(projectId, olderThanMs?): void;
```
Clean up old upload sessions for a project
###### Parameters [#parameters-2]
| Parameter | Type | Description |
| -------------- | -------- | --------------------------------------------------- |
| `projectId` | `string` | The project ID |
| `olderThanMs?` | `number` | Remove sessions older than this (default: 24 hours) |
###### Returns [#returns-8]
`void`
###### Inherited from [#inherited-from]
```ts
ReturnType.cleanupUploadSessions
```
##### completeCustomThumbnailUpload() [#completecustomthumbnailupload]
```ts
completeCustomThumbnailUpload(assetId, data): Promise<{
key: string;
status: string;
}>;
```
Finalize the multipart upload for a custom thumbnail. Committing the
upload starts the background processing that generates the thumbnail
outputs.
###### Parameters [#parameters-3]
| Parameter | Type |
| --------------- | ------------------------------------------------------------------------------------------------------- |
| `assetId` | `string` |
| `data` | \{ `key`: `string`; `parts`: \{ `ETag`: `string`; `PartNumber`: `number`; }\[]; `uploadId`: `string`; } |
| `data.key` | `string` |
| `data.parts` | \{ `ETag`: `string`; `PartNumber`: `number`; }\[] |
| `data.uploadId` | `string` |
###### Returns [#returns-9]
`Promise`\<\{
`key`: `string`;
`status`: `string`;
}>
###### Inherited from [#inherited-from-1]
```ts
ReturnType.completeCustomThumbnailUpload
```
##### completeUpload() [#completeupload]
```ts
completeUpload(uploadData): Promise;
```
Complete a multipart upload initiated by `createAssets`.
Takes the same `{ uploadId, parts }` shape as
`nuramaClient.scratch.completeUpload`, plus the `key` and `assetId`.
###### Parameters [#parameters-4]
| Parameter | Type | Description |
| ------------ | --------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| `uploadData` | [`CompleteMultipartUploadData`](/docs/reference/sdk/routes/asset#completemultipartuploaddata) | Data including key, uploadId, parts, and assetId. |
###### Returns [#returns-10]
`Promise`\<`any`>
Upload completion response from the server.
###### Inherited from [#inherited-from-2]
```ts
ReturnType.completeUpload
```
##### completeUploadSession() [#completeuploadsession]
```ts
completeUploadSession(projectId, sessionId): void;
```
Mark an upload session as completed
###### Parameters [#parameters-5]
| Parameter | Type | Description |
| ----------- | -------- | -------------- |
| `projectId` | `string` | The project ID |
| `sessionId` | `string` | The session ID |
###### Returns [#returns-11]
`void`
###### Inherited from [#inherited-from-3]
```ts
ReturnType.completeUploadSession
```
##### createPublicLink() [#createpubliclink]
```ts
createPublicLink(assetId, data): Promise;
```
Create a public download link for an asset.
###### Parameters [#parameters-6]
| Parameter | Type | Description |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| `assetId` | `string` | The asset ID. |
| `data` | \{ `mode?`: [`PublicAssetLinkMode`](/docs/reference/sdk/routes/asset#publicassetlinkmode-1); `projectId`: `string`; `validity?`: `number`; } | Link creation data. |
| `data.mode?` | [`PublicAssetLinkMode`](/docs/reference/sdk/routes/asset#publicassetlinkmode-1) | - |
| `data.projectId` | `string` | The project ID. |
| `data.validity?` | `number` | Link validity in milliseconds. |
###### Returns [#returns-12]
`Promise`\<[`PublicAssetLink`](/docs/reference/sdk/routes/asset#publicassetlink)>
The created public link.
###### Inherited from [#inherited-from-4]
```ts
ReturnType.createPublicLink
```
##### createShortLink() [#createshortlink]
```ts
createShortLink(assetId, data?): Promise;
```
Creates a short link for an asset.
If a short link already exists for the asset with the same visibility, returns the existing one.
###### Parameters [#parameters-7]
| Parameter | Type | Description |
| --------- | --------------------------------------------------------------------------------------- | ----------------------------------------------- |
| `assetId` | `string` | The ID of the asset to create a short link for. |
| `data?` | [`CreateAssetShortLinkData`](/docs/reference/sdk/routes/asset#createassetshortlinkdata) | Optional data including visibility context. |
###### Returns [#returns-13]
`Promise`\<[`CreateAssetShortLinkResponse`](/docs/reference/sdk/routes/asset#createassetshortlinkresponse)>
The short link object and short URL.
###### Inherited from [#inherited-from-5]
```ts
ReturnType.createShortLink
```
##### deleteAsset() [#deleteasset]
```ts
deleteAsset(assetId): Promise;
```
Deletes an asset (marks for deletion).
###### Parameters [#parameters-8]
| Parameter | Type | Description |
| --------- | -------- | ------------------------------ |
| `assetId` | `string` | The ID of the asset to delete. |
###### Returns [#returns-14]
`Promise`\<[`AssetWithChats`](/docs/reference/sdk/routes/asset#assetwithchats)>
###### Inherited from [#inherited-from-6]
```ts
ReturnType.deleteAsset
```
##### disablePublicLink() [#disablepubliclink]
```ts
disablePublicLink(assetId, linkId): Promise;
```
Disable a public download link.
###### Parameters [#parameters-9]
| Parameter | Type | Description |
| --------- | -------- | ------------- |
| `assetId` | `string` | The asset ID. |
| `linkId` | `string` | The link ID. |
###### Returns [#returns-15]
`Promise`\<[`PublicAssetLink`](/docs/reference/sdk/routes/asset#publicassetlink)>
The disabled public link.
###### Inherited from [#inherited-from-7]
```ts
ReturnType.disablePublicLink
```
##### downloadAssets() [#downloadassets]
```ts
downloadAssets(assetIds): Promise;
```
Generates signed download URLs for the original files of specified assets.
###### Parameters [#parameters-10]
| Parameter | Type | Description |
| ---------- | ----------- | ---------------------- |
| `assetIds` | `string`\[] | An array of asset IDs. |
###### Returns [#returns-16]
`Promise`\<[`DownloadAssetsResponse`](/docs/reference/sdk/routes/asset#downloadassetsresponse)>
Array of download URL results.
###### Inherited from [#inherited-from-8]
```ts
ReturnType.downloadAssets
```
##### getAsset() [#getasset]
```ts
getAsset(assetId, params?): Promise;
```
Retrieves a specific asset by its ID with optional chat data.
###### Parameters [#parameters-11]
| Parameter | Type | Description |
| --------- | ------------------------------------------------------------------- | -------------------------------------------- |
| `assetId` | `string` | The ID of the asset. |
| `params?` | [`GetAssetParams`](/docs/reference/sdk/routes/asset#getassetparams) | Optional parameters for chat data inclusion. |
###### Returns [#returns-17]
`Promise`\<[`AssetWithChats`](/docs/reference/sdk/routes/asset#assetwithchats)>
The asset object with optional chat data.
###### Inherited from [#inherited-from-9]
```ts
ReturnType.getAsset
```
##### getAssetAccessActivity() [#getassetaccessactivity]
```ts
getAssetAccessActivity(assetId, params?): Promise<{
breakdown: {
count: number;
label: string;
value: string;
}[];
eventType: string | null;
from: string;
groupBy: string;
range: string;
series: {
count: number;
date: string;
eventType: string;
}[];
to: string;
totals: {
count: number;
eventType: string;
}[];
}>;
```
Get aggregated access-activity for a single asset. Returns totals per
eventType, a breakdown for the requested dimension, and a zero-filled
daily series.
###### Parameters [#parameters-12]
| Parameter | Type |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `assetId` | `string` |
| `params?` | \{ `eventType?`: `"play_started"` \| `"play_completed"` \| `"download"` \| `"embed_resolved"`; `groupBy?`: `"visibility"` \| `"referrerHost"` \| `"country"` \| `"userAgentClass"` \| `"day"`; `limit?`: `number`; `range?`: `"7d"` \| `"30d"` \| `"90d"`; } |
| `params.eventType?` | `"play_started"` \| `"play_completed"` \| `"download"` \| `"embed_resolved"` |
| `params.groupBy?` | `"visibility"` \| `"referrerHost"` \| `"country"` \| `"userAgentClass"` \| `"day"` |
| `params.limit?` | `number` |
| `params.range?` | `"7d"` \| `"30d"` \| `"90d"` |
###### Returns [#returns-18]
`Promise`\<\{
`breakdown`: \{
`count`: `number`;
`label`: `string`;
`value`: `string`;
}\[];
`eventType`: `string` | `null`;
`from`: `string`;
`groupBy`: `string`;
`range`: `string`;
`series`: \{
`count`: `number`;
`date`: `string`;
`eventType`: `string`;
}\[];
`to`: `string`;
`totals`: \{
`count`: `number`;
`eventType`: `string`;
}\[];
}>
###### Inherited from [#inherited-from-10]
```ts
ReturnType.getAssetAccessActivity
```
##### getAssetPage() [#getassetpage]
```ts
getAssetPage(assetId, params?): Promise;
```
Gets the page number an asset appears on based on specified filters and sorting.
###### Parameters [#parameters-13]
| Parameter | Type | Description |
| --------- | --------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `assetId` | `string` | The ID of the asset to find the page for. |
| `params?` | [`GetAssetPageParams`](/docs/reference/sdk/routes/asset#getassetpageparams) | Query parameters for sorting, filtering, and pagination limit. |
###### Returns [#returns-19]
`Promise`\<[`AssetPageResponse`](/docs/reference/sdk/routes/asset#assetpageresponse)>
Object containing the page number.
###### Inherited from [#inherited-from-11]
```ts
ReturnType.getAssetPage
```
##### getAssetReferences() [#getassetreferences]
```ts
getAssetReferences(assetId): Promise;
```
Lists every location an asset is referenced — its primary file system and
each secondary reference (reviewer, submission, public), grouped and counted.
Renaming an asset retitles it at every one of these locations, and deleting
its last primary reference removes them all — so this is what the rename and
delete confirmations show the user before either happens.
###### Parameters [#parameters-14]
| Parameter | Type | Description |
| --------- | -------- | -------------------- |
| `assetId` | `string` | The ID of the asset. |
###### Returns [#returns-20]
`Promise`\<`AssetReferences`>
The asset's references.
###### Inherited from [#inherited-from-12]
```ts
ReturnType.getAssetReferences
```
##### getCustomThumbnailUploadUrl() [#getcustomthumbnailuploadurl]
```ts
getCustomThumbnailUploadUrl(assetId, data): Promise<{
assetId: string;
expires: number;
fileName: string;
key: string;
mimeType: string;
status: string;
uploadId: string;
urls: string[];
}>;
```
Mint signed multipart upload URLs for a user-supplied custom thumbnail
image. Once the upload is completed, background processing generates
the custom-thumbnail outputs and attaches them to the asset; the
`assetFileUpdate` websocket event fires when they are ready.
Caller flow:
1. multipartUpload(file, response.urls, response.key, response.uploadId)
2. completeCustomThumbnailUpload(\{ assetId, key, uploadId, parts })
3. wait for the assetFileUpdate websocket event
###### Parameters [#parameters-15]
| Parameter | Type |
| --------------- | ---------------------------------------------------------------------- |
| `assetId` | `string` |
| `data` | \{ `fileName`: `string`; `mimeType`: `string`; `sizeInMB`: `number`; } |
| `data.fileName` | `string` |
| `data.mimeType` | `string` |
| `data.sizeInMB` | `number` |
###### Returns [#returns-21]
`Promise`\<\{
`assetId`: `string`;
`expires`: `number`;
`fileName`: `string`;
`key`: `string`;
`mimeType`: `string`;
`status`: `string`;
`uploadId`: `string`;
`urls`: `string`\[];
}>
###### Inherited from [#inherited-from-13]
```ts
ReturnType.getCustomThumbnailUploadUrl
```
##### getDocumentViewUrl() [#getdocumentviewurl]
```ts
getDocumentViewUrl(assetId): Promise;
```
Mints a short-lived signed URL for rendering a document inline.
A document's `media` PDF is kept in private storage, so unlike images
and video it cannot be addressed by keyPath through the public file URL.
Fetch this each time a document is opened; do not cache it past `expires`.
###### Parameters [#parameters-16]
| Parameter | Type | Description |
| --------- | -------- | ------------------------ |
| `assetId` | `string` | The document asset's ID. |
###### Returns [#returns-22]
`Promise`\<[`DocumentViewUrlResponse`](/docs/reference/sdk/routes/asset#documentviewurlresponse)>
Signed URL, expiry and page count.
###### Inherited from [#inherited-from-14]
```ts
ReturnType.getDocumentViewUrl
```
##### getFile() [#getfile]
```ts
getFile(assetId, fileId): Promise;
```
Retrieves a specific file from an asset.
###### Parameters [#parameters-17]
| Parameter | Type | Description |
| --------- | -------- | -------------------- |
| `assetId` | `string` | The ID of the asset. |
| `fileId` | `string` | The ID of the file. |
###### Returns [#returns-23]
`Promise`\<`File`>
The file object.
###### Inherited from [#inherited-from-15]
```ts
ReturnType.getFile
```
##### getFilesByFunctionType() [#getfilesbyfunctiontype]
```ts
getFilesByFunctionType(assetId, functionType): Promise;
```
Retrieves files of a specific function type from an asset.
###### Parameters [#parameters-18]
| Parameter | Type | Description |
| -------------- | -------- | --------------------------------------------------------------- |
| `assetId` | `string` | The ID of the asset. |
| `functionType` | `string` | The function type of the files (e.g., 'thumbnail', 'original'). |
###### Returns [#returns-24]
`Promise`\<`File`\[]>
An array of file objects.
###### Inherited from [#inherited-from-16]
```ts
ReturnType.getFilesByFunctionType
```
##### getPublicLinks() [#getpubliclinks]
```ts
getPublicLinks(assetId, options?): Promise<{
results: PublicAssetLink[];
}>;
```
Get all public download links for an asset.
###### Parameters [#parameters-19]
| Parameter | Type | Description |
| ---------------------- | ------------------------------- | ------------- |
| `assetId` | `string` | The asset ID. |
| `options?` | \{ `bypassCache?`: `boolean`; } | - |
| `options.bypassCache?` | `boolean` | - |
###### Returns [#returns-25]
`Promise`\<\{
`results`: [`PublicAssetLink`](/docs/reference/sdk/routes/asset#publicassetlink)\[];
}>
The public links.
###### Inherited from [#inherited-from-17]
```ts
ReturnType.getPublicLinks
```
##### getUploadSession() [#getuploadsession]
```ts
getUploadSession(projectId, sessionId): UploadSessionData | null;
```
Get a specific upload session
###### Parameters [#parameters-20]
| Parameter | Type | Description |
| ----------- | -------- | -------------- |
| `projectId` | `string` | The project ID |
| `sessionId` | `string` | The session ID |
###### Returns [#returns-26]
`UploadSessionData` | `null`
Upload session data or null if not found
###### Inherited from [#inherited-from-18]
```ts
ReturnType.getUploadSession
```
##### getUploadSessions() [#getuploadsessions]
```ts
getUploadSessions(projectId): UploadSessionData[];
```
Get all active upload sessions for a project
###### Parameters [#parameters-21]
| Parameter | Type | Description |
| ----------- | -------- | ---------------------------------- |
| `projectId` | `string` | The project ID to get sessions for |
###### Returns [#returns-27]
`UploadSessionData`\[]
Array of upload session data
###### Inherited from [#inherited-from-19]
```ts
ReturnType.getUploadSessions
```
##### hasActiveUploads() [#hasactiveuploads]
```ts
hasActiveUploads(staleMs?): boolean;
```
True when any upload is genuinely in flight anywhere in the app (across
all projects and tabs). Intended for app-level guards — e.g. suppressing
an automatic version-update page refresh while bytes are still uploading.
Stale (crashed-tab) sessions are ignored via the freshness window.
###### Parameters [#parameters-22]
| Parameter | Type | Description |
| ---------- | -------- | ------------------------------------------------------------------------------------ |
| `staleMs?` | `number` | Max age of the last progress update that still counts as active (default: 2 minutes) |
###### Returns [#returns-28]
`boolean`
###### Inherited from [#inherited-from-20]
```ts
ReturnType.hasActiveUploads
```
##### multipartUpload() [#multipartupload]
```ts
multipartUpload(
file,
signedUrls,
key,
uploadId,
options?
): Promise;
```
Uploads a file using multipart upload with the provided signed URLs
###### Parameters [#parameters-23]
| Parameter | Type | Description |
| ------------ | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `file` | `string` \| `File` \| `Blob` \| `Buffer`\<`ArrayBufferLike`> | The file to upload (File/Blob in browser, Buffer/string path in Node.js) |
| `signedUrls` | `string`\[] | Array of signed URLs for each part |
| `key` | `string` | The storage key returned alongside the signed URLs |
| `uploadId` | `string` | The multipart upload id returned alongside the signed URLs |
| `options` | [`MultipartUploadOptions`](/docs/reference/sdk/routes/asset#multipartuploadoptions) | Upload options |
###### Returns [#returns-29]
`Promise`\<[`MultipartUploadResult`](/docs/reference/sdk/routes/asset#multipartuploadresult)>
The completed upload data
###### Inherited from [#inherited-from-21]
```ts
ReturnType.multipartUpload
```
##### offUploadSessionMessage() [#offuploadsessionmessage]
```ts
offUploadSessionMessage(listenerId): void;
```
Unregister a cross-tab upload session message listener
###### Parameters [#parameters-24]
| Parameter | Type | Description |
| ------------ | -------- | ------------------ |
| `listenerId` | `string` | Unique listener ID |
###### Returns [#returns-30]
`void`
###### Inherited from [#inherited-from-22]
```ts
ReturnType.offUploadSessionMessage
```
##### onUploadSessionMessage() [#onuploadsessionmessage]
```ts
onUploadSessionMessage(listenerId, callback): void;
```
Register a listener for cross-tab upload session messages
###### Parameters [#parameters-25]
| Parameter | Type | Description |
| ------------ | --------------------- | ------------------------------------ |
| `listenerId` | `string` | Unique listener ID |
| `callback` | (`message`) => `void` | Callback function to handle messages |
###### Returns [#returns-31]
`void`
###### Inherited from [#inherited-from-23]
```ts
ReturnType.onUploadSessionMessage
```
##### promoteAttachmentToProject() [#promoteattachmenttoproject]
```ts
promoteAttachmentToProject(assetId, payload): Promise<{
asset: Asset;
deduped: boolean;
}>;
```
Promote a chat-message attachment into a project as a fresh,
independent project asset. The source attachment is left untouched;
the new project asset has its own lifecycle, post-processing
pipeline, and storage footprint.
Idempotent: a second promote of the same source into the same
project returns the existing promoted asset with `deduped: true`.
Requires `canCreateAsset` on the destination project — reviewers
are blocked. The server additionally rejects when the source
attachment's workspace doesn't match the destination project's.
###### Parameters [#parameters-26]
| Parameter | Type |
| ------------------- | -------------------------------------------------- |
| `assetId` | `string` |
| `payload` | \{ `fileName?`: `string`; `projectId`: `string`; } |
| `payload.fileName?` | `string` |
| `payload.projectId` | `string` |
###### Returns [#returns-32]
`Promise`\<\{
`asset`: `Asset`;
`deduped`: `boolean`;
}>
###### Inherited from [#inherited-from-24]
```ts
ReturnType.promoteAttachmentToProject
```
##### reactivatePublicLink() [#reactivatepubliclink]
```ts
reactivatePublicLink(
assetId,
linkId,
data?
): Promise;
```
Reactivate a disabled/expired public download link.
###### Parameters [#parameters-27]
| Parameter | Type | Description |
| ---------------- | --------------------------- | ----------------------------- |
| `assetId` | `string` | The asset ID. |
| `linkId` | `string` | The link ID. |
| `data?` | \{ `validity?`: `number`; } | Reactivation data. |
| `data.validity?` | `number` | New validity in milliseconds. |
###### Returns [#returns-33]
`Promise`\<[`PublicAssetLink`](/docs/reference/sdk/routes/asset#publicassetlink)>
The reactivated public link.
###### Inherited from [#inherited-from-25]
```ts
ReturnType.reactivatePublicLink
```
##### recordAccessActivity() [#recordaccessactivity]
```ts
recordAccessActivity(assetId, body): Promise;
```
Record an authenticated play event from the in-app player. Fire-and-forget;
server returns 204. Throw-on-failure is fine because the caller already
de-dupes per session.
###### Parameters [#parameters-28]
| Parameter | Type |
| ----------------- | ---------------------------------------------------------------------------------------------------- |
| `assetId` | `string` |
| `body` | \{ `eventType`: `"play_started"` \| `"play_completed"`; `visibility`: `"creator"` \| `"reviewer"`; } |
| `body.eventType` | `"play_started"` \| `"play_completed"` |
| `body.visibility` | `"creator"` \| `"reviewer"` |
###### Returns [#returns-34]
`Promise`\<`void`>
###### Inherited from [#inherited-from-26]
```ts
ReturnType.recordAccessActivity
```
##### removeCustomThumbnail() [#removecustomthumbnail]
```ts
removeCustomThumbnail(assetId): Promise;
```
Remove the custom thumbnail from an asset. Soft-deletes all custom
thumb files; the asset falls back to the auto-generated thumbnail.
###### Parameters [#parameters-29]
| Parameter | Type |
| --------- | -------- |
| `assetId` | `string` |
###### Returns [#returns-35]
`Promise`\<`Asset`>
###### Inherited from [#inherited-from-27]
```ts
ReturnType.removeCustomThumbnail
```
##### removeUploadSession() [#removeuploadsession]
```ts
removeUploadSession(projectId, sessionId): void;
```
Remove an upload session
###### Parameters [#parameters-30]
| Parameter | Type | Description |
| ----------- | -------- | -------------- |
| `projectId` | `string` | The project ID |
| `sessionId` | `string` | The session ID |
###### Returns [#returns-36]
`void`
###### Inherited from [#inherited-from-28]
```ts
ReturnType.removeUploadSession
```
##### repairAssets() [#repairassets]
```ts
repairAssets(assetIds): Promise;
```
Attempts to repair assets (e.g., regenerate signed URLs for pending uploads).
###### Parameters [#parameters-31]
| Parameter | Type | Description |
| ---------- | ----------- | -------------------------------- |
| `assetIds` | `string`\[] | An array of asset IDs to repair. |
###### Returns [#returns-37]
`Promise`\<[`RepairAssetsResponse`](/docs/reference/sdk/routes/asset#repairassetsresponse)>
Array of repair results.
###### Inherited from [#inherited-from-29]
```ts
ReturnType.repairAssets
```
##### tagAsset() [#tagasset]
```ts
tagAsset(assetId, tagData): Promise;
```
Tags an asset with a specific tag.
###### Parameters [#parameters-32]
| Parameter | Type | Description |
| --------- | --------------------------------------------------------------- | --------------------------- |
| `assetId` | `string` | The ID of the asset to tag. |
| `tagData` | [`TagAssetData`](/docs/reference/sdk/routes/asset#tagassetdata) | Data containing the tag ID. |
###### Returns [#returns-38]
`Promise`\<[`AssetWithChats`](/docs/reference/sdk/routes/asset#assetwithchats)>
The updated asset object.
###### Inherited from [#inherited-from-30]
```ts
ReturnType.tagAsset
```
##### untagAsset() [#untagasset]
```ts
untagAsset(assetId, untagData): Promise;
```
Untags an asset by removing a specific tag.
###### Parameters [#parameters-33]
| Parameter | Type | Description |
| ----------- | ------------------------------------------------------------------- | ------------------------------------- |
| `assetId` | `string` | The ID of the asset to untag. |
| `untagData` | [`UntagAssetData`](/docs/reference/sdk/routes/asset#untagassetdata) | Data containing the tag ID to remove. |
###### Returns [#returns-39]
`Promise`\<[`AssetWithChats`](/docs/reference/sdk/routes/asset#assetwithchats)>
The updated asset object.
###### Inherited from [#inherited-from-31]
```ts
ReturnType.untagAsset
```
##### updateAsset() [#updateasset]
```ts
updateAsset(assetId, updateData): Promise;
```
Updates an asset.
###### Parameters [#parameters-34]
| Parameter | Type | Description |
| ------------ | --------------------------------------------------------------------- | -------------------------------------------------- |
| `assetId` | `string` | The ID of the asset to update. |
| `updateData` | [`UpdateAssetData`](/docs/reference/sdk/routes/asset#updateassetdata) | Data to update (e.g., name, meta, tags, folderId). |
###### Returns [#returns-40]
`Promise`\<[`AssetWithChats`](/docs/reference/sdk/routes/asset#assetwithchats)>
The updated asset object.
###### Inherited from [#inherited-from-32]
```ts
ReturnType.updateAsset
```
##### updatePublicLink() [#updatepubliclink]
```ts
updatePublicLink(
assetId,
linkId,
data
): Promise;
```
Update a public download link (extend expiration or change status).
###### Parameters [#parameters-35]
| Parameter | Type | Description |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------- |
| `assetId` | `string` | The asset ID. |
| `linkId` | `string` | The link ID. |
| `data` | \{ `mode?`: [`PublicAssetLinkMode`](/docs/reference/sdk/routes/asset#publicassetlinkmode-1); `status?`: `string`; `validity?`: `number`; } | Update data. |
| `data.mode?` | [`PublicAssetLinkMode`](/docs/reference/sdk/routes/asset#publicassetlinkmode-1) | - |
| `data.status?` | `string` | - |
| `data.validity?` | `number` | - |
###### Returns [#returns-41]
`Promise`\<[`PublicAssetLink`](/docs/reference/sdk/routes/asset#publicassetlink)>
The updated public link.
###### Inherited from [#inherited-from-33]
```ts
ReturnType.updatePublicLink
```
***
### AuthMethods [#authmethods]
#### Extends [#extends-2]
* `ReturnType`\<*typeof* [`default`](/docs/reference/sdk/routes/auth#default)>
#### Methods [#methods-2]
##### changePassword() [#changepassword]
```ts
changePassword(
currentPassword,
newPassword,
mfaToken?
): Promise;
```
Changes the authenticated user's password.
Requires current password verification and MFA token if MFA is enabled.
All refresh tokens will be invalidated after password change.
###### Parameters [#parameters-36]
| Parameter | Type | Description |
| ----------------- | -------- | --------------------------------------- |
| `currentPassword` | `string` | The current password for verification. |
| `newPassword` | `string` | The new password. |
| `mfaToken?` | `string` | MFA token (required if MFA is enabled). |
###### Returns [#returns-42]
`Promise`\<`void`>
Promise resolving when complete.
###### Inherited from [#inherited-from-34]
```ts
ReturnType.changePassword
```
##### disableMfa() [#disablemfa]
```ts
disableMfa(mfaToken): Promise;
```
Disables multi-factor authentication for the authenticated user.
Requires a current valid MFA token for confirmation.
###### Parameters [#parameters-37]
| Parameter | Type | Description |
| ---------- | -------- | --------------------------- |
| `mfaToken` | `string` | The current MFA token code. |
###### Returns [#returns-43]
`Promise`\<`void`>
Promise resolving when complete.
###### Inherited from [#inherited-from-35]
```ts
ReturnType.disableMfa
```
##### enableMfa() [#enablemfa]
```ts
enableMfa(): Promise;
```
Enables multi-factor authentication for the authenticated user.
###### Returns [#returns-44]
`Promise`\<`MFAEnableResponse`>
Promise resolving to MFA setup details (secret, OTP URL, backup codes).
###### Inherited from [#inherited-from-36]
```ts
ReturnType.enableMfa
```
##### exchangeOAuthCode() [#exchangeoauthcode]
```ts
exchangeOAuthCode(code): Promise;
```
###### Parameters [#parameters-38]
| Parameter | Type |
| --------- | -------- |
| `code` | `string` |
###### Returns [#returns-45]
`Promise`\<`OAuthExchangeResponse`>
###### Inherited from [#inherited-from-37]
```ts
ReturnType.exchangeOAuthCode
```
##### forgotPassword() [#forgotpassword]
```ts
forgotPassword(email): Promise;
```
Forgets a user's password.
###### Parameters [#parameters-39]
| Parameter | Type | Description |
| --------- | -------- | ------------------------- |
| `email` | `string` | The user's email address. |
###### Returns [#returns-46]
`Promise`\<`void`>
###### Inherited from [#inherited-from-38]
```ts
ReturnType.forgotPassword
```
##### getLinkedOAuthProviders() [#getlinkedoauthproviders]
```ts
getLinkedOAuthProviders(): Promise;
```
Gets all OAuth providers linked to the authenticated user's account.
###### Returns [#returns-47]
`Promise`\<`LinkedAuthProvider`\[]>
Promise resolving to array of linked OAuth providers.
###### Inherited from [#inherited-from-39]
```ts
ReturnType.getLinkedOAuthProviders
```
##### linkOAuthProvider() [#linkoauthprovider]
```ts
linkOAuthProvider(provider): Promise;
```
Links an OAuth provider to the authenticated user's account.
This allows users to sign in with multiple OAuth providers.
###### Parameters [#parameters-40]
| Parameter | Type | Description |
| ---------- | --------------- | ------------------------------------------------------------- |
| `provider` | `OAuthProvider` | The OAuth provider to link (google, apple, microsoft, adobe). |
###### Returns [#returns-48]
`Promise`\<[`LoginRegisterResponse`](/docs/reference/sdk/routes/auth#loginregisterresponse)>
Promise resolving to user data with updated linked providers.
###### Inherited from [#inherited-from-40]
```ts
ReturnType.linkOAuthProvider
```
##### lockAccount() [#lockaccount]
```ts
lockAccount(token): Promise;
```
Locks a user account using a lock account token.
This is used when a user receives a password changed notification
for a change they did not initiate, allowing them to immediately
secure their account.
###### Parameters [#parameters-41]
| Parameter | Type | Description |
| --------- | -------- | ------------------------------------------------------- |
| `token` | `string` | The lock account token from the password changed email. |
###### Returns [#returns-49]
`Promise`\<`void`>
Promise resolving when the account is locked.
###### Inherited from [#inherited-from-41]
```ts
ReturnType.lockAccount
```
##### login() [#login]
```ts
login(credentials): Promise;
```
Logs in a user.
###### Parameters [#parameters-42]
| Parameter | Type | Description |
| ------------- | ---------------------------------------------------------------------- | ------------------ |
| `credentials` | [`LoginCredentials`](/docs/reference/sdk/routes/auth#logincredentials) | Login credentials. |
###### Returns [#returns-50]
`Promise`\<[`LoginRegisterResponse`](/docs/reference/sdk/routes/auth#loginregisterresponse)>
Object containing user info and tokens (or MFA challenge token).
###### Inherited from [#inherited-from-42]
```ts
ReturnType.login
```
##### logout() [#logout]
```ts
logout(refreshToken): Promise;
```
Logs out a user.
###### Parameters [#parameters-43]
| Parameter | Type | Description |
| -------------- | -------- | -------------------------------- |
| `refreshToken` | `string` | The refresh token to invalidate. |
###### Returns [#returns-51]
`Promise`\<`void`>
###### Inherited from [#inherited-from-43]
```ts
ReturnType.logout
```
##### refreshTokens() [#refreshtokens]
```ts
refreshTokens(refreshToken?): Promise;
```
Refreshes user tokens.
###### Parameters [#parameters-44]
| Parameter | Type | Description |
| --------------- | -------- | ------------------ |
| `refreshToken?` | `string` | The refresh token. |
###### Returns [#returns-52]
`Promise`\<[`RefreshResponse`](/docs/reference/sdk/routes/auth#refreshresponse)>
Object containing new access and refresh tokens.
###### Inherited from [#inherited-from-44]
```ts
ReturnType.refreshTokens
```
##### register() [#register]
```ts
register(userData): Promise;
```
Registers a new user.
###### Parameters [#parameters-45]
| Parameter | Type | Description |
| ---------- | ---------------------------------------------------------------------- | ----------------------- |
| `userData` | [`RegisterUserData`](/docs/reference/sdk/routes/auth#registeruserdata) | User registration data. |
###### Returns [#returns-53]
`Promise`\<[`LoginRegisterResponse`](/docs/reference/sdk/routes/auth#loginregisterresponse)>
Object containing user info and tokens.
###### Inherited from [#inherited-from-45]
```ts
ReturnType.register
```
##### registerGuest() [#registerguest]
```ts
registerGuest(data): Promise;
```
Registers a guest account for public chat participation.
Always returns void (204) regardless of outcome for anti-enumeration.
###### Parameters [#parameters-46]
| Parameter | Type | Description |
| ------------------ | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `data` | \{ `color?`: `string`; `displayName`: `string`; `email`: `string`; `publicToken`: `string`; } | Guest registration data (email, displayName, optional approved color, publicToken). |
| `data.color?` | `string` | - |
| `data.displayName` | `string` | - |
| `data.email` | `string` | - |
| `data.publicToken` | `string` | - |
###### Returns [#returns-54]
`Promise`\<`void`>
###### Inherited from [#inherited-from-46]
```ts
ReturnType.registerGuest
```
##### resendVerification() [#resendverification]
```ts
resendVerification(email): Promise;
```
Public, unauthenticated resend of the verification email keyed by
address. For users past the verification grace window who can't log
in or call the authed sendVerificationEmail. Always resolves (the
server returns 204 regardless of whether the email exists).
###### Parameters [#parameters-47]
| Parameter | Type | Description |
| --------- | -------- | ----------------------------------------------------- |
| `email` | `string` | The email address to resend the verification link to. |
###### Returns [#returns-55]
`Promise`\<`void`>
###### Inherited from [#inherited-from-47]
```ts
ReturnType.resendVerification
```
##### resetPassword() [#resetpassword]
```ts
resetPassword(params): Promise;
```
Resets a user's password.
###### Parameters [#parameters-48]
| Parameter | Type | Description |
| --------- | ------------------------------------------------------------------------ | ----------------- |
| `params` | [`ResetPasswordData`](/docs/reference/sdk/routes/auth#resetpassworddata) | Input parameters. |
###### Returns [#returns-56]
`Promise`\<`void`>
Promise resolving when complete.
###### Inherited from [#inherited-from-48]
```ts
ReturnType.resetPassword
```
##### sendVerificationEmail() [#sendverificationemail]
```ts
sendVerificationEmail(): Promise;
```
Sends a verification email to the authenticated user.
###### Returns [#returns-57]
`Promise`\<`void`>
Promise resolving when complete.
###### Inherited from [#inherited-from-49]
```ts
ReturnType.sendVerificationEmail
```
##### setPassword() [#setpassword]
```ts
setPassword(password, mfaToken?): Promise;
```
Sets a password for an OAuth-only user account.
This allows OAuth users to add local authentication as a backup.
###### Parameters [#parameters-49]
| Parameter | Type | Description |
| ----------- | -------- | --------------------------------------- |
| `password` | `string` | The password to set. |
| `mfaToken?` | `string` | MFA token (required if MFA is enabled). |
###### Returns [#returns-58]
`Promise`\<`void`>
Promise resolving when complete.
###### Inherited from [#inherited-from-50]
```ts
ReturnType.setPassword
```
##### unlinkOAuthProvider() [#unlinkoauthprovider]
```ts
unlinkOAuthProvider(provider): Promise;
```
Unlinks an OAuth provider from the authenticated user's account.
User must have at least one authentication method remaining (password or another OAuth provider).
###### Parameters [#parameters-50]
| Parameter | Type | Description |
| ---------- | --------------- | --------------------------------------------------------------- |
| `provider` | `OAuthProvider` | The OAuth provider to unlink (google, apple, microsoft, adobe). |
###### Returns [#returns-59]
`Promise`\<`void`>
Promise resolving when complete.
###### Inherited from [#inherited-from-51]
```ts
ReturnType.unlinkOAuthProvider
```
##### upgradeGuest() [#upgradeguest]
```ts
upgradeGuest(data): Promise<{
user: User;
}>;
```
Upgrades a guest account to a standard account with a password.
Requires the user to be authenticated as a guest.
###### Parameters [#parameters-51]
| Parameter | Type | Description |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `data` | \{ `company?`: `string`; `firstName?`: `string`; `lastName?`: `string`; `password`: `string`; `userName?`: `string`; } | Upgrade data (password, optional firstName, lastName, company, userName). |
| `data.company?` | `string` | - |
| `data.firstName?` | `string` | - |
| `data.lastName?` | `string` | - |
| `data.password` | `string` | - |
| `data.userName?` | `string` | - |
###### Returns [#returns-60]
`Promise`\<\{
`user`: `User`;
}>
Promise resolving to the upgraded user data.
###### Inherited from [#inherited-from-52]
```ts
ReturnType.upgradeGuest
```
##### verifyBackupCode() [#verifybackupcode]
```ts
verifyBackupCode(backupCode): Promise;
```
Verifies an MFA backup code.
This is used during login when a user has lost access to their authenticator app.
###### Parameters [#parameters-52]
| Parameter | Type | Description |
| ------------ | -------- | ----------------------------------------- |
| `backupCode` | `string` | The backup code (8-character hex string). |
###### Returns [#returns-61]
`Promise`\<`MFAVerifyResponse`>
Promise resolving to user/token data upon successful verification.
###### Inherited from [#inherited-from-53]
```ts
ReturnType.verifyBackupCode
```
##### verifyEmail() [#verifyemail]
```ts
verifyEmail(token): Promise;
```
Verifies a user's email using the provided token.
###### Parameters [#parameters-53]
| Parameter | Type | Description |
| --------- | -------- | ----------------------------- |
| `token` | `string` | The email verification token. |
###### Returns [#returns-62]
`Promise`\<`void`>
Promise resolving when complete.
###### Inherited from [#inherited-from-54]
```ts
ReturnType.verifyEmail
```
##### verifyGuest() [#verifyguest]
```ts
verifyGuest(token): Promise;
```
Verifies a guest account using the token from the verification email.
Stores auth tokens on success and returns user data.
###### Parameters [#parameters-54]
| Parameter | Type | Description |
| --------- | -------- | ----------------------------- |
| `token` | `string` | The guest verification token. |
###### Returns [#returns-63]
`Promise`\<[`LoginRegisterResponse`](/docs/reference/sdk/routes/auth#loginregisterresponse)>
Promise resolving to user data and auth tokens.
###### Inherited from [#inherited-from-55]
```ts
ReturnType.verifyGuest
```
##### verifyMfa() [#verifymfa]
```ts
verifyMfa(mfaToken): Promise;
```
Verifies an MFA token (e.g., TOTP code).
This is used both during initial MFA setup and during login challenges.
###### Parameters [#parameters-55]
| Parameter | Type | Description |
| ---------- | -------- | ------------------- |
| `mfaToken` | `string` | The MFA token code. |
###### Returns [#returns-64]
`Promise`\<`MFAVerifyResponse`>
Promise resolving to user/token data upon successful verification.
###### Inherited from [#inherited-from-56]
```ts
ReturnType.verifyMfa
```
***
### NuramaClientOptions [#nuramaclientoptions]
#### Properties [#properties-2]
| Property | Type | Description |
| ------------------------------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apiKey?` | `string` | Long-lived API key to use for every request (e.g., a bot API key starting with `nrm_bot_`). When set, the client skips JWT refresh logic and uses the key as the bearer token. |
| `browserMode?` | `boolean` | Whether to run in browser mode (uses localStorage for token storage). Default: false |
| `cacheDurationSeconds?` | `number` | Cache duration in seconds. Default: 5 |
| `debug?` | `boolean` | Enable debug logging. Default: false |
| `enableCache?` | `boolean` | Enable response caching. Default: true |
| `fetch?` | (`input`, `init?`) => `Promise`\<`Response`> | Custom fetch implementation. If not provided, will use global fetch |
| `invalidateCacheOnMutation?` | `boolean` | After a successful write (POST/PUT/PATCH/DELETE) to a resource, evict cached GET responses for that resource so the next read returns fresh data (read-after-write consistency). Default: true. |
| `onMaintenance?` | () => `void` | Invoked when the API returns a `{ error: 'maintenance' }` body with a 418 or 503 status — i.e. the site is in a maintenance window. Lets an already-loaded (cached) app surface a maintenance message instead of failing silently. |
| `onUnauthorized?` | (`reason?`) => `void` | Callback invoked when authentication fails and re-login is required (e.g., refresh token expired/missing). `reason.type` carries the API's error type when available — notably `emailVerificationRequired` when the refresh was rejected because the user's email-verification grace period has expired, so callers can prompt verification instead of a plain logout. |
| `refreshLockTimeoutMs?` | `number` | Timeout in ms for the refresh lock to prevent multiple simultaneous refreshes. Default: 5000 |
| `refreshTokenStorageKey?` | `string` | Key used to store the refresh token in storage. Default: 'nurama\_refresh\_token' |
| `tokenExpiryBufferSeconds?` | `number` | Number of seconds before token expiry to trigger refresh. Default: 300 (5 minutes) |
| `tokenRefreshMaxWaitMs?` | `number` | Maximum time in ms to wait for token refresh. Default: 10000 |
| `tokenRefreshRetryDelayMs?` | `number` | Delay in ms between token refresh retries. Default: 1000 |
| `tokenStorageKey?` | `string` | Key used to store the access token in storage. Default: 'nurama\_token' |
| `websocketURL?` | `string` | WebSocket server URL. If not provided, will use the baseURL |
***
### ProjectMethods [#projectmethods]
#### Extends [#extends-3]
* `ReturnType`\<*typeof* [`default`](/docs/reference/sdk/routes/project#default)>
#### Methods [#methods-3]
##### addItemsToPublicFileSystem() [#additemstopublicfilesystem]
```ts
addItemsToPublicFileSystem(
projectId,
publicId,
addItemsData
): Promise;
```
Adds additional items to an existing public file system.
###### Parameters [#parameters-56]
| Parameter | Type | Description |
| -------------- | ----------------------------------------------------------------------------------------------------- | --------------------------------- |
| `projectId` | `string` | The ID of the project. |
| `publicId` | `string` | The ID of the public file system. |
| `addItemsData` | [`AddItemsToPublicFileSystemData`](/docs/reference/sdk/routes/project#additemstopublicfilesystemdata) | Data for adding items. |
###### Returns [#returns-65]
`Promise`\<[`PublicFileSystemResponse`](/docs/reference/sdk/routes/project#publicfilesystemresponse)>
The updated public file system object.
###### Inherited from [#inherited-from-57]
```ts
ReturnType.addItemsToPublicFileSystem
```
##### addItemsToSubmission() [#additemstosubmission]
```ts
addItemsToSubmission(
projectId,
submissionId,
addItemsData
): Promise;
```
Adds items to an existing submission.
###### Parameters [#parameters-57]
| Parameter | Type | Description |
| -------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------- |
| `projectId` | `string` | The ID of the project. |
| `submissionId` | `string` | The ID of the submission. |
| `addItemsData` | [`AddItemsToSubmissionData`](/docs/reference/sdk/routes/project#additemstosubmissiondata) | Data for adding items to the submission. |
###### Returns [#returns-66]
`Promise`\<`ChatSubmission`>
The updated submission object.
###### Inherited from [#inherited-from-58]
```ts
ReturnType.addItemsToSubmission
```
##### copyItemsToPath() [#copyitemstopath]
```ts
copyItemsToPath(
projectId,
visibility,
copyData
): Promise<{
count: number;
}>;
```
Copies items to a specific path within a project.
###### Parameters [#parameters-58]
| Parameter | Type | Description |
| ------------ | ------------------------------------------------------------------- | ------------------------------------------------- |
| `projectId` | `string` | The ID of the project. |
| `visibility` | `"creator"` \| `"reviewer"` | The visibility context ('creator' or 'reviewer'). |
| `copyData` | [`CopyItemsData`](/docs/reference/sdk/routes/project#copyitemsdata) | Data for copying items. |
###### Returns [#returns-67]
`Promise`\<\{
`count`: `number`;
}>
Object containing the count of copied items.
###### Inherited from [#inherited-from-59]
```ts
ReturnType.copyItemsToPath
```
##### copyPublicItemsAtPath() [#copypublicitemsatpath]
```ts
copyPublicItemsAtPath(
projectId,
token,
copyData
): Promise<{
count: number;
}>;
```
Copies items within a public file system (authenticated management).
###### Parameters [#parameters-59]
| Parameter | Type | Description |
| ----------- | ------------------------------------------------------------------------------- | ------------------------ |
| `projectId` | `string` | The ID of the project. |
| `token` | `string` | The public access token. |
| `copyData` | [`CopyPublicItemsData`](/docs/reference/sdk/routes/project#copypublicitemsdata) | Data for copying items. |
###### Returns [#returns-68]
`Promise`\<\{
`count`: `number`;
}>
Object containing the count of copied items.
###### Inherited from [#inherited-from-60]
```ts
ReturnType.copyPublicItemsAtPath
```
##### copySubmissionItems() [#copysubmissionitems]
```ts
copySubmissionItems(
projectId,
submissionId,
copyData
): Promise<{
count: number;
}>;
```
Copies items within a submission.
###### Parameters [#parameters-60]
| Parameter | Type | Description |
| -------------- | --------------------------------------------------------------------------------------- | ------------------------- |
| `projectId` | `string` | The ID of the project. |
| `submissionId` | `string` | The ID of the submission. |
| `copyData` | [`CopySubmissionItemsData`](/docs/reference/sdk/routes/project#copysubmissionitemsdata) | Data for copying items. |
###### Returns [#returns-69]
`Promise`\<\{
`count`: `number`;
}>
Object containing the count of copied items.
###### Inherited from [#inherited-from-61]
```ts
ReturnType.copySubmissionItems
```
##### createAssets() [#createassets]
```ts
createAssets(projectId, fileUploadBody): Promise;
```
Create assets within a project and return their signed links for upload.
###### Parameters [#parameters-61]
| Parameter | Type | Description |
| ---------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------- |
| `projectId` | `string` | The ID of the project. |
| `fileUploadBody` | [`ProjectFileUploadBody`](/docs/reference/sdk/routes/project#projectfileuploadbody) | List of files to upload with optional destination path. |
###### Returns [#returns-70]
`Promise`\<`any`\[]>
Array of results, each containing asset info and signed URL data.
###### Inherited from [#inherited-from-62]
```ts
ReturnType.createAssets
```
##### createFolder() [#createfolder]
```ts
createFolder(
projectId,
visibility,
folderData
): Promise;
```
Creates a folder within a project with file system integration.
###### Parameters [#parameters-62]
| Parameter | Type | Description |
| ------------ | ------------------------------------------------------------------------- | ------------------------------------------------- |
| `projectId` | `string` | The ID of the project. |
| `visibility` | `"creator"` \| `"reviewer"` | The visibility context ('creator' or 'reviewer'). |
| `folderData` | [`CreateFolderData`](/docs/reference/sdk/routes/project#createfolderdata) | Data for creating the folder. |
###### Returns [#returns-71]
`Promise`\<`Folder`>
The created folder object.
###### Inherited from [#inherited-from-63]
```ts
ReturnType.createFolder
```
##### createLogo() [#createlogo]
```ts
createLogo(projectId, logoData): Promise;
```
Creates a new logo asset for a project.
###### Parameters [#parameters-63]
| Parameter | Type | Description |
| ----------- | --------------------------------------------------------------------- | --------------------------- |
| `projectId` | `string` | The ID of the project. |
| `logoData` | [`LogoUploadData`](/docs/reference/sdk/routes/project#logouploaddata) | File metadata for the logo. |
###### Returns [#returns-72]
`Promise`\<`any`>
Object containing signed URL data and updated project info.
###### Inherited from [#inherited-from-64]
```ts
ReturnType.createLogo
```
##### createProject() [#createproject]
```ts
createProject(projectData): Promise;
```
Creates a new project.
###### Parameters [#parameters-64]
| Parameter | Type | Description |
| ------------- | --------------------------------------------------------------------------- | ------------------------- |
| `projectData` | [`CreateProjectData`](/docs/reference/sdk/routes/project#createprojectdata) | Data for the new project. |
###### Returns [#returns-73]
`Promise`\<`Project`>
The created project object.
###### Inherited from [#inherited-from-65]
```ts
ReturnType.createProject
```
##### createProjectPublicAssetChatMessage() [#createprojectpublicassetchatmessage]
```ts
createProjectPublicAssetChatMessage(
projectId,
token,
assetId,
data
): Promise;
```
Creates a message on an asset's public chat from an authenticated project context.
Creates the chat lazily if it doesn't exist yet.
Unlike the public endpoint, this does NOT check token expiration.
###### Parameters [#parameters-65]
| Parameter | Type | Description |
| ----------- | -------------------------------- | ------------------------ |
| `projectId` | `string` | The ID of the project. |
| `token` | `string` | The public access token. |
| `assetId` | `string` | The ID of the asset. |
| `data` | `CreatePublicChatMessageRequest` | Message data. |
###### Returns [#returns-74]
`Promise`\<`CreatePublicAssetChatMessageResponse`>
The chat and created message.
###### Inherited from [#inherited-from-66]
```ts
ReturnType.createProjectPublicAssetChatMessage
```
##### createProjectPublicChatMessage() [#createprojectpublicchatmessage]
```ts
createProjectPublicChatMessage(
projectId,
token,
chatId,
data
): Promise;
```
Creates a message in an existing public chat from an authenticated project context.
Unlike the public endpoint, this does NOT check token expiration.
###### Parameters [#parameters-66]
| Parameter | Type | Description |
| ----------- | -------------------------------- | ------------------------ |
| `projectId` | `string` | The ID of the project. |
| `token` | `string` | The public access token. |
| `chatId` | `string` | The ID of the chat. |
| `data` | `CreatePublicChatMessageRequest` | Message data. |
###### Returns [#returns-75]
`Promise`\<`ChatMessage`>
The created message.
###### Inherited from [#inherited-from-67]
```ts
ReturnType.createProjectPublicChatMessage
```
##### createProjectPublicTopicChatMessage() [#createprojectpublictopicchatmessage]
```ts
createProjectPublicTopicChatMessage(
projectId,
token,
data
): Promise;
```
Creates a message on the main public topic chat from an authenticated project context.
Creates the chat lazily if it doesn't exist yet.
Unlike the public endpoint, this does NOT check token expiration.
###### Parameters [#parameters-67]
| Parameter | Type | Description |
| ----------- | -------------------------------- | ------------------------ |
| `projectId` | `string` | The ID of the project. |
| `token` | `string` | The public access token. |
| `data` | `CreatePublicChatMessageRequest` | Message data. |
###### Returns [#returns-76]
`Promise`\<`CreatePublicAssetChatMessageResponse`>
The chat and created message.
###### Inherited from [#inherited-from-68]
```ts
ReturnType.createProjectPublicTopicChatMessage
```
##### createPublicFileSystem() [#createpublicfilesystem]
```ts
createPublicFileSystem(projectId, publicFileSystemData): Promise;
```
Creates a public file system with a secure token for sharing project assets publicly.
###### Parameters [#parameters-68]
| Parameter | Type | Description |
| ---------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------- |
| `projectId` | `string` | The ID of the project. |
| `publicFileSystemData` | [`CreatePublicFileSystemData`](/docs/reference/sdk/routes/project#createpublicfilesystemdata) | Data for creating the public file system. |
###### Returns [#returns-77]
`Promise`\<[`PublicFileSystemResponse`](/docs/reference/sdk/routes/project#publicfilesystemresponse)>
The created public file system object.
###### Inherited from [#inherited-from-69]
```ts
ReturnType.createPublicFileSystem
```
##### createPublicFolder() [#createpublicfolder]
```ts
createPublicFolder(
projectId,
token,
folderData
): Promise;
```
Creates a folder inside a public file system (authenticated management).
###### Parameters [#parameters-69]
| Parameter | Type | Description |
| ------------ | ------------------------------------------------------------------------- | ----------------------------------------------------- |
| `projectId` | `string` | The ID of the project. |
| `token` | `string` | The public access token. |
| `folderData` | [`CreateFolderData`](/docs/reference/sdk/routes/project#createfolderdata) | Data for creating the folder (name, color, basePath). |
###### Returns [#returns-78]
`Promise`\<`Folder`>
The created folder object.
###### Inherited from [#inherited-from-70]
```ts
ReturnType.createPublicFolder
```
##### createSubmission() [#createsubmission]
```ts
createSubmission(projectId, submissionData): Promise;
```
Creates a new submission for a project.
###### Parameters [#parameters-70]
| Parameter | Type | Description |
| ---------------- | --------------------------------------------------------------------------------- | ------------------------ |
| `projectId` | `string` | The ID of the project. |
| `submissionData` | [`CreateSubmissionData`](/docs/reference/sdk/routes/project#createsubmissiondata) | Data for the submission. |
###### Returns [#returns-79]
`Promise`\<`ChatSubmission`>
The created submission object.
###### Inherited from [#inherited-from-71]
```ts
ReturnType.createSubmission
```
##### createSubmissionFolder() [#createsubmissionfolder]
```ts
createSubmissionFolder(
projectId,
submissionId,
folderData
): Promise;
```
Creates a folder within a submission.
###### Parameters [#parameters-71]
| Parameter | Type | Description |
| -------------- | --------------------------------------------------------------------------------------------- | ----------------------------- |
| `projectId` | `string` | The ID of the project. |
| `submissionId` | `string` | The ID of the submission. |
| `folderData` | [`CreateSubmissionFolderData`](/docs/reference/sdk/routes/project#createsubmissionfolderdata) | Data for creating the folder. |
###### Returns [#returns-80]
`Promise`\<`Folder`>
The created folder object.
###### Inherited from [#inherited-from-72]
```ts
ReturnType.createSubmissionFolder
```
##### deleteItemsAtPath() [#deleteitemsatpath]
```ts
deleteItemsAtPath(
projectId,
visibility,
deleteData
): Promise<{
count: number;
}>;
```
Deletes items at a specific path within a project.
###### Parameters [#parameters-72]
| Parameter | Type | Description |
| ------------ | ----------------------------------------------------------------------- | ------------------------------------------------- |
| `projectId` | `string` | The ID of the project. |
| `visibility` | `"creator"` \| `"reviewer"` | The visibility context ('creator' or 'reviewer'). |
| `deleteData` | [`DeleteItemsData`](/docs/reference/sdk/routes/project#deleteitemsdata) | Data for deleting items. |
###### Returns [#returns-81]
`Promise`\<\{
`count`: `number`;
}>
Object containing the count of deleted items.
###### Inherited from [#inherited-from-73]
```ts
ReturnType.deleteItemsAtPath
```
##### deleteProject() [#deleteproject]
```ts
deleteProject(projectId): Promise;
```
Deletes a project (marks for deletion).
###### Parameters [#parameters-73]
| Parameter | Type | Description |
| ----------- | -------- | -------------------------------- |
| `projectId` | `string` | The ID of the project to delete. |
###### Returns [#returns-82]
`Promise`\<`void`>
The deleted public release record.
###### Inherited from [#inherited-from-74]
```ts
ReturnType.deleteProject
```
##### deletePublicFileSystem() [#deletepublicfilesystem]
```ts
deletePublicFileSystem(projectId, publicId): Promise;
```
Deletes a public file system and invalidates its access token.
###### Parameters [#parameters-74]
| Parameter | Type | Description |
| ----------- | -------- | --------------------------------- |
| `projectId` | `string` | The ID of the project. |
| `publicId` | `string` | The ID of the public file system. |
###### Returns [#returns-83]
`Promise`\<[`PublicFileSystemResponse`](/docs/reference/sdk/routes/project#publicfilesystemresponse)>
The deleted public release record.
###### Inherited from [#inherited-from-75]
```ts
ReturnType.deletePublicFileSystem
```
##### deletePublicItemsAtPath() [#deletepublicitemsatpath]
```ts
deletePublicItemsAtPath(
projectId,
token,
deleteData
): Promise<{
count: number;
}>;
```
Deletes items from a public file system (authenticated management).
###### Parameters [#parameters-75]
| Parameter | Type | Description |
| ------------ | ----------------------------------------------------------------------------------- | ------------------------ |
| `projectId` | `string` | The ID of the project. |
| `token` | `string` | The public access token. |
| `deleteData` | [`DeletePublicItemsData`](/docs/reference/sdk/routes/project#deletepublicitemsdata) | Data for deleting items. |
###### Returns [#returns-84]
`Promise`\<\{
`count`: `number`;
}>
Object containing the count of deleted items.
###### Inherited from [#inherited-from-76]
```ts
ReturnType.deletePublicItemsAtPath
```
##### deleteSubmissionItems() [#deletesubmissionitems]
```ts
deleteSubmissionItems(
projectId,
submissionId,
deleteData
): Promise<{
count: number;
}>;
```
Deletes items within a submission.
###### Parameters [#parameters-76]
| Parameter | Type | Description |
| -------------- | ------------------------------------------------------------------------------------------- | ------------------------- |
| `projectId` | `string` | The ID of the project. |
| `submissionId` | `string` | The ID of the submission. |
| `deleteData` | [`DeleteSubmissionItemsData`](/docs/reference/sdk/routes/project#deletesubmissionitemsdata) | Data for deleting items. |
###### Returns [#returns-85]
`Promise`\<\{
`count`: `number`;
}>
Object containing the count of deleted items.
###### Inherited from [#inherited-from-77]
```ts
ReturnType.deleteSubmissionItems
```
##### getAssets() [#getassets]
```ts
getAssets(
projectId,
visibility,
params?
): Promise>;
```
Lists a project's assets for one visibility tier.
`creator` requires `canGetCreatorAssets`; `reviewer` requires `canGetReviewerAssets`.
###### Parameters [#parameters-77]
| Parameter | Type | Description |
| ------------ | ------------------------------------------------------------------------- | --------------------------------------------- |
| `projectId` | `string` | The project ID. |
| `visibility` | `"creator"` \| `"reviewer"` | Which tier's assets to list. |
| `params?` | [`ListAssetsParams`](/docs/reference/sdk/routes/project#listassetsparams) | Filters and pagination. See ListAssetsParams. |
###### Returns [#returns-86]
`Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/project#paginatedresponse)\<`Asset`>>
Paginated assets.
###### Throws [#throws]
'projectId is required.' or 'visibility is required.'.
###### Inherited from [#inherited-from-78]
```ts
ReturnType.getAssets
```
##### getFolders() [#getfolders]
```ts
getFolders(
projectId,
visibility,
params?
): Promise>;
```
Gets folders within a project with specified visibility.
###### Parameters [#parameters-78]
| Parameter | Type | Description |
| ------------ | --------------------------------------------------------------------------- | ------------------------------------------------- |
| `projectId` | `string` | The ID of the project. |
| `visibility` | `"creator"` \| `"reviewer"` | The visibility context ('creator' or 'reviewer'). |
| `params?` | [`ListFoldersParams`](/docs/reference/sdk/routes/project#listfoldersparams) | Query parameters for filtering and pagination. |
###### Returns [#returns-87]
`Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/project#paginatedresponse)\<`Folder`>>
Paginated list of folders.
###### Inherited from [#inherited-from-79]
```ts
ReturnType.getFolders
```
##### getHighlightedMessages() [#gethighlightedmessages]
```ts
getHighlightedMessages(
projectId,
visibility,
params?
): Promise>;
```
Lists highlighted chat messages across a project for one visibility tier (cursor pagination only).
`creator` requires `canGetCreatorHighlights`; `reviewer` requires `canGetReviewerHighlights`.
###### Parameters [#parameters-79]
| Parameter | Type | Description |
| ------------ | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `projectId` | `string` | The project ID. |
| `visibility` | `"creator"` \| `"reviewer"` | Which tier's highlights to list. |
| `params?` | [`GetHighlightedMessagesParams`](/docs/reference/sdk/routes/project#gethighlightedmessagesparams) | Cursor pagination. See GetHighlightedMessagesParams. |
###### Returns [#returns-88]
`Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/project#paginatedresponse)\<`ChatMessage`>>
Paginated highlighted messages.
###### Throws [#throws-1]
'projectId is required.' or 'visibility is required.'.
###### Inherited from [#inherited-from-80]
```ts
ReturnType.getHighlightedMessages
```
##### getHomeFeed() [#gethomefeed]
```ts
getHomeFeed(
projectId,
visibility,
params?
): Promise>;
```
Gets the home feed for a project with a specified visibility.
###### Parameters [#parameters-80]
| Parameter | Type | Description |
| ------------ | --------------------------------------------------------------------- | ------------------------------------------------- |
| `projectId` | `string` | The ID of the project. |
| `visibility` | `"creator"` \| `"reviewer"` | The visibility context ('creator' or 'reviewer'). |
| `params?` | [`ListFeedParams`](/docs/reference/sdk/routes/project#listfeedparams) | Query parameters for filtering and pagination. |
###### Returns [#returns-89]
`Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/project#paginatedresponse)\<`Asset`>>
Paginated feed items.
###### Inherited from [#inherited-from-81]
```ts
ReturnType.getHomeFeed
```
##### getItemsAtPath() [#getitemsatpath]
```ts
getItemsAtPath(
projectId,
visibility,
path?,
params?,
usePost?
): Promise>;
```
Gets items at a specific path within a project.
###### Parameters [#parameters-81]
| Parameter | Type | Default value | Description |
| ------------ | --------------------------------------------------------------------------------- | ------------- | ----------------------------------------------------------------- |
| `projectId` | `string` | `undefined` | The ID of the project. |
| `visibility` | `"creator"` \| `"reviewer"` | `undefined` | The visibility context ('creator' or 'reviewer'). |
| `path?` | `string` | `undefined` | The path to get items from (optional, defaults to root). |
| `params?` | [`GetItemsAtPathParams`](/docs/reference/sdk/routes/project#getitemsatpathparams) | `undefined` | Query parameters for filtering and pagination. |
| `usePost?` | `boolean` | `false` | Whether to use POST method (useful for large resourceIds arrays). |
###### Returns [#returns-90]
`Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/project#paginatedresponse)\<`any`>>
Paginated list of items at the path.
###### Inherited from [#inherited-from-82]
```ts
ReturnType.getItemsAtPath
```
##### getProject() [#getproject]
```ts
getProject(projectId): Promise;
```
Retrieves a specific project by its ID.
###### Parameters [#parameters-82]
| Parameter | Type | Description |
| ----------- | -------- | ---------------------- |
| `projectId` | `string` | The ID of the project. |
###### Returns [#returns-91]
`Promise`\<`Project`>
The project object.
###### Inherited from [#inherited-from-83]
```ts
ReturnType.getProject
```
##### getProjectChat() [#getprojectchat]
```ts
getProjectChat(
projectId,
visibility,
params?
): Promise;
```
Gets the project chat with the specified visibility.
###### Parameters [#parameters-83]
| Parameter | Type | Description |
| ------------ | ------------------------------------------------------------------- | ------------------------------------------------- |
| `projectId` | `string` | The ID of the project. |
| `visibility` | `"creator"` \| `"reviewer"` | The visibility context ('creator' or 'reviewer'). |
| `params?` | [`GetChatParams`](/docs/reference/sdk/routes/project#getchatparams) | Query parameters for message/reply limits. |
###### Returns [#returns-92]
`Promise`\<`Chat`>
The chat object.
###### Inherited from [#inherited-from-84]
```ts
ReturnType.getProjectChat
```
##### getProjectPublicAsset() [#getprojectpublicasset]
```ts
getProjectPublicAsset(
projectId,
token,
assetId
): Promise;
```
Gets a public asset with its public chat from an authenticated project context.
Unlike the public endpoint, this does NOT check token expiration.
Use this for internal management of public file systems.
###### Parameters [#parameters-84]
| Parameter | Type | Description |
| ----------- | -------- | -------------------------------- |
| `projectId` | `string` | The ID of the project. |
| `token` | `string` | The public access token. |
| `assetId` | `string` | The ID of the asset to retrieve. |
###### Returns [#returns-93]
`Promise`\<`PublicAssetResponse`>
The asset with its public chat.
###### Inherited from [#inherited-from-85]
```ts
ReturnType.getProjectPublicAsset
```
##### getProjectPublicChat() [#getprojectpublicchat]
```ts
getProjectPublicChat(projectId, token): Promise;
```
Gets a public chat from an authenticated project context.
Unlike the public endpoint, this does NOT check token expiration.
Use this for internal management of public file systems.
###### Parameters [#parameters-85]
| Parameter | Type | Description |
| ----------- | -------- | ------------------------ |
| `projectId` | `string` | The ID of the project. |
| `token` | `string` | The public access token. |
###### Returns [#returns-94]
`Promise`\<`any`>
The public chat or null if none exists.
###### Inherited from [#inherited-from-86]
```ts
ReturnType.getProjectPublicChat
```
##### getProjectPublicChatMessages() [#getprojectpublicchatmessages]
```ts
getProjectPublicChatMessages(
projectId,
token,
chatId,
params?
): Promise;
```
Gets messages from a public chat from an authenticated project context.
Unlike the public endpoint, this does NOT check token expiration.
Use this for internal management of public file systems.
###### Parameters [#parameters-86]
| Parameter | Type | Description |
| ----------- | ----------------------------------------------------------------------------------------------- | -------------------------------- |
| `projectId` | `string` | The ID of the project. |
| `token` | `string` | The public access token. |
| `chatId` | `string` | The ID of the chat. |
| `params?` | [`GetPublicChatMessagesParams`](/docs/reference/sdk/routes/project#getpublicchatmessagesparams) | Query parameters for pagination. |
###### Returns [#returns-95]
`Promise`\<`PublicChatMessagesResponse`>
Paginated list of chat messages.
###### Inherited from [#inherited-from-87]
```ts
ReturnType.getProjectPublicChatMessages
```
##### getProjects() [#getprojects]
```ts
getProjects(): Promise;
```
Retrieves projects accessible by the user.
NOTE: API endpoint `/v1/projects` does not currently support pagination.
###### Returns [#returns-96]
`Promise`\<`Project`\[]>
List of project objects.
###### Inherited from [#inherited-from-88]
```ts
ReturnType.getProjects
```
##### getPublicAudit() [#getpublicaudit]
```ts
getPublicAudit(projectId, params?): Promise>;
```
Get the public audit for a project — assets that are or have been publicly exposed.
###### Parameters [#parameters-87]
| Parameter | Type | Description |
| ------------------------- | -------------------------------------------------------------------------- | ---------------------------------------- |
| `projectId` | `string` | - |
| `params?` | \{ `currentlyPublic?`: `boolean`; `limit?`: `number`; `page?`: `number`; } | - |
| `params.currentlyPublic?` | `boolean` | When true, only assets currently public. |
| `params.limit?` | `number` | - |
| `params.page?` | `number` | - |
###### Returns [#returns-97]
`Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/project#paginatedresponse)\<[`PublicAuditAssetResponse`](/docs/reference/sdk/routes/project#publicauditassetresponse)>>
###### Requires [#requires]
`projectAdmin` or `projectOwner` on the project (or workspace-tier admin via inheritance).
###### Inherited from [#inherited-from-89]
```ts
ReturnType.getPublicAudit
```
##### getPublicFileSystem() [#getpublicfilesystem]
```ts
getPublicFileSystem(projectId, publicId): Promise;
```
Retrieves a specific public file system by its ID.
###### Parameters [#parameters-88]
| Parameter | Type | Description |
| ----------- | -------- | --------------------------------- |
| `projectId` | `string` | The ID of the project. |
| `publicId` | `string` | The ID of the public file system. |
###### Returns [#returns-98]
`Promise`\<[`PublicFileSystemResponse`](/docs/reference/sdk/routes/project#publicfilesystemresponse)>
The public file system object.
###### Inherited from [#inherited-from-90]
```ts
ReturnType.getPublicFileSystem
```
##### getPublicFileSystems() [#getpublicfilesystems]
```ts
getPublicFileSystems(projectId, params?): Promise>;
```
Gets all public file systems for a project.
###### Parameters [#parameters-89]
| Parameter | Type | Description |
| ----------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `projectId` | `string` | The ID of the project. |
| `params?` | [`ListPublicFileSystemsParams`](/docs/reference/sdk/routes/project#listpublicfilesystemsparams) | Query parameters (pagination, sort, search, status, creatorId). |
###### Returns [#returns-99]
`Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/project#paginatedresponse)\<[`PublicFileSystemResponse`](/docs/reference/sdk/routes/project#publicfilesystemresponse)>>
Paginated list of public file systems.
###### Inherited from [#inherited-from-91]
```ts
ReturnType.getPublicFileSystems
```
##### getPublicItemsAtPath() [#getpublicitemsatpath]
```ts
getPublicItemsAtPath(
projectId,
token,
path?,
params?
): Promise>;
```
Gets items from a public file system at a specific path (authenticated management).
###### Parameters [#parameters-90]
| Parameter | Type | Description |
| ----------- | --------------------------------------------------------------------------------- | -------------------------------------------------------- |
| `projectId` | `string` | The ID of the project. |
| `token` | `string` | The public access token. |
| `path?` | `string` | The path to get items from (optional, defaults to root). |
| `params?` | [`GetItemsAtPathParams`](/docs/reference/sdk/routes/project#getitemsatpathparams) | Query parameters for filtering and pagination. |
###### Returns [#returns-100]
`Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/project#paginatedresponse)\<`any`>>
Paginated list of public file system items.
###### Inherited from [#inherited-from-92]
```ts
ReturnType.getPublicItemsAtPath
```
##### getSubmission() [#getsubmission]
```ts
getSubmission(
projectId,
submissionId,
params?
): Promise;
```
Retrieves a specific submission by its ID.
###### Parameters [#parameters-91]
| Parameter | Type | Description |
| -------------- | ------------------------------------------------------------------------------- | ------------------------------------------------ |
| `projectId` | `string` | The ID of the project. |
| `submissionId` | `string` | The ID of the submission. |
| `params?` | [`GetSubmissionParams`](/docs/reference/sdk/routes/project#getsubmissionparams) | Query parameters for chat message/reply options. |
###### Returns [#returns-101]
`Promise`\<`ChatSubmission`>
The submission object.
###### Inherited from [#inherited-from-93]
```ts
ReturnType.getSubmission
```
##### getSubmissionItems() [#getsubmissionitems]
```ts
getSubmissionItems(
projectId,
submissionId,
path?,
params?
): Promise>;
```
Gets files for a specific submission.
###### Parameters [#parameters-92]
| Parameter | Type | Description |
| -------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------- |
| `projectId` | `string` | The ID of the project. |
| `submissionId` | `string` | The ID of the submission. |
| `path?` | `string` | The path to get items from (optional, defaults to root). |
| `params?` | [`GetItemsAtPathParams`](/docs/reference/sdk/routes/project#getitemsatpathparams) | Query parameters for filtering and pagination. |
###### Returns [#returns-102]
`Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/project#paginatedresponse)\<`any`>>
Paginated list of files.
###### Inherited from [#inherited-from-94]
```ts
ReturnType.getSubmissionItems
```
##### getSubmissions() [#getsubmissions]
```ts
getSubmissions(projectId, params?): Promise>;
```
Retrieves submissions for a project.
###### Parameters [#parameters-93]
| Parameter | Type | Description |
| ----------- | ----------------------------------------------------------------------------------- | ---------------------------------------------- |
| `projectId` | `string` | The ID of the project. |
| `params?` | [`ListSubmissionsParams`](/docs/reference/sdk/routes/project#listsubmissionsparams) | Query parameters for filtering and pagination. |
###### Returns [#returns-103]
`Promise`\<[`PaginatedResponse`](/docs/reference/sdk/routes/project#paginatedresponse)\<`ChatSubmission`>>
Paginated list of submissions.
###### Inherited from [#inherited-from-95]
```ts
ReturnType.getSubmissions
```
##### getTopAccessActivity() [#gettopaccessactivity]
```ts
getTopAccessActivity(projectId, params?): Promise;
```
Top-N assets in a project by access-activity event type (plays, downloads, embeds).
Requires project read access. Returns asset IDs and counts only; hydrate names and
thumbnails through the normal asset fetch path.
###### Parameters [#parameters-94]
| Parameter | Type | Description | | |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------- | ----- | ----------------------------- |
| `projectId` | `string` | The project ID. | | |
| `params?` | \{ `eventType?`: `"play_started"` \| `"play_completed"` \| `"download"` \| `"embed_resolved"`; `limit?`: `number`; `range?`: `"7d"` \| `"30d"` \| `"90d"`; } | `range` ('7d' | '30d' | '90d'), `eventType`, `limit`. |
| `params.eventType?` | `"play_started"` \| `"play_completed"` \| `"download"` \| `"embed_resolved"` | - | | |
| `params.limit?` | `number` | - | | |
| `params.range?` | `"7d"` \| `"30d"` \| `"90d"` | - | | |
###### Returns [#returns-104]
`Promise`\<[`ProjectTopAccessActivityResponse`](/docs/reference/sdk/routes/project#projecttopaccessactivityresponse)>
Ranked asset IDs with counts.
###### Throws [#throws-2]
'projectId is required.' when `projectId` is falsy.
###### Inherited from [#inherited-from-96]
```ts
ReturnType.getTopAccessActivity
```
##### moveItemsToPath() [#moveitemstopath]
```ts
moveItemsToPath(
projectId,
visibility,
moveData
): Promise;
```
Moves items to a specific path within a project.
###### Parameters [#parameters-95]
| Parameter | Type | Description |
| ------------ | ------------------------------------------------------------------- | ------------------------------------------------- |
| `projectId` | `string` | The ID of the project. |
| `visibility` | `"creator"` \| `"reviewer"` | The visibility context ('creator' or 'reviewer'). |
| `moveData` | [`MoveItemsData`](/docs/reference/sdk/routes/project#moveitemsdata) | Data for moving items. |
###### Returns [#returns-105]
`Promise`\<[`MoveItemsResult`](/docs/reference/sdk/routes/project#moveitemsresult)>
Object containing the count of moved items.
###### Inherited from [#inherited-from-97]
```ts
ReturnType.moveItemsToPath
```
##### movePublicItemsAtPath() [#movepublicitemsatpath]
```ts
movePublicItemsAtPath(
projectId,
token,
moveData
): Promise<{
count: number;
}>;
```
Moves items within a public file system (authenticated management).
###### Parameters [#parameters-96]
| Parameter | Type | Description |
| ----------- | ------------------------------------------------------------------------------- | ------------------------ |
| `projectId` | `string` | The ID of the project. |
| `token` | `string` | The public access token. |
| `moveData` | [`MovePublicItemsData`](/docs/reference/sdk/routes/project#movepublicitemsdata) | Data for moving items. |
###### Returns [#returns-106]
`Promise`\<\{
`count`: `number`;
}>
Object containing the count of moved items.
###### Inherited from [#inherited-from-98]
```ts
ReturnType.movePublicItemsAtPath
```
##### moveSubmissionItems() [#movesubmissionitems]
```ts
moveSubmissionItems(
projectId,
submissionId,
moveData
): Promise<{
count: number;
}>;
```
Moves items within a submission.
###### Parameters [#parameters-97]
| Parameter | Type | Description |
| -------------- | --------------------------------------------------------------------------------------- | ------------------------- |
| `projectId` | `string` | The ID of the project. |
| `submissionId` | `string` | The ID of the submission. |
| `moveData` | [`MoveSubmissionItemsData`](/docs/reference/sdk/routes/project#movesubmissionitemsdata) | Data for moving items. |
###### Returns [#returns-107]
`Promise`\<\{
`count`: `number`;
}>
Object containing the count of moved items.
###### Inherited from [#inherited-from-99]
```ts
ReturnType.moveSubmissionItems
```
##### previewDeleteItemsAtPath() [#previewdeleteitemsatpath]
```ts
previewDeleteItemsAtPath(
projectId,
visibility,
deleteData
): Promise;
```
Asks what deleting these paths would reach, without deleting anything.
Computed from the same cascade the delete runs, so the answer is what
will happen rather than an estimate of it. Only SECONDARY references
come back — the reviewer, submission and public-release copies that
would go with the selection.
###### Parameters [#parameters-98]
| Parameter | Type | Description |
| ------------ | ----------------------------------------------------------------------- | ------------------------------- |
| `projectId` | `string` | - |
| `visibility` | `"creator"` \| `"reviewer"` | - |
| `deleteData` | [`DeleteItemsData`](/docs/reference/sdk/routes/project#deleteitemsdata) | The same body the delete takes. |
###### Returns [#returns-108]
`Promise`\<`DeleteImpact`>
###### Inherited from [#inherited-from-100]
```ts
ReturnType.previewDeleteItemsAtPath
```
##### publishItems() [#publishitems]
```ts
publishItems(projectId, publishData): Promise;
```
Publishes a list of items (assets, folders) within a project.
###### Parameters [#parameters-99]
| Parameter | Type | Description |
| ------------- | ------------------------------------------------------------------------- | -------------------------- |
| `projectId` | `string` | The ID of the project. |
| `publishData` | [`PublishItemsData`](/docs/reference/sdk/routes/project#publishitemsdata) | Data for publishing items. |
###### Returns [#returns-109]
`Promise`\<`any`>
Object containing lists of published items and results.
###### Inherited from [#inherited-from-101]
```ts
ReturnType.publishItems
```
##### releasePublicFileSystem() [#releasepublicfilesystem]
```ts
releasePublicFileSystem(projectId, publicId): Promise;
```
Releases a staged (unreleased) public file system, making it externally
accessible via its public token.
###### Parameters [#parameters-100]
| Parameter | Type | Description |
| ----------- | -------- | --------------------------------- |
| `projectId` | `string` | The ID of the project. |
| `publicId` | `string` | The ID of the public file system. |
###### Returns [#returns-110]
`Promise`\<[`PublicFileSystemResponse`](/docs/reference/sdk/routes/project#publicfilesystemresponse)>
The released public file system object.
###### Inherited from [#inherited-from-102]
```ts
ReturnType.releasePublicFileSystem
```
##### releaseSubmission() [#releasesubmission]
```ts
releaseSubmission(projectId, submissionId): Promise;
```
Releases a staged (unreleased) submission, making it visible to reviewers
and firing the deferred "new submission" side effects (emails,
notifications, system messages).
###### Parameters [#parameters-101]
| Parameter | Type | Description |
| -------------- | -------- | ------------------------- |
| `projectId` | `string` | The ID of the project. |
| `submissionId` | `string` | The ID of the submission. |
###### Returns [#returns-111]
`Promise`\<`ChatSubmission`>
The released submission object.
###### Inherited from [#inherited-from-103]
```ts
ReturnType.releaseSubmission
```
##### releaseSubmissionUpdate() [#releasesubmissionupdate]
```ts
releaseSubmissionUpdate(projectId, submissionId): Promise;
```
Re-releases an already-released submission's side effects (the "Release
Update" action) — re-notifies reviewers with the submission-update email
template + `submissionUpdate` notification. Does not change status.
###### Parameters [#parameters-102]
| Parameter | Type | Description |
| -------------- | -------- | ------------------------- |
| `projectId` | `string` | The ID of the project. |
| `submissionId` | `string` | The ID of the submission. |
###### Returns [#returns-112]
`Promise`\<`ChatSubmission`>
The submission object.
###### Inherited from [#inherited-from-104]
```ts
ReturnType.releaseSubmissionUpdate
```
##### searchProject() [#searchproject]
```ts
searchProject(projectId, params): Promise;
```
Full-text search across assets, chat messages, and tasks within a project.
Results are populated per the content type's native list view (asset →
creator/publisher/tags; chatMessage → author/mentions/attachments; task →
creator/assignee/project/origin).
###### Parameters [#parameters-103]
| Parameter | Type | Description |
| ----------- | --------------------- | --------------------------------------------------------------------------------------------------------------- |
| `projectId` | `string` | - |
| `params` | `SearchProjectParams` | At minimum `q`. Optional filters: `contentTypes`, `dateFrom`, `dateTo`, `creatorId`, `sortBy`, `page`, `limit`. |
###### Returns [#returns-113]
`Promise`\<`SearchResponse`>
Paginated search results.
###### Inherited from [#inherited-from-105]
```ts
ReturnType.searchProject
```
##### tagSubmission() [#tagsubmission]
```ts
tagSubmission(
projectId,
submissionId,
tagData
): Promise;
```
Adds a tag to a submission.
###### Parameters [#parameters-104]
| Parameter | Type | Description |
| -------------- | --------------------------------------------------------------------------- | -------------------------------- |
| `projectId` | `string` | The ID of the project. |
| `submissionId` | `string` | The ID of the submission. |
| `tagData` | [`TagSubmissionData`](/docs/reference/sdk/routes/project#tagsubmissiondata) | Data for tagging the submission. |
###### Returns [#returns-114]
`Promise`\<`ChatSubmission`>
The updated submission object.
###### Inherited from [#inherited-from-106]
```ts
ReturnType.tagSubmission
```
##### unpublishItems() [#unpublishitems]
```ts
unpublishItems(projectId, unpublishData): Promise;
```
Unpublishes a list of items (assets, folders) within a project.
###### Parameters [#parameters-105]
| Parameter | Type | Description |
| --------------- | ----------------------------------------------------------------------------- | ---------------------------- |
| `projectId` | `string` | The ID of the project. |
| `unpublishData` | [`UnpublishItemsData`](/docs/reference/sdk/routes/project#unpublishitemsdata) | Data for unpublishing items. |
###### Returns [#returns-115]
`Promise`\<`any`>
Object containing lists of unpublished items and results.
###### Inherited from [#inherited-from-107]
```ts
ReturnType.unpublishItems
```
##### untagSubmission() [#untagsubmission]
```ts
untagSubmission(
projectId,
submissionId,
tagData
): Promise;
```
Removes a tag from a submission.
###### Parameters [#parameters-106]
| Parameter | Type | Description |
| -------------- | --------------------------------------------------------------------------- | ---------------------------------- |
| `projectId` | `string` | The ID of the project. |
| `submissionId` | `string` | The ID of the submission. |
| `tagData` | [`TagSubmissionData`](/docs/reference/sdk/routes/project#tagsubmissiondata) | Data for untagging the submission. |
###### Returns [#returns-116]
`Promise`\<`ChatSubmission`>
The updated submission object.
###### Inherited from [#inherited-from-108]
```ts
ReturnType.untagSubmission
```
##### updateLogo() [#updatelogo]
```ts
updateLogo(projectId, logoData): Promise;
```
Updates the logo asset for a project.
###### Parameters [#parameters-107]
| Parameter | Type | Description |
| ----------- | --------------------------------------------------------------------- | ------------------------------- |
| `projectId` | `string` | The ID of the project. |
| `logoData` | [`LogoUploadData`](/docs/reference/sdk/routes/project#logouploaddata) | File metadata for the new logo. |
###### Returns [#returns-117]
`Promise`\<`any`>
Object containing signed URL data and updated project info.
###### Inherited from [#inherited-from-109]
```ts
ReturnType.updateLogo
```
##### updateProject() [#updateproject]
```ts
updateProject(projectId, updateData): Promise;
```
Updates a project.
###### Parameters [#parameters-108]
| Parameter | Type | Description |
| ------------ | --------------------------------------------------------------------------- | -------------------------------- |
| `projectId` | `string` | The ID of the project to update. |
| `updateData` | [`UpdateProjectData`](/docs/reference/sdk/routes/project#updateprojectdata) | Data to update. |
###### Returns [#returns-118]
`Promise`\<`Project`>
The updated project object.
###### Inherited from [#inherited-from-110]
```ts
ReturnType.updateProject
```
##### updatePublicFileSystem() [#updatepublicfilesystem]
```ts
updatePublicFileSystem(
projectId,
publicId,
updateData
): Promise;
```
Updates an existing public file system's title and description.
###### Parameters [#parameters-109]
| Parameter | Type | Description |
| ------------ | --------------------------------------------------------------------------------------------- | --------------------------------- |
| `projectId` | `string` | The ID of the project. |
| `publicId` | `string` | The ID of the public file system. |
| `updateData` | [`UpdatePublicFileSystemData`](/docs/reference/sdk/routes/project#updatepublicfilesystemdata) | Data to update. |
###### Returns [#returns-119]
`Promise`\<[`PublicFileSystemResponse`](/docs/reference/sdk/routes/project#publicfilesystemresponse)>
The updated public file system object.
###### Inherited from [#inherited-from-111]
```ts
ReturnType.updatePublicFileSystem
```
##### updateSetting() [#updatesetting]
```ts
updateSetting(
projectId,
name,
value
): Promise;
```
Updates a single project setting (e.g. `aiPolishEnabled`,
`aiCustomPreprompt`). Pass `null` to inherit the workspace's value;
pass a typed value to override. The valid setting names are validated
server-side against `projectService.validProjectSettings`.
###### Parameters [#parameters-110]
| Parameter | Type | Description | | |
| ----------- | --------- | ------------------------------------- | ------- | ------- |
| `projectId` | `string` | - | | |
| `name` | `string` | Setting key (e.g. 'aiPolishEnabled'). | | |
| `value` | `unknown` | null (inherit) | boolean | string. |
###### Returns [#returns-120]
`Promise`\<`Project`>
###### Inherited from [#inherited-from-112]
```ts
ReturnType.updateSetting
```
##### updateSubmission() [#updatesubmission]
```ts
updateSubmission(
projectId,
submissionId,
updateData
): Promise;
```
Updates a submission.
###### Parameters [#parameters-111]
| Parameter | Type | Description |
| -------------- | --------------------------------------------------------------------------------- | ------------------------- |
| `projectId` | `string` | The ID of the project. |
| `submissionId` | `string` | The ID of the submission. |
| `updateData` | [`UpdateSubmissionData`](/docs/reference/sdk/routes/project#updatesubmissiondata) | Data to update. |
###### Returns [#returns-121]
`Promise`\<`ChatSubmission`>
The updated submission object.
###### Inherited from [#inherited-from-113]
```ts
ReturnType.updateSubmission
```
***
### SDKVersionInfo [#sdkversioninfo]
SDK Version Information
AUTO-GENERATED - DO NOT EDIT MANUALLY
Generated at: 2026-09-22T16:09:58.836Z
#### Properties [#properties-3]
| Property | Type |
| ------------------------------------------ | -------- |
| `buildHash` | `string` |
| `buildTimestamp` | `string` |
| `gitCommit` | `string` |
| `version` | `string` |
***
### SubscriptionMethods [#subscriptionmethods]
#### Extends [#extends-4]
* `ReturnType`\<*typeof* [`default`](/docs/reference/sdk/routes/subscription#default)>
#### Methods [#methods-4]
##### cancelWorkspaceSubscription() [#cancelworkspacesubscription]
```ts
cancelWorkspaceSubscription(workspaceId): Promise;
```
Cancels the subscription for a specific workspace.
Requires authentication and permission.
###### Parameters [#parameters-112]
| Parameter | Type | Description |
| ------------- | -------- | ------------------------ |
| `workspaceId` | `string` | The ID of the workspace. |
###### Returns [#returns-122]
`Promise`\<`any`>
The cancellation response.
###### Inherited from [#inherited-from-114]
```ts
ReturnType.cancelWorkspaceSubscription
```
##### createWorkspaceOrder() [#createworkspaceorder]
```ts
createWorkspaceOrder(workspaceId, orderData): Promise;
```
Creates a subscription order for a specific workspace.
Requires authentication and permission.
###### Parameters [#parameters-113]
| Parameter | Type | Description |
| ------------- | -------------------------------------------------------------------------------------------------- | ------------------------ |
| `workspaceId` | `string` | The ID of the workspace. |
| `orderData` | [`CreateWorkspaceOrderParams`](/docs/reference/sdk/routes/subscription#createworkspaceorderparams) | The order data. |
###### Returns [#returns-123]
`Promise`\<`any`>
The created order response.
###### Inherited from [#inherited-from-115]
```ts
ReturnType.createWorkspaceOrder
```
##### getResourceLimits() [#getresourcelimits]
```ts
getResourceLimits(resourceId): Promise;
```
Retrieves the resource limits (e.g., storage, seats) for a specific resource (typically workspace).
Requires authentication.
###### Parameters [#parameters-114]
| Parameter | Type | Description |
| ------------ | -------- | ------------------------------------------- |
| `resourceId` | `string` | The ID of the resource (e.g., workspaceId). |
###### Returns [#returns-124]
`Promise`\<[`ResourceLimits`](/docs/reference/sdk/routes/subscription#resourcelimits)>
An object containing the resource limits.
###### Inherited from [#inherited-from-116]
```ts
ReturnType.getResourceLimits
```
##### getRoleUsage() [#getroleusage]
```ts
getRoleUsage(resourceId): Promise;
```
Retrieves per-role (creator / reviewer) seat usage and caps for a
workspace. `limit` is `null` when the plan is unlimited for that
seat type. Requires authentication.
###### Parameters [#parameters-115]
| Parameter | Type | Description |
| ------------ | -------- | ----------------- |
| `resourceId` | `string` | The workspace ID. |
###### Returns [#returns-125]
`Promise`\<[`RoleUsage`](/docs/reference/sdk/routes/subscription#roleusage)>
Creator- and reviewer-side seat usage.
###### Inherited from [#inherited-from-117]
```ts
ReturnType.getRoleUsage
```
##### getSeatUsage() [#getseatusage]
```ts
getSeatUsage(resourceId): Promise;
```
Retrieves the seat usage for a specific resource (typically workspace).
Requires authentication.
###### Parameters [#parameters-116]
| Parameter | Type | Description |
| ------------ | -------- | ------------------------------------------- |
| `resourceId` | `string` | The ID of the resource (e.g., workspaceId). |
###### Returns [#returns-126]
`Promise`\<[`SeatUsage`](/docs/reference/sdk/routes/subscription#seatusage)>
An object containing seat usage details.
###### Inherited from [#inherited-from-118]
```ts
ReturnType.getSeatUsage
```
##### getStorageUsage() [#getstorageusage]
```ts
getStorageUsage(resourceId): Promise;
```
Retrieves the storage usage for a specific resource (typically workspace).
Requires authentication.
###### Parameters [#parameters-117]
| Parameter | Type | Description |
| ------------ | -------- | ------------------------------------------- |
| `resourceId` | `string` | The ID of the resource (e.g., workspaceId). |
###### Returns [#returns-127]
`Promise`\<[`StorageUsage`](/docs/reference/sdk/routes/subscription#storageusage)>
An object containing storage usage details.
###### Inherited from [#inherited-from-119]
```ts
ReturnType.getStorageUsage
```
##### getUserSubscriptions() [#getusersubscriptions]
```ts
getUserSubscriptions(params?): Promise;
```
Retrieves all subscriptions owned by the currently authenticated user.
Requires authentication.
###### Parameters [#parameters-118]
| Parameter | Type | Description |
| --------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------- |
| `params?` | [`GetSubscriptionsParams`](/docs/reference/sdk/routes/subscription#getsubscriptionsparams) | Optional query parameters for status and sorting. |
###### Returns [#returns-128]
`Promise`\<`Subscription`\[]>
An array of subscription objects.
###### Inherited from [#inherited-from-120]
```ts
ReturnType.getUserSubscriptions
```
##### getWorkspaceOrders() [#getworkspaceorders]
```ts
getWorkspaceOrders(workspaceId, params?): Promise;
```
Retrieves subscription orders for a specific workspace.
Requires authentication and permission.
###### Parameters [#parameters-119]
| Parameter | Type | Description |
| ------------- | ---------------------------------------------------------------------------------------------------- | -------------------------- |
| `workspaceId` | `string` | The ID of the workspace. |
| `params?` | [`GetSubscriptionOrdersParams`](/docs/reference/sdk/routes/subscription#getsubscriptionordersparams) | Optional query parameters. |
###### Returns [#returns-129]
`Promise`\<`any`\[]>
An array of subscription order objects.
###### Inherited from [#inherited-from-121]
```ts
ReturnType.getWorkspaceOrders
```
##### getWorkspaceSubscription() [#getworkspacesubscription]
```ts
getWorkspaceSubscription(workspaceId): Promise;
```
Retrieves the active subscription for a specific workspace.
Requires authentication and permission.
###### Parameters [#parameters-120]
| Parameter | Type | Description |
| ------------- | -------- | ------------------------ |
| `workspaceId` | `string` | The ID of the workspace. |
###### Returns [#returns-130]
`Promise`\<`Subscription`>
The workspace subscription object.
###### Inherited from [#inherited-from-122]
```ts
ReturnType.getWorkspaceSubscription
```
##### getWorkspaceUsageSummary() [#getworkspaceusagesummary]
```ts
getWorkspaceUsageSummary(workspaceId): Promise<{
billableSeatCount: number;
storageUsedInBytes: number;
}>;
```
Retrieves the workspace usage summary (billable seats and storage used).
Requires authentication and subscription management permission.
###### Parameters [#parameters-121]
| Parameter | Type | Description |
| ------------- | -------- | ------------------------ |
| `workspaceId` | `string` | The ID of the workspace. |
###### Returns [#returns-131]
`Promise`\<\{
`billableSeatCount`: `number`;
`storageUsedInBytes`: `number`;
}>
Usage summary.
###### Inherited from [#inherited-from-123]
```ts
ReturnType.getWorkspaceUsageSummary
```
##### resumeWorkspaceSubscription() [#resumeworkspacesubscription]
```ts
resumeWorkspaceSubscription(workspaceId): Promise;
```
Reverse a scheduled (period-end) cancellation, keeping the workspace's
subscription on its normal renewal cycle. Only valid while the
subscription is still active with a pending cancellation; a fully
lapsed subscription can't be resumed (the owner must re-subscribe).
Requires authentication and permission.
###### Parameters [#parameters-122]
| Parameter | Type | Description |
| ------------- | -------- | ------------------------ |
| `workspaceId` | `string` | The ID of the workspace. |
###### Returns [#returns-132]
`Promise`\<`any`>
The resume response.
###### Inherited from [#inherited-from-124]
```ts
ReturnType.resumeWorkspaceSubscription
```
##### swapWorkspacePlan() [#swapworkspaceplan]
```ts
swapWorkspacePlan(workspaceId, params): Promise<{
subscription: Subscription | null;
warnings: PlanChangeWarning[];
}>;
```
Swap the workspace's active basePlan line for a different basePlan product.
Same code path both upgrades and downgrades; the API's pre-flight
capacity check is what distinguishes a permitted change from a refused
one. Pass `dryRun: true` to get the pre-flight verdict without mutating.
On over-allocation the API returns 400 `planCapacityInsufficient` with
`errorData.violations: [{ resource, current, newLimit }]`, surfaced via
the SDK's normal error path.
On success, returns the updated subscription plus a `warnings[]` array
of feature-gate capabilities the destination plan does NOT include
(suitable for showing as a confirmation notice).
###### Parameters [#parameters-123]
| Parameter | Type |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `workspaceId` | `string` |
| `params` | \{ `billingPeriod`: `"month"` \| `"year"`; `currency`: `string`; `dryRun?`: `boolean`; `newProductId`: `string`; } |
| `params.billingPeriod` | `"month"` \| `"year"` |
| `params.currency` | `string` |
| `params.dryRun?` | `boolean` |
| `params.newProductId` | `string` |
###### Returns [#returns-133]
`Promise`\<\{
`subscription`: `Subscription` | `null`;
`warnings`: [`PlanChangeWarning`](/docs/reference/sdk/routes/subscription#planchangewarning)\[];
}>
###### Inherited from [#inherited-from-125]
```ts
ReturnType.swapWorkspacePlan
```
***
### UserMethods [#usermethods]
#### Extends [#extends-5]
* `ReturnType`\<*typeof* [`default`](/docs/reference/sdk/routes/user#default)>
#### Methods [#methods-5]
##### createAvatar() [#createavatar]
```ts
createAvatar(fileData): Promise;
```
Creates a new avatar for the user.
###### Parameters [#parameters-124]
| Parameter | Type | Description |
| ---------- | ------------------------------------------------------ | ---------------------------------------------------- |
| `fileData` | [`FileData`](/docs/reference/sdk/routes/user#filedata) | File metadata (e.g., \{ name, checksum, sizeInMB }). |
###### Returns [#returns-134]
`Promise`\<`any`>
Object containing signed URL data and updated user info.
###### Inherited from [#inherited-from-126]
```ts
ReturnType.createAvatar
```
##### deleteCurrentUser() [#deletecurrentuser]
```ts
deleteCurrentUser(): Promise;
```
Deletes the current user.
Requires authentication.
###### Returns [#returns-135]
`Promise`\<`void`>
###### Inherited from [#inherited-from-127]
```ts
ReturnType.deleteCurrentUser
```
##### getSelf() [#getself]
```ts
getSelf(): Promise;
```
Retrieves the current user's profile.
Requires authentication.
###### Returns [#returns-136]
`Promise`\<`PublicUser`>
The current user's profile.
###### Throws [#throws-3]
If no user ID is found in the token.
###### Inherited from [#inherited-from-128]
```ts
ReturnType.getSelf
```
##### getTodos() [#gettodos]
```ts
getTodos(): Promise<{
todos: UserTodo[];
}>;
```
Get the current user's active site-level Todos for the onboarding
drawer. Returns only todos whose completion condition isn't met and
(for dismissibles) that the user hasn't opted out of. Server
computes from live state — no caching on the server side, so a
fresh call always reflects ground truth.
###### Returns [#returns-137]
`Promise`\<\{
`todos`: [`UserTodo`](/docs/reference/sdk/routes/user#usertodo)\[];
}>
###### Inherited from [#inherited-from-129]
```ts
ReturnType.getTodos
```
##### getUser() [#getuser]
```ts
getUser(userId): Promise;
```
Retrieves the public profile of a specific user.
Requires authentication.
###### Parameters [#parameters-125]
| Parameter | Type | Description |
| --------- | -------- | ------------------------------- |
| `userId` | `string` | The ID of the user to retrieve. |
###### Returns [#returns-138]
`Promise`\<`PublicUser`>
Public user object.
###### Inherited from [#inherited-from-130]
```ts
ReturnType.getUser
```
##### markSeen() [#markseen]
```ts
markSeen(element): Promise;
```
Record that the current user has seen a one-time UI element (welcome
video, tutorial coachmark). Idempotent. Returns the updated user.
###### Parameters [#parameters-126]
| Parameter | Type | Description |
| --------- | -------- | ----------------------------------------------------------------------------- |
| `element` | `string` | one-time element key (must be one of the element keys the server recognises). |
###### Returns [#returns-139]
`Promise`\<`User`>
###### Inherited from [#inherited-from-131]
```ts
ReturnType.markSeen
```
##### unmarkSeen() [#unmarkseen]
```ts
unmarkSeen(elements?): Promise;
```
Remove one-time UI elements from the current user's `hasSeen` so they
display again. Pass specific element keys, or omit to clear ALL.
Returns the updated user.
###### Parameters [#parameters-127]
| Parameter | Type | Description |
| ----------- | ----------- | -------------------------------------- |
| `elements?` | `string`\[] | elements to remove; omit to clear all. |
###### Returns [#returns-140]
`Promise`\<`User`>
###### Inherited from [#inherited-from-132]
```ts
ReturnType.unmarkSeen
```
##### updateAvatar() [#updateavatar]
```ts
updateAvatar(fileData): Promise;
```
Updates the user's avatar.
###### Parameters [#parameters-128]
| Parameter | Type | Description |
| ---------- | ------------------------------------------------------ | ---------------------------------------------------- |
| `fileData` | [`FileData`](/docs/reference/sdk/routes/user#filedata) | File metadata (e.g., \{ name, checksum, sizeInMB }). |
###### Returns [#returns-141]
`Promise`\<`any`>
Object containing signed URL data and updated user info.
###### Inherited from [#inherited-from-133]
```ts
ReturnType.updateAvatar
```
##### updatePreferences() [#updatepreferences]
```ts
updatePreferences(preferenceData): Promise;
```
Updates the user's preferences.
###### Parameters [#parameters-129]
| Parameter | Type | Description |
| ---------------- | -------------------------------------------------------------------- | ----------------------------------------------------------- |
| `preferenceData` | [`PreferencesData`](/docs/reference/sdk/routes/user#preferencesdata) | Preference data to update (e.g., \{ hide: \['feedHint'] }). |
###### Returns [#returns-142]
`Promise`\<`User`>
Updated user object.
###### Inherited from [#inherited-from-134]
```ts
ReturnType.updatePreferences
```
##### updateSelf() [#updateself]
```ts
updateSelf(updateData): Promise;
```
Updates the logged-in user's profile.
Requires authentication.
At least one field must be provided.
###### Parameters [#parameters-130]
| Parameter | Type | Description |
| ------------ | ------------------------------------------------------------------ | ------------------------------- |
| `updateData` | [`UpdateUserData`](/docs/reference/sdk/routes/user#updateuserdata) | The user data fields to update. |
###### Returns [#returns-143]
`Promise`\<`User`>
The updated user object.
###### Inherited from [#inherited-from-135]
```ts
ReturnType.updateSelf
```
***
### WorkspaceMethods [#workspacemethods]
#### Extends [#extends-6]
* `ReturnType`\<*typeof* [`default`](/docs/reference/sdk/routes/workspace#default)>
#### Methods [#methods-6]
##### createIcon() [#createicon]
```ts
createIcon(workspaceId, fileData): Promise;
```
Request signed URL data to upload a workspace icon (the small square
shown in sidebars and tabs — distinct from the logo).
###### Parameters [#parameters-131]
| Parameter | Type |
| ------------- | ----------------------------------------------------------- |
| `workspaceId` | `string` |
| `fileData` | [`FileData`](/docs/reference/sdk/routes/workspace#filedata) |
###### Returns [#returns-144]
`Promise`\<`any`>
Response containing signed URL data and workspace info.
###### Inherited from [#inherited-from-136]
```ts
ReturnType.createIcon
```
##### createLogo() [#createlogo-1]
```ts
createLogo(workspaceId, fileData): Promise;
```
Request signed URL data to upload a workspace logo.
Caller then multipart-uploads the file using the returned `signedUrlData`
and calls `client.asset.completeUpload(...)` to finalize.
###### Parameters [#parameters-132]
| Parameter | Type |
| ------------- | ----------------------------------------------------------- |
| `workspaceId` | `string` |
| `fileData` | [`FileData`](/docs/reference/sdk/routes/workspace#filedata) |
###### Returns [#returns-145]
`Promise`\<`any`>
Response containing signed URL data and workspace info.
###### Inherited from [#inherited-from-137]
```ts
ReturnType.createLogo
```
##### createWorkspace() [#createworkspace]
```ts
createWorkspace(data): Promise;
```
Creates a new workspace.
Requires authentication.
###### Parameters [#parameters-133]
| Parameter | Type | Description |
| --------- | --------------------------------------------------------------------------------- | --------------- |
| `data` | [`CreateWorkspaceData`](/docs/reference/sdk/routes/workspace#createworkspacedata) | Workspace data. |
###### Returns [#returns-146]
`Promise`\<`any`>
The created workspace object.
###### Inherited from [#inherited-from-138]
```ts
ReturnType.createWorkspace
```
##### deleteWorkspace() [#deleteworkspace]
```ts
deleteWorkspace(workspaceId): Promise;
```
Soft-delete a workspace. All nested resources (projects, chats,
assets) become inaccessible; bytes are reclaimed by the cleanup
cron.
###### Parameters [#parameters-134]
| Parameter | Type | Description |
| ------------- | -------- | ---------------------------------- |
| `workspaceId` | `string` | The ID of the workspace to delete. |
###### Returns [#returns-147]
`Promise`\<`any`>
Object confirming the status change.
###### Inherited from [#inherited-from-139]
```ts
ReturnType.deleteWorkspace
```
##### getWorkspace() [#getworkspace]
```ts
getWorkspace(workspaceId): Promise;
```
Retrieves a specific workspace by its ID.
Requires authentication.
###### Parameters [#parameters-135]
| Parameter | Type | Description |
| ------------- | -------- | ------------------------------------ |
| `workspaceId` | `string` | The ID of the workspace to retrieve. |
###### Returns [#returns-148]
`Promise`\<`any`>
The workspace object.
###### Inherited from [#inherited-from-140]
```ts
ReturnType.getWorkspace
```
##### listProjects() [#listprojects]
```ts
listProjects(workspaceId): Promise;
```
List the projects inside a workspace that the calling user has
access to.
###### Parameters [#parameters-136]
| Parameter | Type | Description |
| ------------- | -------- | ------------------------ |
| `workspaceId` | `string` | The ID of the workspace. |
###### Returns [#returns-149]
`Promise`\<`any`\[]>
An array of project objects.
###### Inherited from [#inherited-from-141]
```ts
ReturnType.listProjects
```
##### listWorkspaces() [#listworkspaces]
```ts
listWorkspaces(sortParams?): Promise;
```
Lists all workspaces the authenticated user has access to.
Requires authentication.
###### Parameters [#parameters-137]
| Parameter | Type | Description |
| ------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sortParams?` | [`SortParams`](/docs/reference/sdk/routes/workspace#sortparams) | Optional sorting. Keys are field names (`id`, `name`, `createdAt`, `updatedAt`); values are 1 for ascending or -1 for descending. Sent as `?sort[name]=1&sort[createdAt]=-1`. |
###### Returns [#returns-150]
`Promise`\<`any`\[]>
Workspaces with the caller's `roles` and the workspace `capabilities`.
###### Inherited from [#inherited-from-142]
```ts
ReturnType.listWorkspaces
```
##### updateIcon() [#updateicon]
```ts
updateIcon(workspaceId, fileData): Promise;
```
Request signed URL data to replace the workspace icon. Same upload
shape as `createIcon`.
###### Parameters [#parameters-138]
| Parameter | Type |
| ------------- | ----------------------------------------------------------- |
| `workspaceId` | `string` |
| `fileData` | [`FileData`](/docs/reference/sdk/routes/workspace#filedata) |
###### Returns [#returns-151]
`Promise`\<`any`>
Response containing signed URL data and workspace info.
###### Inherited from [#inherited-from-143]
```ts
ReturnType.updateIcon
```
##### updateLogo() [#updatelogo-1]
```ts
updateLogo(workspaceId, fileData): Promise;
```
Request signed URL data to replace the workspace logo. Same upload
shape as `createLogo`; existing logo is replaced once `completeUpload`
lands.
###### Parameters [#parameters-139]
| Parameter | Type |
| ------------- | ----------------------------------------------------------- |
| `workspaceId` | `string` |
| `fileData` | [`FileData`](/docs/reference/sdk/routes/workspace#filedata) |
###### Returns [#returns-152]
`Promise`\<`any`>
Response containing signed URL data and workspace info.
###### Inherited from [#inherited-from-144]
```ts
ReturnType.updateLogo
```
##### updateSetting() [#updatesetting-1]
```ts
updateSetting(
workspaceId,
settingName,
value
): Promise;
```
Toggle a single workspace boolean setting (e.g. an `enableX` feature
flag).
###### Parameters [#parameters-140]
| Parameter | Type | Description |
| ------------- | --------- | ------------------------------ |
| `workspaceId` | `string` | The ID of the workspace. |
| `settingName` | `string` | The name of the setting. |
| `value` | `boolean` | The new value for the setting. |
###### Returns [#returns-153]
`Promise`\<`any`>
The updated workspace object with new settings.
###### Inherited from [#inherited-from-145]
```ts
ReturnType.updateSetting
```
##### updateWorkspace() [#updateworkspace]
```ts
updateWorkspace(workspaceId, updateData): Promise;
```
Update workspace metadata (name, description, etc.).
###### Parameters [#parameters-141]
| Parameter | Type |
| ------------- | --------------------------------------------------------------------------------- |
| `workspaceId` | `string` |
| `updateData` | [`UpdateWorkspaceData`](/docs/reference/sdk/routes/workspace#updateworkspacedata) |
###### Returns [#returns-154]
`Promise`\<`any`>
The updated workspace object.
###### Inherited from [#inherited-from-146]
```ts
ReturnType.updateWorkspace
```
## Functions [#functions]
### isApiError() [#isapierror]
```ts
function isApiError(error): error is ApiError;
```
Narrow an unknown thrown value to an API error carrying an HTTP status.
#### Parameters [#parameters-142]
| Parameter | Type |
| --------- | --------- |
| `error` | `unknown` |
#### Returns [#returns-155]
`error is ApiError`
## References [#references]
### Bot [#bot]
Re-exports [Bot](/docs/reference/sdk/routes/bot#bot)
***
### BotApiKeySummary [#botapikeysummary]
Re-exports [BotApiKeySummary](/docs/reference/sdk/routes/bot#botapikeysummary)
***
### BotProjectMembership [#botprojectmembership]
Re-exports [BotProjectMembership](/docs/reference/sdk/routes/bot#botprojectmembership)
***
### BotProjectRole [#botprojectrole]
Re-exports [BotProjectRole](/docs/reference/sdk/routes/bot#botprojectrole)
***
### CreateBotData [#createbotdata]
Re-exports [CreateBotData](/docs/reference/sdk/routes/bot#createbotdata)
***
### CreateBotResponse [#createbotresponse]
Re-exports [CreateBotResponse](/docs/reference/sdk/routes/bot#createbotresponse)
***
### CreateSupportTicketRequest [#createsupportticketrequest]
Re-exports [CreateSupportTicketRequest](/docs/reference/sdk/routes/supportTicket#createsupportticketrequest)
***
### CreateTokenData [#createtokendata]
Re-exports [CreateTokenData](/docs/reference/sdk/routes/token#createtokendata)
***
### CreateTokenResponse [#createtokenresponse]
Re-exports [CreateTokenResponse](/docs/reference/sdk/routes/token#createtokenresponse)
***
### CreateWebhookData [#createwebhookdata]
Re-exports [CreateWebhookData](/docs/reference/sdk/routes/webhook#createwebhookdata)
***
### CreateWebhookResponse [#createwebhookresponse]
Re-exports [CreateWebhookResponse](/docs/reference/sdk/routes/webhook#createwebhookresponse)
***
### HealthStatus [#healthstatus]
Re-exports [HealthStatus](/docs/reference/sdk/routes/version#healthstatus)
***
### ListDeliveriesParams [#listdeliveriesparams]
Re-exports [ListDeliveriesParams](/docs/reference/sdk/routes/webhook#listdeliveriesparams)
***
### ListDeliveriesResponse [#listdeliveriesresponse]
Re-exports [ListDeliveriesResponse](/docs/reference/sdk/routes/webhook#listdeliveriesresponse)
***
### RotateBotKeyResponse [#rotatebotkeyresponse]
Re-exports [RotateBotKeyResponse](/docs/reference/sdk/routes/bot#rotatebotkeyresponse)
***
### RotateWebhookSecretResponse [#rotatewebhooksecretresponse]
Re-exports [RotateWebhookSecretResponse](/docs/reference/sdk/routes/webhook#rotatewebhooksecretresponse)
***
### SupportTicket [#supportticket]
Re-exports [SupportTicket](/docs/reference/sdk/routes/supportTicket#supportticket)
***
### SupportTicketListParams [#supportticketlistparams]
Re-exports [SupportTicketListParams](/docs/reference/sdk/routes/supportTicket#supportticketlistparams)
***
### SupportTicketListResponse [#supportticketlistresponse]
Re-exports [SupportTicketListResponse](/docs/reference/sdk/routes/supportTicket#supportticketlistresponse)
***
### SupportTicketScope [#supportticketscope]
Re-exports [SupportTicketScope](/docs/reference/sdk/routes/supportTicket#supportticketscope)
***
### SupportTicketScopeOptions [#supportticketscopeoptions]
Re-exports [SupportTicketScopeOptions](/docs/reference/sdk/routes/supportTicket#supportticketscopeoptions)
***
### SupportTicketStatus [#supportticketstatus]
Re-exports [SupportTicketStatus](/docs/reference/sdk/routes/supportTicket#supportticketstatus-1)
***
### TestWebhookResponse [#testwebhookresponse]
Re-exports [TestWebhookResponse](/docs/reference/sdk/routes/webhook#testwebhookresponse)
***
### TokenKind [#tokenkind]
Re-exports [TokenKind](/docs/reference/sdk/routes/token#tokenkind)
***
### TokenScope [#tokenscope]
Re-exports [TokenScope](/docs/reference/sdk/routes/token#tokenscope)
***
### TokenSummary [#tokensummary]
Re-exports [TokenSummary](/docs/reference/sdk/routes/token#tokensummary)
***
### UpdateBotAvatarFileData [#updatebotavatarfiledata]
Re-exports [UpdateBotAvatarFileData](/docs/reference/sdk/routes/bot#updatebotavatarfiledata)
***
### UpdateBotAvatarResponse [#updatebotavatarresponse]
Re-exports [UpdateBotAvatarResponse](/docs/reference/sdk/routes/bot#updatebotavatarresponse)
***
### UpdateBotData [#updatebotdata]
Re-exports [UpdateBotData](/docs/reference/sdk/routes/bot#updatebotdata)
***
### UpdateWebhookData [#updatewebhookdata]
Re-exports [UpdateWebhookData](/docs/reference/sdk/routes/webhook#updatewebhookdata)
***
### UserTodo [#usertodo]
Re-exports [UserTodo](/docs/reference/sdk/routes/user#usertodo)
***
### WebhookAttempt [#webhookattempt]
Re-exports [WebhookAttempt](/docs/reference/sdk/routes/webhook#webhookattempt)
***
### WebhookAttemptStatus [#webhookattemptstatus]
Re-exports [WebhookAttemptStatus](/docs/reference/sdk/routes/webhook#webhookattemptstatus-1)
***
### WebhookEvent [#webhookevent]
Re-exports [WebhookEvent](/docs/reference/sdk/routes/webhook#webhookevent)
***
### WebhookSubscription [#webhooksubscription]
Re-exports [WebhookSubscription](/docs/reference/sdk/routes/webhook#webhooksubscription)
***
### WebhookSubscriptionStatus [#webhooksubscriptionstatus]
Re-exports [WebhookSubscriptionStatus](/docs/reference/sdk/routes/webhook#webhooksubscriptionstatus-1)
# SDK reference (/docs/reference/sdk)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
Generated from the TypeScript sources of [`@nurama/sdk`](https://www.npmjs.com/package/@nurama/sdk). Start with the [method index](./sdk/method-index) for a task-oriented view, then use the namespace pages for signatures and types.
## Clients [#clients]
* [BotClient](/docs/reference/sdk/BotClient)
* [NuramaClient](/docs/reference/sdk/NuramaClient)
## Namespaces [#namespaces]
Available on both clients as `client.` / `bot.`.
* [`ai`](/docs/reference/sdk/routes/ai)
* [`asset`](/docs/reference/sdk/routes/asset)
* [`auth`](/docs/reference/sdk/routes/auth)
* [`blogPosts`](/docs/reference/sdk/routes/blogPosts)
* [`board`](/docs/reference/sdk/routes/board)
* [`bot`](/docs/reference/sdk/routes/bot)
* [`chat`](/docs/reference/sdk/routes/chat)
* [`chatAi`](/docs/reference/sdk/routes/chatAi)
* [`config`](/docs/reference/sdk/routes/config)
* [`convo`](/docs/reference/sdk/routes/convo)
* [`credits`](/docs/reference/sdk/routes/credits)
* [`device`](/docs/reference/sdk/routes/device)
* [`folder`](/docs/reference/sdk/routes/folder)
* [`invite`](/docs/reference/sdk/routes/invite)
* [`membership`](/docs/reference/sdk/routes/membership)
* [`notification`](/docs/reference/sdk/routes/notification)
* [`payment`](/docs/reference/sdk/routes/payment)
* [`product`](/docs/reference/sdk/routes/product)
* [`project`](/docs/reference/sdk/routes/project)
* [`public`](/docs/reference/sdk/routes/public)
* [`scratch`](/docs/reference/sdk/routes/scratch)
* [`settings`](/docs/reference/sdk/routes/settings)
* [`shortlink`](/docs/reference/sdk/routes/shortlink)
* [`socket`](/docs/reference/sdk/routes/socket)
* [`storage`](/docs/reference/sdk/routes/storage)
* [`subscription`](/docs/reference/sdk/routes/subscription)
* [`supportChat`](/docs/reference/sdk/routes/supportChat)
* [`supportTicket`](/docs/reference/sdk/routes/supportTicket)
* [`tag`](/docs/reference/sdk/routes/tag)
* [`task`](/docs/reference/sdk/routes/task)
* [`taskRelation`](/docs/reference/sdk/routes/taskRelation)
* [`token`](/docs/reference/sdk/routes/token)
* [`user`](/docs/reference/sdk/routes/user)
* [`version`](/docs/reference/sdk/routes/version)
* [`webhook`](/docs/reference/sdk/routes/webhook)
* [`workspace`](/docs/reference/sdk/routes/workspace)
# Method index (/docs/reference/sdk/method-index)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
> Method index for `@nurama/sdk` and `@nurama/sdk/bot`, organized for both human readers and AI assistants working in this repo. Use this as the single starting point when building tools, integrations, or bots — most things you'd think to write from scratch already exist as a method here.
## Two clients [#two-clients]
* **`NuramaClient`** (`packages/sdk/src/NuramaClient.ts`) — JWT-authenticated, full surface. For server-side code acting on behalf of a user, or admin tooling.
* **`BotClient`** (`packages/sdk/src/BotClient.ts`) — bot API key (`nrm_bot_…`), reduced surface (no auth/user-self/payment/subscription/device/bot-administration). Default base URLs are `https://bot.nurama.com` (HTTP) and `https://bot-ws.nurama.com` (WebSocket). Use this from any process running as a bot user.
```js
import BotClient from '@nurama/sdk/bot';
const bot = new BotClient(process.env.NURAMA_BOT_API_KEY);
```
Both clients expose the same namespace objects (`bot.chat`, `client.chat`, etc.); the only difference is what's reachable. This document covers the **bot-reachable** subset. Non-bot namespaces (`auth`, `payment`, `subscription`, `device`) are intentionally omitted.
## Conventions [#conventions]
* **Read-only** vs **mutating** — flagged on every method. Bots in read-heavy workflows should default to read-only methods unless their purpose is explicitly to write.
* **Method names repeat the noun** — `asset.getAsset`, `board.createBoard`, `supportTicket.listSupportTickets`, never `asset.get`. Methods close over the client rather than `this`, so a namespace can be destructured (`const { getAsset, updateAsset } = client.asset`) and names from different namespaces never collide. Verb vocabulary: `get`/`list` for reads, `create`, `update`, `delete`, `add`/`remove` for membership-style changes, and the action name (`follow`, `tag`, `publish`, ...) for actions.
* **Methods live in the namespace of the resource in the URL** — `/tasks/{id}/links` is `task.getTaskLinks`, `/public-download/{token}` is `public.resolvePublicDownload`.
* **Visibility is an argument** — reads that differ by tier take `visibility: 'creator' | 'reviewer'` (e.g. `project.getAssets(projectId, 'reviewer')`, `project.getHomeFeed`, `project.getFolders`, `project.getProjectChat`, `project.getHighlightedMessages`). Always pass the tier matching the originating chat; never read across tiers.
* **Pagination** — methods returning `PaginatedResponse` accept `{ limit, paginate: 'cursor' | 'index', cursor?, page? }`. Cursor pagination is the default for streams; index pagination for fixed-size lists. Backend caps `limit` at 20 in most places.
* **Required IDs** — `chatId`, `projectId`, `messageId`, etc. throw if missing. Always pass them.
## Bot-relevant subset (start here) [#bot-relevant-subset-start-here]
For most bot tools, you'll want one of these:
| Goal | Method | Notes |
| -------------------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
| Get the chat the bot was @mentioned in | `bot.chat.getChat(chatId)` | Read-only. Returns `chatType`, `topicType`, `topicId`, `visibility`, `participants`. |
| Get recent chat history | `bot.chat.getMessages(chatId, params)` | Read-only. `sort: { createdAt: -1 }, limit: 20, excludeReplies: true` is the conventional shape. |
| Get one message | `bot.chat.getMessage(messageId)` | Read-only. Used for reply-author lookups. |
| Reply in a chat | `bot.chat.createMessage(chatId, { content, assetMentions?, mentions? })` | **Mutating.** Pass `assetMentions: [uuid…]` to render `{{assetMention:UUID}}` tokens as clickable. |
| List active assets in a project | `bot.project.getHomeFeed(projectId, visibility, params)` | Read-only. Same shape as the FE feed; pass `chatMessageLimit: 20` to get chat data inline. |
| List project members | `bot.membership.getProjectMemberships(projectId, params)` | Read-only. |
| Get bot's own memberships | `bot.membership.getMyMemberships()` | Read-only. Used at startup. |
| Subscribe to events | `bot.socket.subscribe(channel, event, handler)` | Channels: `/user/{botUserId}`, `/project/{projectId}`, `/project/{projectId}/{visibility}`. |
| Emit typing indicator | `bot.socket.emit(channel, 'typing:start', { chatId })` / `typing:stop` | Bot must already be subscribed to `channel`. Server fans out to chat/project channels automatically. |
If your tool is doing something that doesn't fit the table above, scan the per-namespace sections below before writing new code.
***
## `bot.chat` — chats and messages [#botchat--chats-and-messages]
> Reference: [chat](/docs/reference/sdk/routes/chat)
### Topic chats (auto-created for projects/assets/tasks) [#topic-chats-auto-created-for-projectsassetstasks]
* **read** `createTopicChat(data)` — programmatic topic-chat creation (rare; usually auto-created).
* **read** `getChatByTopicId(topicId, { topicType, visibility })` — fetch by topic instead of chatId.
* **read** `getChat(chatId)` — single chat with metadata + recentMessages refs.
* **mutate** `updateChatSubject(chatId, { subject })`
* **mutate** `deleteChat(chatId)` — *destructive*
### Member chats (private DMs) [#member-chats-private-dms]
* **mutate** `createMemberChat(data)` — start a 1:1 or group chat.
* **read** `getUsersMemberChats(params)` — paginated list of bot's member chats.
* **read** `getMemberChat(chatId)` — single member chat.
* **mutate** `updateMemberChat(chatId, data)`
* **mutate** `archiveMemberChat(chatId)` / `unarchiveMemberChat(chatId)`
* **mutate** `addMembers(chatId, { memberIds })` / `removeMembers(chatId, { memberIds })`
* **read** `getAddableMembers(chatId)` — who can be invited.
* **mutate** `updateMemberChatIcon(chatId, fileData)`
* **mutate** `deleteMemberChat(chatId)` — *destructive*
### Messages [#messages]
* **mutate** `createMessage(chatId, { content, attachments?, mentions?, assetMentions?, folderMentions?, replyToId?, quotes? })` — primary write for bots.
* **read** `getMessages(chatId, { limit, sort, excludeReplies, contentSearch?, authorId?, hasAttachments?, hasAnnotations?, highlighted?, type? })` — paginated.
* **read** `getMessage(messageId, { replies? })`
* **mutate** `reviseMessage(messageId, data)`
* **mutate** `deleteMessage(messageId)` — *destructive*
* **read** `getReplies(messageId, params)`
* **read** `getMessagePage(messageId, params)` — find which page a message is on.
* **mutate** `addAttachments(messageId, attachments)` / `removeAttachment(messageId, assetId)`
* **read** `getMentions(params)` — bot's @-mentions across chats.
* **mutate** `createReaction(messageId, { emoji })` / `removeReaction(messageId)`
* **mutate** `highlightMessage(messageId)` / `unhighlightMessage(messageId)`
* **mutate** `createMessageShortLink(messageId)` — returns `{ code, shortUrl }`.
* **read** `fetchLinkPreviews({ urls })`
### Mentionable resources (chat-scoped autocomplete) [#mentionable-resources-chat-scoped-autocomplete]
* **read** `getMentionableAssets(chatId, params)` — assets reachable from this chat.
* **read** `getMentionableFolders(chatId, params)`
### Summaries + chat following [#summaries--chat-following]
* **mutate** `generateSummary(chatId, data)` — generate an AI summary of recent activity.
* **read** `getSummaries(chatId, params)`
* **mutate** `followChat(chatId)` / `unfollowChat(chatId)`
### Asset chat shortcut [#asset-chat-shortcut]
* **mutate** `createAssetChatAndMessage(assetId, visibility, data, params)` — create a chat (if absent) and post a message in one call.
***
## `bot.project` — projects, assets-in-project, submissions, file system [#botproject--projects-assets-in-project-submissions-file-system]
> Reference: [project](/docs/reference/sdk/routes/project) (the largest namespace)
### Project CRUD [#project-crud]
* **read** `getProjects()` — bot's accessible projects (also see `bot.workspace.listProjects(workspaceId)`).
* **read** `getProject(projectId)`
* **mutate** `createProject(data)` / `updateProject(projectId, data)` / `deleteProject(projectId)`
* **mutate** `createLogo(projectId, fileData)` / `updateLogo(projectId, fileData)`
### Assets in a project (visibility-scoped) [#assets-in-a-project-visibility-scoped]
* **read** `getAssets(projectId, visibility, params)` — flat lists, no chat data.
* **read** `getHomeFeed(projectId, visibility, params)` — assets *with* their chat data inline. **This is what the FE uses.** Pass `chatMessageLimit: 20`, `mediaTypes: ['image','video','audio']` to mirror the FE feed.
* **read** `getHomeFeed(projectId, visibility, params)` — visibility-parameterized version.
* **mutate** `createAssets(projectId, fileUploadBody)` — initiate uploads.
### Folders [#folders]
* **read** `getFolders(projectId, visibility, params)`
* **read** `getFolders(projectId, visibility, params)`
* **mutate** `createFolder(projectId, visibility, data)`
### Project chats [#project-chats]
* **read** `getProjectChat(projectId, visibility, params)`
### File-system path operations (visibility-scoped) [#file-system-path-operations-visibility-scoped]
* **read** `getItemsAtPath(projectId, visibility, path, params, usePost?)`
* **mutate** `moveItemsToPath(projectId, visibility, data)` / `copyItemsToPath` / `deleteItemsAtPath` — *destructive*
### Submissions [#submissions]
* **mutate** `createSubmission(projectId, data)`
* **read** `getSubmissions(projectId, params)` / `getSubmission(projectId, submissionId, params)`
* **read** `getSubmissionAssets(projectId, submissionId, params)`
* **read** `getSubmissionItems(projectId, submissionId, path?, params)`
* **mutate** `addItemsToSubmission` / `updateSubmission` / `tagSubmission` / `untagSubmission`
* **mutate** `createSubmissionFolder` / `moveSubmissionItems` / `copySubmissionItems` / `deleteSubmissionItems` — *destructive last one*
### Publishing [#publishing]
* **mutate** `publishItems(projectId, data)` / `unpublishItems(projectId, data)`
### Public file systems (shareable links) [#public-file-systems-shareable-links]
* **read** `getPublicFileSystems(projectId, params)` / `getPublicFileSystem(projectId, publicId)` / `getPublicAudit(...)`
* **mutate** `createPublicFileSystem(projectId, data)` / `updatePublicFileSystem` / `deletePublicFileSystem`
* **mutate** `addItemsToPublicFileSystem` / `getPublicItemsAtPath` / `movePublicItemsAtPath` / `copyPublicItemsAtPath` / `deletePublicItemsAtPath`
***
## `bot.asset` — single-asset operations [#botasset--single-asset-operations]
> Reference: [asset](/docs/reference/sdk/routes/asset)
* **read** `getAsset(assetId, { includeChats? })`
* **mutate** `updateAsset(assetId, data)` / `deleteAsset(assetId)` — *destructive last one*
* **read** `getFile(assetId, fileId)` — file metadata.
* **read** `getFilesByFunctionType(assetId, functionType)` — e.g. `'thumbnail'`, `'original'`, `'media'`.
* **read** `getAssetPage(assetId, params)` — find which page in a list this asset appears on.
* **mutate** `tagAsset(assetId, data)` / `untagAsset(assetId, data)`
* **mutate** `multipartUpload(...)` / `completeMultipartUpload(uploadData)` — file upload pipeline.
* **mutate** `repairAssets(assetIds)` — re-trigger post-processing.
* **read** `downloadAssets(assetIds)` — returns signed download URLs.
* **mutate** `createShortLink(assetId, data?)`
* **mutate** `createPublicLink(...)` / `updatePublicLink(...)` / `disablePublicLink` / `reactivatePublicLink`
* **read** `getPublicLinks(assetId)`
***
## `bot.folder` — single-folder operations [#botfolder--single-folder-operations]
> Reference: [folder](/docs/reference/sdk/routes/folder)
* **read** `getFolder(folderId)` / `getFoldersAssets(folderId, params)`
* **mutate** `updateFolder(folderId, data)` / `updateFolderName(folderId, { name })` / `updateFolderIcon(folderId, data)`
* **mutate** `deleteFolder(folderId)` — *destructive*
* **mutate** `tagFolder(folderId, data)` / `untagFolder(folderId, data)`
***
## `bot.membership` — who has access to what [#botmembership--who-has-access-to-what]
> Reference: [membership](/docs/reference/sdk/routes/membership)
* **read** `getMyMemberships()` — for the bot user. Used at startup to derive the bot's projects.
* **read** `getWorkspaceMemberships(workspaceId, params)` / `getProjectMemberships(projectId, params)` — paginated, supports `nameSearch` and `billable` filters.
* **read** `getProjectMentionableUsers(projectId, visibility)` — autocomplete for @mentions.
* **read** `getWorkspaceLastSeen(workspaceId, { userIds })` / `getProjectLastSeen(projectId, { userIds })` — bulk last-active timestamps (1–100 users).
* **mutate** `addRole(data)` / `removeRole(data)` — *privileged; bot needs admin scope*.
* **mutate** `deleteMembership(membershipId)` / `leaveResource(resourceId)` — *destructive*
***
## `bot.notification` — historical notifications [#botnotification--historical-notifications]
> Reference: [notification](/docs/reference/sdk/routes/notification)
* **read** `getNotifications(data)` — paginated by channels/types.
* **read** `getNewNotifications(data)` — unread since last seen.
* **read** `getNewNotificationCount(data)` / `getNewNotificationCountBulk(data)` — counts only.
* **read** `getUsersLastNotificationsSeen(data)` — last-seen timestamp per channel/type.
* **mutate** `updateUsersLastSeen(data)` — mark seen.
For real-time notifications, use `bot.socket.subscribe` instead.
***
## `bot.task` — tasks and acknowledgement [#bottask--tasks-and-acknowledgement]
> Reference: [task](/docs/reference/sdk/routes/task)
* **read** `getMyTasks(params)` — bot's tasks; filter by `projectId`, `creatorId`, `relatedToId`, `visibility`, `acknowledged`.
* **mutate** `updateTaskStatus(taskId, { status })` — `pending` / `inProgress` / `complete` / `cancelled`.
* **mutate** `acknowledgeTask(taskId)` — clears the unacknowledged flag.
* **read** `getUnacknowledgedTaskCount(projectId)` / `getTaskEvents(taskId, params)`
***
## `bot.user` — user profiles [#botuser--user-profiles]
> Reference: [user](/docs/reference/sdk/routes/user)
* **read** `getUser(userId)` — public profile (sanitized).
* **read** `getSelf()` — bot's own profile.
* **mutate** `updateSelf(data)` / `updatePreferences(data)` / `createAvatar(fileData)` / `updateAvatar(fileData)` — bot self-administration.
***
## `bot.workspace` — workspaces and their projects [#botworkspace--workspaces-and-their-projects]
> Reference: [workspace](/docs/reference/sdk/routes/workspace)
* **read** `getWorkspace(workspaceId)` / `listWorkspaces(sortParams)` / `listProjects(workspaceId)`
* **mutate** `createWorkspace(data)` / `updateWorkspace(workspaceId, data)` / `updateSetting(workspaceId, name, value)`
* **mutate** `deleteWorkspace(workspaceId)` — *destructive*
* **mutate** Logo/icon CRUD: `createLogo` / `updateLogo` / `createIcon` / `updateIcon`
***
## `bot.board` — kanban boards [#botboard--kanban-boards]
> Reference: [board](/docs/reference/sdk/routes/board)
* **read** `getProjectBoards(projectId, params)` / `getProjectTasks(projectId, params)` / `getBoard(boardId)` / `getBoardTasks(...)` / `getTaskLinks(taskId)`
* **mutate** `createBoard` / `updateBoard` / `deleteBoard` — *destructive last*
* **mutate** Column ops: `addColumn` / `reorderColumns` / `updateColumn` / `deleteColumn`
* **mutate** Task ops: `createBoardTask` / `addExistingTaskToBoard` / `moveTask` / `removeTaskFromBoard` / `updateTaskDetails`
* **mutate** Linking: `linkTask(taskId, data)` / `unlinkTask(taskId, linkedTaskId)`
* **mutate** Tagging: `tagBoard` / `untagBoard` / `tagTask` / `untagTask`
***
## `bot.convo` — live conversations [#botconvo--live-conversations]
> Reference: [convo](/docs/reference/sdk/routes/convo)
* **mutate** `startConvo(data)` / `joinConvo(convoId)` / `rejoinConvo` / `leaveConvo` / `completeConvo` / `deleteConvo` / `updateConvo`
* **read** `getConvo(convoId)` / `getScopeConvos(...)`
***
## `bot.public` — public file system access [#botpublic--public-file-system-access]
> Reference: [public](/docs/reference/sdk/routes/public)
For when bots interact with publicly shared content via tokens.
* **read** `getPublicFileSystem(token)` / `getPublicItems(token, params)` / `getPublicItemsAtPath(token, path, params)` / `getPublicAsset(token, assetId)` / `getPublicChat(token, chatId?)` / `getPublicChatMessages(...)`
* **mutate** `createPublicChatMessage(...)` / `createPublicTopicChatMessage(...)` / `createPublicAssetChatMessage(...)`
* **read** `downloadAssets(token, data)` — public signed downloads.
***
## `bot.shortlink` [#botshortlink]
> Reference: [shortlink](/docs/reference/sdk/routes/shortlink)
* **read** `resolveShortLink(code)` — returns the canonical resource the link points to.
* **read** `resolvePublicDownload(token)` / `getPublicDownloadUrl(token)`
***
## `bot.tag` — workspace tags [#bottag--workspace-tags]
> Reference: [tag](/docs/reference/sdk/routes/tag)
* **mutate** `createTag(data)` / `updateTag(tagId, data)` / `deleteTag(tagId)`
* **read** `getTags(...)`
***
## `bot.invite` — invitations [#botinvite--invitations]
> Reference: [invite](/docs/reference/sdk/routes/invite)
* **mutate** `inviteUser(data)` / `acceptInvite(inviteId)` / `cancelInvite(inviteId)` / `resendInvite(inviteId)`
* **read** `getInvites(params)` / `getInviteById(inviteId)` / `getInvitesForResource(resourceId, params)`
***
## `bot.settings` — resource settings [#botsettings--resource-settings]
> Reference: [settings](/docs/reference/sdk/routes/settings)
* **read** `getEffectiveSettings(...)` — resolved with inheritance.
* **read** `getResourceSettings(...)` / `getAllResourceSettings()`
* **mutate** `updateResourceSettings(...)` / `resetResourceSettings(...)` / `cleanupOrphanedSettings()`
***
## `bot.storage` — storage usage [#botstorage--storage-usage]
> Reference: [storage](/docs/reference/sdk/routes/storage)
* **read** `getStorageChart(...)` / `getStorageRecord(...)`
***
## `bot.socket` — real-time events [#botsocket--real-time-events]
> Reference: [socket](/docs/reference/sdk/routes/socket)
* `connect(channel, options)` / `connectPublic(publicToken, options)` — establish a Socket.IO namespace connection.
* `subscribe(channel, event, handler)` / `subscribePublic(publicToken, event, handler)` — most bots use this directly; auto-connects.
* `unsubscribe(channel, event, handler)`
* `disconnect(channel)` / `disconnectAll()`
* `emit(channel, event, data)` — publish on a connected channel (typing indicators, collab events).
* `isConnected(channel)` / `onReconnectFailed(channel, callback)`
### Channel patterns [#channel-patterns]
* `/user/{userId}` — personal channel: chatMention notifications, member-chat fan-out.
* `/project/{projectId}` — project-wide events.
* `/project/{projectId}/{visibility}` — visibility-scoped events: `chatCreateMessage` for topic chats fans out here. Subscribe to both `creator` and `reviewer` if the bot's role spans both tiers.
* `/chat/{chatId}` — followers-only stream for one chat.
* `/public/{publicToken}` — public file-system events.
### Event types you'll encounter [#event-types-youll-encounter]
* `chatMention` — bot was @-mentioned. `tokens: { chatId, messageId, mentions, message }`.
* `chatCreateMessage` — any new message in a chat the bot has visibility on. Includes the full message at `changes.create[].resource`.
* `chatReviseMessage` / `chatDeleteMessage` / `chatRefreshMessage` / `chatRemoveAttachment`
* `convoStart` / `convoJoin` / `convoLeave` / `convoComplete` / `convoDelete` / `convoUpdate`
* `assetStatusUpdate` / `assetFileUpdate`
* `userAvatarUpdate` / `userPublicUpdate`
* `taskCreate` / `taskUpdate`
### Server-listened events (emit from bot) [#server-listened-events-emit-from-bot]
* `typing:start { chatId }` / `typing:stop { chatId }` — server resolves fanout from `chatId`; bot must be authenticated on the channel it emits from.
***
# ai (/docs/reference/sdk/routes/ai)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
## Interfaces [#interfaces]
### ComposeWithNuRequest [#composewithnurequest]
#### Properties [#properties]
| Property | Type | Description |
| ------------------------------------ | -------------------------------------------- | ---------------------------------------------------------------- |
| `chatId` | `string` | Chat being composed into. Read server-side for context and tone. |
| `messages` | [`ComposeWithNuTurn`](#composewithnuturn)\[] | - |
| `projectId?` | `string` | - |
| `workspaceId` | `string` | - |
***
### ComposeWithNuResponse [#composewithnuresponse]
#### Properties [#properties-1]
| Property | Type | Description |
| ---------------------------------------- | ------------------ | ------------------------------------------------------------------------ |
| `balanceAfter` | `number` \| `null` | - |
| `billedCredits` | `number` | - |
| `eventId` | `string` \| `null` | - |
| `proposal` | `string` \| `null` | Wording the user may put in their composer, or null for a pure question. |
| `text` | `string` | What Nu said to the user. Never posted anywhere. |
***
### ComposeWithNuTurn [#composewithnuturn]
One turn of the drafting conversation, as sent back on each request.
#### Properties [#properties-2]
| Property | Type | Description |
| --------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `proposal?` | `string` \| `null` | Wording this turn offered. Held per turn so an earlier draft stays takeable after the conversation has moved on — the user may prefer the version from three turns ago. |
| `role` | `"user"` \| `"assistant"` | - |
| `text` | `string` | - |
***
### CreateRevisionSourceUploadRequest [#createrevisionsourceuploadrequest]
Source-upload mint request. Returns a multipart upload bundle that
the caller drives like any other scratch / asset upload (PUT each
`urls[i]` with the corresponding part, collect the ETags, then call
`nuramaClient.scratch.completeUpload`). The server always records
the upload as `image/jpeg` — the only supported source is a captured
video frame, which is always JPEG. Size cap: 25 MB (the image
provider's per-image limit).
#### Properties [#properties-3]
| Property | Type | Description |
| -------------------------------------- | -------- | ---------------------------------------------- |
| `assetId?` | `string` | Audit-only lineage — the originating asset id. |
| `projectId?` | `string` | - |
| `sizeInMB` | `number` | - |
| `workspaceId` | `string` | - |
***
### CreateRevisionSourceUploadResponse [#createrevisionsourceuploadresponse]
#### Properties [#properties-4]
| Property | Type | Description |
| -------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `expires` | `string` | ISO timestamp. The scratch upload expires and is removed after this. |
| `key` | `string` | Storage key for the upload. Pass to `nuramaClient.asset.multipartUpload`, which echoes it in its progress and result shapes. |
| `scratchId` | `string` | Use as `source.scratchId` on the subsequent `generateRevision` call. |
| `uploadId` | `string` | Pass to `nuramaClient.scratch.completeUpload` along with the parts. |
| `urls` | `string`\[] | One signed PUT URL per multipart part. Single-element array for sub-chunk-size payloads (1080p JPEG frames are well under). |
***
### GeneratedTask [#generatedtask]
#### Properties [#properties-5]
| Property | Type |
| ------------------------------------ | -------- |
| `description` | `string` |
| `subject` | `string` |
***
### GenerateImageRevisionRequest [#generateimagerevisionrequest]
#### Properties [#properties-6]
| Property | Type | Description |
| --------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `assetId?` | `string` | Audit-only — the caller has already resolved the asset's media URL. |
| `jobId?` | `string` | Groups all revisions from one modal session. |
| `mask?` | \{ `dataUrl`: `string`; } | Optional alpha-channel mask PNG (data URL) matching the source image's dimensions. Transparent pixels mark the edit region; opaque pixels are preserved. When supplied, the server forwards it as OpenAI's top-level `mask` field — NOT as another `references[]` entry — and auto-augments the prompt with a region directive. |
| `mask.dataUrl` | `string` | - |
| `projectId?` | `string` | - |
| `prompt` | `string` | - |
| `references?` | `string`\[] | Prior revisions to condition on (public URLs or data URLs). |
| `source` | [`ImageRevisionSource`](#imagerevisionsource) | - |
| `sourceAspect?` | `number` | Source image's aspect ratio (width / height). Two effects when set: 1. The server picks the closest OpenAI-supported generation size — landscape, portrait, or square — instead of always generating 1024×1024. Reduces the gap between the model's output aspect and the source aspect before any padding. 2. After generation, the server pads the result with black bars (letterbox/pillarbox) so the final bytes exactly match this aspect. The user gets an output image whose framing matches the input they started from, with the generated content centred and the unfilled edges padded. Omit (or pass `1.0`) for legacy square output. |
| `workspaceId` | `string` | - |
***
### GenerateImageRevisionResponse [#generateimagerevisionresponse]
#### Properties [#properties-7]
| Property | Type | Description |
| ------------------------------------------ | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `balanceAfter` | `number` \| `null` | - |
| `billedCredits` | `number` | - |
| `eventId` | `string` \| `null` | - |
| `model` | `string` | - |
| `quality` | `string` | - |
| `revisionId` | `string` | Scratch id of the generated revision. Use it in one of two ways: - "Upload to project" → call `nuramaClient.scratch.promote(id)` to materialise it as a project-scoped Asset. - "Attach to chat" → pass `{ scratchId }` as a chat-message attachment item; the chat-send endpoint promotes it to a chat-scoped Asset at send time. |
| `revisionUrl` | `string` \| `null` | Public URL of the revision, ready to render directly. |
***
### GenerateTasksRequest [#generatetasksrequest]
#### Properties [#properties-8]
| Property | Type | Description |
| --------------------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `contextMessages?` | [`TaskGenerationContextMessage`](#taskgenerationcontextmessage)\[] | Preceding chat messages (oldest first) to give the model conversational lead-in. Server caps at 10 messages and trims long content per-message; the focal `messageText` is the actual instruction. |
| `messageId?` | `string` | Optional source chat message id — reserved for future audit linking. |
| `messageText` | `string` | - |
| `projectId` | `string` | - |
| `workspaceId` | `string` | - |
***
### GenerateTasksResponse [#generatetasksresponse]
#### Properties [#properties-9]
| Property | Type |
| ------------------------------------------ | ------------------------------------ |
| `balanceAfter` | `number` |
| `billedCredits` | `number` |
| `eventId` | `string` \| `null` |
| `tasks` | [`GeneratedTask`](#generatedtask)\[] |
***
### ListTonesResponse [#listtonesresponse]
#### Properties [#properties-10]
| Property | Type |
| ------------------------ | ---------------------------- |
| `tones` | [`ToneEntry`](#toneentry)\[] |
***
### PolishRequest [#polishrequest]
#### Properties [#properties-11]
| Property | Type |
| -------------------------------------- | -------- |
| `projectId?` | `string` |
| `text` | `string` |
| `toneId` | `string` |
| `workspaceId` | `string` |
***
### PolishResponse [#polishresponse]
#### Properties [#properties-12]
| Property | Type |
| ------------------------------------------ | ------------------ |
| `balanceAfter` | `number` |
| `billedCredits` | `number` |
| `eventId` | `string` \| `null` |
| `polishedText` | `string` |
***
### SubmitAiFeedbackRequest [#submitaifeedbackrequest]
One Nu Feedback submission.
#### Properties [#properties-13]
| Property | Type | Description |
| --------------------------------------- | --------------------------------- | ------------------------------------------------------------------- |
| `chatId` | `string` | - |
| `contextItems?` | `Record`\<`string`, `unknown`>\[] | - |
| `messageId?` | `string` | - |
| `notes?` | `string` | The user's own words on what worked or didn't. Optional. |
| `pageContext?` | `Record`\<`string`, `unknown`> | Extras the client already holds, folded into the stored snapshot. |
| `projectId?` | `string` | - |
| `rating` | `"positive"` \| `"negative"` | - |
| `surface` | `"chat"` \| `"assist"` | Which AI surface produced the reply — the two are tuned separately. |
| `workspaceId?` | `string` | - |
***
### TaskGenerationContextMessage [#taskgenerationcontextmessage]
#### Properties [#properties-14]
| Property | Type | Description |
| ----------------------------------- | -------- | --------------------------------------------------------------------- |
| `authorName?` | `string` | Display name of the message author. Optional but improves the prompt. |
| `content` | `string` | - |
***
### ToneEntry [#toneentry]
#### Properties [#properties-15]
| Property | Type |
| ------------------------ | -------- |
| `id` | `string` |
| `label` | `string` |
## Type Aliases [#type-aliases]
### ImageRevisionSource [#imagerevisionsource]
```ts
type ImageRevisionSource =
| {
url: string;
}
| {
scratchId: string;
}
| {
dataUrl: string;
};
```
Source for an image revision call. Exactly one of:
* `url` — public media URL (typical for image assets).
* `scratchId` — id of a scratch upload created via
`createRevisionSourceUpload`. Preferred for
captured video frames: the bytes go straight to
storage instead of through the request body.
* `dataUrl` — DEPRECATED: a captured video frame serialised as
a base64 data URL inline in the request body. Kept
for backward compatibility only; new code should
always use the `scratchId` flow.
## Functions [#functions]
### default() [#default]
```ts
function default(client): {
composeWithNu: Promise;
createRevisionSourceUpload: Promise;
generateRevision: Promise;
generateTasks: Promise;
listTones: Promise;
polish: Promise;
submitFeedback: Promise<{
id: string;
}>;
};
```
Methods for the Nu AI assistant integration points.
Nu is the platform-native AI feature set. Each integration point is gated
by workspace settings (`allowAiFeatures` master switch + per-feature toggle
* role allowlist) and metered against the workspace's credit balance.
MVP exposes a single integration point — Polish — used by the chat
composer to rewrite a draft message in a selected tone.
#### Parameters [#parameters]
| Parameter | Type |
| --------- | ----------------------------------------------------- |
| `client` | [`default`](/docs/reference/sdk/NuramaClient#default) |
#### Returns [#returns]
| Name | Type | Description |
| ------------------------------ | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `composeWithNu()` | (`data`) => `Promise`\<[`ComposeWithNuResponse`](#composewithnuresponse)> | One turn of a Compose-with-Nu drafting conversation. Send only the drafting thread — the chat being written into is read server-side from `chatId`, under the caller's own permissions. The result is Nu's commentary plus, when it has one, a proposed message. Nothing is posted: the proposal is the user's to take or discard. |
| `createRevisionSourceUpload()` | (`data`) => `Promise`\<[`CreateRevisionSourceUploadResponse`](#createrevisionsourceuploadresponse)> | Mint a signed-URL bundle for uploading a source image (typically a captured video frame) into Scratch BEFORE calling `generateRevision`. Use the resulting `scratchId` as the `source.scratchId` on the generate call. Why this exists: video frames are captured client-side and need to reach OpenAI as a public media URL. Posting the bytes inline (as `dataUrl`) makes the API node a pass-through for multi-MB payloads; staging on Scratch first keeps the node out of the byte path entirely. |
| `generateRevision()` | (`data`) => `Promise`\<[`GenerateImageRevisionResponse`](#generateimagerevisionresponse)> | Generate one image revision (prompt-driven variant of a source image or video frame). The result is staged as a scratch upload — the caller then chooses one of two outcomes: - "Add to project" → call `nuramaClient.scratch.promote(id)` to create a project-scoped Asset immediately. - "Attach to chat" → pass `{ scratchId, name? }` as an item in the chat message's `attachments[]`; the server promotes each one to a chat-scoped Asset at send time. |
| `generateTasks()` | (`data`) => `Promise`\<[`GenerateTasksResponse`](#generatetasksresponse)> | Convert a chat message into one or more board-task drafts. The response's `tasks` array holds the drafts for the user to review and edit before creating them (for example with `nuramaClient.task.bulkCreate`). Requires both the AI add-on AND the Boards add-on on the workspace; the server returns `productNotActive` if either is missing. |
| `listTones()` | () => `Promise`\<[`ListTonesResponse`](#listtonesresponse)> | Returns the catalogue of polish tones the platform supports. Use it to populate a tone picker instead of hard-coding the ids. |
| `polish()` | (`data`) => `Promise`\<[`PolishResponse`](#polishresponse)> | - |
| `submitFeedback()` | (`data`) => `Promise`\<\{ `id`: `string`; }> | Record a thumbs-up / thumbs-down on one assistant reply. `chatId` is required because it is what the server authorises against — a user can only rate a reply in a chat they can already read — and it is what the stored transcript snapshot is built from. |
# asset (/docs/reference/sdk/routes/asset)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
## Interfaces [#interfaces]
### AssetWithChats [#assetwithchats]
#### Extends [#extends]
* `Omit`\<`Asset`, `"chats"`>
#### Properties [#properties]
| Property | Type | Description | Inherited from |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| `aiGenerated?` | `boolean` | True when the bytes were produced by a platform AI process (e.g. promoted from an `aiRevision` scratch row). Drives the "AI Generated" system chip in the asset view; also queryable for admin filtering. Distinct from user tags — set at create/promote time, not editable. | `Omit.aiGenerated` |
| `chats?` | \{ `creator?`: [`Chat`](#chat); `reviewer?`: [`Chat`](#chat); } | - | - |
| `chats.creator?` | [`Chat`](#chat) | - | - |
| `chats.reviewer?` | [`Chat`](#chat) | - | - |
| `checksum` | `string` | MD5 checksum of original file. **Format** md5 | `Omit.checksum` |
| `checksumAlgorithm?` | `"md5"` | The algorithm used for computing the checksum. | `Omit.checksumAlgorithm` |
| `createdAt?` | `number` | The timestamp when the asset was created. **Format** int64 | `Omit.createdAt` |
| `creator?` | `PublicUser` | Public user information of the creator. | `Omit.creator` |
| `creatorId` | `string` | The ID of the user who created the asset. **Format** objectId | `Omit.creatorId` |
| `everPublic?` | `boolean` | One-way flag set true once the asset has been publicly exposed (link or file system) at any point. | `Omit.everPublic` |
| `expectedUploadSizeInMB` | `number` | Expected upload size of the asset in megabytes, used to determine signed link generation. | `Omit.expectedUploadSizeInMB` |
| `files?` | `File`\[] | The files associated with the asset. | `Omit.files` |
| `fileSystemPaths?` | `string`\[] | Array of file system entry IDs associated with this asset. **Format** objectId | `Omit.fileSystemPaths` |
| `folder?` | `string` \| `Folder` \| `null` | Populated folder data. | `Omit.folder` |
| `folderId?` | `string` \| `null` | If the asset is in a folder the folder ID goes here. If not this is null. **Format** objectId **Default** `null` | `Omit.folderId` |
| `functionType` | `"avatar"` \| `"attachment"` \| `"media"` \| `"logo"` \| `"icon"` | The function of the asset on the platform. | `Omit.functionType` |
| `hasActivePublicFileSystem?` | `boolean` | True when the asset is a member of at least one active, non-expired public file system. | `Omit.hasActivePublicFileSystem` |
| `hasActivePublicLink?` | `boolean` | True when the asset has at least one active public download link. | `Omit.hasActivePublicLink` |
| `id` | `string` | The id of the asset. **Format** objectId | `Omit.id` |
| `inheritance?` | `any` | Populated inheritance data. | `Omit.inheritance` |
| `inheritanceId?` | `string` \| `null` | ID of the inheritance object associated with this asset. **Format** objectId | `Omit.inheritanceId` |
| `keyPath` | `string` | Storage path of the asset's original file, relative to the storage root. | `Omit.keyPath` |
| `mediaType` | `"image"` \| `"video"` \| `"audio"` \| `"file"` \| `"3d"` \| `"document"` | The media type of the asset. | `Omit.mediaType` |
| `meta?` | `Record`\<`string`, `any`> | Additional metadata for the asset. **Default** `{}` | `Omit.meta` |
| `name` | `string` | The name of the asset used on the platform. | `Omit.name` |
| `ownerResourceId` | `string` | The id of the resource that the asset is attached to. **Format** objectId | `Omit.ownerResourceId` |
| `ownerResourceType` | `"project"` \| `"chatMessage"` \| `"user"` | The type of the owner resource. | `Omit.ownerResourceType` |
| `publishedOn?` | `string` \| `null` | The date when the asset was published. If not published, this will be null. **Format** date-time **Default** `null` | `Omit.publishedOn` |
| `publisher?` | `PublicUser` | Public user information of the publisher (if published). | `Omit.publisher` |
| `publisherId?` | `string` \| `null` | The ID of the user who published the asset (if published). **Format** objectId **Default** `null` | `Omit.publisherId` |
| `sizeInBytes` | `number` | The total size of the asset in bytes. | `Omit.sizeInBytes` |
| `slug?` | `string` | The URL-friendly slug of the asset name. | `Omit.slug` |
| `status` | `"active"` \| `"pendingDelete"` \| `"inactive"` | The status of the asset. **Default** `active` | `Omit.status` |
| `submissionFileSystemIds?` | `string`\[] | Submission file system IDs the asset currently belongs to. Empty when not in any submission. | `Omit.submissionFileSystemIds` |
| `tags?` | `string`\[] | Tags associated with the asset. **Format** objectId | `Omit.tags` |
| `updatedAt?` | `number` | The timestamp when the asset was last updated. **Format** int64 | `Omit.updatedAt` |
| `visibility?` | (`"creator"` \| `"reviewer"` \| `"member"` \| `"public"`)\[] | The visibility settings for the asset. **Default** `['creator']` | `Omit.visibility` |
***
### Chat [#chat]
#### Properties [#properties-1]
| Property | Type |
| ------------------------------------------- | -------- |
| `_id?` | `string` |
| `id?` | `string` |
| `recentMessages?` | `any`\[] |
| `totalMessages?` | `number` |
***
### CompleteMultipartUploadData [#completemultipartuploaddata]
#### Properties [#properties-2]
| Property | Type |
| ------------------------------ | ------------------------------------------------- |
| `assetId` | `string` |
| `key` | `string` |
| `parts` | \{ `ETag`: `string`; `PartNumber`: `number`; }\[] |
| `uploadId` | `string` |
***
### CreateAssetShortLinkData [#createassetshortlinkdata]
#### Properties [#properties-3]
| Property | Type |
| ------------------------------------- | --------------------------- |
| `visibility?` | `"creator"` \| `"reviewer"` |
***
### CreateAssetShortLinkResponse [#createassetshortlinkresponse]
#### Properties [#properties-4]
| Property | Type |
| -------------------------------- | --------------------------- |
| `shortLink` | [`ShortLink`](#shortlink-1) |
| `shortUrl` | `string` |
***
### DocumentViewUrlResponse [#documentviewurlresponse]
#### Properties [#properties-5]
| Property | Type | Description |
| ------------------------------------------------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `expires` | `number` | Unix seconds. Refetch rather than reusing a URL past this. |
| `originalPageCount` | `number` | Pages in the source document. Equals `pageCount` unless truncated. |
| `pageCount` | `number` | From `meta.document.pageCount`; 0 when processing has not reported it. |
| `pagesTruncated` | `boolean` | True when the `media` PDF holds only the first `pageCount` pages of a longer document, because post-processing hit its `maxPages` cap. The PDF itself is internally consistent, so this flag is the only way to know. |
| `truncatedFrom` | `"start"` \| `"end"` | Which end of the document the `media` PDF kept. `'start'` for everything read front-to-back; `'end'` for logs, whose newest lines are at the bottom. Only meaningful when `pagesTruncated` is true. |
| `url` | `string` | Signed URL for the document's `media` PDF, served inline. |
***
### GetAssetPageParams [#getassetpageparams]
#### Properties [#properties-6]
| Property | Type |
| ------------------------------------- | -------------------------------- |
| `inFolder?` | `boolean` |
| `limit?` | `number` |
| `sort?` | `Record`\<`string`, `-1` \| `1`> |
| `visibility?` | `string` |
***
### GetAssetParams [#getassetparams]
#### Properties [#properties-7]
| Property | Type |
| ----------------------------------------------- | --------------------------- |
| `chatMessageLimit?` | `number` |
| `chatMessageSort?` | \{ `id?`: `1` \| `-1`; } |
| `chatMessageSort.id?` | `1` \| `-1` |
| `chatReplyLimit?` | `number` |
| `chatReplySort?` | \{ `id?`: `1` \| `-1`; } |
| `chatReplySort.id?` | `1` \| `-1` |
| `chatVisibility?` | `"creator"` \| `"reviewer"` |
***
### MultipartUploadOptions [#multipartuploadoptions]
#### Properties [#properties-8]
| Property | Type |
| ----------------------------------------------------------------- | ---------------------- |
| `abortSignal?` | `AbortSignal` |
| `assetId?` | `string` |
| `enableProgressPersistence?` | `boolean` |
| `fileName?` | `string` |
| `fileSize?` | `number` |
| `maxRetries?` | `number` |
| `onProgress?` | (`progress`) => `void` |
| `projectId?` | `string` |
| `sessionId?` | `string` |
***
### MultipartUploadResult [#multipartuploadresult]
#### Properties [#properties-9]
| Property | Type |
| -------------------------------- | ------------------------------------------------- |
| `key` | `string` |
| `parts` | \{ `ETag`: `string`; `PartNumber`: `number`; }\[] |
| `uploadId` | `string` |
***
### PartUploadOptions [#partuploadoptions]
#### Properties [#properties-10]
| Property | Type |
| ------------------------------------------- | ---------------------- |
| `abortSignal?` | `AbortSignal` |
| `maxRetries?` | `number` |
| `onPartProgress?` | (`progress`) => `void` |
***
### PublicAssetLink [#publicassetlink]
#### Properties [#properties-11]
| Property | Type | Description |
| ---------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `assetId` | `string` | - |
| `createdAt` | `string` | - |
| `creatorId` | `string` | - |
| `expires` | `string` \| `null` | - |
| `id` | `string` | - |
| `isExpired?` | `boolean` | - |
| `mode?` | [`PublicAssetLinkMode`](#publicassetlinkmode-1) | Capability mode for this link. - 'download' — direct-download link only; embed iframe blocked. - 'embed' — embeddable iframe only; direct download blocked. - 'embed-download' — both endpoints allowed (default; backward-compatible). Enforced server-side at /v1/public-download/\{token}/download and /embed-files. |
| `projectId` | `string` | - |
| `publicUrl` | `string` | - |
| `status` | `"active"` \| `"expired"` \| `"disabled"` | - |
| `token` | `string` | - |
| `updatedAt` | `string` | - |
***
### ShortLink [#shortlink]
#### Properties [#properties-12]
| Property | Type |
| -------------------------------------- | ---------------------------------------------------------------------------------- |
| `code` | `string` |
| `createdAt` | `string` |
| `creatorId` | `string` |
| `id` | `string` |
| `resourceId` | `string` |
| `resourceType` | `"asset"` \| `"project"` \| `"workspace"` \| `"chatMessage"` \| `"chatSubmission"` |
| `updatedAt?` | `string` |
| `visibility` | `"creator"` \| `"reviewer"` \| `null` |
***
### TagAssetData [#tagassetdata]
#### Properties [#properties-13]
| Property | Type |
| ------------------------ | -------- |
| `tagId` | `string` |
***
### UntagAssetData [#untagassetdata]
#### Properties [#properties-14]
| Property | Type |
| -------------------------- | -------- |
| `tagId` | `string` |
***
### UpdateAssetData [#updateassetdata]
#### Properties [#properties-15]
| Property | Type |
| --------------------------------- | -------------------------- |
| `folderId?` | `string` \| `null` |
| `meta?` | `Record`\<`string`, `any`> |
| `name?` | `string` |
| `tags?` | `string`\[] |
## Type Aliases [#type-aliases]
### AssetPageResponse [#assetpageresponse]
```ts
type AssetPageResponse = {
page: number;
};
```
#### Properties [#properties-16]
| Property | Type |
| ---------------------- | -------- |
| `page` | `number` |
***
### AssetResponse [#assetresponse]
```ts
type AssetResponse = AssetWithChats;
```
***
### DownloadAssetsResponse [#downloadassetsresponse]
```ts
type DownloadAssetsResponse = any[];
```
***
### FileResponse [#fileresponse]
```ts
type FileResponse = File;
```
***
### PublicAssetLinkMode [#publicassetlinkmode]
```ts
type PublicAssetLinkMode = "download" | "embed" | "embed-download";
```
***
### RepairAssetsResponse [#repairassetsresponse]
```ts
type RepairAssetsResponse = any[];
```
## Functions [#functions]
### default() [#default]
```ts
function default(client): {
cleanupUploadSessions: void;
completeCustomThumbnailUpload: Promise<{
key: string;
status: string;
}>;
completeUpload: Promise;
completeUploadSession: void;
createPublicLink: Promise;
createShortLink: Promise;
deleteAsset: Promise;
disablePublicLink: Promise;
downloadAssets: Promise;
getAsset: Promise;
getAssetAccessActivity: Promise<{
breakdown: {
count: number;
label: string;
value: string;
}[];
eventType: string | null;
from: string;
groupBy: string;
range: string;
series: {
count: number;
date: string;
eventType: string;
}[];
to: string;
totals: {
count: number;
eventType: string;
}[];
}>;
getAssetPage: Promise;
getAssetReferences: Promise;
getCustomThumbnailUploadUrl: Promise<{
assetId: string;
expires: number;
fileName: string;
key: string;
mimeType: string;
status: string;
uploadId: string;
urls: string[];
}>;
getDocumentViewUrl: Promise;
getFile: Promise;
getFilesByFunctionType: Promise;
getPublicLinks: Promise<{
results: PublicAssetLink[];
}>;
getUploadSession: UploadSessionData | null;
getUploadSessions: UploadSessionData[];
hasActiveUploads: boolean;
multipartUpload: Promise;
offUploadSessionMessage: void;
onUploadSessionMessage: void;
promoteAttachmentToProject: Promise<{
asset: Asset;
deduped: boolean;
}>;
reactivatePublicLink: Promise;
recordAccessActivity: Promise;
removeCustomThumbnail: Promise;
removeUploadSession: void;
repairAssets: Promise;
tagAsset: Promise;
untagAsset: Promise;
updateAsset: Promise;
updatePublicLink: Promise;
};
```
Defines asset-related methods for the NuramaClient.
#### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ----------------------------------------------------- | -------------------------- |
| `client` | [`default`](/docs/reference/sdk/NuramaClient#default) | The NuramaClient instance. |
#### Returns [#returns]
An object containing the asset-related methods.
| Name | Type | Description |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `cleanupUploadSessions()` | (`projectId`, `olderThanMs?`) => `void` | Clean up old upload sessions for a project |
| `completeCustomThumbnailUpload()` | (`assetId`, `data`) => `Promise`\<\{ `key`: `string`; `status`: `string`; }> | Finalize the multipart upload for a custom thumbnail. Committing the upload starts the background processing that generates the thumbnail outputs. |
| `completeUpload()` | (`uploadData`) => `Promise`\<`any`> | Complete a multipart upload initiated by `createAssets`. Takes the same `{ uploadId, parts }` shape as `nuramaClient.scratch.completeUpload`, plus the `key` and `assetId`. |
| `completeUploadSession()` | (`projectId`, `sessionId`) => `void` | Mark an upload session as completed |
| `createPublicLink()` | (`assetId`, `data`) => `Promise`\<[`PublicAssetLink`](#publicassetlink)> | Create a public download link for an asset. |
| `createShortLink()` | (`assetId`, `data?`) => `Promise`\<[`CreateAssetShortLinkResponse`](#createassetshortlinkresponse)> | Creates a short link for an asset. If a short link already exists for the asset with the same visibility, returns the existing one. |
| `deleteAsset()` | (`assetId`) => `Promise`\<[`AssetWithChats`](#assetwithchats)> | Deletes an asset (marks for deletion). |
| `disablePublicLink()` | (`assetId`, `linkId`) => `Promise`\<[`PublicAssetLink`](#publicassetlink)> | Disable a public download link. |
| `downloadAssets()` | (`assetIds`) => `Promise`\<[`DownloadAssetsResponse`](#downloadassetsresponse)> | Generates signed download URLs for the original files of specified assets. |
| `getAsset()` | (`assetId`, `params?`) => `Promise`\<[`AssetWithChats`](#assetwithchats)> | Retrieves a specific asset by its ID with optional chat data. |
| `getAssetAccessActivity()` | (`assetId`, `params?`) => `Promise`\<\{ `breakdown`: \{ `count`: `number`; `label`: `string`; `value`: `string`; }\[]; `eventType`: `string` \| `null`; `from`: `string`; `groupBy`: `string`; `range`: `string`; `series`: \{ `count`: `number`; `date`: `string`; `eventType`: `string`; }\[]; `to`: `string`; `totals`: \{ `count`: `number`; `eventType`: `string`; }\[]; }> | Get aggregated access-activity for a single asset. Returns totals per eventType, a breakdown for the requested dimension, and a zero-filled daily series. |
| `getAssetPage()` | (`assetId`, `params?`) => `Promise`\<[`AssetPageResponse`](#assetpageresponse)> | Gets the page number an asset appears on based on specified filters and sorting. |
| `getAssetReferences()` | (`assetId`) => `Promise`\<`AssetReferences`> | Lists every location an asset is referenced — its primary file system and each secondary reference (reviewer, submission, public), grouped and counted. Renaming an asset retitles it at every one of these locations, and deleting its last primary reference removes them all — so this is what the rename and delete confirmations show the user before either happens. |
| `getCustomThumbnailUploadUrl()` | (`assetId`, `data`) => `Promise`\<\{ `assetId`: `string`; `expires`: `number`; `fileName`: `string`; `key`: `string`; `mimeType`: `string`; `status`: `string`; `uploadId`: `string`; `urls`: `string`\[]; }> | Mint signed multipart upload URLs for a user-supplied custom thumbnail image. Once the upload is completed, background processing generates the custom-thumbnail outputs and attaches them to the asset; the `assetFileUpdate` websocket event fires when they are ready. Caller flow: 1. multipartUpload(file, response.urls, response.key, response.uploadId) 2. completeCustomThumbnailUpload(\{ assetId, key, uploadId, parts }) 3. wait for the assetFileUpdate websocket event |
| `getDocumentViewUrl()` | (`assetId`) => `Promise`\<[`DocumentViewUrlResponse`](#documentviewurlresponse)> | Mints a short-lived signed URL for rendering a document inline. A document's `media` PDF is kept in private storage, so unlike images and video it cannot be addressed by keyPath through the public file URL. Fetch this each time a document is opened; do not cache it past `expires`. |
| `getFile()` | (`assetId`, `fileId`) => `Promise`\<`File`> | Retrieves a specific file from an asset. |
| `getFilesByFunctionType()` | (`assetId`, `functionType`) => `Promise`\<`File`\[]> | Retrieves files of a specific function type from an asset. |
| `getPublicLinks()` | (`assetId`, `options?`) => `Promise`\<\{ `results`: [`PublicAssetLink`](#publicassetlink)\[]; }> | Get all public download links for an asset. |
| `getUploadSession()` | (`projectId`, `sessionId`) => `UploadSessionData` \| `null` | Get a specific upload session |
| `getUploadSessions()` | (`projectId`) => `UploadSessionData`\[] | Get all active upload sessions for a project |
| `hasActiveUploads()` | (`staleMs?`) => `boolean` | True when any upload is genuinely in flight anywhere in the app (across all projects and tabs). Intended for app-level guards — e.g. suppressing an automatic version-update page refresh while bytes are still uploading. Stale (crashed-tab) sessions are ignored via the freshness window. |
| `multipartUpload()` | ( `file`, `signedUrls`, `key`, `uploadId`, `options?` ) => `Promise`\<[`MultipartUploadResult`](#multipartuploadresult)> | Uploads a file using multipart upload with the provided signed URLs |
| `offUploadSessionMessage()` | (`listenerId`) => `void` | Unregister a cross-tab upload session message listener |
| `onUploadSessionMessage()` | (`listenerId`, `callback`) => `void` | Register a listener for cross-tab upload session messages |
| `promoteAttachmentToProject()` | (`assetId`, `payload`) => `Promise`\<\{ `asset`: `Asset`; `deduped`: `boolean`; }> | Promote a chat-message attachment into a project as a fresh, independent project asset. The source attachment is left untouched; the new project asset has its own lifecycle, post-processing pipeline, and storage footprint. Idempotent: a second promote of the same source into the same project returns the existing promoted asset with `deduped: true`. Requires `canCreateAsset` on the destination project — reviewers are blocked. The server additionally rejects when the source attachment's workspace doesn't match the destination project's. |
| `reactivatePublicLink()` | ( `assetId`, `linkId`, `data?` ) => `Promise`\<[`PublicAssetLink`](#publicassetlink)> | Reactivate a disabled/expired public download link. |
| `recordAccessActivity()` | (`assetId`, `body`) => `Promise`\<`void`> | Record an authenticated play event from the in-app player. Fire-and-forget; server returns 204. Throw-on-failure is fine because the caller already de-dupes per session. |
| `removeCustomThumbnail()` | (`assetId`) => `Promise`\<`Asset`> | Remove the custom thumbnail from an asset. Soft-deletes all custom thumb files; the asset falls back to the auto-generated thumbnail. |
| `removeUploadSession()` | (`projectId`, `sessionId`) => `void` | Remove an upload session |
| `repairAssets()` | (`assetIds`) => `Promise`\<[`RepairAssetsResponse`](#repairassetsresponse)> | Attempts to repair assets (e.g., regenerate signed URLs for pending uploads). |
| `tagAsset()` | (`assetId`, `tagData`) => `Promise`\<[`AssetWithChats`](#assetwithchats)> | Tags an asset with a specific tag. |
| `untagAsset()` | (`assetId`, `untagData`) => `Promise`\<[`AssetWithChats`](#assetwithchats)> | Untags an asset by removing a specific tag. |
| `updateAsset()` | (`assetId`, `updateData`) => `Promise`\<[`AssetWithChats`](#assetwithchats)> | Updates an asset. |
| `updatePublicLink()` | ( `assetId`, `linkId`, `data` ) => `Promise`\<[`PublicAssetLink`](#publicassetlink)> | Update a public download link (extend expiration or change status). |
# auth (/docs/reference/sdk/routes/auth)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
## Interfaces [#interfaces]
### ChangePasswordData [#changepassworddata]
#### Properties [#properties]
| Property | Type |
| -------------------------------------------- | -------- |
| `currentPassword` | `string` |
| `mfaToken?` | `string` |
| `newPassword` | `string` |
***
### DisableMFAData [#disablemfadata]
#### Properties [#properties-1]
| Property | Type |
| -------------------------------- | -------- |
| `mfaToken` | `string` |
***
### LoginCredentials [#logincredentials]
#### Properties [#properties-2]
| Property | Type | Description |
| ------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `inviteId?` | `string` | Optional. When signing in to accept an invite, pass the invite id: it only reaches the user through the message sent to that address, so quoting it proves control of the inbox and lifts the email-verification grace block for this login. Credentials are still required. |
| `login` | `string` | - |
| `password` | `string` | - |
***
### LoginRegisterResponse [#loginregisterresponse]
#### Properties [#properties-3]
| Property | Type |
| -------------------------- | ------------ |
| `tokens` | `AuthTokens` |
| `user` | `User` |
***
### RefreshResponse [#refreshresponse]
#### Extends [#extends]
* `AuthTokens`
#### Properties [#properties-4]
| Property | Type | Inherited from |
| --------------------------------- | ------- | ---------------------- |
| `access` | `Token` | `AuthTokens.access` |
| `refresh` | `Token` | `AuthTokens.refresh` |
| `verifyMfa?` | `Token` | `AuthTokens.verifyMfa` |
***
### RegisterUserData [#registeruserdata]
#### Extends [#extends-1]
* `Pick`\<`User`, `"firstName"` | `"lastName"` | `"email"`>
#### Properties [#properties-5]
| Property | Type | Description | Inherited from |
| -------------------------------- | -------- | -------------------------------------------------------------- | ---------------- |
| `email` | `string` | The email address of the user. **Format** email | `Pick.email` |
| `firstName` | `string` | The first name of the user. **Min Length** 3 **Max Length** 35 | `Pick.firstName` |
| `lastName` | `string` | The last name of the user. **Max Length** 35 | `Pick.lastName` |
| `password` | `string` | - | - |
***
### ResetPasswordData [#resetpassworddata]
#### Properties [#properties-6]
| Property | Type |
| -------------------------------- | -------- |
| `password` | `string` |
| `token` | `string` |
***
### VerifyBackupCodeData [#verifybackupcodedata]
#### Properties [#properties-7]
| Property | Type |
| ---------------------------------- | -------- |
| `backupCode` | `string` |
***
### VerifyMFAData [#verifymfadata]
#### Properties [#properties-8]
| Property | Type |
| -------------------------------- | -------- |
| `mfaToken` | `string` |
## Functions [#functions]
### default() [#default]
```ts
function default(client): {
changePassword: Promise;
disableMfa: Promise;
enableMfa: Promise;
exchangeOAuthCode: Promise;
forgotPassword: Promise;
getLinkedOAuthProviders: Promise;
linkOAuthProvider: Promise;
lockAccount: Promise;
login: Promise;
logout: Promise;
refreshTokens: Promise;
register: Promise;
registerGuest: Promise;
resendVerification: Promise;
resetPassword: Promise;
sendVerificationEmail: Promise;
setPassword: Promise;
unlinkOAuthProvider: Promise;
upgradeGuest: Promise<{
user: User;
}>;
verifyBackupCode: Promise;
verifyEmail: Promise;
verifyGuest: Promise;
verifyMfa: Promise;
};
```
Defines authentication-related methods for the NuramaClient.
#### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ----------------------------------------------------- | -------------------------- |
| `client` | [`default`](/docs/reference/sdk/NuramaClient#default) | The NuramaClient instance. |
#### Returns [#returns]
An object containing the authentication methods.
| Name | Type | Description |
| --------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `changePassword()` | ( `currentPassword`, `newPassword`, `mfaToken?` ) => `Promise`\<`void`> | Changes the authenticated user's password. Requires current password verification and MFA token if MFA is enabled. All refresh tokens will be invalidated after password change. |
| `disableMfa()` | (`mfaToken`) => `Promise`\<`void`> | Disables multi-factor authentication for the authenticated user. Requires a current valid MFA token for confirmation. |
| `enableMfa()` | () => `Promise`\<`MFAEnableResponse`> | Enables multi-factor authentication for the authenticated user. |
| `exchangeOAuthCode()` | (`code`) => `Promise`\<`OAuthExchangeResponse`> | - |
| `forgotPassword()` | (`email`) => `Promise`\<`void`> | Forgets a user's password. |
| `getLinkedOAuthProviders()` | () => `Promise`\<`LinkedAuthProvider`\[]> | Gets all OAuth providers linked to the authenticated user's account. |
| `linkOAuthProvider()` | (`provider`) => `Promise`\<[`LoginRegisterResponse`](#loginregisterresponse)> | Links an OAuth provider to the authenticated user's account. This allows users to sign in with multiple OAuth providers. |
| `lockAccount()` | (`token`) => `Promise`\<`void`> | Locks a user account using a lock account token. This is used when a user receives a password changed notification for a change they did not initiate, allowing them to immediately secure their account. |
| `login()` | (`credentials`) => `Promise`\<[`LoginRegisterResponse`](#loginregisterresponse)> | Logs in a user. |
| `logout()` | (`refreshToken`) => `Promise`\<`void`> | Logs out a user. |
| `refreshTokens()` | (`refreshToken?`) => `Promise`\<[`RefreshResponse`](#refreshresponse)> | Refreshes user tokens. |
| `register()` | (`userData`) => `Promise`\<[`LoginRegisterResponse`](#loginregisterresponse)> | Registers a new user. |
| `registerGuest()` | (`data`) => `Promise`\<`void`> | Registers a guest account for public chat participation. Always returns void (204) regardless of outcome for anti-enumeration. |
| `resendVerification()` | (`email`) => `Promise`\<`void`> | Public, unauthenticated resend of the verification email keyed by address. For users past the verification grace window who can't log in or call the authed sendVerificationEmail. Always resolves (the server returns 204 regardless of whether the email exists). |
| `resetPassword()` | (`params`) => `Promise`\<`void`> | Resets a user's password. |
| `sendVerificationEmail()` | () => `Promise`\<`void`> | Sends a verification email to the authenticated user. |
| `setPassword()` | (`password`, `mfaToken?`) => `Promise`\<`void`> | Sets a password for an OAuth-only user account. This allows OAuth users to add local authentication as a backup. |
| `unlinkOAuthProvider()` | (`provider`) => `Promise`\<`void`> | Unlinks an OAuth provider from the authenticated user's account. User must have at least one authentication method remaining (password or another OAuth provider). |
| `upgradeGuest()` | (`data`) => `Promise`\<\{ `user`: `User`; }> | Upgrades a guest account to a standard account with a password. Requires the user to be authenticated as a guest. |
| `verifyBackupCode()` | (`backupCode`) => `Promise`\<`MFAVerifyResponse`> | Verifies an MFA backup code. This is used during login when a user has lost access to their authenticator app. |
| `verifyEmail()` | (`token`) => `Promise`\<`void`> | Verifies a user's email using the provided token. |
| `verifyGuest()` | (`token`) => `Promise`\<[`LoginRegisterResponse`](#loginregisterresponse)> | Verifies a guest account using the token from the verification email. Stores auth tokens on success and returns user data. |
| `verifyMfa()` | (`mfaToken`) => `Promise`\<`MFAVerifyResponse`> | Verifies an MFA token (e.g., TOTP code). This is used both during initial MFA setup and during login challenges. |
# blogPosts (/docs/reference/sdk/routes/blogPosts)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
## Functions [#functions]
### default() [#default]
```ts
function default(client): {
listBlogPosts: Promise;
};
```
Read-only blog feed (Nurama News, shown on the web app's /news page).
Auth: any signed-in user. No workspace coupling — the feed is
platform-level, identical for every user.
The server normalises the post payload and sanitises post HTML, so
the returned `bodyHtml` is safe to render directly.
#### Parameters [#parameters]
| Parameter | Type |
| --------- | ----------------------------------------------------- |
| `client` | [`default`](/docs/reference/sdk/NuramaClient#default) |
#### Returns [#returns]
| Name | Type | Description |
| ----------------- | ------------------------------------------------- | --------------------------------------- |
| `listBlogPosts()` | (`params?`) => `Promise`\<`BlogPostListResponse`> | List the most recent Nurama News posts. |
# board (/docs/reference/sdk/routes/board)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
## Interfaces [#interfaces]
### AddColumnData [#addcolumndata]
#### Properties [#properties]
| Property | Type | Description |
| ----------------------------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `color?` | `string` | - |
| `description?` | `string` | - |
| `isDefault?` | `boolean` | - |
| `name` | `string` | - |
| `reviewersCanContribute?` | `boolean` | When true, reviewer-role users may create tasks in this column on a reviewer-visibility board. |
| `sortOrder?` | `number` | - |
| `taskStatus?` | `"pending"` \| `"inProgress"` \| `"complete"` \| `"closed"` \| `null` | - |
***
### AddExistingTaskData [#addexistingtaskdata]
#### Properties [#properties-1]
| Property | Type |
| ------------------------------- | -------- |
| `columnId?` | `string` |
| `taskId` | `string` |
***
### CreateBoardData [#createboarddata]
#### Properties [#properties-2]
| Property | Type |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `columns?` | \{ `color?`: `string`; `description?`: `string`; `isDefault?`: `boolean`; `name`: `string`; `sortOrder?`: `number`; `taskStatus?`: `"pending"` \| `"inProgress"` \| `"complete"` \| `"closed"` \| `null`; }\[] |
| `description?` | `string` |
| `name` | `string` |
| `projectId` | `string` |
| `visibility?` | (`"creator"` \| `"reviewer"`)\[] |
***
### CreateBoardTaskData [#createboardtaskdata]
#### Properties [#properties-3]
| Property | Type | Description |
| --------------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `announce?` | \{ `chatId`: `string`; `messageId`: `string`; } | Optional announce flag. When supplied, after the task is created the server posts a Nu reply in `chatId` threaded under `messageId` with this task as a single taskCard and links them via TaskRelation. Mirrors the same flag on `tasks.bulkCreate`. |
| `announce.chatId` | `string` | - |
| `announce.messageId` | `string` | - |
| `assignedToId?` | `string` | - |
| `columnId?` | `string` | - |
| `description?` | `string` | - |
| `subject` | `string` | - |
***
### LinkTaskData [#linktaskdata]
#### Properties [#properties-4]
| Property | Type |
| -------------------------------------- | ----------------------------------------------------------- |
| `linkedTaskId` | `string` |
| `linkType?` | `"related"` \| `"blocks"` \| `"blockedBy"` \| `"duplicate"` |
***
### MoveTaskData [#movetaskdata]
#### Properties [#properties-5]
| Property | Type | Description |
| ----------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `columnId?` | `string` | Required for same-board moves; optional when `targetBoardId` is set (server defaults to the target board's default column). |
| `sortOrder?` | `number` | - |
| `targetBoardId?` | `string` | When supplied AND different from the URL `boardId`, the server performs a cross-board move — `boardId` and `columnId` are updated together. Omit for the original same-board move. |
***
### ReorderColumnsData [#reordercolumnsdata]
#### Properties [#properties-6]
| Property | Type |
| ------------------------------ | ---------------------------------------------- |
| `columns` | \{ `id`: `string`; `sortOrder`: `number`; }\[] |
***
### UpdateBoardData [#updateboarddata]
#### Properties [#properties-7]
| Property | Type | Description |
| --------------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cascade?` | `boolean` | When narrowing visibility, opt into automatic cleanup of dependent tasks, assignees, and relations. If omitted (or false) and dependents exist, the server returns 409 with a structured `errorData.blockers` payload. |
| `description?` | `string` \| `null` | - |
| `name?` | `string` | - |
| `sortOrder?` | `number` | - |
| `status?` | `"active"` \| `"archived"` | - |
| `visibility?` | (`"creator"` \| `"reviewer"`)\[] | - |
***
### UpdateColumnData [#updatecolumndata]
#### Properties [#properties-8]
| Property | Type | Description |
| ------------------------------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `color?` | `string` \| `null` | - |
| `description?` | `string` \| `null` | - |
| `isDefault?` | `boolean` | - |
| `name?` | `string` | - |
| `reviewersCanContribute?` | `boolean` | When true, reviewer-role users may create tasks in this column on a reviewer-visibility board. |
| `sortOrder?` | `number` | - |
| `taskStatus?` | `"pending"` \| `"inProgress"` \| `"complete"` \| `"closed"` \| `null` | - |
***
### UpdateTaskDetailsData [#updatetaskdetailsdata]
#### Properties [#properties-9]
| Property | Type |
| ----------------------------------------- | ------------------ |
| `assignedToId?` | `string` \| `null` |
| `description?` | `string` \| `null` |
| `subject?` | `string` |
## Functions [#functions]
### default() [#default]
```ts
function default(client): {
addColumn: Promise;
addExistingTaskToBoard: Promise;
createBoard: Promise;
createBoardTask: Promise;
deleteBoard: Promise<{
deletedTaskIds: string[];
disposition: string;
message: string;
reassignedTaskIds: string[];
}>;
deleteColumn: Promise;
followBoard: Promise;
getBoard: Promise;
getBoardTasks: Promise;
getProjectBoards: Promise;
getProjectTasks: Promise;
moveTask: Promise;
removeTaskFromBoard: Promise;
reorderColumns: Promise;
tagBoard: Promise;
unfollowBoard: Promise;
untagBoard: Promise;
updateBoard: Promise;
updateColumn: Promise;
};
```
#### Parameters [#parameters]
| Parameter | Type |
| --------- | ----------------------------------------------------- |
| `client` | [`default`](/docs/reference/sdk/NuramaClient#default) |
#### Returns [#returns]
| Name | Type | Description |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `addColumn()` | (`boardId`, `data`) => `Promise`\<`BoardColumn`> | Add a column to a board. Appended at the end unless `sortOrder` is provided. |
| `addExistingTaskToBoard()` | (`boardId`, `data`) => `Promise`\<`Task`> | Attach an existing project task to a board (no new task is created). |
| `createBoard()` | (`data`) => `Promise`\<`Board`> | Create a new board inside a project. If `columns` are omitted the server seeds the standard four-column layout. |
| `createBoardTask()` | (`boardId`, `data`) => `Promise`\<`Task`> | Create a task directly on a board. When `announce` is supplied the server also posts a Nu reply in the named chat threaded under the given message, with this task linked via TaskRelation. |
| `deleteBoard()` | (`boardId`, `body?`) => `Promise`\<\{ `deletedTaskIds`: `string`\[]; `disposition`: `string`; `message`: `string`; `reassignedTaskIds`: `string`\[]; }> | Delete a board. `disposition` controls what happens to its tasks: `unassign` (default — tasks survive boardless), `delete`, or `reassign` to another board/column. |
| `deleteColumn()` | ( `boardId`, `columnId`, `targetColumnId?` ) => `Promise`\<`void`> | Delete a column. If the column holds tasks, pass `targetColumnId` to move them; otherwise the call fails. |
| `followBoard()` | (`boardId`) => `Promise`\<`Board`> | Follow a board to receive notifications about its tasks. |
| `getBoard()` | (`boardId`) => `Promise`\<`BoardWithTasks`> | Fetch a board with its columns and tasks populated. |
| `getBoardTasks()` | (`boardId`, `params?`) => `Promise`\<`Task`\[]> | List tasks on a board, optionally narrowed by column / assignee / tag / status / search. |
| `getProjectBoards()` | (`projectId`, `params?`) => `Promise`\<`Board`\[]> | List boards in a project. Filters by visibility, free-text search, and tag ids. |
| `getProjectTasks()` | (`projectId`, `params?`) => `Promise`\<`any`> | List every task in a project across all boards. Use `boardId: 'unassigned'` to fetch only tasks not yet placed on a board. |
| `moveTask()` | ( `boardId`, `taskId`, `data` ) => `Promise`\<`Task`> | Move a task to a different column on the same board. |
| `removeTaskFromBoard()` | (`boardId`, `taskId`) => `Promise`\<`Task`> | Detach a task from a board. The task itself is preserved as boardless. |
| `reorderColumns()` | (`boardId`, `data`) => `Promise`\<`BoardColumn`\[]> | Reorder a board's columns. The request must include every column id. |
| `tagBoard()` | (`boardId`, `tagId`) => `Promise`\<`Board`> | Attach a tag to a board. |
| `unfollowBoard()` | (`boardId`) => `Promise`\<`Board`> | Stop following a board. |
| `untagBoard()` | (`boardId`, `tagId`) => `Promise`\<`Board`> | Detach a tag from a board. |
| `updateBoard()` | (`boardId`, `data`) => `Promise`\<`Board`> | Update a board's metadata. Set `cascade: true` to opt into automatic cleanup of dependent tasks when narrowing visibility; otherwise the server returns 409 with a `blockers` payload. |
| `updateColumn()` | ( `boardId`, `columnId`, `data` ) => `Promise`\<`BoardColumn`> | Update column metadata (name, color, task-status mapping, etc.). |
# bot (/docs/reference/sdk/routes/bot)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
## Interfaces [#interfaces]
### Bot [#bot]
#### Properties [#properties]
| Property | Type | Description |
| --------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `accountType` | `"bot"` | - |
| `apiKey?` | [`BotApiKeySummary`](#botapikeysummary) | - |
| `apiKeys?` | [`BotApiKeySummary`](#botapikeysummary)\[] | - |
| `avatar?` | `any` | Populated avatar Asset (joined server-side from `avatarId`). The web client resolves the image URL from this field via `getAvatarUrl()`. |
| `avatarId` | `string` \| `null` | - |
| `color` | `string` | - |
| `createdAt` | `string` | - |
| `displayName` | `string` | - |
| `id` | `string` | - |
| `membershipId?` | `string` | - |
| `projectMemberships?` | [`BotProjectMembership`](#botprojectmembership)\[] | Project memberships within the workspace the bot belongs to. Populated by `listBots` and `getBot`. Empty array if the bot has no project assignments. |
| `roles?` | `string`\[] | - |
| `status` | `string` | - |
| `updatedAt` | `string` | - |
***
### BotApiKeySummary [#botapikeysummary]
#### Properties [#properties-1]
| Property | Type | Description |
| ---------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------ |
| `createdAt` | `string` | - |
| `expiresAt?` | `string` \| `null` | - |
| `id` | `string` | - |
| `keyPrefix` | `string` | - |
| `kind?` | `"botAccess"` \| `"pat"` \| `"oauthAccess"` \| `"oauthRefresh"` \| `null` | Discriminator. Bot keys mint as 'botAccess'. |
| `lastUsed?` | `string` \| `null` | - |
| `name` | `string` | - |
| `scopes?` | `string`\[] | Granted action verbs. Empty array = unscoped (legacy). |
| `status` | `"active"` \| `"revoked"` | - |
***
### BotProjectMembership [#botprojectmembership]
#### Properties [#properties-2]
| Property | Type |
| ---------------------------------------- | -------------------------------------- |
| `membershipId` | `string` |
| `projectId` | `string` |
| `projectName` | `string` |
| `roles` | [`BotProjectRole`](#botprojectrole)\[] |
***
### CreateBotData [#createbotdata]
#### Properties [#properties-3]
| Property | Type | Description |
| ----------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `color?` | `string` | Optional hex color from the approved palette. Auto-assigned if omitted. |
| `name` | `string` | Display name for the bot. 1–50 characters. |
| `roles` | (`"workspaceAdmin"` \| `"workspaceMember"` \| `"workspaceChatMember"`)\[] | Workspace roles to grant the bot. Must be one or more of: workspaceAdmin, workspaceMember, workspaceChatMember. |
| `scopes?` | `string`\[] | Optional API-key scopes. Defaults to \[] (legacy — bot key can call any route that isn't yet scope-gated). Once a route is gated by `requireTokenScope` the bot needs the matching scope here for that route to work. |
***
### CreateBotResponse [#createbotresponse]
#### Properties [#properties-4]
| Property | Type | Description |
| -------------------------- | ------------- | ------------------------------------------------------------------------------------------------- |
| `bot` | [`Bot`](#bot) | - |
| `rawKey` | `string` | Raw API key, returned ONCE at creation time. Store it immediately — it cannot be retrieved again. |
***
### RotateBotKeyResponse [#rotatebotkeyresponse]
#### Properties [#properties-5]
| Property | Type | Description |
| ---------------------------- | --------------------------------------- | ------------------------------- |
| `apiKey` | [`BotApiKeySummary`](#botapikeysummary) | - |
| `rawKey` | `string` | New raw API key. Returned once. |
***
### UpdateBotAvatarFileData [#updatebotavatarfiledata]
#### Properties [#properties-6]
| Property | Type |
| ------------------------------ | -------- |
| `checksum` | `string` |
| `name` | `string` |
| `sizeInMB` | `number` |
***
### UpdateBotAvatarResponse [#updatebotavatarresponse]
#### Indexable [#indexable]
```ts
[k: string]: unknown
```
#### Properties [#properties-7]
| Property | Type |
| ----------------------------------------- | ---------------------------------------------------------------- |
| `asset?` | \{ \[`k`: `string`]: `unknown`; `id`: `string`; } |
| `asset.id` | `string` |
| `signedUrlData?` | \{ `key`: `string`; `uploadId`: `string`; `urls`: `string`\[]; } |
| `signedUrlData.key` | `string` |
| `signedUrlData.uploadId` | `string` |
| `signedUrlData.urls` | `string`\[] |
| `user` | \{ `avatarId`: `string` \| `null`; `id`: `string`; } |
| `user.avatarId` | `string` \| `null` |
| `user.id` | `string` |
***
### UpdateBotData [#updatebotdata]
#### Properties [#properties-8]
| Property | Type |
| --------------------------- | -------- |
| `color?` | `string` |
| `name?` | `string` |
## Type Aliases [#type-aliases]
### BotProjectRole [#botprojectrole]
```ts
type BotProjectRole = "creator" | "reviewer" | "projectAdmin";
```
## Functions [#functions]
### default() [#default]
```ts
function default(client): {
createBot: Promise;
deleteBot: Promise;
getBot: Promise;
listBots: Promise;
listProjectMemberships: Promise;
removeProjectMembership: Promise;
rotateBotKey: Promise;
setProjectMembership: Promise;
updateBot: Promise;
updateBotAvatar: Promise;
};
```
Bot user administration methods. Used by workspace owners/admins (callers
holding a JWT) to manage bot users in a workspace. Bots themselves cannot
call these endpoints — bot administration is restricted server-side.
#### Parameters [#parameters]
| Parameter | Type |
| --------- | ----------------------------------------------------- |
| `client` | [`default`](/docs/reference/sdk/NuramaClient#default) |
#### Returns [#returns]
| Name | Type | Description |
| --------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `createBot()` | (`workspaceId`, `data`) => `Promise`\<[`CreateBotResponse`](#createbotresponse)> | Create a bot user in a workspace. Returns the new bot and the raw API key (shown only once). |
| `deleteBot()` | (`workspaceId`, `botId`) => `Promise`\<`void`> | Delete a bot user. Revokes all API keys, removes the workspace membership, and marks the user inactive. |
| `getBot()` | (`workspaceId`, `botId`) => `Promise`\<[`Bot`](#bot)> | Get a single bot's details, including all of its API key metadata (no secrets). |
| `listBots()` | (`workspaceId`) => `Promise`\<[`Bot`](#bot)\[]> | List bot users in a workspace. |
| `listProjectMemberships()` | (`workspaceId`, `botId`) => `Promise`\<[`BotProjectMembership`](#botprojectmembership)\[]> | List the bot's project memberships within the workspace. |
| `removeProjectMembership()` | ( `workspaceId`, `botId`, `projectId` ) => `Promise`\<`void`> | Remove the bot's membership on a project. Idempotent. |
| `rotateBotKey()` | (`workspaceId`, `botId`) => `Promise`\<[`RotateBotKeyResponse`](#rotatebotkeyresponse)> | Revoke the bot's current API key and issue a new one. The new raw key is returned once. |
| `setProjectMembership()` | ( `workspaceId`, `botId`, `projectId`, `data` ) => `Promise`\<[`BotProjectMembership`](#botprojectmembership)> | Upsert the bot's membership on a project. Replaces roles if a membership already exists; creates one otherwise. Idempotent. |
| `updateBot()` | ( `workspaceId`, `botId`, `data` ) => `Promise`\<[`Bot`](#bot)> | Update a bot's display name and/or color. |
| `updateBotAvatar()` | ( `workspaceId`, `botId`, `fileData` ) => `Promise`\<[`UpdateBotAvatarResponse`](#updatebotavatarresponse)> | Request signed URL data to upload a new avatar for the bot. Upload the file with `client.asset.multipartUpload(...)` using the returned `signedUrlData`, then call `client.asset.completeUpload(...)` to finalize. |
# chat (/docs/reference/sdk/routes/chat)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
## Interfaces [#interfaces]
### AddableMembersByScope [#addablemembersbyscope]
Addable members for a legacy project-scoped member chat, split by the membership they come from.
#### Properties [#properties]
| Property | Type |
| ---------------------------------------------------- | --------------- |
| `projectMembership` | `Membership`\[] |
| `workspaceMembership` | `Membership`\[] |
***
### AttachmentUploadRecord [#attachmentuploadrecord]
One entry of an upload response: the created asset plus the signed upload data the
caller uses to PUT the bytes, or a per-file failure (`status: 'fail'` with `error`).
#### Properties [#properties-1]
| Property | Type |
| ----------------------------------------------------------- | ----------------------- |
| `asset?` | `Asset` |
| `error?` | `string` |
| `id` | `string` \| `number` |
| `name` | `string` |
| `signedUrlData?` | `any` |
| `status` | `"success"` \| `"fail"` |
| `uploadChunkSizeInBytes?` | `number` |
***
### BaseAnnotation [#baseannotation]
#### Extended by [#extended-by]
* [`NestedDotAnnotation`](#nesteddotannotation)
* [`NestedShapeAnnotation`](#nestedshapeannotation)
* [`NestedTextAnnotation`](#nestedtextannotation)
* [`NestedPathAnnotation`](#nestedpathannotation)
* [`DotAnnotation`](#dotannotation)
* [`FrameCommentAnnotation`](#framecommentannotation)
* [`ShapeAnnotation`](#shapeannotation)
* [`TextAnnotation`](#textannotation)
* [`PathAnnotation`](#pathannotation)
#### Properties [#properties-2]
| Property | Type |
| ----------------------------------------------- | --------------------------------------------------------------------------------------- |
| `angle?` | `number` |
| `color?` | `string` |
| `endTimestamp?` | `number` |
| `fillRule?` | `"nonzero"` \| `"evenodd"` |
| `flipX?` | `boolean` |
| `flipY?` | `boolean` |
| `frame?` | `number` |
| `height?` | `number` |
| `left?` | `number` |
| `opacity?` | `number` |
| `originX?` | `"left"` \| `"center"` \| `"right"` |
| `originY?` | `"center"` \| `"top"` \| `"bottom"` |
| `scaleX?` | `number` |
| `scaleY?` | `number` |
| `shadow?` | \{ `blur?`: `number`; `color?`: `string`; `offsetX?`: `number`; `offsetY?`: `number`; } |
| `shadow.blur?` | `number` |
| `shadow.color?` | `string` |
| `shadow.offsetX?` | `number` |
| `shadow.offsetY?` | `number` |
| `skewX?` | `number` |
| `skewY?` | `number` |
| `startTimestamp?` | `number` |
| `strokeDashArray?` | `number`\[] |
| `strokeLineCap?` | `"butt"` \| `"round"` \| `"square"` |
| `strokeLineJoin?` | `"round"` \| `"miter"` \| `"bevel"` |
| `strokeMiterLimit?` | `number` |
| `timestamp?` | `number` |
| `top?` | `number` |
| `visible?` | `boolean` |
| `width?` | `number` |
***
### CreateAssetChatAndMessageData [#createassetchatandmessagedata]
#### Extends [#extends]
* [`CreateMessageData`](#createmessagedata)
#### Properties [#properties-3]
| Property | Type | Description | Inherited from |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
| `annotations?` | [`Annotation`](#annotation)\[] | - | [`CreateMessageData`](#createmessagedata).[`annotations`](#annotations-1) |
| `assetMentions?` | `string`\[] | - | [`CreateMessageData`](#createmessagedata).[`assetMentions`](#assetmentions-1) |
| `attachments?` | ( \| [`FileAttachmentData`](#fileattachmentdata) \| [`ScratchAttachmentRef`](#scratchattachmentref))\[] | - | [`CreateMessageData`](#createmessagedata).[`attachments`](#attachments-1) |
| `content?` | `string` | - | [`CreateMessageData`](#createmessagedata).[`content`](#content-1) |
| `folderMentions?` | `string`\[] | - | [`CreateMessageData`](#createmessagedata).[`folderMentions`](#foldermentions-1) |
| `linkPreviews?` | `LinkPreview`\[] | - | [`CreateMessageData`](#createmessagedata).[`linkPreviews`](#linkpreviews-1) |
| `mentions?` | `string`\[] | - | [`CreateMessageData`](#createmessagedata).[`mentions`](#mentions-1) |
| `pageContext?` | \{ `pageTitle?`: `string`; `path?`: `string`; `visibleAssetIds?`: `string`\[]; } | AI-chat only. Sent on the regular chat endpoint when the target chat is an AI topic so the assistant sees a snapshot of the page the user was looking at. Regular chats ignore this field. | [`CreateMessageData`](#createmessagedata).[`pageContext`](#pagecontext-1) |
| `pageContext.pageTitle?` | `string` | - | - |
| `pageContext.path?` | `string` | - | - |
| `pageContext.visibleAssetIds?` | `string`\[] | - | - |
| `publicMentions?` | `string`\[] | - | [`CreateMessageData`](#createmessagedata).[`publicMentions`](#publicmentions-1) |
| `quotes?` | `string`\[] | - | [`CreateMessageData`](#createmessagedata).[`quotes`](#quotes-1) |
| `replyToId?` | `string` | - | [`CreateMessageData`](#createmessagedata).[`replyToId`](#replytoid-1) |
| `submissionMentions?` | `string`\[] | - | [`CreateMessageData`](#createmessagedata).[`submissionMentions`](#submissionmentions-1) |
| `taskMentions?` | `string`\[] | - | [`CreateMessageData`](#createmessagedata).[`taskMentions`](#taskmentions-1) |
***
### CreateAssetChatAndMessageParams [#createassetchatandmessageparams]
#### Extends [#extends-1]
* [`SortParams`](#sortparams)
#### Properties [#properties-4]
| Property | Type | Inherited from |
| ------------------------------- | -------------------------------- | ---------------------------------------------- |
| `messages?` | `number` | - |
| `replies?` | `number` | - |
| `sort?` | `Record`\<`string`, `-1` \| `1`> | [`SortParams`](#sortparams).[`sort`](#sort-12) |
***
### CreateMemberChatData [#creatememberchatdata]
#### Properties [#properties-5]
| Property | Type | Description |
| -------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `color?` | `string` | Optional hex colour from the approved palette (see `GET /config`). |
| `memberIds` | `string`\[] | - |
| `scopeId` | `string` | - |
| `scopeType` | `"project"` \| `"workspace"` | Only `workspace` is accepted by the API; `project` is rejected with 400 (project-scoped member chats are no longer created). |
| `subject?` | `string` | - |
***
### CreateMessageData [#createmessagedata]
#### Extended by [#extended-by-1]
* [`CreateAssetChatAndMessageData`](#createassetchatandmessagedata)
#### Properties [#properties-6]
| Property | Type | Description |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `annotations?` | [`Annotation`](#annotation)\[] | - |
| `assetMentions?` | `string`\[] | - |
| `attachments?` | ( \| [`FileAttachmentData`](#fileattachmentdata) \| [`ScratchAttachmentRef`](#scratchattachmentref))\[] | - |
| `content?` | `string` | - |
| `folderMentions?` | `string`\[] | - |
| `linkPreviews?` | `LinkPreview`\[] | - |
| `mentions?` | `string`\[] | - |
| `pageContext?` | \{ `pageTitle?`: `string`; `path?`: `string`; `visibleAssetIds?`: `string`\[]; } | AI-chat only. Sent on the regular chat endpoint when the target chat is an AI topic so the assistant sees a snapshot of the page the user was looking at. Regular chats ignore this field. |
| `pageContext.pageTitle?` | `string` | - |
| `pageContext.path?` | `string` | - |
| `pageContext.visibleAssetIds?` | `string`\[] | - |
| `publicMentions?` | `string`\[] | - |
| `quotes?` | `string`\[] | - |
| `replyToId?` | `string` | - |
| `submissionMentions?` | `string`\[] | - |
| `taskMentions?` | `string`\[] | - |
***
### CreateReactionData [#createreactiondata]
#### Properties [#properties-7]
| Property | Type |
| ------------------------ | -------- |
| `emoji` | `string` |
***
### CreateTopicChatData [#createtopicchatdata]
#### Properties [#properties-8]
| Property | Type |
| ----------------------------------- | --------------------------- |
| `subject?` | `string` |
| `topicId` | `string` |
| `topicType` | `"asset"` \| `"project"` |
| `visibility?` | `"creator"` \| `"reviewer"` |
***
### DateRangeParams [#daterangeparams]
#### Extended by [#extended-by-2]
* [`GetUsersMemberChatsParams`](#getusersmemberchatsparams)
* [`GetUsersMentionsParams`](#getusersmentionsparams)
* [`GetMessagesParams`](#getmessagesparams)
* [`GetRepliesParams`](#getrepliesparams)
#### Properties [#properties-9]
| Property | Type |
| ----------------------------------------- | -------------------- |
| `createdAfter?` | `string` \| `number` |
| `createdBefore?` | `string` \| `number` |
| `updatedBefore?` | `string` \| `number` |
***
### DotAnnotation [#dotannotation]
#### Extends [#extends-2]
* [`BaseAnnotation`](#baseannotation)
#### Properties [#properties-10]
| Property | Type | Inherited from |
| ------------------------------------------------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `angle?` | `number` | [`BaseAnnotation`](#baseannotation).[`angle`](#angle) |
| `color?` | `string` | [`BaseAnnotation`](#baseannotation).[`color`](#color) |
| `coordinates` | [`PercentageCoordinates`](#percentagecoordinates) | - |
| `endTimestamp?` | `number` | [`BaseAnnotation`](#baseannotation).[`endTimestamp`](#endtimestamp) |
| `fillRule?` | `"nonzero"` \| `"evenodd"` | [`BaseAnnotation`](#baseannotation).[`fillRule`](#fillrule) |
| `flipX?` | `boolean` | [`BaseAnnotation`](#baseannotation).[`flipX`](#flipx) |
| `flipY?` | `boolean` | [`BaseAnnotation`](#baseannotation).[`flipY`](#flipy) |
| `frame?` | `number` | [`BaseAnnotation`](#baseannotation).[`frame`](#frame) |
| `height?` | `number` | [`BaseAnnotation`](#baseannotation).[`height`](#height) |
| `left?` | `number` | [`BaseAnnotation`](#baseannotation).[`left`](#left) |
| `nestedAnnotations?` | [`NestedAnnotation`](#nestedannotation)\[] | - |
| `opacity?` | `number` | [`BaseAnnotation`](#baseannotation).[`opacity`](#opacity) |
| `originX?` | `"left"` \| `"center"` \| `"right"` | [`BaseAnnotation`](#baseannotation).[`originX`](#originx) |
| `originY?` | `"center"` \| `"top"` \| `"bottom"` | [`BaseAnnotation`](#baseannotation).[`originY`](#originy) |
| `radius?` | `number` | - |
| `scaleX?` | `number` | [`BaseAnnotation`](#baseannotation).[`scaleX`](#scalex) |
| `scaleY?` | `number` | [`BaseAnnotation`](#baseannotation).[`scaleY`](#scaley) |
| `shadow?` | \{ `blur?`: `number`; `color?`: `string`; `offsetX?`: `number`; `offsetY?`: `number`; } | [`BaseAnnotation`](#baseannotation).[`shadow`](#shadow) |
| `shadow.blur?` | `number` | - |
| `shadow.color?` | `string` | - |
| `shadow.offsetX?` | `number` | - |
| `shadow.offsetY?` | `number` | - |
| `skewX?` | `number` | [`BaseAnnotation`](#baseannotation).[`skewX`](#skewx) |
| `skewY?` | `number` | [`BaseAnnotation`](#baseannotation).[`skewY`](#skewy) |
| `startTimestamp?` | `number` | [`BaseAnnotation`](#baseannotation).[`startTimestamp`](#starttimestamp) |
| `strokeDashArray?` | `number`\[] | [`BaseAnnotation`](#baseannotation).[`strokeDashArray`](#strokedasharray) |
| `strokeLineCap?` | `"butt"` \| `"round"` \| `"square"` | [`BaseAnnotation`](#baseannotation).[`strokeLineCap`](#strokelinecap) |
| `strokeLineJoin?` | `"round"` \| `"miter"` \| `"bevel"` | [`BaseAnnotation`](#baseannotation).[`strokeLineJoin`](#strokelinejoin) |
| `strokeMiterLimit?` | `number` | [`BaseAnnotation`](#baseannotation).[`strokeMiterLimit`](#strokemiterlimit) |
| `timestamp?` | `number` | [`BaseAnnotation`](#baseannotation).[`timestamp`](#timestamp) |
| `top?` | `number` | [`BaseAnnotation`](#baseannotation).[`top`](#top) |
| `type` | `"dot"` | - |
| `visible?` | `boolean` | [`BaseAnnotation`](#baseannotation).[`visible`](#visible) |
| `width?` | `number` | [`BaseAnnotation`](#baseannotation).[`width`](#width) |
***
### FetchLinkPreviewsData [#fetchlinkpreviewsdata]
#### Properties [#properties-11]
| Property | Type |
| ---------------------- | ----------- |
| `urls` | `string`\[] |
***
### FileAttachmentData [#fileattachmentdata]
#### Properties [#properties-12]
| Property | Type |
| ------------------------------ | -------- |
| `checksum` | `string` |
| `id` | `number` |
| `name` | `string` |
| `sizeInMB` | `number` |
***
### FrameCommentAnnotation [#framecommentannotation]
#### Extends [#extends-3]
* [`BaseAnnotation`](#baseannotation)
#### Properties [#properties-13]
| Property | Type | Inherited from |
| --------------------------------------------------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `angle?` | `number` | [`BaseAnnotation`](#baseannotation).[`angle`](#angle) |
| `color?` | `string` | [`BaseAnnotation`](#baseannotation).[`color`](#color) |
| `endTimestamp?` | `number` | [`BaseAnnotation`](#baseannotation).[`endTimestamp`](#endtimestamp) |
| `fillRule?` | `"nonzero"` \| `"evenodd"` | [`BaseAnnotation`](#baseannotation).[`fillRule`](#fillrule) |
| `flipX?` | `boolean` | [`BaseAnnotation`](#baseannotation).[`flipX`](#flipx) |
| `flipY?` | `boolean` | [`BaseAnnotation`](#baseannotation).[`flipY`](#flipy) |
| `frame?` | `number` | [`BaseAnnotation`](#baseannotation).[`frame`](#frame) |
| `height?` | `number` | [`BaseAnnotation`](#baseannotation).[`height`](#height) |
| `left?` | `number` | [`BaseAnnotation`](#baseannotation).[`left`](#left) |
| `nestedAnnotations?` | [`NestedAnnotation`](#nestedannotation)\[] | - |
| `opacity?` | `number` | [`BaseAnnotation`](#baseannotation).[`opacity`](#opacity) |
| `originX?` | `"left"` \| `"center"` \| `"right"` | [`BaseAnnotation`](#baseannotation).[`originX`](#originx) |
| `originY?` | `"center"` \| `"top"` \| `"bottom"` | [`BaseAnnotation`](#baseannotation).[`originY`](#originy) |
| `scaleX?` | `number` | [`BaseAnnotation`](#baseannotation).[`scaleX`](#scalex) |
| `scaleY?` | `number` | [`BaseAnnotation`](#baseannotation).[`scaleY`](#scaley) |
| `shadow?` | \{ `blur?`: `number`; `color?`: `string`; `offsetX?`: `number`; `offsetY?`: `number`; } | [`BaseAnnotation`](#baseannotation).[`shadow`](#shadow) |
| `shadow.blur?` | `number` | - |
| `shadow.color?` | `string` | - |
| `shadow.offsetX?` | `number` | - |
| `shadow.offsetY?` | `number` | - |
| `skewX?` | `number` | [`BaseAnnotation`](#baseannotation).[`skewX`](#skewx) |
| `skewY?` | `number` | [`BaseAnnotation`](#baseannotation).[`skewY`](#skewy) |
| `startTimestamp?` | `number` | [`BaseAnnotation`](#baseannotation).[`startTimestamp`](#starttimestamp) |
| `strokeDashArray?` | `number`\[] | [`BaseAnnotation`](#baseannotation).[`strokeDashArray`](#strokedasharray) |
| `strokeLineCap?` | `"butt"` \| `"round"` \| `"square"` | [`BaseAnnotation`](#baseannotation).[`strokeLineCap`](#strokelinecap) |
| `strokeLineJoin?` | `"round"` \| `"miter"` \| `"bevel"` | [`BaseAnnotation`](#baseannotation).[`strokeLineJoin`](#strokelinejoin) |
| `strokeMiterLimit?` | `number` | [`BaseAnnotation`](#baseannotation).[`strokeMiterLimit`](#strokemiterlimit) |
| `timestamp?` | `number` | [`BaseAnnotation`](#baseannotation).[`timestamp`](#timestamp) |
| `top?` | `number` | [`BaseAnnotation`](#baseannotation).[`top`](#top) |
| `type` | `"frameComment"` | - |
| `visible?` | `boolean` | [`BaseAnnotation`](#baseannotation).[`visible`](#visible) |
| `width?` | `number` | [`BaseAnnotation`](#baseannotation).[`width`](#width) |
***
### GetChatByTopicIdParams [#getchatbytopicidparams]
#### Extends [#extends-4]
* [`SortParams`](#sortparams)
#### Properties [#properties-14]
| Property | Type | Inherited from |
| ------------------------------------- | -------------------------------- | ---------------------------------------------- |
| `messages?` | `number` | - |
| `replies?` | `number` | - |
| `sort?` | `Record`\<`string`, `-1` \| `1`> | [`SortParams`](#sortparams).[`sort`](#sort-12) |
| `topicType` | `string` | - |
| `visibility?` | `"creator"` \| `"reviewer"` | - |
***
### GetMentionableAssetsParams [#getmentionableassetsparams]
#### Extends [#extends-5]
* [`PaginationParams`](#paginationparams).[`SortParams`](#sortparams)
#### Properties [#properties-15]
| Property | Type | Inherited from |
| ------------------------------------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------- |
| `cursor?` | `string` | [`PaginationParams`](#paginationparams).[`cursor`](#cursor-9) |
| `includeCounts?` | `boolean` | [`PaginationParams`](#paginationparams).[`includeCounts`](#includecounts-9) |
| `includeCursorRecord?` | `boolean` | [`PaginationParams`](#paginationparams).[`includeCursorRecord`](#includecursorrecord-9) |
| `includeStartAtRecord?` | `boolean` | [`PaginationParams`](#paginationparams).[`includeStartAtRecord`](#includestartatrecord-9) |
| `limit?` | `number` | [`PaginationParams`](#paginationparams).[`limit`](#limit-9) |
| `nameSearch?` | `string` | - |
| `page?` | `number` | [`PaginationParams`](#paginationparams).[`page`](#page-9) |
| `paginate?` | `"cursor"` \| `"index"` | [`PaginationParams`](#paginationparams).[`paginate`](#paginate-9) |
| `paginateReverse?` | `boolean` | [`PaginationParams`](#paginationparams).[`paginateReverse`](#paginatereverse-9) |
| `sort?` | `Record`\<`string`, `-1` \| `1`> | [`SortParams`](#sortparams).[`sort`](#sort-12) |
| `startAt?` | `string` | [`PaginationParams`](#paginationparams).[`startAt`](#startat-9) |
***
### GetMentionableFoldersParams [#getmentionablefoldersparams]
#### Extends [#extends-6]
* [`PaginationParams`](#paginationparams).[`SortParams`](#sortparams)
#### Properties [#properties-16]
| Property | Type | Inherited from |
| --------------------------------------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------- |
| `cursor?` | `string` | [`PaginationParams`](#paginationparams).[`cursor`](#cursor-9) |
| `includeCounts?` | `boolean` | [`PaginationParams`](#paginationparams).[`includeCounts`](#includecounts-9) |
| `includeCursorRecord?` | `boolean` | [`PaginationParams`](#paginationparams).[`includeCursorRecord`](#includecursorrecord-9) |
| `includeStartAtRecord?` | `boolean` | [`PaginationParams`](#paginationparams).[`includeStartAtRecord`](#includestartatrecord-9) |
| `limit?` | `number` | [`PaginationParams`](#paginationparams).[`limit`](#limit-9) |
| `nameSearch?` | `string` | - |
| `page?` | `number` | [`PaginationParams`](#paginationparams).[`page`](#page-9) |
| `paginate?` | `"cursor"` \| `"index"` | [`PaginationParams`](#paginationparams).[`paginate`](#paginate-9) |
| `paginateReverse?` | `boolean` | [`PaginationParams`](#paginationparams).[`paginateReverse`](#paginatereverse-9) |
| `sort?` | `Record`\<`string`, `-1` \| `1`> | [`SortParams`](#sortparams).[`sort`](#sort-12) |
| `startAt?` | `string` | [`PaginationParams`](#paginationparams).[`startAt`](#startat-9) |
***
### GetMentionablePublicsParams [#getmentionablepublicsparams]
#### Extends [#extends-7]
* [`PaginationParams`](#paginationparams).[`SortParams`](#sortparams)
#### Properties [#properties-17]
| Property | Type | Inherited from |
| --------------------------------------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------- |
| `cursor?` | `string` | [`PaginationParams`](#paginationparams).[`cursor`](#cursor-9) |
| `includeCounts?` | `boolean` | [`PaginationParams`](#paginationparams).[`includeCounts`](#includecounts-9) |
| `includeCursorRecord?` | `boolean` | [`PaginationParams`](#paginationparams).[`includeCursorRecord`](#includecursorrecord-9) |
| `includeStartAtRecord?` | `boolean` | [`PaginationParams`](#paginationparams).[`includeStartAtRecord`](#includestartatrecord-9) |
| `limit?` | `number` | [`PaginationParams`](#paginationparams).[`limit`](#limit-9) |
| `nameSearch?` | `string` | - |
| `page?` | `number` | [`PaginationParams`](#paginationparams).[`page`](#page-9) |
| `paginate?` | `"cursor"` \| `"index"` | [`PaginationParams`](#paginationparams).[`paginate`](#paginate-9) |
| `paginateReverse?` | `boolean` | [`PaginationParams`](#paginationparams).[`paginateReverse`](#paginatereverse-9) |
| `sort?` | `Record`\<`string`, `-1` \| `1`> | [`SortParams`](#sortparams).[`sort`](#sort-12) |
| `startAt?` | `string` | [`PaginationParams`](#paginationparams).[`startAt`](#startat-9) |
***
### GetMentionableSubmissionsParams [#getmentionablesubmissionsparams]
#### Extends [#extends-8]
* [`PaginationParams`](#paginationparams).[`SortParams`](#sortparams)
#### Properties [#properties-18]
| Property | Type | Inherited from |
| --------------------------------------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------- |
| `cursor?` | `string` | [`PaginationParams`](#paginationparams).[`cursor`](#cursor-9) |
| `includeCounts?` | `boolean` | [`PaginationParams`](#paginationparams).[`includeCounts`](#includecounts-9) |
| `includeCursorRecord?` | `boolean` | [`PaginationParams`](#paginationparams).[`includeCursorRecord`](#includecursorrecord-9) |
| `includeStartAtRecord?` | `boolean` | [`PaginationParams`](#paginationparams).[`includeStartAtRecord`](#includestartatrecord-9) |
| `limit?` | `number` | [`PaginationParams`](#paginationparams).[`limit`](#limit-9) |
| `nameSearch?` | `string` | - |
| `page?` | `number` | [`PaginationParams`](#paginationparams).[`page`](#page-9) |
| `paginate?` | `"cursor"` \| `"index"` | [`PaginationParams`](#paginationparams).[`paginate`](#paginate-9) |
| `paginateReverse?` | `boolean` | [`PaginationParams`](#paginationparams).[`paginateReverse`](#paginatereverse-9) |
| `sort?` | `Record`\<`string`, `-1` \| `1`> | [`SortParams`](#sortparams).[`sort`](#sort-12) |
| `startAt?` | `string` | [`PaginationParams`](#paginationparams).[`startAt`](#startat-9) |
***
### GetMentionableTasksParams [#getmentionabletasksparams]
#### Extends [#extends-9]
* [`PaginationParams`](#paginationparams).[`SortParams`](#sortparams)
#### Properties [#properties-19]
| Property | Type | Inherited from |
| --------------------------------------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------- |
| `cursor?` | `string` | [`PaginationParams`](#paginationparams).[`cursor`](#cursor-9) |
| `includeCounts?` | `boolean` | [`PaginationParams`](#paginationparams).[`includeCounts`](#includecounts-9) |
| `includeCursorRecord?` | `boolean` | [`PaginationParams`](#paginationparams).[`includeCursorRecord`](#includecursorrecord-9) |
| `includeStartAtRecord?` | `boolean` | [`PaginationParams`](#paginationparams).[`includeStartAtRecord`](#includestartatrecord-9) |
| `limit?` | `number` | [`PaginationParams`](#paginationparams).[`limit`](#limit-9) |
| `nameSearch?` | `string` | - |
| `page?` | `number` | [`PaginationParams`](#paginationparams).[`page`](#page-9) |
| `paginate?` | `"cursor"` \| `"index"` | [`PaginationParams`](#paginationparams).[`paginate`](#paginate-9) |
| `paginateReverse?` | `boolean` | [`PaginationParams`](#paginationparams).[`paginateReverse`](#paginatereverse-9) |
| `sort?` | `Record`\<`string`, `-1` \| `1`> | [`SortParams`](#sortparams).[`sort`](#sort-12) |
| `startAt?` | `string` | [`PaginationParams`](#paginationparams).[`startAt`](#startat-9) |
***
### GetMessageParams [#getmessageparams]
#### Extends [#extends-10]
* [`SortParams`](#sortparams)
#### Properties [#properties-20]
| Property | Type | Inherited from |
| ------------------------------- | -------------------------------- | ---------------------------------------------- |
| `replies?` | `number` | - |
| `sort?` | `Record`\<`string`, `-1` \| `1`> | [`SortParams`](#sortparams).[`sort`](#sort-12) |
***
### GetMessagesParams [#getmessagesparams]
#### Extends [#extends-11]
* [`PaginationParams`](#paginationparams).[`SortParams`](#sortparams).[`DateRangeParams`](#daterangeparams)
#### Properties [#properties-21]
| Property | Type | Inherited from |
| --------------------------------------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------- |
| `authorId?` | `string` | - |
| `contentSearch?` | `string` | - |
| `createdAfter?` | `string` \| `number` | [`DateRangeParams`](#daterangeparams).[`createdAfter`](#createdafter) |
| `createdBefore?` | `string` \| `number` | [`DateRangeParams`](#daterangeparams).[`createdBefore`](#createdbefore) |
| `cursor?` | `string` | [`PaginationParams`](#paginationparams).[`cursor`](#cursor-9) |
| `excludeReplies?` | `boolean` | - |
| `hasAnnotations?` | `boolean` | - |
| `hasAttachments?` | `boolean` | - |
| `highlighted?` | `boolean` | - |
| `includeCounts?` | `boolean` | [`PaginationParams`](#paginationparams).[`includeCounts`](#includecounts-9) |
| `includeCursorRecord?` | `boolean` | [`PaginationParams`](#paginationparams).[`includeCursorRecord`](#includecursorrecord-9) |
| `includeStartAtRecord?` | `boolean` | [`PaginationParams`](#paginationparams).[`includeStartAtRecord`](#includestartatrecord-9) |
| `isConvoMessage?` | `boolean` | - |
| `limit?` | `number` | [`PaginationParams`](#paginationparams).[`limit`](#limit-9) |
| `page?` | `number` | [`PaginationParams`](#paginationparams).[`page`](#page-9) |
| `paginate?` | `"cursor"` \| `"index"` | [`PaginationParams`](#paginationparams).[`paginate`](#paginate-9) |
| `paginateReverse?` | `boolean` | [`PaginationParams`](#paginationparams).[`paginateReverse`](#paginatereverse-9) |
| `replies?` | `number` | - |
| `replyLimit?` | `number` | - |
| `replySort?` | `Record`\<`string`, `-1` \| `1`> | - |
| `sort?` | `Record`\<`string`, `-1` \| `1`> | [`SortParams`](#sortparams).[`sort`](#sort-12) |
| `startAt?` | `string` | [`PaginationParams`](#paginationparams).[`startAt`](#startat-9) |
| `type?` | `"user"` \| `"system"` | - |
| `updatedBefore?` | `string` \| `number` | [`DateRangeParams`](#daterangeparams).[`updatedBefore`](#updatedbefore) |
***
### GetRepliesParams [#getrepliesparams]
#### Extends [#extends-12]
* [`PaginationParams`](#paginationparams).[`SortParams`](#sortparams).[`DateRangeParams`](#daterangeparams)
#### Properties [#properties-22]
| Property | Type | Inherited from |
| --------------------------------------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------- |
| `createdAfter?` | `string` \| `number` | [`DateRangeParams`](#daterangeparams).[`createdAfter`](#createdafter) |
| `createdBefore?` | `string` \| `number` | [`DateRangeParams`](#daterangeparams).[`createdBefore`](#createdbefore) |
| `cursor?` | `string` | [`PaginationParams`](#paginationparams).[`cursor`](#cursor-9) |
| `includeCounts?` | `boolean` | [`PaginationParams`](#paginationparams).[`includeCounts`](#includecounts-9) |
| `includeCursorRecord?` | `boolean` | [`PaginationParams`](#paginationparams).[`includeCursorRecord`](#includecursorrecord-9) |
| `includeStartAtRecord?` | `boolean` | [`PaginationParams`](#paginationparams).[`includeStartAtRecord`](#includestartatrecord-9) |
| `limit?` | `number` | [`PaginationParams`](#paginationparams).[`limit`](#limit-9) |
| `page?` | `number` | [`PaginationParams`](#paginationparams).[`page`](#page-9) |
| `paginate?` | `"cursor"` \| `"index"` | [`PaginationParams`](#paginationparams).[`paginate`](#paginate-9) |
| `paginateReverse?` | `boolean` | [`PaginationParams`](#paginationparams).[`paginateReverse`](#paginatereverse-9) |
| `sort?` | `Record`\<`string`, `-1` \| `1`> | [`SortParams`](#sortparams).[`sort`](#sort-12) |
| `startAt?` | `string` | [`PaginationParams`](#paginationparams).[`startAt`](#startat-9) |
| `updatedBefore?` | `string` \| `number` | [`DateRangeParams`](#daterangeparams).[`updatedBefore`](#updatedbefore) |
***
### GetUsersMemberChatsParams [#getusersmemberchatsparams]
#### Extends [#extends-13]
* [`PaginationParams`](#paginationparams).[`SortParams`](#sortparams).[`DateRangeParams`](#daterangeparams)
#### Properties [#properties-23]
| Property | Type | Inherited from |
| --------------------------------------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------- |
| `archived?` | `boolean` | - |
| `createdAfter?` | `string` \| `number` | [`DateRangeParams`](#daterangeparams).[`createdAfter`](#createdafter) |
| `createdBefore?` | `string` \| `number` | [`DateRangeParams`](#daterangeparams).[`createdBefore`](#createdbefore) |
| `cursor?` | `string` | [`PaginationParams`](#paginationparams).[`cursor`](#cursor-9) |
| `includeCounts?` | `boolean` | [`PaginationParams`](#paginationparams).[`includeCounts`](#includecounts-9) |
| `includeCursorRecord?` | `boolean` | [`PaginationParams`](#paginationparams).[`includeCursorRecord`](#includecursorrecord-9) |
| `includeStartAtRecord?` | `boolean` | [`PaginationParams`](#paginationparams).[`includeStartAtRecord`](#includestartatrecord-9) |
| `limit?` | `number` | [`PaginationParams`](#paginationparams).[`limit`](#limit-9) |
| `memberSearch?` | `string` | - |
| `page?` | `number` | [`PaginationParams`](#paginationparams).[`page`](#page-9) |
| `paginate?` | `"cursor"` \| `"index"` | [`PaginationParams`](#paginationparams).[`paginate`](#paginate-9) |
| `paginateReverse?` | `boolean` | [`PaginationParams`](#paginationparams).[`paginateReverse`](#paginatereverse-9) |
| `recentMessages?` | `number` | - |
| `scopeId?` | `string` | - |
| `sort?` | `Record`\<`string`, `-1` \| `1`> | [`SortParams`](#sortparams).[`sort`](#sort-12) |
| `startAt?` | `string` | [`PaginationParams`](#paginationparams).[`startAt`](#startat-9) |
| `subjectSearch?` | `string` | - |
| `updatedBefore?` | `string` \| `number` | [`DateRangeParams`](#daterangeparams).[`updatedBefore`](#updatedbefore) |
***
### GetUsersMentionsParams [#getusersmentionsparams]
#### Extends [#extends-14]
* [`PaginationParams`](#paginationparams).[`SortParams`](#sortparams).[`DateRangeParams`](#daterangeparams)
#### Properties [#properties-24]
| Property | Type | Inherited from |
| --------------------------------------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------- |
| `authorId?` | `string` | - |
| `chatId?` | `string` | - |
| `createdAfter?` | `string` \| `number` | [`DateRangeParams`](#daterangeparams).[`createdAfter`](#createdafter) |
| `createdBefore?` | `string` \| `number` | [`DateRangeParams`](#daterangeparams).[`createdBefore`](#createdbefore) |
| `cursor?` | `string` | [`PaginationParams`](#paginationparams).[`cursor`](#cursor-9) |
| `includeCounts?` | `boolean` | [`PaginationParams`](#paginationparams).[`includeCounts`](#includecounts-9) |
| `includeCursorRecord?` | `boolean` | [`PaginationParams`](#paginationparams).[`includeCursorRecord`](#includecursorrecord-9) |
| `includeStartAtRecord?` | `boolean` | [`PaginationParams`](#paginationparams).[`includeStartAtRecord`](#includestartatrecord-9) |
| `limit?` | `number` | [`PaginationParams`](#paginationparams).[`limit`](#limit-9) |
| `page?` | `number` | [`PaginationParams`](#paginationparams).[`page`](#page-9) |
| `paginate?` | `"cursor"` \| `"index"` | [`PaginationParams`](#paginationparams).[`paginate`](#paginate-9) |
| `paginateReverse?` | `boolean` | [`PaginationParams`](#paginationparams).[`paginateReverse`](#paginatereverse-9) |
| `sort?` | `Record`\<`string`, `-1` \| `1`> | [`SortParams`](#sortparams).[`sort`](#sort-12) |
| `startAt?` | `string` | [`PaginationParams`](#paginationparams).[`startAt`](#startat-9) |
| `updatedBefore?` | `string` \| `number` | [`DateRangeParams`](#daterangeparams).[`updatedBefore`](#updatedbefore) |
***
### LinkPreviewResponse [#linkpreviewresponse]
#### Properties [#properties-25]
| Property | Type |
| ------------------------------ | ---------------- |
| `previews` | `LinkPreview`\[] |
***
### MemberIdList [#memberidlist]
#### Properties [#properties-26]
| Property | Type |
| ---------------------------------- | ----------- |
| `memberIds` | `string`\[] |
***
### MentionablePublic [#mentionablepublic]
Mentionable public collection entry returned by
`getMentionablePublics`. `token` is the URL-safe stable identifier
used in the `publicMention:` message-token payload.
#### Properties [#properties-27]
| Property | Type |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| `chatId` | `string` \| `null` |
| `createdAt` | `string` |
| `creator` | \| \{ `displayName?`: `string`; `firstName?`: `string`; `id`: `string`; `lastName?`: `string`; } \| `null` |
| `description` | `string` \| `null` |
| `expiresAt` | `string` \| `null` |
| `id` | `string` |
| `status` | `string` |
| `title` | `string` |
| `token` | `string` |
***
### MentionableSubmission [#mentionablesubmission]
Mentionable submission entry returned by
`getMentionableSubmissions`. Each submission's `id` doubles as the
`chatId` (the ChatSubmission row IS the submission chat).
#### Properties [#properties-28]
| Property | Type |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `chatId` | `string` |
| `creator` | \| \{ `displayName?`: `string`; `firstName?`: `string`; `id`: `string`; `lastName?`: `string`; } \| `null` |
| `description` | `string` \| `null` |
| `id` | `string` |
| `lastMessageAt` | `string` \| `null` |
| `publishedAt` | `string` |
| `status` | `string` |
| `subject` | `string` |
| `totalMessages` | `number` |
| `version` | `string` \| `null` |
***
### NestedDotAnnotation [#nesteddotannotation]
#### Extends [#extends-15]
* [`BaseAnnotation`](#baseannotation)
#### Properties [#properties-29]
| Property | Type | Inherited from |
| ------------------------------------------------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `angle?` | `number` | [`BaseAnnotation`](#baseannotation).[`angle`](#angle) |
| `color?` | `string` | [`BaseAnnotation`](#baseannotation).[`color`](#color) |
| `coordinates` | [`PercentageCoordinates`](#percentagecoordinates) | - |
| `endTimestamp?` | `number` | [`BaseAnnotation`](#baseannotation).[`endTimestamp`](#endtimestamp) |
| `fillRule?` | `"nonzero"` \| `"evenodd"` | [`BaseAnnotation`](#baseannotation).[`fillRule`](#fillrule) |
| `flipX?` | `boolean` | [`BaseAnnotation`](#baseannotation).[`flipX`](#flipx) |
| `flipY?` | `boolean` | [`BaseAnnotation`](#baseannotation).[`flipY`](#flipy) |
| `frame?` | `number` | [`BaseAnnotation`](#baseannotation).[`frame`](#frame) |
| `height?` | `number` | [`BaseAnnotation`](#baseannotation).[`height`](#height) |
| `left?` | `number` | [`BaseAnnotation`](#baseannotation).[`left`](#left) |
| `opacity?` | `number` | [`BaseAnnotation`](#baseannotation).[`opacity`](#opacity) |
| `originX?` | `"left"` \| `"center"` \| `"right"` | [`BaseAnnotation`](#baseannotation).[`originX`](#originx) |
| `originY?` | `"center"` \| `"top"` \| `"bottom"` | [`BaseAnnotation`](#baseannotation).[`originY`](#originy) |
| `radius?` | `number` | - |
| `scaleX?` | `number` | [`BaseAnnotation`](#baseannotation).[`scaleX`](#scalex) |
| `scaleY?` | `number` | [`BaseAnnotation`](#baseannotation).[`scaleY`](#scaley) |
| `shadow?` | \{ `blur?`: `number`; `color?`: `string`; `offsetX?`: `number`; `offsetY?`: `number`; } | [`BaseAnnotation`](#baseannotation).[`shadow`](#shadow) |
| `shadow.blur?` | `number` | - |
| `shadow.color?` | `string` | - |
| `shadow.offsetX?` | `number` | - |
| `shadow.offsetY?` | `number` | - |
| `skewX?` | `number` | [`BaseAnnotation`](#baseannotation).[`skewX`](#skewx) |
| `skewY?` | `number` | [`BaseAnnotation`](#baseannotation).[`skewY`](#skewy) |
| `startTimestamp?` | `number` | [`BaseAnnotation`](#baseannotation).[`startTimestamp`](#starttimestamp) |
| `strokeDashArray?` | `number`\[] | [`BaseAnnotation`](#baseannotation).[`strokeDashArray`](#strokedasharray) |
| `strokeLineCap?` | `"butt"` \| `"round"` \| `"square"` | [`BaseAnnotation`](#baseannotation).[`strokeLineCap`](#strokelinecap) |
| `strokeLineJoin?` | `"round"` \| `"miter"` \| `"bevel"` | [`BaseAnnotation`](#baseannotation).[`strokeLineJoin`](#strokelinejoin) |
| `strokeMiterLimit?` | `number` | [`BaseAnnotation`](#baseannotation).[`strokeMiterLimit`](#strokemiterlimit) |
| `timestamp?` | `number` | [`BaseAnnotation`](#baseannotation).[`timestamp`](#timestamp) |
| `top?` | `number` | [`BaseAnnotation`](#baseannotation).[`top`](#top) |
| `type` | `"dot"` | - |
| `visible?` | `boolean` | [`BaseAnnotation`](#baseannotation).[`visible`](#visible) |
| `width?` | `number` | [`BaseAnnotation`](#baseannotation).[`width`](#width) |
***
### NestedPathAnnotation [#nestedpathannotation]
#### Extends [#extends-16]
* [`BaseAnnotation`](#baseannotation)
#### Properties [#properties-30]
| Property | Type | Inherited from |
| ------------------------------------------------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `angle?` | `number` | [`BaseAnnotation`](#baseannotation).[`angle`](#angle) |
| `color?` | `string` | [`BaseAnnotation`](#baseannotation).[`color`](#color) |
| `endTimestamp?` | `number` | [`BaseAnnotation`](#baseannotation).[`endTimestamp`](#endtimestamp) |
| `fillRule?` | `"nonzero"` \| `"evenodd"` | [`BaseAnnotation`](#baseannotation).[`fillRule`](#fillrule) |
| `flipX?` | `boolean` | [`BaseAnnotation`](#baseannotation).[`flipX`](#flipx) |
| `flipY?` | `boolean` | [`BaseAnnotation`](#baseannotation).[`flipY`](#flipy) |
| `frame?` | `number` | [`BaseAnnotation`](#baseannotation).[`frame`](#frame) |
| `height?` | `number` | [`BaseAnnotation`](#baseannotation).[`height`](#height) |
| `left?` | `number` | [`BaseAnnotation`](#baseannotation).[`left`](#left) |
| `opacity?` | `number` | [`BaseAnnotation`](#baseannotation).[`opacity`](#opacity) |
| `originX?` | `"left"` \| `"center"` \| `"right"` | [`BaseAnnotation`](#baseannotation).[`originX`](#originx) |
| `originY?` | `"center"` \| `"top"` \| `"bottom"` | [`BaseAnnotation`](#baseannotation).[`originY`](#originy) |
| `pathData` | `string` | - |
| `scaleX?` | `number` | [`BaseAnnotation`](#baseannotation).[`scaleX`](#scalex) |
| `scaleY?` | `number` | [`BaseAnnotation`](#baseannotation).[`scaleY`](#scaley) |
| `shadow?` | \{ `blur?`: `number`; `color?`: `string`; `offsetX?`: `number`; `offsetY?`: `number`; } | [`BaseAnnotation`](#baseannotation).[`shadow`](#shadow) |
| `shadow.blur?` | `number` | - |
| `shadow.color?` | `string` | - |
| `shadow.offsetX?` | `number` | - |
| `shadow.offsetY?` | `number` | - |
| `skewX?` | `number` | [`BaseAnnotation`](#baseannotation).[`skewX`](#skewx) |
| `skewY?` | `number` | [`BaseAnnotation`](#baseannotation).[`skewY`](#skewy) |
| `startTimestamp?` | `number` | [`BaseAnnotation`](#baseannotation).[`startTimestamp`](#starttimestamp) |
| `strokeColor?` | `string` | - |
| `strokeDashArray?` | `number`\[] | [`BaseAnnotation`](#baseannotation).[`strokeDashArray`](#strokedasharray) |
| `strokeLineCap?` | `"butt"` \| `"round"` \| `"square"` | [`BaseAnnotation`](#baseannotation).[`strokeLineCap`](#strokelinecap) |
| `strokeLineJoin?` | `"round"` \| `"miter"` \| `"bevel"` | [`BaseAnnotation`](#baseannotation).[`strokeLineJoin`](#strokelinejoin) |
| `strokeMiterLimit?` | `number` | [`BaseAnnotation`](#baseannotation).[`strokeMiterLimit`](#strokemiterlimit) |
| `strokeWidth?` | `number` | - |
| `timestamp?` | `number` | [`BaseAnnotation`](#baseannotation).[`timestamp`](#timestamp) |
| `top?` | `number` | [`BaseAnnotation`](#baseannotation).[`top`](#top) |
| `type` | `"path"` | - |
| `visible?` | `boolean` | [`BaseAnnotation`](#baseannotation).[`visible`](#visible) |
| `width?` | `number` | [`BaseAnnotation`](#baseannotation).[`width`](#width) |
***
### NestedShapeAnnotation [#nestedshapeannotation]
#### Extends [#extends-17]
* [`BaseAnnotation`](#baseannotation)
#### Properties [#properties-31]
| Property | Type | Inherited from |
| ------------------------------------------------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `angle?` | `number` | [`BaseAnnotation`](#baseannotation).[`angle`](#angle) |
| `color?` | `string` | [`BaseAnnotation`](#baseannotation).[`color`](#color) |
| `coordinates` | [`PercentageCoordinates`](#percentagecoordinates)\[] | - |
| `endTimestamp?` | `number` | [`BaseAnnotation`](#baseannotation).[`endTimestamp`](#endtimestamp) |
| `fillColor?` | `string` | - |
| `fillRule?` | `"nonzero"` \| `"evenodd"` | [`BaseAnnotation`](#baseannotation).[`fillRule`](#fillrule) |
| `flipX?` | `boolean` | [`BaseAnnotation`](#baseannotation).[`flipX`](#flipx) |
| `flipY?` | `boolean` | [`BaseAnnotation`](#baseannotation).[`flipY`](#flipy) |
| `frame?` | `number` | [`BaseAnnotation`](#baseannotation).[`frame`](#frame) |
| `height?` | `number` | [`BaseAnnotation`](#baseannotation).[`height`](#height) |
| `left?` | `number` | [`BaseAnnotation`](#baseannotation).[`left`](#left) |
| `opacity?` | `number` | [`BaseAnnotation`](#baseannotation).[`opacity`](#opacity) |
| `originX?` | `"left"` \| `"center"` \| `"right"` | [`BaseAnnotation`](#baseannotation).[`originX`](#originx) |
| `originY?` | `"center"` \| `"top"` \| `"bottom"` | [`BaseAnnotation`](#baseannotation).[`originY`](#originy) |
| `scaleX?` | `number` | [`BaseAnnotation`](#baseannotation).[`scaleX`](#scalex) |
| `scaleY?` | `number` | [`BaseAnnotation`](#baseannotation).[`scaleY`](#scaley) |
| `shadow?` | \{ `blur?`: `number`; `color?`: `string`; `offsetX?`: `number`; `offsetY?`: `number`; } | [`BaseAnnotation`](#baseannotation).[`shadow`](#shadow) |
| `shadow.blur?` | `number` | - |
| `shadow.color?` | `string` | - |
| `shadow.offsetX?` | `number` | - |
| `shadow.offsetY?` | `number` | - |
| `skewX?` | `number` | [`BaseAnnotation`](#baseannotation).[`skewX`](#skewx) |
| `skewY?` | `number` | [`BaseAnnotation`](#baseannotation).[`skewY`](#skewy) |
| `startTimestamp?` | `number` | [`BaseAnnotation`](#baseannotation).[`startTimestamp`](#starttimestamp) |
| `strokeColor?` | `string` | - |
| `strokeDashArray?` | `number`\[] | [`BaseAnnotation`](#baseannotation).[`strokeDashArray`](#strokedasharray) |
| `strokeLineCap?` | `"butt"` \| `"round"` \| `"square"` | [`BaseAnnotation`](#baseannotation).[`strokeLineCap`](#strokelinecap) |
| `strokeLineJoin?` | `"round"` \| `"miter"` \| `"bevel"` | [`BaseAnnotation`](#baseannotation).[`strokeLineJoin`](#strokelinejoin) |
| `strokeMiterLimit?` | `number` | [`BaseAnnotation`](#baseannotation).[`strokeMiterLimit`](#strokemiterlimit) |
| `strokeWidth?` | `number` | - |
| `timestamp?` | `number` | [`BaseAnnotation`](#baseannotation).[`timestamp`](#timestamp) |
| `top?` | `number` | [`BaseAnnotation`](#baseannotation).[`top`](#top) |
| `type` | `"rectangle"` \| `"circle"` \| `"triangle"` \| `"arrow"` \| `"line"` | - |
| `visible?` | `boolean` | [`BaseAnnotation`](#baseannotation).[`visible`](#visible) |
| `width?` | `number` | [`BaseAnnotation`](#baseannotation).[`width`](#width) |
***
### NestedTextAnnotation [#nestedtextannotation]
#### Extends [#extends-18]
* [`BaseAnnotation`](#baseannotation)
#### Properties [#properties-32]
| Property | Type | Inherited from |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `angle?` | `number` | [`BaseAnnotation`](#baseannotation).[`angle`](#angle) |
| `color?` | `string` | [`BaseAnnotation`](#baseannotation).[`color`](#color) |
| `content` | `string` | - |
| `coordinates` | [`PercentageCoordinates`](#percentagecoordinates) | - |
| `endTimestamp?` | `number` | [`BaseAnnotation`](#baseannotation).[`endTimestamp`](#endtimestamp) |
| `fillRule?` | `"nonzero"` \| `"evenodd"` | [`BaseAnnotation`](#baseannotation).[`fillRule`](#fillrule) |
| `flipX?` | `boolean` | [`BaseAnnotation`](#baseannotation).[`flipX`](#flipx) |
| `flipY?` | `boolean` | [`BaseAnnotation`](#baseannotation).[`flipY`](#flipy) |
| `fontFamily?` | \| `"Arial"` \| `"Helvetica"` \| `"Times New Roman"` \| `"Courier New"` \| `"Georgia"` \| `"Verdana"` | - |
| `fontSize?` | `number` | - |
| `fontStyle?` | `"normal"` \| `"italic"` | - |
| `fontWeight?` | `"normal"` \| `"bold"` | - |
| `frame?` | `number` | [`BaseAnnotation`](#baseannotation).[`frame`](#frame) |
| `height?` | `number` | [`BaseAnnotation`](#baseannotation).[`height`](#height) |
| `left?` | `number` | [`BaseAnnotation`](#baseannotation).[`left`](#left) |
| `opacity?` | `number` | [`BaseAnnotation`](#baseannotation).[`opacity`](#opacity) |
| `originX?` | `"left"` \| `"center"` \| `"right"` | [`BaseAnnotation`](#baseannotation).[`originX`](#originx) |
| `originY?` | `"center"` \| `"top"` \| `"bottom"` | [`BaseAnnotation`](#baseannotation).[`originY`](#originy) |
| `scaleX?` | `number` | [`BaseAnnotation`](#baseannotation).[`scaleX`](#scalex) |
| `scaleY?` | `number` | [`BaseAnnotation`](#baseannotation).[`scaleY`](#scaley) |
| `shadow?` | \{ `blur?`: `number`; `color?`: `string`; `offsetX?`: `number`; `offsetY?`: `number`; } | [`BaseAnnotation`](#baseannotation).[`shadow`](#shadow) |
| `shadow.blur?` | `number` | - |
| `shadow.color?` | `string` | - |
| `shadow.offsetX?` | `number` | - |
| `shadow.offsetY?` | `number` | - |
| `skewX?` | `number` | [`BaseAnnotation`](#baseannotation).[`skewX`](#skewx) |
| `skewY?` | `number` | [`BaseAnnotation`](#baseannotation).[`skewY`](#skewy) |
| `startTimestamp?` | `number` | [`BaseAnnotation`](#baseannotation).[`startTimestamp`](#starttimestamp) |
| `strokeDashArray?` | `number`\[] | [`BaseAnnotation`](#baseannotation).[`strokeDashArray`](#strokedasharray) |
| `strokeLineCap?` | `"butt"` \| `"round"` \| `"square"` | [`BaseAnnotation`](#baseannotation).[`strokeLineCap`](#strokelinecap) |
| `strokeLineJoin?` | `"round"` \| `"miter"` \| `"bevel"` | [`BaseAnnotation`](#baseannotation).[`strokeLineJoin`](#strokelinejoin) |
| `strokeMiterLimit?` | `number` | [`BaseAnnotation`](#baseannotation).[`strokeMiterLimit`](#strokemiterlimit) |
| `textColor?` | `string` | - |
| `timestamp?` | `number` | [`BaseAnnotation`](#baseannotation).[`timestamp`](#timestamp) |
| `top?` | `number` | [`BaseAnnotation`](#baseannotation).[`top`](#top) |
| `type` | `"text"` | - |
| `visible?` | `boolean` | [`BaseAnnotation`](#baseannotation).[`visible`](#visible) |
| `width?` | `number` | [`BaseAnnotation`](#baseannotation).[`width`](#width) |
***
### PaginationParams [#paginationparams]
#### Extended by [#extended-by-3]
* [`GetUsersMemberChatsParams`](#getusersmemberchatsparams)
* [`GetUsersMentionsParams`](#getusersmentionsparams)
* [`GetMessagesParams`](#getmessagesparams)
* [`GetRepliesParams`](#getrepliesparams)
* [`GetMentionableAssetsParams`](#getmentionableassetsparams)
* [`GetMentionableFoldersParams`](#getmentionablefoldersparams)
* [`GetMentionableTasksParams`](#getmentionabletasksparams)
* [`GetMentionableSubmissionsParams`](#getmentionablesubmissionsparams)
* [`GetMentionablePublicsParams`](#getmentionablepublicsparams)
#### Properties [#properties-33]
| Property | Type |
| --------------------------------------------------------- | ----------------------- |
| `cursor?` | `string` |
| `includeCounts?` | `boolean` |
| `includeCursorRecord?` | `boolean` |
| `includeStartAtRecord?` | `boolean` |
| `limit?` | `number` |
| `page?` | `number` |
| `paginate?` | `"cursor"` \| `"index"` |
| `paginateReverse?` | `boolean` |
| `startAt?` | `string` |
***
### PathAnnotation [#pathannotation]
#### Extends [#extends-19]
* [`BaseAnnotation`](#baseannotation)
#### Properties [#properties-34]
| Property | Type | Inherited from |
| --------------------------------------------------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `angle?` | `number` | [`BaseAnnotation`](#baseannotation).[`angle`](#angle) |
| `color?` | `string` | [`BaseAnnotation`](#baseannotation).[`color`](#color) |
| `endTimestamp?` | `number` | [`BaseAnnotation`](#baseannotation).[`endTimestamp`](#endtimestamp) |
| `fillRule?` | `"nonzero"` \| `"evenodd"` | [`BaseAnnotation`](#baseannotation).[`fillRule`](#fillrule) |
| `flipX?` | `boolean` | [`BaseAnnotation`](#baseannotation).[`flipX`](#flipx) |
| `flipY?` | `boolean` | [`BaseAnnotation`](#baseannotation).[`flipY`](#flipy) |
| `frame?` | `number` | [`BaseAnnotation`](#baseannotation).[`frame`](#frame) |
| `height?` | `number` | [`BaseAnnotation`](#baseannotation).[`height`](#height) |
| `left?` | `number` | [`BaseAnnotation`](#baseannotation).[`left`](#left) |
| `nestedAnnotations?` | [`NestedAnnotation`](#nestedannotation)\[] | - |
| `opacity?` | `number` | [`BaseAnnotation`](#baseannotation).[`opacity`](#opacity) |
| `originX?` | `"left"` \| `"center"` \| `"right"` | [`BaseAnnotation`](#baseannotation).[`originX`](#originx) |
| `originY?` | `"center"` \| `"top"` \| `"bottom"` | [`BaseAnnotation`](#baseannotation).[`originY`](#originy) |
| `pathData` | `string` | - |
| `scaleX?` | `number` | [`BaseAnnotation`](#baseannotation).[`scaleX`](#scalex) |
| `scaleY?` | `number` | [`BaseAnnotation`](#baseannotation).[`scaleY`](#scaley) |
| `shadow?` | \{ `blur?`: `number`; `color?`: `string`; `offsetX?`: `number`; `offsetY?`: `number`; } | [`BaseAnnotation`](#baseannotation).[`shadow`](#shadow) |
| `shadow.blur?` | `number` | - |
| `shadow.color?` | `string` | - |
| `shadow.offsetX?` | `number` | - |
| `shadow.offsetY?` | `number` | - |
| `skewX?` | `number` | [`BaseAnnotation`](#baseannotation).[`skewX`](#skewx) |
| `skewY?` | `number` | [`BaseAnnotation`](#baseannotation).[`skewY`](#skewy) |
| `startTimestamp?` | `number` | [`BaseAnnotation`](#baseannotation).[`startTimestamp`](#starttimestamp) |
| `strokeColor?` | `string` | - |
| `strokeDashArray?` | `number`\[] | [`BaseAnnotation`](#baseannotation).[`strokeDashArray`](#strokedasharray) |
| `strokeLineCap?` | `"butt"` \| `"round"` \| `"square"` | [`BaseAnnotation`](#baseannotation).[`strokeLineCap`](#strokelinecap) |
| `strokeLineJoin?` | `"round"` \| `"miter"` \| `"bevel"` | [`BaseAnnotation`](#baseannotation).[`strokeLineJoin`](#strokelinejoin) |
| `strokeMiterLimit?` | `number` | [`BaseAnnotation`](#baseannotation).[`strokeMiterLimit`](#strokemiterlimit) |
| `strokeWidth?` | `number` | - |
| `timestamp?` | `number` | [`BaseAnnotation`](#baseannotation).[`timestamp`](#timestamp) |
| `top?` | `number` | [`BaseAnnotation`](#baseannotation).[`top`](#top) |
| `type` | `"path"` | - |
| `visible?` | `boolean` | [`BaseAnnotation`](#baseannotation).[`visible`](#visible) |
| `width?` | `number` | [`BaseAnnotation`](#baseannotation).[`width`](#width) |
***
### PercentageCoordinates [#percentagecoordinates]
#### Properties [#properties-35]
| Property | Type |
| ---------------- | -------- |
| `x` | `number` |
| `y` | `number` |
***
### ReviseMessageData [#revisemessagedata]
#### Properties [#properties-36]
| Property | Type |
| ----------------------------------------------------- | ------------------------------ |
| `annotations?` | [`Annotation`](#annotation)\[] |
| `assetMentions?` | `string`\[] |
| `content?` | `string` |
| `folderMentions?` | `string`\[] |
| `linkPreviews?` | `LinkPreview`\[] |
| `mentions?` | `string`\[] |
| `publicMentions?` | `string`\[] |
| `quotes?` | `string`\[] |
| `submissionMentions?` | `string`\[] |
| `taskMentions?` | `string`\[] |
***
### ScratchAttachmentRef [#scratchattachmentref]
Scratch-shape attachment ref — points at bytes already uploaded as a
scratch upload. Used by AI Revision (Attach to chat) and the Nurama
Support chat (image attachments). The chat-send endpoint accepts
either this shape OR the upload-shape (`FileAttachmentData`) in the
same `attachments[]` array; the server handles each item according
to its shape.
#### Properties [#properties-37]
| Property | Type |
| -------------------------------- | -------- |
| `name?` | `string` |
| `scratchId` | `string` |
***
### ShapeAnnotation [#shapeannotation]
#### Extends [#extends-20]
* [`BaseAnnotation`](#baseannotation)
#### Properties [#properties-38]
| Property | Type | Inherited from |
| --------------------------------------------------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `angle?` | `number` | [`BaseAnnotation`](#baseannotation).[`angle`](#angle) |
| `color?` | `string` | [`BaseAnnotation`](#baseannotation).[`color`](#color) |
| `coordinates` | [`PercentageCoordinates`](#percentagecoordinates)\[] | - |
| `endTimestamp?` | `number` | [`BaseAnnotation`](#baseannotation).[`endTimestamp`](#endtimestamp) |
| `fillColor?` | `string` | - |
| `fillRule?` | `"nonzero"` \| `"evenodd"` | [`BaseAnnotation`](#baseannotation).[`fillRule`](#fillrule) |
| `flipX?` | `boolean` | [`BaseAnnotation`](#baseannotation).[`flipX`](#flipx) |
| `flipY?` | `boolean` | [`BaseAnnotation`](#baseannotation).[`flipY`](#flipy) |
| `frame?` | `number` | [`BaseAnnotation`](#baseannotation).[`frame`](#frame) |
| `height?` | `number` | [`BaseAnnotation`](#baseannotation).[`height`](#height) |
| `left?` | `number` | [`BaseAnnotation`](#baseannotation).[`left`](#left) |
| `nestedAnnotations?` | [`NestedAnnotation`](#nestedannotation)\[] | - |
| `opacity?` | `number` | [`BaseAnnotation`](#baseannotation).[`opacity`](#opacity) |
| `originX?` | `"left"` \| `"center"` \| `"right"` | [`BaseAnnotation`](#baseannotation).[`originX`](#originx) |
| `originY?` | `"center"` \| `"top"` \| `"bottom"` | [`BaseAnnotation`](#baseannotation).[`originY`](#originy) |
| `scaleX?` | `number` | [`BaseAnnotation`](#baseannotation).[`scaleX`](#scalex) |
| `scaleY?` | `number` | [`BaseAnnotation`](#baseannotation).[`scaleY`](#scaley) |
| `shadow?` | \{ `blur?`: `number`; `color?`: `string`; `offsetX?`: `number`; `offsetY?`: `number`; } | [`BaseAnnotation`](#baseannotation).[`shadow`](#shadow) |
| `shadow.blur?` | `number` | - |
| `shadow.color?` | `string` | - |
| `shadow.offsetX?` | `number` | - |
| `shadow.offsetY?` | `number` | - |
| `skewX?` | `number` | [`BaseAnnotation`](#baseannotation).[`skewX`](#skewx) |
| `skewY?` | `number` | [`BaseAnnotation`](#baseannotation).[`skewY`](#skewy) |
| `startTimestamp?` | `number` | [`BaseAnnotation`](#baseannotation).[`startTimestamp`](#starttimestamp) |
| `strokeColor?` | `string` | - |
| `strokeDashArray?` | `number`\[] | [`BaseAnnotation`](#baseannotation).[`strokeDashArray`](#strokedasharray) |
| `strokeLineCap?` | `"butt"` \| `"round"` \| `"square"` | [`BaseAnnotation`](#baseannotation).[`strokeLineCap`](#strokelinecap) |
| `strokeLineJoin?` | `"round"` \| `"miter"` \| `"bevel"` | [`BaseAnnotation`](#baseannotation).[`strokeLineJoin`](#strokelinejoin) |
| `strokeMiterLimit?` | `number` | [`BaseAnnotation`](#baseannotation).[`strokeMiterLimit`](#strokemiterlimit) |
| `strokeWidth?` | `number` | - |
| `timestamp?` | `number` | [`BaseAnnotation`](#baseannotation).[`timestamp`](#timestamp) |
| `top?` | `number` | [`BaseAnnotation`](#baseannotation).[`top`](#top) |
| `type` | `"rectangle"` \| `"circle"` \| `"triangle"` \| `"arrow"` \| `"line"` | - |
| `visible?` | `boolean` | [`BaseAnnotation`](#baseannotation).[`visible`](#visible) |
| `width?` | `number` | [`BaseAnnotation`](#baseannotation).[`width`](#width) |
***
### SortParams [#sortparams]
#### Extended by [#extended-by-4]
* [`GetUsersMemberChatsParams`](#getusersmemberchatsparams)
* [`GetUsersMentionsParams`](#getusersmentionsparams)
* [`GetChatByTopicIdParams`](#getchatbytopicidparams)
* [`GetMessagesParams`](#getmessagesparams)
* [`CreateAssetChatAndMessageParams`](#createassetchatandmessageparams)
* [`GetMessageParams`](#getmessageparams)
* [`GetRepliesParams`](#getrepliesparams)
* [`GetMentionableAssetsParams`](#getmentionableassetsparams)
* [`GetMentionableFoldersParams`](#getmentionablefoldersparams)
* [`GetMentionableTasksParams`](#getmentionabletasksparams)
* [`GetMentionableSubmissionsParams`](#getmentionablesubmissionsparams)
* [`GetMentionablePublicsParams`](#getmentionablepublicsparams)
#### Properties [#properties-39]
| Property | Type |
| -------------------------- | -------------------------------- |
| `sort?` | `Record`\<`string`, `-1` \| `1`> |
***
### TextAnnotation [#textannotation]
#### Extends [#extends-21]
* [`BaseAnnotation`](#baseannotation)
#### Properties [#properties-40]
| Property | Type | Inherited from |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `angle?` | `number` | [`BaseAnnotation`](#baseannotation).[`angle`](#angle) |
| `color?` | `string` | [`BaseAnnotation`](#baseannotation).[`color`](#color) |
| `content` | `string` | - |
| `coordinates` | [`PercentageCoordinates`](#percentagecoordinates) | - |
| `endTimestamp?` | `number` | [`BaseAnnotation`](#baseannotation).[`endTimestamp`](#endtimestamp) |
| `fillRule?` | `"nonzero"` \| `"evenodd"` | [`BaseAnnotation`](#baseannotation).[`fillRule`](#fillrule) |
| `flipX?` | `boolean` | [`BaseAnnotation`](#baseannotation).[`flipX`](#flipx) |
| `flipY?` | `boolean` | [`BaseAnnotation`](#baseannotation).[`flipY`](#flipy) |
| `fontFamily?` | \| `"Arial"` \| `"Helvetica"` \| `"Times New Roman"` \| `"Courier New"` \| `"Georgia"` \| `"Verdana"` | - |
| `fontSize?` | `number` | - |
| `fontStyle?` | `"normal"` \| `"italic"` | - |
| `fontWeight?` | `"normal"` \| `"bold"` | - |
| `frame?` | `number` | [`BaseAnnotation`](#baseannotation).[`frame`](#frame) |
| `height?` | `number` | [`BaseAnnotation`](#baseannotation).[`height`](#height) |
| `left?` | `number` | [`BaseAnnotation`](#baseannotation).[`left`](#left) |
| `nestedAnnotations?` | [`NestedAnnotation`](#nestedannotation)\[] | - |
| `opacity?` | `number` | [`BaseAnnotation`](#baseannotation).[`opacity`](#opacity) |
| `originX?` | `"left"` \| `"center"` \| `"right"` | [`BaseAnnotation`](#baseannotation).[`originX`](#originx) |
| `originY?` | `"center"` \| `"top"` \| `"bottom"` | [`BaseAnnotation`](#baseannotation).[`originY`](#originy) |
| `scaleX?` | `number` | [`BaseAnnotation`](#baseannotation).[`scaleX`](#scalex) |
| `scaleY?` | `number` | [`BaseAnnotation`](#baseannotation).[`scaleY`](#scaley) |
| `shadow?` | \{ `blur?`: `number`; `color?`: `string`; `offsetX?`: `number`; `offsetY?`: `number`; } | [`BaseAnnotation`](#baseannotation).[`shadow`](#shadow) |
| `shadow.blur?` | `number` | - |
| `shadow.color?` | `string` | - |
| `shadow.offsetX?` | `number` | - |
| `shadow.offsetY?` | `number` | - |
| `skewX?` | `number` | [`BaseAnnotation`](#baseannotation).[`skewX`](#skewx) |
| `skewY?` | `number` | [`BaseAnnotation`](#baseannotation).[`skewY`](#skewy) |
| `startTimestamp?` | `number` | [`BaseAnnotation`](#baseannotation).[`startTimestamp`](#starttimestamp) |
| `strokeDashArray?` | `number`\[] | [`BaseAnnotation`](#baseannotation).[`strokeDashArray`](#strokedasharray) |
| `strokeLineCap?` | `"butt"` \| `"round"` \| `"square"` | [`BaseAnnotation`](#baseannotation).[`strokeLineCap`](#strokelinecap) |
| `strokeLineJoin?` | `"round"` \| `"miter"` \| `"bevel"` | [`BaseAnnotation`](#baseannotation).[`strokeLineJoin`](#strokelinejoin) |
| `strokeMiterLimit?` | `number` | [`BaseAnnotation`](#baseannotation).[`strokeMiterLimit`](#strokemiterlimit) |
| `textColor?` | `string` | - |
| `timestamp?` | `number` | [`BaseAnnotation`](#baseannotation).[`timestamp`](#timestamp) |
| `top?` | `number` | [`BaseAnnotation`](#baseannotation).[`top`](#top) |
| `type` | `"text"` | - |
| `visible?` | `boolean` | [`BaseAnnotation`](#baseannotation).[`visible`](#visible) |
| `width?` | `number` | [`BaseAnnotation`](#baseannotation).[`width`](#width) |
***
### UpdateChatSubjectData [#updatechatsubjectdata]
#### Properties [#properties-41]
| Property | Type |
| ------------------------------ | -------- |
| `subject` | `string` |
***
### UpdateMemberChatData [#updatememberchatdata]
#### Properties [#properties-42]
| Property | Type |
| ------------------------------- | -------- |
| `color?` | `string` |
| `subject?` | `string` |
***
### UpdateMemberChatIconData [#updatememberchaticondata]
#### Properties [#properties-43]
| Property | Type |
| -------------------------------- | -------- |
| `checksum` | `string` |
| `name` | `string` |
| `sizeInMB` | `number` |
## Type Aliases [#type-aliases]
### Annotation [#annotation]
```ts
type Annotation =
| DotAnnotation
| FrameCommentAnnotation
| ShapeAnnotation
| TextAnnotation
| PathAnnotation;
```
***
### AttachmentResponse [#attachmentresponse]
```ts
type AttachmentResponse = AttachmentUploadRecord;
```
***
### ChatMessageResponse [#chatmessageresponse]
```ts
type ChatMessageResponse = ChatMessage;
```
***
### ChatResponse [#chatresponse]
```ts
type ChatResponse = Chat;
```
***
### MemberChatResponse [#memberchatresponse]
```ts
type MemberChatResponse = ChatMember;
```
***
### MemberResponse [#memberresponse]
```ts
type MemberResponse = Membership;
```
***
### NestedAnnotation [#nestedannotation]
```ts
type NestedAnnotation =
| NestedDotAnnotation
| NestedShapeAnnotation
| NestedTextAnnotation
| NestedPathAnnotation;
```
***
### PaginatedResponse [#paginatedresponse]
```ts
type PaginatedResponse = PaginatedResult | CursorPaginatedResult & {
results?: T[];
};
```
#### Type Declaration [#type-declaration]
| Name | Type |
| ---------- | ------ |
| `results?` | `T`\[] |
#### Type Parameters [#type-parameters]
| Type Parameter |
| -------------- |
| `T` |
## Functions [#functions]
### default() [#default]
```ts
function default(client): {
addAttachments: Promise;
addMembers: Promise;
archiveMemberChat: Promise;
createAssetChatAndMessage: Promise;
createMemberChat: Promise;
createMessage: Promise;
createMessageShortLink: Promise<{
code: string;
shortUrl: string;
}>;
createReaction: Promise;
createTopicChat: Promise;
deleteChat: Promise;
deleteMemberChat: Promise;
deleteMessage: Promise;
fetchLinkPreviews: Promise;
followChat: Promise;
getAddableMembers: Promise;
getChat: Promise;
getChatByTopicId: Promise;
getMemberChat: Promise;
getMentionableAssets: Promise>;
getMentionableFolders: Promise>;
getMentionablePublics: Promise>;
getMentionableSubmissions: Promise>;
getMentionableTasks: Promise>;
getMentions: Promise>;
getMessage: Promise;
getMessages: Promise>;
getReplies: Promise>;
getScopeAddableMembers: Promise;
getUsersMemberChats: Promise>;
getWorkspaceProjectChats: Promise;
highlightMessage: Promise;
removeAttachment: Promise;
removeMembers: Promise;
removeReaction: Promise;
reviseMessage: Promise;
unarchiveMemberChat: Promise;
unfollowChat: Promise;
unhighlightMessage: Promise;
updateChatSubject: Promise;
updateMemberChat: Promise;
updateMemberChatIcon: Promise<{
chat: ChatMember;
} & AttachmentUploadRecord>;
};
```
Defines chat-related methods for the NuramaClient.
#### Parameters [#parameters]
| Parameter | Type | Description |
| --------- | ----------------------------------------------------- | -------------------------- |
| `client` | [`default`](/docs/reference/sdk/NuramaClient#default) | The NuramaClient instance. |
#### Returns [#returns]
An object containing the chat-related methods.
| Name | Type | Description |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `addAttachments()` | (`messageId`, `attachments`) => `Promise`\<[`AttachmentUploadRecord`](#attachmentuploadrecord)\[]> | Creates attachment assets for an existing message and returns signed upload URLs for them. Only the message's author may attach, and in topic/submission chats they also need `canCreateAttachment`. Only image and video file names are accepted, each `checksum` must be a 32-64 character hex MD5/SHA-256 digest, `id` must be an integer no greater than 10, and the message may hold at most 6 attachments in total (`exceedsMaxAttachments`). The request is also checked against the workspace storage quota (`uploadRequestExceedsSubscription`). **Throws** 'messageId is required.' when `messageId` is falsy. |
| `addMembers()` | (`chatId`, `data`) => `Promise`\<`ChatMember`> | Adds users to a member chat by user ID. The caller must be a member of the chat, and every user must be chat-eligible in the chat's scope (`membersInvalid` otherwise). `memberIds` is not enforced by validation, but the request cannot succeed without it. **Throws** 'chatId is required.' when `chatId` is falsy. |
| `archiveMemberChat()` | (`chatId`) => `Promise`\<`ChatMember`> | Archives a member chat for the calling user only. Adds the caller to the chat's `archivedBy` list; other members' view of the chat is unaffected. The caller must be a member of the chat. **Throws** 'chatId is required.' when `chatId` is falsy. |
| `createAssetChatAndMessage()` | ( `assetId`, `visibility`, `data`, `params?` ) => `Promise`\<`any`> | Posts a message to an asset's chat at the given visibility, creating the chat first if it does not exist yet (asset chats are normally auto-created, so this mainly covers legacy assets). Only media assets are accepted (`assetInvalidFunctionType` / 404 otherwise). Requires both `canCreate{Creator\|Reviewer}Chat` and `canCreate{Creator\|Reviewer}ChatMessage` on the asset for the chosen visibility. The body follows the same rules as `createMessage`. The `params` argument is neither validated nor forwarded by the API handler, so the returned chat always carries 10 recent messages with 10 replies each, sorted `{ id: -1 }`. **Throws** 'assetId is required.' when `assetId` is falsy. |
| `createMemberChat()` | (`data`) => `Promise`\<`ChatMember`> | Creates a member ("Team") chat in a workspace with the given members. Only `scopeType: 'workspace'` is accepted by the API: project-scoped member chats are deprecated and `social` is not supported yet, so both are rejected with 400 even though the type still allows them. Requires `canCreateWorkspaceMemberChat` on the workspace. The caller is always added as the first member, every member must be chat-eligible in the scope (`membersInvalid` otherwise), and a random approved colour is assigned (the API also accepts an optional `color`, not exposed on this type). |
| `createMessage()` | (`chatId`, `data`) => `Promise`\<`ChatMessage`> | Posts a message to any chat type (topic, member, submission, AI, support). Either `content` (max 10,000 chars) or at least one attachment is required. API tokens need the `chat:write` scope (`tokenScopeMissing` / 403 otherwise); users need message-create permission on the chat, e.g. `canCreateCreatorChatMessage` / `canCreateReviewerChatMessage` for topic chats or membership for member chats. Limits: 6 attachments, 10 of each mention kind, 5 quotes, 5 link previews and 100 annotations. Mentioning users in topic/member/submission chats creates tasks and notifications for them. `pageContext` is only read by AI chats and ignored by every other chat type. **Throws** 'chatId is required.' when `chatId` is falsy. |
| `createMessageShortLink()` | (`messageId`) => `Promise`\<\{ `code`: `string`; `shortUrl`: `string`; }> | Creates a short link for a chat message, or returns the existing one if the message already has a short link. Visibility is inherited from the parent chat (`creator` / `reviewer` for topic chats, `null` for member chats). Requires read access to the message's chat (`canCreateMessageShortLink`). **Throws** 'messageId is required.' when `messageId` is falsy. |
| `createReaction()` | (`messageId`, `data`) => `Promise`\<`ChatMessage`> | Adds the caller's emoji reaction to a message, replacing any reaction they already had on it. Each user holds at most one reaction per message. Requires message-create permission on the chat (`canCreateReaction`). `emoji` must be 1-10 characters. **Throws** 'messageId is required.' when `messageId` is falsy. |
| `createTopicChat()` | (`data`) => `Promise`\<`Chat`> | Creates a topic chat for a project or asset at a given visibility. Requires `canCreateCreatorChat` (visibility `creator`) or `canCreateReviewerChat` (visibility `reviewer`) on the topic resource. Although `visibility` is optional in the type, the permission check only passes when it is one of those two values, so omitting it results in 403. |
| `deleteChat()` | (`chatId`) => `Promise`\<`void`> | Marks a topic chat for deletion. In practice this only succeeds for `user`-topic chats owned by the caller: project and asset topic chats are refused with `topicChatsMayNotBeDeleted`, and any other topic type with `unknownError`. Member chats are deleted with `deleteMemberChat`. **Throws** 'chatId is required.' when `chatId` is falsy. |
| `deleteMemberChat()` | (`chatId`) => `Promise`\<`void`> | Marks a member chat, its messages and its attachments for deletion. Only the chat's creator may delete it; other members receive 403. From the members' perspective the chat disappears immediately; the rows are removed later by the cleanup service. **Throws** 'chatId is required.' when `chatId` is falsy. |
| `deleteMessage()` | (`messageId`) => `Promise`\<`ChatMessage`> | Marks a message for deletion. Only the author may delete, and in topic/submission chats they also need `canDeleteOwnChatMessage`. The row is removed later by the cleanup service. **Throws** 'messageId is required.' when `messageId` is falsy. |
| `fetchLinkPreviews()` | (`data`) => `Promise`\<[`LinkPreviewResponse`](#linkpreviewresponse)> | Fetches Open Graph / meta-tag preview data for one to five URLs. Each preview carries an HMAC-SHA256 `signature` that must be passed back unchanged in `linkPreviews` when creating or revising a message, as the API verifies it to reject spoofed previews. Duplicate URLs are collapsed and URLs that fail validation, fetching or SSRF checks are omitted, so `previews` may be shorter than `urls`. Rate limited to 30 requests per minute per IP. |
| `followChat()` | (`chatId`) => `Promise`\<`void`> | Adds the caller to a chat's following list so they are notified about new messages and updates. Works with topic, member and submission chats and is idempotent. Requires message-create permission on the chat (`canCreateChatMessage`). **Throws** 'chatId is required.' when `chatId` is falsy. |
| `getAddableMembers()` | (`chatId`) => `Promise`\<[`AddableMembersByScope`](#addablemembersbyscope) \| `Membership`\[]> | Lists the members that can be added to an existing member chat, based on the chat's scope and the caller's role in it. The caller must be a member of the chat. For workspace-scoped chats the result is a flat array of memberships; for legacy project-scoped chats it is an `AddableMembersByScope` object. **Throws** 'chatId is required.' when `chatId` is falsy. |
| `getChat()` | (`chatId`) => `Promise`\<`Chat`> | Retrieves a topic chat (project, asset, task or public) by ID without its messages. Requires `canGetCreatorChat` or `canGetReviewerChat` on the chat, matching its visibility. Only topic chats are served here; member chats are served by `getMemberChat` and a member chat ID yields `chatNotFound`. **Throws** 'chatId is required.' when `chatId` is falsy. |
| `getChatByTopicId()` | (`topicId`, `params`) => `Promise`\<`Chat`> | Retrieves the topic chat for a project, asset, public release or task, together with its most recent messages and their replies. Requires `canGetCreatorChat` or `canGetReviewerChat` on the chat, matching `params.visibility`. `replies` (default 10, max 100) and `sort` (default `{ id: -1 }`) are honoured, but `messages` is accepted and then not forwarded by the API handler, so 10 recent messages are always returned. **Throws** 'topicId is required.' when `topicId` is falsy. |
| `getMemberChat()` | (`chatId`) => `Promise`\<`ChatMember`> | Retrieves a member chat by ID without its messages. The caller must be a member of the chat. **Throws** 'chatId is required.' when `chatId` is falsy. |
| `getMentionableAssets()` | (`chatId`, `params?`) => `Promise`\<[`PaginatedResponse`](#paginatedresponse)\<`Asset`>> | Lists the active assets that can be mentioned (`{{assetMention:assetId}}`) in a chat. What is returned depends on the chat: project and asset topic chats return the project's assets at the chat's visibility; project-scoped member chats and submission chats return all of the project's assets; AI chats return the topic project's assets filtered to the caller's own visibility tiers; workspace/social member chats return an empty list. Requires read access to the chat (`canGetChatMentionableAssets`). Defaults to index pagination (`page`, `limit` max 100, sort `{ name: 1 }`); pass `paginate: 'cursor'` for cursor pagination. `startAt` / `includeStartAtRecord` are not accepted here. **Throws** 'chatId is required.' when `chatId` is falsy. |
| `getMentionableFolders()` | (`chatId`, `params?`) => `Promise`\<[`PaginatedResponse`](#paginatedresponse)\<`Folder`>> | Lists the active folders that can be mentioned (`{{folderMention:folderId}}`) in a chat. What is returned depends on the chat: project and asset topic chats return the project's folders at the chat's visibility; project-scoped member chats return all of the project's folders; submission chats return the project's reviewer-visibility folders; AI chats return the topic project's folders filtered to the caller's own visibility tiers; workspace/social member chats return an empty list. Requires read access to the chat (`canGetChatMentionableFolders`). Defaults to index pagination (`page`, `limit` max 100, sort `{ name: 1 }`); pass `paginate: 'cursor'` for cursor pagination. `startAt` / `includeStartAtRecord` are not accepted here. **Throws** 'chatId is required.' when `chatId` is falsy. |
| `getMentionablePublics()` | (`chatId`, `params?`) => `Promise`\<[`PaginatedResponse`](#paginatedresponse)\<[`MentionablePublic`](#mentionablepublic)>> | Lists the active public releases (share links) owned by a chat's project that can be mentioned (`{{publicMention:token}}`). The project is resolved from the chat exactly as for `getMentionableSubmissions`; chats without a project return an empty page. Requires read access to the chat (`canGetChatMentionablePublics`). Index pagination only (`page`, `limit` max 100, sort `{ createdAt: -1 }`, also sortable by `title` and `expires`); cursor-pagination params cause a 400. **Throws** 'chatId is required.' when `chatId` is falsy. |
| `getMentionableSubmissions()` | (`chatId`, `params?`) => `Promise`\<[`PaginatedResponse`](#paginatedresponse)\<[`MentionableSubmission`](#mentionablesubmission)>> | Lists the active submissions in a chat's project that can be mentioned (`{{submissionMention:submissionId}}`). The project is resolved from the chat (project/asset/task topic chats, project-scoped member chats, submission chats and project-scoped AI chats); chats without a project return an empty page. Requires read access to the chat (`canGetChatMentionableSubmissions`). Index pagination only (`page`, `limit` max 100, sort `{ createdAt: -1 }`, also sortable by `subject` and `lastMessageAt`); cursor-pagination params cause a 400. **Throws** 'chatId is required.' when `chatId` is falsy. |
| `getMentionableTasks()` | (`chatId`, `params?`) => `Promise`\<[`PaginatedResponse`](#paginatedresponse)\<`any`>> | Lists the board tasks that can be mentioned (`{{taskMention:taskId}}`) in a chat. Requires the workspace to have the `boards` capability (`capabilityNotAvailable` / 403 otherwise) and read access to the chat (`canGetChatMentionableTasks`). Project, asset and task topic chats return tasks in the project on boards whose visibility includes the chat's; project-scoped member chats return every board task in the project; submission chats return tasks on reviewer-visible boards; workspace/social member chats return an empty list. Legacy tasks without a board are never returned. Defaults to index pagination (`page`, `limit` max 100, sort `{ updatedAt: -1 }`); pass `paginate: 'cursor'` for cursor pagination. **Throws** 'chatId is required.' when `chatId` is falsy. |
| `getMentions()` | (`params?`) => `Promise`\<[`PaginatedResponse`](#paginatedresponse)\<`ChatMessage`>> | Lists the messages in which the caller was mentioned. Defaults to index pagination (`page`, `limit` max 100, sort `{ id: -1 }`); pass `paginate: 'cursor'` for cursor pagination. Filter with `chatId` and/or `authorId`. `createdBefore` is only accepted with index pagination; `createdAfter` and `updatedBefore` from DateRangeParams are not accepted by this endpoint and cause a 400. |
| `getMessage()` | (`messageId`, `params?`) => `Promise`\<`ChatMessage`> | Retrieves a single message by ID with its most recent replies. Requires read access to the message's chat (`canGetChatMessage`). `replies` defaults to 10 (max 100) and `sort` (default `{ id: -1 }`) orders the included replies. **Throws** 'messageId is required.' when `messageId` is falsy. |
| `getMessages()` | (`chatId`, `params?`) => `Promise`\<[`PaginatedResponse`](#paginatedresponse)\<`ChatMessage`>> | Lists a chat's active messages with their recent replies and populated attachments and mentions. Requires read access to the chat (`canGetChat`); API tokens need the `chat:read` scope (`tokenScopeMissing` / 403 otherwise). Defaults to index pagination (`page`, `limit` max 100, sort `{ id: -1 }`); pass `paginate: 'cursor'` for cursor pagination. `createdBefore` / `createdAfter` are only accepted with index pagination and `updatedBefore` is not accepted at all. `replyLimit` (default 10, max 100) sets the replies returned per message; `replies` is a deprecated alias that takes precedence over `replyLimit` whenever it is set to anything other than 10. **Throws** 'chatId is required.' when `chatId` is falsy. |
| `getReplies()` | (`messageId`, `params?`) => `Promise`\<[`PaginatedResponse`](#paginatedresponse)\<`ChatMessage`>> | Lists the active replies to a message, with attachments populated. Requires read access to the message's chat (`canGetChatMessage`). Defaults to index pagination (`page`, `limit` max 100, sort `{ id: -1 }`); pass `paginate: 'cursor'` for cursor pagination. `createdBefore` / `createdAfter` are only accepted with index pagination and `updatedBefore` is not accepted at all. **Throws** 'messageId is required.' when `messageId` is falsy. |
| `getScopeAddableMembers()` | (`scopeType`, `scopeId`) => `Promise`\<[`AddableMembersByScope`](#addablemembersbyscope) \| `Membership`\[]> | Lists the members addable to a NEW member chat, by scope, before the chat exists. Use this to populate the create-chat member picker — unlike the raw membership-list endpoints it isn't admin-gated, so non-admin members allowed to start a Team Chat still get the correct list. Requires `canCreateWorkspaceMemberChat` (or `canCreateProjectMemberChat`) on the scope. For `project` scope the result is an `AddableMembersByScope` object; note that project-scoped member chats can no longer be created. **Throws** 'scopeType is required.' or 'scopeId is required.' when either is falsy. |
| `getUsersMemberChats()` | (`params?`) => `Promise`\<[`PaginatedResponse`](#paginatedresponse)\<`ChatMember`>> | Lists the member chats the caller belongs to, most recently updated first, each with its recent messages. Defaults to index pagination (`page`, `limit` max 20); pass `paginate: 'cursor'` for cursor pagination. `updatedBefore` is only accepted with index pagination, `recentMessages` caps the messages returned per chat (default and max 20), and `archived` narrows to chats the caller has (`true`) or has not (`false`) archived. `createdBefore` / `createdAfter` from DateRangeParams are not accepted by this endpoint and cause a 400. |
| `getWorkspaceProjectChats()` | (`workspaceId`) => `Promise`\<`any`\[]> | Retrieves every project topic chat (creator/reviewer) the caller can access across all projects in a workspace, with the latest message and message count for each, ordered by most recent activity. Powers the workspace-level "Project Chat" list. Requires `canGetWorkspace` on the workspace; access to each project's chats is derived from the caller's inherited `canGetCreatorChat` / `canGetReviewerChat`. **Throws** 'workspaceId is required.' when `workspaceId` is falsy. |
| `highlightMessage()` | (`messageId`) => `Promise`\<`ChatMessage`> | Highlights a message, recording the caller as the highlighter. In topic and submission chats this requires `canHighlightMessage` on the chat; in member chats any member may highlight. For project and asset topic chats a system message is posted in the project chat of the same visibility, a `chatHighlightMessage` notification is sent and project members are emailed. **Throws** 'messageId is required.' when `messageId` is falsy. |
| `removeAttachment()` | (`messageId`, `assetId`) => `Promise`\<`ChatMessage`> | Removes an attachment from a message and marks the asset for deletion. Only the author may remove attachments, and in topic/submission chats they also need `canDeleteOwnAttachment`. If the message is left with no content and no attachments it is marked for deletion as well, and the deleted message is returned. **Throws** 'messageId is required.' or 'assetId is required.' when either is falsy. |
| `removeMembers()` | (`chatId`, `data`) => `Promise`\<`ChatMember`> | Removes users from a member chat by user ID. The caller must be a member of the chat. The chat's creator cannot be removed (`ownerCannotLeaveChat`) and unknown user IDs produce `userNotFound`. Sent as a DELETE with a JSON body. **Throws** 'chatId is required.' when `chatId` is falsy. |
| `removeReaction()` | (`messageId`) => `Promise`\<`ChatMessage`> | Removes the caller's own reaction from a message. Gated by the same permission as `createReaction`. Calling it when the caller has no reaction is a no-op that still returns the message. **Throws** 'messageId is required.' when `messageId` is falsy. |
| `reviseMessage()` | (`messageId`, `data`) => `Promise`\<`ChatMessage`> | Revises a message's content, mentions, quotes, annotations and link previews, keeping the previous version as a revision. Only the author may revise, and in topic/submission chats they also need `canUpdateOwnChatMessage`. Annotations are replaced, not merged: omit `annotations` to keep the current ones, send `[]` to remove them all. `linkPreviews` likewise replaces the stored previews. Same size limits as `createMessage`. **Throws** 'messageId is required.' when `messageId` is falsy. |
| `unarchiveMemberChat()` | (`chatId`) => `Promise`\<`ChatMember`> | Unarchives a member chat for the calling user only. Removes the caller from the chat's `archivedBy` list. The caller must be a member of the chat. **Throws** 'chatId is required.' when `chatId` is falsy. |
| `unfollowChat()` | (`chatId`) => `Promise`\<`void`> | Removes the caller from a chat's following list. Works with topic, member and submission chats and is idempotent. No chat permission is checked, so users can stop notifications for a chat they have since lost access to. **Throws** 'chatId is required.' when `chatId` is falsy. |
| `unhighlightMessage()` | (`messageId`) => `Promise`\<`ChatMessage`> | Removes the highlight from a message. Clears the highlighter fields and removes the associated system messages and notification. Same permission as `highlightMessage`. **Throws** 'messageId is required.' when `messageId` is falsy. |
| `updateChatSubject()` | (`chatId`, `data`) => `Promise`\<`Chat`> | Updates the subject of a topic chat. Requires `canUpdateCreatorChat` or `canUpdateReviewerChat` on the chat, matching its visibility. `subject` is limited to 100 characters. For member chats use `updateMemberChat`. **Throws** 'chatId is required.' when `chatId` is falsy. |
| `updateMemberChat()` | (`chatId`, `data`) => `Promise`\<`ChatMember`> | Updates a member chat's subject and/or colour. The caller must be a member of the chat. `subject` is limited to 100 characters and `color` must be one of the approved palette colours. **Throws** 'chatId is required.' when `chatId` is falsy. |
| `updateMemberChatIcon()` | (`chatId`, `data`) => `Promise`\<\{ `chat`: `ChatMember`; } & [`AttachmentUploadRecord`](#attachmentuploadrecord)> | Creates an icon asset for a member chat and returns signed upload URLs for it. Any existing icon is marked for deletion. The caller must be a member of the chat; `sizeInMB` is capped at 10 and `name` at 100 characters. Upload the file to the returned `signedUrlData.urls` afterwards, exactly as for any asset upload. **Throws** 'chatId is required.' when `chatId` is falsy. |
# chatAi (/docs/reference/sdk/routes/chatAi)
{/* Generated by scripts/generate.mjs from content/generated. Do not edit. */}
## Functions [#functions]
### default() [#default]
```ts
function default(client): {
createTopic: Promise;
deleteTopic: Promise