# Authentication
Source: https://docs.sublay.io/v7/authentication

How Sublay handles user identity — built-in auth, external JWT integration, and OAuth.

Sublay supports three authentication models. You choose the one that fits how your application manages users, and they can coexist within the same project.

<CardGroup>
  <Card title="Built-in Auth" icon="lock">
    Sublay manages the full user lifecycle: sign-up, sign-in, and password reset using email and password. No external auth system needed.
  </Card>

  <Card title="OAuth" icon="key">
    Sign in with Google, GitHub, Apple, or Facebook. Supports linking multiple providers to one account.
  </Card>

  <Card title="External Auth" icon="server">
    Your backend signs a JWT. Sublay verifies it and creates or matches a user automatically. Keep your existing auth stack.
  </Card>
</CardGroup>

***

## Token Model

All three auth modes produce the same token pair: an **access token** and a **refresh token**.

| Token         | Lifetime   | Purpose                                                           |
| ------------- | ---------- | ----------------------------------------------------------------- |
| Access token  | 30 minutes | Sent with every API request in the `Authorization: Bearer` header |
| Refresh token | 30 days    | Used to obtain a new access token when the current one expires    |

**Refresh token rotation** is enforced. Every time a refresh token is used, it is revoked and a new one is issued in its place. If the same refresh token is used twice (token reuse detected), the entire token family is revoked, signing out all sessions that shared it.

<Note>
  A 30-second grace period allows two requests that race to refresh the same token (e.g., two browser tabs loading simultaneously) to both succeed. The first request rotates the token; a second request arriving within that window receives the successor token instead of a reuse error.
</Note>

The React/React Native SDK handles token storage and refresh automatically. When using the API directly, your code must exchange the refresh token for a new access token before each expiry.

***

## Built-in Auth

Sublay provides a complete email/password authentication system out of the box. Use it when you do not have an existing user identity system and want Sublay to manage everything.

**What it includes:**

* User sign-up with email and password
* Sign-in returning an access token + refresh token + user object
* Sign-out (revokes the refresh token)
* Password change (requires current password)
* Password reset via email link (requires an email provider configured in the dashboard)

Users created through built-in auth can link OAuth providers to their account later — see the OAuth section below.

See [SDK Reference → Authentication → Built-in](/sdk/authentication/built-in) for implementation guidance, or [API Reference → Auth](/api-reference/auth/sign-up) for the raw endpoint reference.

***

## External Auth

Use this model when your application already has its own user management system (Supabase Auth, Auth0, Firebase Auth, NextAuth, a custom system, or anything else) and you want Sublay to associate its data with those users — without rebuilding auth.

### How It Works

<Steps>
  <Step title="Generate a JWT key pair in the dashboard">
    Sublay generates an RSA key pair (RS256) for your project. The **public key** is stored in Sublay. The **private key** is shown to you once — store it securely as a server-side environment variable. If it is lost or compromised, generate a new key pair from the dashboard.
  </Step>

  <Step title="Sign a JWT on your server when a user logs in">
    When your application detects a logged-in user, make a request to your own backend. Your backend signs a JWT with your private key and returns it to the client.

    The JWT payload must include:

    | Claim      | Value                                       |
    | ---------- | ------------------------------------------- |
    | `sub`      | Your external user ID (string)              |
    | `iss`      | Your Sublay project ID                      |
    | `userData` | Object with user profile fields (see below) |

    The `userData` object can include:

    | Field            | Type     | Notes                                            |
    | ---------------- | -------- | ------------------------------------------------ |
    | `email`          | `string` | Optional but recommended                         |
    | `name`           | `string` | Display name                                     |
    | `username`       | `string` | Unique per project                               |
    | `avatar`         | `string` | URL of the user's profile picture                |
    | `bio`            | `string` | Short bio                                        |
    | `location`       | `string` | User's location                                  |
    | `birthdate`      | `string` | ISO 8601 date                                    |
    | `metadata`       | `object` | Public custom data                               |
    | `secureMetadata` | `object` | Private custom data (not exposed to other users) |

    The signed JWT is safe to pass to the client — it cannot be tampered with because the signature covers the payload using your private key.
  </Step>

  <Step title="Pass the JWT to Sublay">
    Pass the signed JWT to `SublayProvider` via the `signedToken` prop (SDK), or call the verify external user API endpoint directly.

    Sublay verifies the JWT against the project's stored public key. If valid, it looks up the user by the `sub` claim. If the user does not exist, it is created from the `userData` fields. If the user already exists, their profile fields are updated if anything has changed.

    On success, Sublay returns its own access token + refresh token pair tied to this user.
  </Step>
</Steps>

### Profile Sync

Every time a valid external JWT is presented, Sublay compares the `userData` fields against the stored user record and updates any fields that have changed. Your user profiles in Sublay stay in sync with your external system automatically — no separate update call needed.

### Security

The private key must never leave your server. Signing happens server-side; the client only receives the finished JWT. Because Sublay verifies using your public key, a client cannot forge or modify user data.

See [SDK Reference → Authentication → External](/sdk/authentication/external) for implementation guidance.

***

## OAuth

OAuth allows users to sign in using a third-party provider. Sublay handles the full flow: PKCE generation, state management, callback processing, and user creation or linking.

**Supported providers:** Google, GitHub, Apple, Facebook

### Setup

Each provider must be configured in the project dashboard with:

* The provider's client ID and client secret
* A list of allowed redirect URIs (the URLs Sublay may redirect back to after authentication)

### Flow Overview

<Steps>
  <Step title="Request an authorization URL">
    Call the authorize endpoint with the provider name and the `redirectAfterAuth` URL. Sublay creates a short-lived state record (10-minute TTL) and returns an authorization URL pointing to the provider. For Google, a PKCE code verifier and challenge are generated automatically.
  </Step>

  <Step title="Redirect the user to the provider">
    Redirect the user to the authorization URL. They authenticate with the provider and are sent back to Sublay's callback endpoint.
  </Step>

  <Step title="Sublay processes the callback">
    Sublay exchanges the authorization code for the provider's tokens, fetches the user profile, and resolves which Sublay user to return using this priority:

    1. **Existing identity** — if this provider account has signed in before, the matching user is returned immediately.
    2. **Verified email match** — if the provider supplies a verified email that matches an existing user, the new identity is linked to that account automatically.
    3. **New user** — if no match is found, a new user is created from the provider profile (name, email, avatar).

    Sublay then redirects to the `redirectAfterAuth` URL with Sublay tokens appended as query parameters.
  </Step>

  <Step title="Complete sign-in in your app">
    Your app reads the tokens from the redirect URL, stores them, and the user is signed in.
  </Step>
</Steps>

### Account Linking

A user can link multiple OAuth providers (and a password account) to a single Sublay user record. To link an additional provider, the user must be signed in, and the OAuth flow is initiated via the link endpoint rather than the authorize endpoint. The new identity is attached to the existing account.

This enables scenarios like "sign in with Google on a laptop and GitHub on another device" — both map to the same user.

See [SDK Reference → Authentication → OAuth](/sdk/authentication/oauth) for the full integration guide.

***

## Multi-Account Support

The SDK supports multiple simultaneously signed-in accounts in a single app instance. This is separate from account linking — it means multiple distinct user sessions can be held at once, with the ability to switch between them.

Use cases: apps where a person manages multiple accounts, shared devices, or testing flows.

See [SDK Reference → Authentication → Multi-Account](/sdk/authentication/multi-account) for the full guide.

***

## Authorization

Beyond authentication, Sublay enforces authorization on every request:

* Most write operations require an authenticated user (or a service API key)
* Ownership checks are enforced server-side — a user cannot modify another user's content through the normal API
* Space roles (owner, admin, moderator, member) control what is permitted within a space
* Service API keys bypass user-level authorization and are intended for server-side use only — see [Integration Options](/integration-options#service-api-key-recommended-for-server-to-server)


# Bundles
Source: https://docs.sublay.io/v7/bundles

Sublay features are modular. Each project is assembled from bundles — groups of features you install per project and can add or remove at any time.

Sublay is not one monolithic feature set. It's a collection of **bundles** — self-contained feature modules you turn on per project. A bundle groups everything a feature needs (its database tables and the endpoints and SDK hooks that operate on them), so your project only carries the features you actually use.

Every project gets its own isolated database schema. Installing a bundle provisions that bundle's tables into your project's schema and switches the feature on. Removing a bundle takes it back out.

<Note>
  Bundles are about **provisioning**, not pricing. Installing a bundle makes the feature available in your project; what each plan allows (quotas, AI access, etc.) is a separate concern. See [Semantic Search & AI](/semantic-search-ai) for an example of a feature that needs both its bundle *and* a paid plan.
</Note>

## The core bundle

Every project always has the **`core`** bundle. It's installed automatically when the project is created and cannot be removed. Core provides the foundation that every other feature builds on:

* **Users, authentication & identity** — email/password accounts, OAuth identities, and OAuth provider configuration. See [Authentication](/authentication).

Because OAuth identity lives in core, [OAuth sign-in](/sdk/authentication/oauth) works on every project without installing anything extra.

## Available bundles

On top of core, you choose which of these to install. Most are independent — install only what you need — but a few depend on another bundle (see below).

| Bundle          | Feature                                                                                 | What it adds                                                                                                                                                      |
| --------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entities`      | [Entities](/sdk/entities/overview)                                                      | The base content unit — posts, articles, listings, anything your users create — with views, drafts, and publishing                                                |
| `comments`      | [Comments](/sdk/comments/overview)                                                      | Threaded comments on entities                                                                                                                                     |
| `reactions`     | [Reactions](/sdk/reactions/overview)                                                    | Emoji reactions on entities and comments                                                                                                                          |
| `files-images`  | [Storage](/sdk/storage/overview)                                                        | File and image uploads, including user avatars and banners                                                                                                        |
| `follows`       | [Follows](/sdk/relationships/overview)                                                  | Unidirectional follow relationships                                                                                                                               |
| `connections`   | [Connections](/sdk/relationships/overview)                                              | Bidirectional connection (friend-style) requests                                                                                                                  |
| `spaces`        | [Spaces](/sdk/spaces/overview)                                                          | Hierarchical community spaces, membership, roles, and rules                                                                                                       |
| `workspaces`    | [Workspaces](/sdk/workspaces/overview)                                                  | Self-nesting SaaS/team workspaces with invitations and per-member authority                                                                                       |
| `chat`          | [Chat](/sdk/chat/overview)                                                              | Real-time 1:1 and group conversations with message reactions                                                                                                      |
| `collections`   | [Collections](/sdk/collections/overview)                                                | User-owned bookmarking and folders for saving entities                                                                                                            |
| `moderation`    | [Moderation](/sdk/moderation/overview)                                                  | Reports, report resolution, and user suspensions                                                                                                                  |
| `notifications` | [App Notifications](/sdk/app-notifications/overview)                                    | In-app notification system                                                                                                                                        |
| `push`          | [Push Notifications](/push-notifications)                                               | Native OS push delivery to iOS, Android, and Web                                                                                                                  |
| `ai-search`     | [Semantic Search & AI](/sdk/search/overview)                                            | Content embeddings, semantic search, and the AI ask endpoint                                                                                                      |
| `reputation`    | [Reputation](/data-models/reputation), [ReputationGrant](/data-models/reputation-grant) | Per-space reputation buckets with a maintained overall total on each user, plus reputation grants — reputation deliberately given by a user or minted by your app |

### Bundle dependencies

A couple of bundles build directly on another and can't be installed on their own:

* **`comments` and `collections` require `entities`.** Comments attach to an entity and collections save entities, so both need the `entities` bundle installed first. The dashboard pre-checks `entities` for you when you select either; installing them via the API without `entities` returns `409 database/bundle-prerequisite-missing`. For the same reason, `entities` can't be removed while `comments` or `collections` are still installed — remove those first.
* **`interest-matching` requires `ai-search`.** Interest matching builds on the content embeddings that `ai-search` provides, so `ai-search` must be installed first and can't be removed while `interest-matching` is present.

## Choosing bundles when you create a project

When you create a project in the [dashboard](https://dash.sublay.io), you pick the bundles you want. `core` is always included — you can't deselect it — and you can start with **core only** and add the rest later. Nothing is locked in at creation time.

## Adding and removing bundles later

Installed bundles are managed from the **Database** page of your project in the dashboard (`https://dash.sublay.io/<projectId>/database`). From there you can install a bundle you skipped, or remove one you no longer need.

Installing a bundle is an asynchronous operation — the dashboard shows it as **provisioning** while the tables are created, then **installed** once it's ready. This usually takes a moment.

<Warning>
  **Removing a bundle is destructive.** Uninstalling drops the bundle's tables and the data in them, and clears references to that data from other bundles. For example, removing the `spaces` bundle deletes all spaces and clears the `spaceId` on any entities, comments, or conversations that pointed at a space. There is no undo — back up anything you need first.

  Uninstalling the `reputation` bundle is doubly lossy: it drops the reputation buckets table and the grants table — destroying all grant history — **and** zeroes the `reputation` column on every user. Reinstalling starts fresh from zero — past scores are not recomputed. See [Reputation](/data-models/reputation).
</Warning>

## What happens if a bundle isn't installed

Feature endpoints and SDK hooks only work when their bundle is installed. If your app calls a feature whose bundle is missing, the API responds with a clear error instead of a generic failure:

| Situation                   | Response                                | Meaning                                                                                                                                           |
| --------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Bundle not installed        | `403` · `database/tables-not-available` | The feature isn't enabled for this project. The response includes a `dashboardUrl` pointing at the project's Database page so you can install it. |
| Bundle currently installing | `503` · `database/tables-provisioning`  | The bundle is mid-install. This is transient — retry shortly.                                                                                     |

If you hit one of these while building, the fix is almost always to install the bundle for the feature you're using. Open the **Database** page in the dashboard and add it.

<Note>
  This is why a feature can be fully documented and supported but still return `database/tables-not-available` on your project — the docs describe the whole platform, while your project only runs the bundles you've installed.
</Note>


# Claude Code Plugin
Source: https://docs.sublay.io/v7/claude-code

Install the Sublay plugin for Claude Code to give your coding agent an accurate, built-in map of the Sublay platform.

Sublay ships an official **Claude Code plugin** that installs a skill teaching your coding agent what the platform can do — every model, bundle, and capability — so it builds on what already exists instead of reinventing it or inventing what isn't there.

<Note>
  This is complementary to the [MCP Server](/mcp-server). The **plugin** gives the agent a curated map of the platform that it reaches for automatically; the **MCP server** lets it pull exact field- and endpoint-level detail from the docs on demand. Installing the plugin also wires up the docs MCP for you.
</Note>

## Install

In Claude Code, add the marketplace and install the plugin:

```bash theme={null}
/plugin marketplace add sublay-io/claude-skills
/plugin install sublay@sublay-io
```

The first command registers Sublay's plugin marketplace; the second installs the `sublay` plugin from it.

## What you get

<CardGroup>
  <Card title="implementation-expert skill" icon="map">
    A complete, domain-organized map of Sublay — the mental model (project scoping, bundles, the Provider + Hook SDK pattern), every bundle, and each model and capability (entities, spaces, chat, custom tables, storage, semantic search & AI, and more). The agent consults it automatically when you work on anything Sublay-related, so it picks the right SDK hook, REST route, or dashboard surface.
  </Card>

  <Card title="Docs MCP, auto-connected" icon="brain-circuit">
    The plugin bundles the public [docs MCP](/mcp-server) (`https://docs.sublay.io/mcp`, no auth), so when the agent needs exact hook signatures, params, or endpoint shapes, it can search the live docs without any extra setup.
  </Card>
</CardGroup>

## How it behaves

The skill is a **first point of contact, not a full spec**. It holds the shape of the platform — what exists and why — and defers precise, field-level detail to the docs (via the MCP or [docs.sublay.io](https://docs.sublay.io)). That keeps the agent from guessing at APIs while staying lightweight.

You don't need to invoke it manually — Claude Code loads it when your request involves Sublay. You can also call it explicitly with `/sublay:implementation-expert`.

## Updating

When Sublay ships new skills or updates, run:

```bash theme={null}
/plugin marketplace update sublay-io
```

then reinstall or update the plugin to pick up the latest version.


# Custom Tables
Source: https://docs.sublay.io/v7/custom-tables

Provision your own database tables for the remaining 20% of your data model — with SDK row access, table management, and a full dashboard data editor

Sublay ships pre-modeled tables for the features you'd otherwise have to build — users, entities, comments, spaces, reactions, and more. **Custom tables** cover the rest: the app-specific data that doesn't fit any built-in model. You define the table, Sublay provisions it inside your project's isolated schema, and you read and write its rows from the SDKs or the dashboard.

<Note>
  Custom tables live in the same per-project schema as your built-in data, so
  they share your project's isolation and connection. They are addressed through
  a dedicated `/db` surface that **only ever touches custom tables** — built-in
  and bundle tables are never reachable through it.
</Note>

## The `custom_` invisibility model

Every custom table is stored with a `custom_` prefix on its physical name, but you never type that prefix. You work with **logical** names everywhere:

* You create a table called `Events` → Sublay stores it physically as `custom_Events`.
* You read and write rows by calling `client.table("Events")` → Sublay resolves it to `custom_Events`.
* The dashboard displays it as `Events`.

The prefix is what guarantees the `/db` surface can never reach a built-in table. A request for a built-in name like `Comments` resolves to `custom_Comments`, which doesn't exist, so it `404`s — the built-in `Comments` table stays unreachable.

<Warning>
  The prefix is applied **exactly once, unconditionally** — it is never skipped
  if your name already starts with `custom_`. If you name a logical table
  `custom_x`, it is physically stored as `custom_custom_x` and you continue to
  address it as `custom_x`. There is no double-prefix surprise and no name
  collision with the prefix mechanism.
</Warning>

## Managed columns

Every custom table is created with a set of **server-managed columns** that you never write to directly:

| Column      | Type          | When present            | Purpose                                        |
| ----------- | ------------- | ----------------------- | ---------------------------------------------- |
| `id`        | `uuid`        | Always                  | Primary key, defaulted to `gen_random_uuid()`. |
| `createdAt` | `timestamptz` | When `timestamps: true` | Set on insert.                                 |
| `updatedAt` | `timestamptz` | When `timestamps: true` | Bumped automatically on every update.          |
| `deletedAt` | `timestamptz` | When `paranoid: true`   | Soft-delete marker. `null` for live rows.      |

These columns are reserved at create time and at add-column time — you cannot define a column with any of these names. They are rejected from insert/update bodies (a write that includes `id`, `createdAt`, `updatedAt`, or `deletedAt` is refused). `deletedAt` is **read-visible** — you can filter and sort by it and surface it with `includeDeleted` — but never writable.

### Timestamps and soft-delete

Two flags, set when you create the table, control the managed columns:

* **`timestamps`** (default `true`) — emits `createdAt` / `updatedAt`. With timestamps on, the default sort for reads is `createdAt desc`; with timestamps off, the default sort is `id`.
* **`paranoid`** (default `false`, **requires `timestamps`**) — emits `deletedAt` and turns deletes into **soft deletes**. A delete sets `deletedAt` instead of removing the row; soft-deleted rows are excluded from reads by default and resurface only with `includeDeleted`. A [`restore`](/v7/node-sdk/tables#restore) clears `deletedAt`. Pass `force: true` to a delete to hard-delete a paranoid row.

A non-paranoid table has no `deletedAt` column, so every delete is a hard delete.

## Column types

A custom column is one of nine logical types:

| Logical type | Physical SQL type  | Notes                       |
| ------------ | ------------------ | --------------------------- |
| `text`       | `TEXT`             |                             |
| `integer`    | `BIGINT`           | 64-bit integer.             |
| `float`      | `DOUBLE PRECISION` |                             |
| `decimal`    | `NUMERIC`          | Arbitrary-precision number. |
| `boolean`    | `BOOLEAN`          |                             |
| `date`       | `DATE`             | Calendar date, no time.     |
| `timestamp`  | `TIMESTAMPTZ`      | Timestamp with time zone.   |
| `uuid`       | `UUID`             |                             |
| `json`       | `JSONB`            |                             |

Each column carries a `nullable` flag and an optional `defaultValue` (validated against the column's type).

## Surfaces

Custom tables are reachable from every Sublay SDK and from the dashboard:

<CardGroup>
  <Card title="Node SDK — rows" icon="table" href="/v7/node-sdk/tables">
    `client.table(name)` — find, create, update, delete, bulk, restore.
  </Card>

  <Card title="Node SDK — management" icon="wrench" href="/v7/node-sdk/tables-management">
    `client.tables` — create/drop tables and add/drop columns (service-key only).
  </Card>

  <Card title="JS SDK — rows" icon="table" href="/v7/js-sdk/tables">
    `client.table(name)` row operations from any browser or JS runtime.
  </Card>

  <Card title="React hook" icon="react" href="/v7/sdk/tables/overview">
    `useTable(name)` for React and React Native.
  </Card>
</CardGroup>

Table **management** (DDL — creating tables, adding columns) is available in two places only: the **Node SDK** (service-key) and the **dashboard**. The JS SDK and the React hook are row-only, because they authenticate as an end user and hold no service key.

## The dashboard data editor

The dashboard ships a full data editor for custom tables, under the project's **Database** view:

* **Schema management** — create a table (with the full type set, per-column nullable/default, and the `timestamps` / `paranoid` toggles), add a column to an existing table, and drop tables or columns. Drop actions open a confirmation dialog that previews what will be lost (e.g. the affected row count) and gate the action behind typing the table/column name.
* **Row editing** — insert and edit rows through type-aware inputs. Managed columns are not editable. (Row editing is offered for custom tables only — built-in tables stay read-only in the editor.)
* **Soft delete & restore** — on a paranoid table, the grid offers a **Show deleted** toggle; soft-deleted rows render dimmed with a **Restore** action.
* **Filter, sort, paginate** — browse rows with the same filter/sort/pagination contract the SDKs use.

Custom table names display with the `custom_` prefix stripped (`Events`, not `custom_Events`).

<Info>
  **Permissions.** Schema changes (create/drop table, add/drop column) require an
  **owner or admin** role. Row writes (insert, edit, restore) require **owner or
  editor** — the same gate as deleting a row.
</Info>

## Limits

To keep a runaway script from exhausting your schema, custom tables are bounded:

* **100 tables** per project.
* **100 columns** per table.
* **100 rows** per bulk create or bulk delete call.

These ceilings are generous for legitimate data models and far below Postgres's own limits.

## Security: open row CRUD

<Warning>
  **Row CRUD on the `/db` surface is currently open.** The row endpoints capture
  the caller's identity (user token, service key) but **do not enforce any
  authorization** — any caller who can reach your project can read and write
  custom-table rows. There are no row-, field-, or table-level policies yet.

  This is a deliberate, pre-release state. A hard authorization gate is planned
  before general availability, and the captured identity context is the
  integration point that policy layer will build on. **Do not store data in
  custom tables that requires per-row or per-user access control until that gate
  ships.**
</Warning>

Table **management** (DDL) is not open — it requires a service key (SDK) or an owner/admin role (dashboard).


# Use accounts
Source: https://docs.sublay.io/v7/hooks/auth/use-accounts

List all accounts linked in the current app instance

## Overview

`useAccounts` returns the list of all stored accounts and the currently active account. Use it to render an account switcher or display the signed-in user's identity.

## Usage Example

<CodeGroup>
  ```tsx React theme={null}
  import { useAccounts } from "@sublay/react-js";

  function AccountSummaryBar() {
    const { accounts, activeAccount, accountCount } = useAccounts();

    return (
      <div>
        <p>Signed in as: {activeAccount?.name ?? activeAccount?.email ?? "Guest"}</p>
        <p>Total accounts: {accountCount}</p>
        <ul>
          {accounts.map((account) => (
            <li key={account.id}>{account.name ?? account.email}</li>
          ))}
        </ul>
      </div>
    );
  }
  ```

  ```tsx React Native theme={null}
  import { useAccounts } from "@sublay/react-native";

  function ActiveAccountLabel() {
    const { activeAccount } = useAccounts();
    return <Text>{activeAccount?.name ?? "Not signed in"}</Text>;
  }
  ```
</CodeGroup>

## Returns

<ResponseField name="accounts" type="StoredAccount[]">
  Array of all stored accounts, derived from the accounts map in Redux state.
  Each one carries the profile summary, the two credential markers below, and
  the `needsPushRebind` notification marker.
</ResponseField>

<ResponseField name="activeAccount" type="StoredAccount | null">
  The account currently **selected**, or `null` when nothing is selected.

  Selection and session are not the same thing, and the gap between them is a
  state your UI has to render. An account can be selected with no live session
  behind it — during an [`addAccount()`](/hooks/auth/use-add-account) flow, or
  after a sign-in was refused at the account limit. Read `accessToken` from
  [`useAuth`](/hooks/auth/use-auth) for whether a session exists; read this for
  whose account the app is pointed at.
</ResponseField>

<ResponseField name="accountCount" type="number">
  Total number of stored accounts.
</ResponseField>

<ResponseField name="signedOut" type="boolean">
  `true` when there is no active account **because the user deliberately signed
  out** — or removed the active account, deleted it, or had a stored credential
  refused at launch — as opposed to "nothing has ever been selected". Both look like `activeAccount === null`; this is what
  tells them apart, and it is persisted, so it survives a relaunch.

  A launch that could not *reach* the server does not set it: the stored account
  stays selected and its session is restored later. Only a refusal counts.

  While it is `true`, the SDK will not auto-select a stored account at launch.
  It clears as soon as any account is successfully activated.
</ResponseField>

<ResponseField name="accountLimitReached" type="boolean">
  `true` when an account was actually refused admission because the map was
  already at the 5-account limit. Clears on the next successful admission and
  on any removal. See [`useAddAccount`](/hooks/auth/use-add-account) for how it
  differs from `canAddAccount` and from
  [`wouldExceedAccountLimit`](/sdk/authentication/multi-account#three-signals-for-the-account-cap).

  **Render off it — do not read it eagerly.** The clear is dispatched from an
  effect, so it lands one render *after* a successful admission rather than
  synchronously inside the call that caused it. Reading it immediately after
  `await`ing a sign-in returns the value from before that effect flushed, which
  may be a `true` left over from an earlier, unrelated refusal. See
  [When `accountLimitReached` clears](/sdk/authentication/multi-account#when-accountlimitreached-clears).
</ResponseField>

## StoredAccount Type

| Property          | Type                          | Description                                                                                                                     |
| ----------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `id`              | `string`                      | User ID                                                                                                                         |
| `name`            | `string \| null`              | Display name                                                                                                                    |
| `username`        | `string \| null \| undefined` | Username. `undefined` on entries stored by an SDK version before this field existed — absent means *unknown*, not "no username" |
| `email`           | `string \| null`              | Email address                                                                                                                   |
| `avatar`          | `string \| null`              | Avatar URL                                                                                                                      |
| `tokenExpiresAt`  | `number`                      | When this account's stored refresh token expires, as an epoch in **milliseconds**. `0` means unknown                            |
| `needsReauth`     | `boolean`                     | `true` once a transition into this account has actually been refused — the credential is dead                                   |
| `needsPushRebind` | `boolean`                     | `true` when this account's notifications are paused until it is next opened                                                     |

`StoredAccount` is a superset of the `AccountSummary` shape stored in the
account map, so code that only reads `id`/`name`/`username`/`email`/`avatar` is
unaffected.

## Telling a Live Account From a Dead One

A stored account can stop working while it is sitting in the switcher. Two
fields let you show that **before** the user taps it, and you need both —
neither is sufficient on its own:

<ResponseField name="tokenExpiresAt" type="number">
  **Proactive.** Read from the stored refresh token's own `exp` claim when the
  entry is written (a decode, never a verification and never a network call).

  `0` means *unknown* — the token carried no readable numeric `exp`, so the SDK
  recorded nothing rather than guessing. It sorts as already-expired
  deliberately: treating a credential the SDK cannot read as fresh is the worse
  failure.
</ResponseField>

<ResponseField name="needsReauth" type="boolean">
  **Reactive.** Set when a transition into this account is refused — by a switch,
  or by the automatic restore at app launch, which is the most common way a
  revoked credential is discovered. Cleared the moment the account is
  successfully activated again, whether by a switch that works or by signing
  into it afresh.

  This catches every death `tokenExpiresAt` cannot see: reuse detection, a
  password change, a remote sign-out-all, an admin revocation. All of those
  destroy the token family while `exp` is still comfortably in the future. It is
  also set without any network call when the stored entry carries no usable
  credential at all, which is the same conclusion reached sooner.

  A failed switch that could not reach the server does **not** set it — a flaky
  network is not a dead account. `AccountTransitionError.credentialRejected` is
  the same distinction, reported to the caller at the moment of failure; see
  [`useSwitchAccount`](/hooks/auth/use-switch-account#telling-a-dead-account-from-a-dead-network).
</ResponseField>

```tsx theme={null}
const { accounts } = useAccounts();

const needsSignIn = (account: StoredAccount) =>
  account.needsReauth || account.tokenExpiresAt <= Date.now();

accounts.map((account) => (
  <AccountRow
    key={account.id}
    account={account}
    badge={needsSignIn(account) ? "Sign in again" : undefined}
  />
));
```

### Notifications paused: `needsPushRebind`

<ResponseField name="needsPushRebind" type="boolean">
  `true` when this account's push binding points at a device token this device no
  longer holds, because the token rotated while the account was in the
  background.

  Its credential is fine and its data is fine — only the notification routing is
  stale. Switching into the account re-creates the binding and clears this, so
  the useful thing to render is an invitation to open it rather than a sign-in
  prompt: *"Notifications paused — open to resume."*

  Only ever raised for accounts that explicitly enabled push on this device. An
  account that never asked for notifications has none to pause.
</ResponseField>

**Do not conflate it with `needsReauth`.** They mean opposite things about the
account's health, and saying the wrong one is wrong in both directions: telling
a user to sign in again when their notifications are merely stale asks for a
password they do not need, and treating a paused account as fine hides the one
thing a tap would fix.

Neither credential marker is a promise: `needsReauth: false` with a future
`tokenExpiresAt` means *nothing has gone wrong that the SDK knows of*, not that
the next switch is guaranteed to succeed. A switch can still fail, and when it
does the current session is left untouched — see
[When a transition fails](/sdk/authentication/multi-account#when-a-transition-fails).

On Expo, `avatar` and then `email` may be dropped from a stored entry if it
would otherwise exceed SecureStore's per-value limit. `id`, `name`, `username`,
the credential and the markers are never dropped. See
[Where accounts are stored](/sdk/authentication/multi-account#where-accounts-are-stored).

## Rendering the Signed-Out State

No account is auto-selected after a sign-out, removal or deletion, so `activeAccount` can be `null` while `accounts` is non-empty. That is the account-picker state:

```tsx theme={null}
import { useAccounts, useAuth } from "@sublay/react-js";

const { initialized, accessToken } = useAuth();
const { accounts, signedOut } = useAccounts();

if (!initialized) return <Splash />;
if (accessToken) return <App />;
if (signedOut && accounts.length > 0) return <AccountPicker accounts={accounts} />;
return <SignIn />;
```

Branch on `accessToken`, not on `activeAccount`. A selection is not a session:
`addAccount()` leaves the previous account selected while it clears the session,
so a selection-based gate would render your app for an account that has no
tokens behind it. `signedOut` then separates the picker state from a device
where nobody has ever signed in.

## Integration Guide

For multi-account integration guidance, see [Multi-Account](/sdk/authentication/multi-account).


# Add account
Source: https://docs.sublay.io/v7/hooks/auth/use-add-account

Link a new user account to the current app instance

## Overview

`useAddAccount` returns an `addAccount` function that clears the active auth state, allowing the user to sign into a new account. Previously stored accounts are not removed — they remain in the accounts map and can be restored with `useSwitchAccount`.

After the user completes sign-in, the new account is added to the accounts map automatically.

<Note>
  5 accounts can be stored simultaneously. `canAddAccount` is `false` when the
  limit is reached. All 5 genuinely persist on every platform — see
  [Where accounts are stored](/sdk/authentication/multi-account#where-accounts-are-stored).
</Note>

## Usage Example

<CodeGroup>
  ```tsx React theme={null}
  import { useAddAccount } from "@sublay/react-js";

  function AddAccountButton() {
    const { addAccount, canAddAccount } = useAddAccount();

    return (
      <button onClick={addAccount} disabled={!canAddAccount}>
        Add Account
      </button>
    );
  }
  ```

  ```tsx React Native theme={null}
  import { useAddAccount } from "@sublay/react-native";

  function AddAccountButton() {
    const { addAccount, canAddAccount } = useAddAccount();

    return (
      <Button title="Add Account" onPress={addAccount} disabled={!canAddAccount} />
    );
  }
  ```
</CodeGroup>

## Returns

<ResponseField name="addAccount" type="function">
  Clears the current access token, refresh token, and user state from Redux,
  along with the outgoing account's cached API data and account-scoped feature
  state. The existing accounts map is preserved. After calling this function,
  the app should display sign-in UI for the new account.

  **Nothing it does reaches the stored account map.** The selection is left
  exactly where it was and `signedOut` is not touched — opening a sign-in screen
  is this surface's state, not the device's. On the web the map is broadcast to
  every other tab, so a write here would be an instruction to all of them.

  That is also what makes **abandoning** the flow safe. The user backs out and
  quits; the map still names the account they were in, so the next launch
  restores that account rather than moving them into a different one. Until
  then this surface is in the shape the SDK uses everywhere for *stepped out
  without signing out*: an account is still selected, but there is no live
  session behind it. Re-tapping that same account in a switcher signs back into
  it rather than no-opping.

  A no-op when `canAddAccount` is `false`.
</ResponseField>

<ResponseField name="canAddAccount" type="boolean">
  `true` if fewer than 5 accounts are currently stored. `false` at the limit.
</ResponseField>

<ResponseField name="accountLimitReached" type="boolean">
  `true` when an account was actually **refused** admission because the map was
  already full. Clears on the next successful admission and on any removal — one
  render *after*, not synchronously; see the warning below.
</ResponseField>

### `canAddAccount` vs `accountLimitReached`

They answer different questions and are both needed:

|              | `canAddAccount`                                                   | `accountLimitReached`                                      |
| ------------ | ----------------------------------------------------------------- | ---------------------------------------------------------- |
| Kind         | Predicate — "is there room right now?"                            | Event — "did an admission just get refused?"               |
| Derived from | The map size, on every render                                     | A refusal, latched in the store                            |
| Typical use  | Enable/disable the "Add account" button *before* the user commits | Render the error *after* a sign-in was rejected at the cap |

A third signal, [`wouldExceedAccountLimit`](/sdk/authentication/multi-account#three-signals-for-the-account-cap),
answers the same question as `canAddAccount` but *for a specific user id* — which
matters because signing back into an account this device already stores is never
an admission and works at the cap. Use it when you already know whose account is
coming back.

<Warning>
  **`accountLimitReached` clears asynchronously.** The clear rides the same
  effect that records a successful admission, so it lands **one render after**
  the sign-in call resolves — not synchronously inside it. This is fine for
  rendering, and wrong for reading:

  ```tsx theme={null}
  await signInWithEmailAndPassword({ email, password });
  if (accountLimitReached) showCapError();   // ⛔ reads the PRE-effect value
  ```

  That read can return a `true` left over from an earlier, unrelated refusal.
  Render the flag instead of sampling it, and the next render has the settled
  value.
</Warning>

`accountLimitReached` matters because not every refusal has a call to reject. It is set by **every** entry point that refuses an account:

| Entry point                   | Also surfaces as an error?                                                                                                            |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `signUpWithEmailAndPassword`  | Yes — before any network call                                                                                                         |
| `signInWithEmailAndPassword`  | Yes — after the account is resolved                                                                                                   |
| External auth (`signedToken`) | The provider's `auth/initialize` action rejects with the reason; the app **renders** signed-out, with the selection left where it was |
| OAuth, web and Expo           | **No** — the flag is the only channel                                                                                                 |

It is also readable from [`useAccounts`](/hooks/auth/use-accounts).

<Note>
  `canAddAccount` is not a substitute. A sign-in can start without ever going
  through `addAccount()` — a plain sign-in form, an OAuth return, or a map that
  filled in another tab while a request was in flight — and only
  `accountLimitReached` covers those. Conversely the flag is an event: it stays
  `false` until something is actually refused, so it cannot pre-disable a button.
</Note>

For what the refusal leaves behind on each path, see
[Reaching the account limit](/sdk/authentication/multi-account#reaching-the-account-limit).

## Integration Guide

For multi-account integration guidance, see [Multi-Account](/sdk/authentication/multi-account).


# Use auth
Source: https://docs.sublay.io/v7/hooks/auth/use-auth

Access auth state and perform sign-up, sign-in, sign-out, and token management

## Overview

`useAuth` is the primary authentication hook. It returns current token state and functions for all built-in auth operations: sign-up, sign-in, sign-out, password change, setting an initial password, and manual token refresh.

## Usage Example

<CodeGroup>
  ```tsx React theme={null}
  import { useAuth } from "@sublay/react-js";

  function SignInForm() {
    const { initialized, accessToken, signInWithEmailAndPassword, signOut } = useAuth();

    if (!initialized) return <p>Loading...</p>;
    if (accessToken) {
      // `signOut` rejects when the server refuses the push unbind — in which
      // case nothing was torn down and the user should retry.
      return (
        <button onClick={() => signOut().catch(showError)}>Sign Out</button>
      );
    }

    return (
      <button
        onClick={() =>
          signInWithEmailAndPassword({
            email: "user@example.com",
            password: "password123",
          })
        }
      >
        Sign In
      </button>
    );
  }
  ```

  ```tsx React Native theme={null}
  import { useAuth } from "@sublay/react-native";

  function SignInButton() {
    const { initialized, accessToken, signInWithEmailAndPassword } = useAuth();

    if (!initialized) return null;
    if (accessToken) return null;

    return (
      <Button
        title="Sign In"
        onPress={() =>
          signInWithEmailAndPassword({
            email: "user@example.com",
            password: "password123",
          })
        }
      />
    );
  }
  ```
</CodeGroup>

## Returns

`useAuth` returns an object with the following fields:

<ResponseField name="initialized" type="boolean">
  `true` once the SDK has attempted to restore a session from the stored refresh
  token. Always check this before rendering auth-dependent UI.
</ResponseField>

<ResponseField name="accessToken" type="string | null">
  The current JWT access token, or `null` if no user is signed in. Expires every
  30 minutes; the SDK refreshes it automatically.
</ResponseField>

<ResponseField name="refreshToken" type="string | null">
  The current JWT refresh token, or `null` if no user is signed in.
</ResponseField>

<ResponseField name="setRefreshToken" type="function">
  Manually set a refresh token in Redux state. Useful when integrating external
  auth flows that hand tokens directly to the SDK.
</ResponseField>

<ResponseField name="signUpWithEmailAndPassword" type="function">
  Create a new account and sign in. Accepts a `SignUpWithEmailAndPasswordProps`
  object. Throws if registration fails.

  **Parameters:**

  * `email` (required) — User's email address
  * `password` (required) — Password
  * `name` (optional) — Display name
  * `username` (optional) — Unique username
  * `avatar` (optional) — Avatar URL
  * `bio` (optional) — Bio text
  * `location` (optional) — `{ latitude, longitude }`
  * `birthdate` (optional) — Date of birth
  * `metadata` (optional) — Public custom fields
  * `secureMetadata` (optional) — Private custom fields
  * `avatarFile` (optional) — Avatar image file to upload
  * `avatarOptions` (optional) — Image processing options for the avatar
  * `bannerFile` (optional) — Banner image file to upload
  * `bannerOptions` (optional) — Image processing options for the banner

  Also throws [`ACCOUNT_LIMIT_MESSAGE`](#the-account-limit) when the device
  already stores 5 accounts. Normally this happens before any network call, so
  no account is created — but if the fifth slot fills while the request is in
  flight, the refusal lands after it and the created user record persists.
</ResponseField>

<ResponseField name="signInWithEmailAndPassword" type="function">
  Sign in with an existing account. Accepts `{ email: string; password: string }`.
  Throws if credentials are invalid, and throws
  [`ACCOUNT_LIMIT_MESSAGE`](#the-account-limit) if this would be a **sixth**
  account on the device. Signing back in to an account already stored on the
  device always succeeds, even at the limit.
</ResponseField>

<ResponseField name="signOut" type="function">
  Sign out the current account. Sends a sign-out request to the server to revoke
  the refresh token family — and, once this device has a stored push identifier, to
  unbind that account's notifications in the same transaction — then clears
  local auth state.

  **It rejects only when the server refuses the unbind.** In that case nothing is
  torn down locally either: the account keeps its entry and its credential so the
  user can retry, rather than being left receiving notifications from an account
  they can no longer reach. Every other failure — no network, a throttled or
  otherwise rejected request, a device that never registered for push — still
  signs out locally, because a user must always be able to sign out.

  **It does not sign you into another account.** If other accounts are stored,
  they stay in the map but none is activated — see
  [Multi-Account](/sdk/authentication/multi-account).
</ResponseField>

<ResponseField name="changePassword" type="function">
  Change the password for the currently authenticated user. Accepts
  `{ password: string; newPassword: string }`. The current password must be
  correct. Throws if verification fails.

  **Every other session for that user ends, and the caller's does not.** The
  access token the request is authenticated with names the session it was minted
  from, so the server knows which one is asking and nothing extra is sent. The
  user stays signed in where they are standing; every other device must sign in
  again with the new password.

  **It also clears that user's push bindings on every *other* device, and keeps
  this one's.** The hook sends the device identifier it already holds, which is
  what lets the server single out the calling handset and spare exactly its
  binding — so notifications keep arriving where the user is standing, and stop
  on the devices they just locked out. Nothing re-binds a device from its live
  session, so the others stay quiet until each is next opened. On a device that
  has never registered for push there is no identifier to send and no binding to
  keep, and every one of the user's bindings goes. See
  [Change Password](/api-reference/auth/change-password).

  Only this user's sessions are ended. Other accounts stored on this device
  belong to other users and are untouched. The mirror case is the one to plan
  for: when this user changes their password somewhere else, the copy of their
  account stored here as a background account dies — and a stored account killed
  that way still has a valid-looking expiry, so it is only discovered by trying,
  which is what `needsReauth` on
  [`useAccounts`](/hooks/auth/use-accounts#telling-a-live-account-from-a-dead-one)
  records.

  An access token minted before the change keeps working until it expires, up to
  30 minutes, so "other devices no longer work" is about their refresh, not their
  next request.
</ResponseField>

<ResponseField name="setPassword" type="function">
  Set an **initial** password for an OAuth-only user who has no password yet.
  Accepts `{ newPassword: string }`. Unlike `changePassword`, there is no
  current password to verify. Throws if the user already has a password
  (`auth/already-password-authenticated`) — use `changePassword` in that case.
</ResponseField>

<ResponseField name="requestNewAccessToken" type="function">
  Manually trigger an access token refresh using the stored refresh token.
  Declared `() => Promise<string>`: it resolves with the new access token and
  **rejects** on every path that cannot produce one — a failed refresh, no
  stored refresh token to present, or no `projectId`. It never resolves
  `undefined`. The underlying `requestNewAccessTokenThunk` rejects in the same
  cases, so `fulfilled.match(result)` is `false` when no refresh token is
  present. The SDK handles refresh
  automatically in most cases; use this only when you need to force a refresh.

  This refreshes the **active** account only — it presents whatever refresh
  token is in auth state. Switching to a *stored* account no longer goes through
  this thunk: `switchAccount` exchanges the target's credential out of band,
  before it touches the live session, so it cannot disturb the account you are
  currently signed into. If you were observing `auth/requestNewAccessToken`
  actions to detect account switches, watch the accounts slice instead. See
  [When a transition fails](/sdk/authentication/multi-account#when-a-transition-fails).
</ResponseField>

## The Account Limit

A device stores at most **5 accounts**. `signUpWithEmailAndPassword` and `signInWithEmailAndPassword` reject when a sixth would be added, throwing an `Error` whose message is exported as `ACCOUNT_LIMIT_MESSAGE`:

```tsx theme={null}
import { useAuth, ACCOUNT_LIMIT_MESSAGE } from "@sublay/react-js";

try {
  await signInWithEmailAndPassword({ email, password });
} catch (err) {
  if (err instanceof Error && err.message === ACCOUNT_LIMIT_MESSAGE) {
    // Prompt the user to sign out of one of the stored accounts.
  }
}
```

Two behaviours worth knowing:

* **Sign-up is normally refused before the network call**; sign-in is refused after it, because only the server can say which account the credentials belong to. That is deliberate — checking the typed email against the stored accounts would lock users out of their own account whenever the stored email is stale, absent or cased differently. (A sign-up whose fifth slot fills *mid-request* is refused afterwards, and that user record does persist — see [what a refusal leaves behind](/sdk/authentication/multi-account#what-is-left-behind).)
* **A refused sign-in leaves the currently active account signed in.** Nothing is torn down, the accounts map is untouched, and the session the server created for the refused attempt is signed back out, so nothing is left dangling.

The same refusal also sets `accountLimitReached` on [`useAccounts`](/hooks/auth/use-accounts) and [`useAddAccount`](/hooks/auth/use-add-account). That flag is the **only** channel on the OAuth paths, which cannot reject their caller — see [Reaching the account limit](/sdk/authentication/multi-account#reaching-the-account-limit).

## Controlling Error Logging

Handled SDK failures are logged with `console.error`. To change or silence that:

```ts theme={null}
import { setSublayLogLevel } from "@sublay/react-js";

setSublayLogLevel("silent"); // "error" (default) | "warn" | "silent"
```

It is a bare setter rather than a `SublayProvider` prop because the setting is process-global — a prop would be silently last-mount-wins in an app that mounts two providers. It is coarse by design: it silences all SDK logging, including unexpected failures. Errors are still returned to the calling hooks; only the console output changes.

## Integration Guide

For full integration guidance, see [Built-in Auth](/sdk/authentication/built-in).


# Confirm account deletion
Source: https://docs.sublay.io/v7/hooks/auth/use-confirm-account-deletion

Verify the emailed code and permanently delete the authenticated user's account

## Overview

`useConfirmAccountDeletion` returns a function that submits the confirmation code from [`useRequestAccountDeletion`](/hooks/auth/use-request-account-deletion) and **permanently deletes** the authenticated user's account. On success, the local session is torn down just like a sign-out: the deleted account is removed from the multi-account map and **no other account is activated**, even if the user has others signed in. The app renders signed-out.

<Warning>
  Deletion is **immediate and irreversible**. There is no grace period and no
  recovery once this resolves.
</Warning>

<Note>
  Deleting an account ends the session and leaves nothing active, even when other accounts remain stored — read `activeAccount` from [`useAccounts`](/hooks/auth/use-accounts) and render your own next screen when it is `null`.
</Note>

## Usage Example

<CodeGroup>
  ```tsx React theme={null}
  import { useConfirmAccountDeletion } from "@sublay/react-js";
  import { useState } from "react";

  function ConfirmDeletionForm() {
    const confirmAccountDeletion = useConfirmAccountDeletion();
    const [code, setCode] = useState("");
    const [error, setError] = useState("");

    const handleSubmit = async (e: React.FormEvent) => {
      e.preventDefault();
      setError("");
      try {
        await confirmAccountDeletion({ code });
        // Account is gone and the session has been cleared.
      } catch (err: any) {
        setError(err.message ?? "Deletion failed.");
      }
    };

    return (
      <form onSubmit={handleSubmit}>
        {error && <p>{error}</p>}
        <input
          value={code}
          onChange={(e) => setCode(e.target.value)}
          placeholder="Enter the code from your email"
        />
        <button type="submit">Permanently delete my account</button>
      </form>
    );
  }
  ```

  ```tsx React Native theme={null}
  import { useConfirmAccountDeletion } from "@sublay/react-native";

  function ConfirmDeletionScreen({ code }: { code: string }) {
    const confirmAccountDeletion = useConfirmAccountDeletion();

    return (
      <Button
        title="Permanently delete my account"
        onPress={() => confirmAccountDeletion({ code })}
      />
    );
  }
  ```
</CodeGroup>

## Parameters

The returned function accepts:

<ParamField type="string">
  The one-time confirmation code the user received by email. Must match the most recently issued code exactly.
</ParamField>

## Returns

The hook returns an async function that resolves to `void` on success. It throws if the code is invalid or expired, or if the deletion fails.

<Note>
  You don't need to call `signOut` afterward — the hook clears the local session
  for you. Any other stored accounts stay in the map, but none of them is
  activated; the app lands signed-out with the account picker available.
</Note>

## See Also

* [`useRequestAccountDeletion`](/hooks/auth/use-request-account-deletion)
* [Confirm Account Deletion API reference](/api-reference/auth/confirm-account-deletion)


# Fetch OAuth identities
Source: https://docs.sublay.io/v7/hooks/auth/use-oauth-identities

List and manage OAuth identities linked to the current user

<Note>This hook requires the user to be authenticated.</Note>

## Overview

`useOAuthIdentities` fetches the list of OAuth identities linked to the current user's account and provides a function to unlink them. Use it to build a connected accounts settings page.

## Usage Example

```tsx theme={null}
import { useEffect } from "react";
import { useOAuthIdentities } from "@sublay/react-js";

function LinkedIdentities() {
  const { identities, fetchIdentities, unlinkIdentity, isLoading, error } =
    useOAuthIdentities();

  useEffect(() => {
    fetchIdentities();
  }, []);

  if (isLoading) return <p>Loading...</p>;
  if (error) return <p>Error: {error}</p>;

  return (
    <ul>
      {identities.map((identity) => (
        <li key={identity.id}>
          {identity.provider} — {identity.email ?? identity.name ?? "Unknown"}
          <button onClick={() => unlinkIdentity({ identityId: identity.id })}>Unlink</button>
        </li>
      ))}
    </ul>
  );
}
```

## Returns

<ResponseField name="identities" type="OAuthIdentity[]">
  Array of OAuth identities linked to the current user. Initially empty; call
  `fetchIdentities` to populate.
</ResponseField>

<ResponseField name="hasPassword" type="boolean">
  Whether the user has a password set. `false` for OAuth-only accounts, and
  until `fetchIdentities` has run. Use it to prompt the user to
  [set an initial password](/hooks/auth/use-auth) (via `useAuth().setPassword`)
  before they unlink their last identity.
</ResponseField>

<ResponseField name="fetchIdentities" type="function">
  Async function that fetches the identities list from the server and updates
  local state. Returns `void`.
</ResponseField>

<ResponseField name="unlinkIdentity" type="function">
  Async function that unlinks a specific identity. Accepts `{ identityId: string }`.
  On success, removes the identity from the local `identities` array. Fails
  if it would be the last identity and the user has no password set.
</ResponseField>

<ResponseField name="isLoading" type="boolean">
  `true` while a fetch or unlink request is in progress.
</ResponseField>

<ResponseField name="error" type="string | null">
  Error message from the most recent failed operation, or `null` if no error.
</ResponseField>

## OAuthIdentity Type

| Property            | Type             | Description                                        |
| ------------------- | ---------------- | -------------------------------------------------- |
| `id`                | `string`         | Unique identity ID (UUID)                          |
| `provider`          | `string`         | OAuth provider name (e.g., `"google"`, `"github"`) |
| `providerAccountId` | `string`         | The user's ID at the provider                      |
| `email`             | `string \| null` | Email returned by the provider                     |
| `name`              | `string \| null` | Name returned by the provider                      |
| `avatar`            | `string \| null` | Avatar URL returned by the provider                |
| `isVerified`        | `boolean`        | Whether the provider marked the email as verified  |
| `createdAt`         | `string`         | ISO timestamp of when the identity was linked      |

## See Also

* [OAuth integration guide](/sdk/authentication/oauth)
* [List Identities API reference](/api-reference/oauth/list-identities)
* [Unlink Identity API reference](/api-reference/oauth/unlink-identity)


# Use OAuth sign-in
Source: https://docs.sublay.io/v7/hooks/auth/use-oauth-sign-in

Initiate OAuth sign-in, link OAuth providers, and handle the callback — web only

## Overview

`useOAuthSignIn` handles the full redirect-based OAuth flow for web apps. It provides three functions:

* **`initiateOAuth`** — redirect an unauthenticated user to the provider's authorization page to sign in or sign up.
* **`linkOAuthProvider`** — redirect an already-authenticated user to link an additional OAuth provider to their account.
* **`handleOAuthCallback`** — call this on the OAuth callback page to extract tokens from the URL fragment and set the authenticated session.

<Note>
  This page documents the `@sublay/react-js` hook, which uses `window.location` for the redirect-based web flow. For Expo apps, `@sublay/expo` exports a
  `useOAuthSignIn` hook with the **same API** that opens the system browser and returns via a deep link — see [OAuth Authentication → Expo Integration](/sdk/authentication/oauth#expo-integration).
</Note>

## Usage Example

**Initiating sign-in:**

```tsx theme={null}
import { useOAuthSignIn } from "@sublay/react-js";

function SignInPage() {
  const { initiateOAuth, isLoading, error } = useOAuthSignIn();

  return (
    <>
      <button
        onClick={() =>
          initiateOAuth({
            provider: "google",
            redirectAfterAuth: "https://myapp.com/auth/callback",
          })
        }
        disabled={isLoading}
      >
        Sign in with Google
      </button>
      {error && <p>{error}</p>}
    </>
  );
}
```

**Handling the callback:**

```tsx theme={null}
import { useEffect } from "react";
import { useOAuthSignIn } from "@sublay/react-js";

function OAuthCallbackPage() {
  const { handleOAuthCallback } = useOAuthSignIn();

  useEffect(() => {
    handleOAuthCallback();
  }, []);

  return <p>Signing you in...</p>;
}
```

**Linking an additional provider:**

```tsx theme={null}
import { useOAuthSignIn } from "@sublay/react-js";

function LinkGitHub() {
  const { linkOAuthProvider } = useOAuthSignIn();

  return (
    <button
      onClick={() =>
        linkOAuthProvider({
          provider: "github",
          redirectAfterAuth: "https://myapp.com/settings",
        })
      }
    >
      Connect GitHub
    </button>
  );
}
```

## Returns

<ResponseField name="initiateOAuth" type="function">
  Starts the OAuth sign-in / sign-up flow for unauthenticated users. Redirects
  the browser to the provider's authorization page.

  **Parameters:**

  * `provider` (required) — OAuth provider identifier (e.g. `"google"`, `"github"`).
  * `redirectAfterAuth` (optional) — URL to redirect to after authentication. Defaults to the current page URL.
</ResponseField>

<ResponseField name="linkOAuthProvider" type="function">
  Links an additional OAuth provider to the currently authenticated user. The
  user must already be signed in. Redirects the browser to the provider's
  authorization page.

  **Parameters:**

  * `provider` (required) — OAuth provider identifier (e.g. `"google"`, `"github"`).
  * `redirectAfterAuth` (optional) — URL to redirect to after linking. Defaults to the current page URL.
</ResponseField>

<ResponseField name="handleOAuthCallback" type="() => boolean">
  Reads tokens from the URL fragment (`#accessToken=...&refreshToken=...`) after
  the provider redirects back to your app. On success, stores the tokens and
  initializes the session. Returns `true` if tokens were found and set, `false`
  otherwise.

  Call this inside a `useEffect` on your callback page.

  It is **synchronous and returns before the user's identity is known**, so a
  `true` return means "tokens were found", not "this account was admitted". If
  the device already stores 5 accounts and this is a sixth, the session is
  signed back out and `accountLimitReached` is raised a moment later.
</ResponseField>

<ResponseField name="isLoading" type="boolean">
  `true` while the authorization request is in progress. Stays `true` after the
  redirect is triggered (since the page navigates away).
</ResponseField>

<ResponseField name="error" type="string | null">
  Error message if the OAuth flow fails, or `null` when there is no error.

  **The account limit does not appear here.** Reaching the 5-account limit is
  discovered after the provider returns, and this hook has no call left to
  reject — read `accountLimitReached` from
  [`useAccounts`](/hooks/auth/use-accounts) or
  [`useAddAccount`](/hooks/auth/use-add-account) instead. This is the one place
  OAuth differs from email sign-in and external auth, which do throw. See
  [OAuth → The account limit](/sdk/authentication/oauth#the-account-limit).
</ResponseField>

## Integration Guide

For full OAuth setup instructions, see [OAuth Authentication](/sdk/authentication/oauth).


# Remove account
Source: https://docs.sublay.io/v7/hooks/auth/use-remove-account

Remove a linked account from the current app instance

## Overview

`useRemoveAccount` signs out and removes a specific account from the stored accounts map. It sends a sign-out request to the server to revoke the account's refresh token family — and, once this device has a stored push identifier, to unbind that account's push notifications in the **same transaction** — before removing any local state.

If the removed account is the currently active one, **the session ends and no account is left active**, even when other accounts remain stored. The app renders signed-out; choosing what happens next is yours.

<Warning>
  **Removal is atomic once push is involved.** If this device has a stored push identifier, the sign-out request carries it, and if the server **refuses the unbind** nothing is torn down: `removeAccount` **rejects**, `error` carries the reason, and the account keeps its entry and its credential so the user can retry. Its signature is `({ userId }) => Promise<void>`, so nothing warns you at compile time: `await removeAccount(...)` needs a `catch`.

  The strictness is scoped to a **server refusal of the unbind itself** — the sign-out endpoint answering `auth/device-deregistration-failed` or `auth/sign-out-failed`, the two codes it returns when its transaction rolled back. Everything else is best-effort: no network, a throttled or migrating project, a rejected body, the generic `auth/server-error`, or a device with no stored push identifier. An offline user can still remove an account locally.

  One more code arrives on a **success** and never blocks: `auth/push-unbind-status-unknown`, returned with `200` when the server signed the account out without attempting an unbind because it could not determine whether the project has push devices. `removeAccount` resolves, the account is removed, and the SDK warns — the binding may still be live, so it is worth surfacing, but it is not worth making an account unremovable over.

  A stored push identifier is **device** state, not an account's consent: on native the SDK records one when the device already holds OS notification permission, whether or not this particular account ever registered. When the account had no binding, the unbind removes nothing and the removal completes exactly as it would without one.
</Warning>

<Note>
  Removing an account never activates a different one. Read `activeAccount` from [`useAccounts`](/hooks/auth/use-accounts) and render your own next screen when it is `null`.
</Note>

## Usage Example

<CodeGroup>
  ```tsx React theme={null}
  import { useAccounts, useRemoveAccount } from "@sublay/react-js";

  function AccountList() {
    const { accounts } = useAccounts();
    const { removeAccount, isRemoving, error } = useRemoveAccount();

    return (
      <ul>
        {accounts.map((account) => (
          <li key={account.id}>
            {account.name ?? account.email}
            <button
              onClick={() =>
                removeAccount({ userId: account.id }).catch(() => {
                  /* Rejects when the server refuses the push unbind; `error`
                     below carries the reason and nothing was torn down. */
                })
              }
              disabled={isRemoving}
            >
              Remove
            </button>
          </li>
        ))}
        {error && <p>{error}</p>}
      </ul>
    );
  }
  ```

  ```tsx React Native theme={null}
  import { useAccounts, useRemoveAccount } from "@sublay/react-native";

  function AccountItem({ userId }: { userId: string }) {
    const { removeAccount, isRemoving } = useRemoveAccount();

    return (
      <Button
        title="Remove"
        onPress={() =>
          removeAccount({ userId }).catch(() => {
            /* Read `error` from the hook; without a catch this is an
               unhandled rejection. */
          })
        }
        disabled={isRemoving}
      />
    );
  }
  ```
</CodeGroup>

## Parameters

The hook returns a `removeAccount` function that accepts:

<ParamField type="string">
  The ID of the account to remove.
</ParamField>

## Returns

<ResponseField name="removeAccount" type="function">
  Async function that removes the specified account. It **rejects** without
  doing anything when `userId` is not in the accounts map — with an
  [`AccountTransitionError`](/sdk/authentication/multi-account#telling-a-dead-account-from-a-dead-network)
  carrying `accountNotFound: true`, so a stale id is distinguishable from a
  credential failure without matching on message text — or when no `projectId`
  is available. Runtime errors during removal set `error` **and reject** the
  returned promise. Removing a non-active account leaves the current session
  untouched.
</ResponseField>

<ResponseField name="isRemoving" type="boolean">
  `true` while the removal is in progress.
</ResponseField>

<ResponseField name="error" type="string | null">
  Error message if the removal failed, or `null` if no error occurred.
</ResponseField>

## Integration Guide

For multi-account integration guidance, see [Multi-Account](/sdk/authentication/multi-account).


# Request account deletion
Source: https://docs.sublay.io/v7/hooks/auth/use-request-account-deletion

Email the authenticated user a one-time code to confirm self-service account deletion

## Overview

`useRequestAccountDeletion` returns a function that starts the self-service account-deletion flow for the currently authenticated user. It emails the user a 6-digit confirmation code (valid for 10 minutes) and does **not** delete anything on its own. Pass the code the user receives to [`useConfirmAccountDeletion`](/hooks/auth/use-confirm-account-deletion) to finish.

<Warning>
  Only works for accounts with an email on file. Accounts without one (e.g.
  anonymous or foreign-id users) must be deleted server-side with a service key.
</Warning>

## Usage Example

<CodeGroup>
  ```tsx React theme={null}
  import { useRequestAccountDeletion } from "@sublay/react-js";

  function DeleteAccountButton({ onCodeSent }: { onCodeSent: () => void }) {
    const requestAccountDeletion = useRequestAccountDeletion();

    const handleClick = async () => {
      try {
        await requestAccountDeletion();
        onCodeSent(); // reveal the "enter your code" step
      } catch (err: any) {
        // e.g. auth/no-email-on-file
        console.error(err.response?.data?.error ?? "Could not start deletion.");
      }
    };

    return <button onClick={handleClick}>Delete my account</button>;
  }
  ```

  ```tsx React Native theme={null}
  import { useRequestAccountDeletion } from "@sublay/react-native";

  function DeleteAccountButton({ onCodeSent }: { onCodeSent: () => void }) {
    const requestAccountDeletion = useRequestAccountDeletion();

    return (
      <Button
        title="Delete my account"
        onPress={async () => {
          await requestAccountDeletion();
          onCodeSent();
        }}
      />
    );
  }
  ```
</CodeGroup>

## Parameters

The returned function takes no arguments — it always acts on the currently authenticated user.

## Returns

The hook returns an async function. That function resolves to:

<ResponseField name="success" type="boolean">
  `true` when the request completes without a server error.
</ResponseField>

## See Also

* [`useConfirmAccountDeletion`](/hooks/auth/use-confirm-account-deletion)
* [Request Account Deletion API reference](/api-reference/auth/request-account-deletion)


# Request password reset
Source: https://docs.sublay.io/v7/hooks/auth/use-request-password-reset

Send a password reset email to a user

## Overview

`useRequestPasswordReset` returns a function that sends a password reset email to the specified address. The server always responds with a generic success message regardless of whether the address is registered, to prevent user enumeration.

## Usage Example

<CodeGroup>
  ```tsx React theme={null}
  import { useRequestPasswordReset } from "@sublay/react-js";

  function ForgotPasswordForm() {
    const requestPasswordReset = useRequestPasswordReset();

    const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
      e.preventDefault();
      const form = e.currentTarget;
      try {
        const result = await requestPasswordReset({
          email: form.email.value,
        });
        alert(result.message);
      } catch (err) {
        console.error(err);
      }
    };

    return (
      <form onSubmit={handleSubmit}>
        <input name="email" type="email" placeholder="Email" />
        <button type="submit">Send Reset Link</button>
      </form>
    );
  }
  ```

  ```tsx React Native theme={null}
  import { useRequestPasswordReset } from "@sublay/react-native";

  function ForgotPasswordButton({ email }: { email: string }) {
    const requestPasswordReset = useRequestPasswordReset();

    return (
      <Button
        title="Send Reset Link"
        onPress={() => requestPasswordReset({ email })}
      />
    );
  }
  ```
</CodeGroup>

## Parameters

The returned function accepts:

<ParamField type="string">
  The email address to send the reset link to.
</ParamField>

## Returns

The hook returns an async function. That function resolves to:

<ResponseField name="success" type="boolean">
  Always `true` when the request completes without a server error.
</ResponseField>

<ResponseField name="message" type="string">
  A generic success message. The same message is returned whether or not the
  email address is registered.
</ResponseField>

<Note>
  The reset link in the email expires after 1 hour. The link points to a
  server-hosted page that collects the new password and calls the
  Reset Password endpoint.
</Note>

## See Also

* [Request Password Reset API reference](/api-reference/auth/request-password-reset)
* [Reset Password API reference](/api-reference/auth/reset-password)
* [Built-in Auth guide](/sdk/authentication/built-in)


# Send verification email
Source: https://docs.sublay.io/v7/hooks/auth/use-send-verification-email

Send an email verification token or link to the authenticated user

## Overview

`useSendVerificationEmail` returns a function that sends a verification email to the currently authenticated user. The token expires after 5 minutes. Calling it on an already-verified user is a no-op (returns `{ success: true }` without sending).

## Usage Example

<CodeGroup>
  ```tsx React — numeric code theme={null}
  import { useSendVerificationEmail } from "@sublay/react-js";

  function VerifyEmailPrompt() {
    const sendVerificationEmail = useSendVerificationEmail();

    return (
      <button
        onClick={() =>
          sendVerificationEmail({
            mode: "code",
            tokenFormat: "numeric",
            tokenLength: 6,
          })
        }
      >
        Send verification code
      </button>
    );
  }
  ```

  ```tsx React — clickable link theme={null}
  import { useSendVerificationEmail } from "@sublay/react-js";

  function VerifyEmailPrompt() {
    const sendVerificationEmail = useSendVerificationEmail();

    return (
      <button
        onClick={() =>
          sendVerificationEmail({
            mode: "link",
            redirectUrl: "https://yourapp.com/email-verified",
          })
        }
      >
        Send verification link
      </button>
    );
  }
  ```

  ```tsx React Native theme={null}
  import { useSendVerificationEmail } from "@sublay/react-native";

  function VerifyEmailPrompt() {
    const sendVerificationEmail = useSendVerificationEmail();

    return (
      <Button
        title="Send code"
        onPress={() =>
          sendVerificationEmail({
            mode: "code",
            tokenFormat: "numeric",
            tokenLength: 6,
          })
        }
      />
    );
  }
  ```
</CodeGroup>

## Parameters

The returned function requires a props object — `mode` is always required, and which other fields are required depends on it:

<ParamField type="&#x22;code&#x22; | &#x22;link&#x22;">
  How the token is delivered.

  * `"code"` — user receives a token to type into your app
  * `"link"` — user receives a clickable button that verifies automatically
</ParamField>

<ParamField type="&#x22;hex&#x22; | &#x22;numeric&#x22; | &#x22;alpha&#x22; | &#x22;alphanumeric&#x22;">
  Character set for the token.

  * Required when `mode: "code"` — there's no default, since `"hex"` (see below) produces something no one would want to type.
  * Optional when `mode: "link"` (defaults to `"hex"`) — the token is embedded in a URL, never read by a human, so the format doesn't matter.
</ParamField>

<ParamField type="number">
  Length of the generated token (4–12).

  * Required when `mode: "code"` and `tokenFormat` is `"numeric"`, `"alpha"`, or `"alphanumeric"`.
  * Not allowed when `tokenFormat` is `"hex"` — hex ignores length and always produces a fixed 64-character token, so specifying one would be silently meaningless.
  * Optional when `mode: "link"` (defaults to `6`).
</ParamField>

<ParamField type="string">
  URL to redirect to after link verification. Only valid with `mode: "link"`. Receives `?verified=true` or `?verified=false&error=...` as query params.
</ParamField>

<Tip>
  These requirements are enforced by TypeScript, not just documented — `sendVerificationEmail({ mode: "code", tokenFormat: "hex" })` compiles, but `sendVerificationEmail({ mode: "code" })` or `sendVerificationEmail({ mode: "code", tokenFormat: "numeric" })` (missing `tokenLength`) will fail to type-check.
</Tip>

## Returns

The hook returns an async function. That function resolves to:

<ResponseField name="success" type="boolean">
  `true` when the request completes without a server error.
</ResponseField>

## See Also

* [`useVerifyEmail`](/hooks/auth/use-verify-email)
* [Send Verification Email API reference](/api-reference/auth/send-verification-email)
* [Built-in Auth guide](/sdk/authentication/built-in)


# Sign out all
Source: https://docs.sublay.io/v7/hooks/auth/use-sign-out-all

Sign out of all linked accounts at once

## Overview

`useSignOutAll` signs out every stored account simultaneously. It sends a sign-out request for each account's refresh token — and, once this device has a stored push identifier, unbinds each account's push notifications in the same transaction — then clears local auth state.

<Warning>
  **A partial failure keeps the accounts it could not sign out.** When the requests carry this device's push identifier, accounts whose request **succeeded** are removed and accounts whose unbind the server **refused** are kept with their credentials intact; the call then **rejects** with how many failed, so the user can retry. Its signature is `() => Promise<void>`, so nothing warns you at compile time: `await signOutAll()` needs a `catch`. The live session ends either way — an access token is transient state, not the credential the guarantee is about.

  As with [`useRemoveAccount`](/hooks/auth/use-remove-account), only a **server refusal of the unbind** blocks — `auth/device-deregistration-failed` or `auth/sign-out-failed`. Those are the two codes the server returns when it attempted the unbind inside its transaction and rolled the whole thing back. Everything else resolves: a transport failure carries no response, a throttled or migrating project is refused before the unbind is reached, and a device with **no stored push identifier** sends nothing to unbind in the first place. A user can always sign out.

  A third code, `auth/push-unbind-status-unknown`, arrives on a **success** and never blocks: the server signed the account out without attempting an unbind because it could not determine whether the project has push devices. The SDK completes the sign-out and warns; that device may still be bound to the account until it registers again.
</Warning>

## Usage Example

<CodeGroup>
  ```tsx React theme={null}
  import { useSignOutAll } from "@sublay/react-js";

  function SignOutAllButton() {
    const { signOutAll } = useSignOutAll();

    const handleClick = async () => {
      try {
        await signOutAll();
      } catch (err) {
        console.error("Sign out failed:", err);
      }
    };

    return <button onClick={handleClick}>Sign Out All Accounts</button>;
  }
  ```

  ```tsx React Native theme={null}
  import { useSignOutAll } from "@sublay/react-native";

  function SignOutAllButton() {
    const { signOutAll } = useSignOutAll();

    const handlePress = async () => {
      try {
        await signOutAll();
      } catch (err) {
        // Some accounts were kept — surface the reason and let the user retry.
        showError(err);
      }
    };

    return <Button title="Sign Out All" onPress={handlePress} />;
  }
  ```
</CodeGroup>

## Returns

<ResponseField name="signOutAll" type="function">
  Async function that signs out all accounts. Sends a server-side sign-out
  request for each stored refresh token, then resets auth state, resets the API
  cache, and returns every account-scoped feature slice (chat, notifications,
  entity/space lists, collections, table views) to its initial state. The live
  session ends either way.

  The accounts map is cleared entirely when every request came back clean. When
  the server refused an unbind for one or more accounts, those accounts keep
  their entries and credentials, every other account is still removed, and the
  promise **rejects** — see the warning above.
</ResponseField>

<Note>
  Afterwards the app is in the **durable signed-out state**: `activeAccount` is
  `null`, `signedOut` from [`useAccounts`](/hooks/auth/use-accounts) is `true`,
  and no account is auto-selected at the next launch.
</Note>

## Integration Guide

For multi-account integration guidance, see [Multi-Account](/sdk/authentication/multi-account).


# Switch account
Source: https://docs.sublay.io/v7/hooks/auth/use-switch-account

Switch the active user account

## Overview

`useSwitchAccount` switches the active session to a different stored account. It exchanges the target account's stored refresh token for a live session **first**, and only then clears the current auth state and swaps the new one in. If that exchange fails, nothing is touched — you stay signed in where you were.

## Usage Example

<CodeGroup>
  ```tsx React theme={null}
  import { useAccounts, useSwitchAccount } from "@sublay/react-js";

  function AccountSwitcher() {
    const { accounts, activeAccount } = useAccounts();
    const { switchAccount, isSwitching, error } = useSwitchAccount();

    return (
      <ul>
        {accounts.map((account) => (
          <li key={account.id}>
            {account.name ?? account.email}
            {/* Both markers, so a dead account is labelled before it is tapped. */}
            {(account.needsReauth || account.tokenExpiresAt <= Date.now()) && (
              <span> — sign in again</span>
            )}
            {account.id !== activeAccount?.id && (
              <button
                onClick={() =>
                  switchAccount({ userId: account.id }).catch(() => {
                    /* Rejects when the stored credential is refused; `error` below
                       carries the reason and you stay signed in where you were. */
                  })
                }
                disabled={isSwitching}
              >
                Switch
              </button>
            )}
          </li>
        ))}
        {error && <p>{error}</p>}
      </ul>
    );
  }
  ```

  ```tsx React Native theme={null}
  import { useSwitchAccount } from "@sublay/react-native";

  function SwitchButton({ userId }: { userId: string }) {
    const { switchAccount, isSwitching } = useSwitchAccount();

    return (
      <Button
        title="Switch"
        onPress={() =>
          switchAccount({ userId }).catch(() => {
            /* Read `error` from the hook; without a catch this is an
               unhandled rejection. */
          })
        }
        disabled={isSwitching}
      />
    );
  }
  ```
</CodeGroup>

## Parameters

The hook returns a `switchAccount` function that accepts:

<ParamField type="string">
  The ID of the account to switch to. Must be present in the stored accounts map.
</ParamField>

## Returns

<ResponseField name="switchAccount" type="function">
  Async function that switches the active session. It **rejects** without doing
  anything when the id is not in the accounts map — with an
  `AccountTransitionError` carrying `accountNotFound: true` — or when no
  `projectId` is available, and it rejects if the session for the target account
  could not be established. See below. Its signature is
  `({ userId }) => Promise<void>`, so nothing warns you at compile time:
  `await switchAccount(...)` without a `catch` becomes an unhandled rejection.

  Calling it with the ID of the already-active account is a no-op **only while
  that account has a live session**. When the selection names an account with no
  session — after a refusal at the account limit, for instance — re-selecting it
  runs the full transition, so the user has a way back in without restarting the
  app.
</ResponseField>

<ResponseField name="isSwitching" type="boolean">
  `true` while the switch is in progress (validating the target's stored
  credential, then swapping the session over).
</ResponseField>

<ResponseField name="error" type="string | null">
  Error message if the switch failed, or `null` if no error occurred.
</ResponseField>

## Failure Behavior

When the target account's stored refresh token cannot be exchanged for an access token — it expired, was revoked, or the stored entry has no usable token at all — the returned promise **rejects** and `error` is set.

**A failed switch leaves the current session completely intact.** The target's
credential is validated out of band before anything is torn down, so on failure
nothing has changed: the account you were using is still active, still holds its
tokens, and still has its cached data. Only the rejection happened.

* The previously active account is still active, with a live session. Nothing was signed out.
* **Both entries remain in the accounts map**, including the one that failed. That entry is what lets you render a "session expired" prompt for it.
* When the server was the one that refused the credential, that account's `needsReauth` is set, so the switcher can label it without trying again. A switch that failed because the request never reached the server does **not** set it.
* Switching with *no* account active — the account-picker state a user lands in after signing out — leaves nothing selected and marks the app signed out, so the next launch does not silently activate a different account.

```tsx theme={null}
import { AccountTransitionError } from "@sublay/react-js";

const { switchAccount, error } = useSwitchAccount();

async function onPick(userId: string) {
  try {
    await switchAccount({ userId });
    // Session is live for `userId`.
  } catch (err) {
    // Not switched, and nothing else changed — the previous account is still
    // signed in. `error` holds the reason.
    if (err instanceof AccountTransitionError && err.credentialRejected) {
      promptSignIn(userId);   // the server refused the credential
    } else {
      showRetry();            // the request never got an answer
    }
  }
}
```

### Telling a dead account from a dead network

A transition failure rejects with an `AccountTransitionError`, and its two boolean discriminants
are the only way to tell those failures apart — so check with `instanceof` first, as the example
above does, rather than assuming the type. (The hook also throws a plain `Error` when no
`projectId` is configured, and [`removeAccount`](/hooks/auth/use-remove-account) rejects with the
server's own error, unchanged, when it refuses to unbind that account's push notifications.)

<ResponseField name="credentialRejected" type="boolean">
  `true` when the server **refused** the stored credential — expired, revoked, reuse-detected,
  invalidated by a password change or a remote sign-out-all — or when the stored entry carries no
  usable credential at all. This is exactly the case in which `needsReauth` is set.

  `false` when the exchange never got an answer, or the rotated successor could not be persisted.
  Nothing is marked and the same account may work on the next attempt.
</ResponseField>

<ResponseField name="accountNotFound" type="boolean">
  `true` when the `userId` is **not in the accounts map at all** — a stale id, typically from a
  switcher rendered off a snapshot the map has since moved past. No network call went out, nothing
  was marked, and no session was touched. Re-read the list from
  [`useAccounts`](/hooks/auth/use-accounts) rather than prompting a sign-in for an account that is
  not there.

  Never `true` at the same time as `credentialRejected`; both are `false` for a transport failure.
</ResponseField>

Prompting a re-auth on every rejection tells a user with no signal that their account is dead, and
does it again every time they lose signal — which is what this discriminator exists to prevent.
`AccountTransitionError` and `ACCOUNT_TRANSITION_FAILED_MESSAGE` (its default message, used when
the server gave no reason) are both exported.

<Note>
  **The switch costs exactly one token exchange.** The refresh endpoint rotates
  the token it is given, and validating the target's credential *is* that
  exchange — it is not an extra probe in front of one.
</Note>

## Integration Guide

For multi-account integration guidance, see [Multi-Account](/sdk/authentication/multi-account).


# Verify email
Source: https://docs.sublay.io/v7/hooks/auth/use-verify-email

Verify the authenticated user's email address using a token from a verification email

## Overview

`useVerifyEmail` returns a function that submits a verification token to the server. Used with `mode: "code"` from `useSendVerificationEmail`. On success, `user.isVerified` is updated immediately in the local Redux store.

## Usage Example

<CodeGroup>
  ```tsx React theme={null}
  import { useVerifyEmail } from "@sublay/react-js";
  import { useState } from "react";

  function VerifyCodeForm() {
    const verifyEmail = useVerifyEmail();
    const [code, setCode] = useState("");
    const [error, setError] = useState("");

    const handleSubmit = async (e: React.FormEvent) => {
      e.preventDefault();
      setError("");
      try {
        await verifyEmail({ token: code });
        // user.isVerified is now true locally
      } catch (err: any) {
        setError(err.response?.data?.error ?? "Verification failed.");
      }
    };

    return (
      <form onSubmit={handleSubmit}>
        {error && <p>{error}</p>}
        <input
          value={code}
          onChange={(e) => setCode(e.target.value)}
          placeholder="Enter verification code"
        />
        <button type="submit">Verify</button>
      </form>
    );
  }
  ```

  ```tsx React Native theme={null}
  import { useVerifyEmail } from "@sublay/react-native";

  function VerifyCodeScreen({ code }: { code: string }) {
    const verifyEmail = useVerifyEmail();

    return (
      <Button
        title="Verify"
        onPress={() => verifyEmail({ token: code })}
      />
    );
  }
  ```
</CodeGroup>

## Parameters

The returned function accepts:

<ParamField type="string">
  The verification token entered by the user. Must match the token from the most recent verification email exactly.
</ParamField>

## Returns

The hook returns an async function. That function resolves to:

<ResponseField name="success" type="boolean">
  `true` when verification succeeded.
</ResponseField>

<Note>
  On success, `user.isVerified` is optimistically set to `true` in the local
  Redux store immediately — no need to refetch the user.
</Note>

## See Also

* [`useSendVerificationEmail`](/hooks/auth/use-send-verification-email)
* [Verify Email API reference](/api-reference/auth/verify-email)
* [Built-in Auth guide](/sdk/authentication/built-in)


# Create entity
Source: https://docs.sublay.io/v7/hooks/entities/use-create-entity

Create a new entity with optional file and image uploads

<Note>
  **Requires the `entities` bundle.** A project without the entities bundle returns `403 database/tables-not-available`. See [Bundles](/bundles).
</Note>

## Overview

`useCreateEntity` returns a function that creates a new entity. It supports both JSON and multipart form requests — the hook automatically selects multipart when images or files are included.

## Usage Example

```tsx theme={null}
import { useCreateEntity } from "@sublay/react-js";

function NewPost() {
  const createEntity = useCreateEntity();

  const handleCreate = async () => {
    const entity = await createEntity({
      title: "Hello World",
      content: "My first post",
      keywords: ["intro", "welcome"],
    });
    console.log("Created:", entity.id);
  };

  return <button onClick={handleCreate}>Create Post</button>;
}
```

### With image upload

```tsx theme={null}
const entity = await createEntity({
  title: "Photo post",
  images: {
    files: [imageFile],
    options: { width: 1200, height: 800, fit: "cover" },
  },
});
```

## Parameters

<ParamField type="string">
  An ID from your own system to link this entity to an existing item.
</ParamField>

<ParamField type="string">
  An identifier for grouping entities by source (e.g., a section of your app).
</ParamField>

<ParamField type="string">
  The ID of the space this entity belongs to.
</ParamField>

<ParamField type="string">
  Entity title.
</ParamField>

<ParamField type="string">
  Entity body content.
</ParamField>

<ParamField type="Record<string, any>[]">
  Array of attachment objects. Flexible structure — can represent media URLs, file metadata, or any structured data.
</ParamField>

<ParamField type="string[]">
  Tags or keywords for filtering and discovery.
</ParamField>

<ParamField type="Mention[]">
  Users mentioned in the entity content.
</ParamField>

<ParamField type="{ latitude: number; longitude: number }">
  Geographic location for the entity.
</ParamField>

<ParamField type="Record<string, any>">
  Arbitrary project-specific data. Limited to 10 KB.
</ParamField>

<ParamField type="boolean">
  Marks the entity's own NSFW flag. Defaults to `false`. This is only the entity's own flag — its effective NSFW status also inherits from its space. Sublay labels and filters NSFW content but does not blur or age-gate it. See [Entity NSFW flagging](/data-models/entity#nsfw-flagging).
</ParamField>

<ParamField type="boolean">
  If `true`, creates the entity as a draft (not publicly visible). Default `false`.
</ParamField>

<ParamField type="boolean">
  If `true`, the authenticated user is not associated as the entity author.
</ParamField>

<ParamField type="boolean">
  If `true`, the request fails if no authenticated user is present.
</ParamField>

<ParamField type="{ files: File[]; options?: UploadImageOptions }">
  Images to upload and attach. Triggers a multipart form request.
</ParamField>

<ParamField type="{ files: File[]; options?: { pathParts?: string[] } }">
  Files to upload and attach. Triggers a multipart form request.
</ParamField>

## Returns

<ResponseField name="Entity" type="Entity">
  The newly created entity. See [Entity data model](/data-models/entity).
</ResponseField>


# Use entity
Source: https://docs.sublay.io/v7/hooks/entities/use-entity

Access entity state and actions from EntityProvider

<Note>
  **Requires the `entities` bundle.** A project without the entities bundle returns `403 database/tables-not-available`. See [Bundles](/bundles).
</Note>

## Overview

`useEntity` reads from the nearest `EntityProvider` in the component tree and returns the entity's state and actions. It does not fetch data itself — it accesses what `EntityProvider` has already loaded.

<Note>
  `useEntity` must be used inside an `EntityProvider`. See [EntityProvider & useEntity](/sdk/entities/provider-and-hook) for setup instructions.
</Note>

## Usage Example

```tsx theme={null}
import { useEntity } from "@sublay/react-js";

function EntityContent() {
  const { entity, updateEntity, deleteEntity } = useEntity();

  if (!entity) return <p>Loading...</p>;

  return (
    <div>
      <h1>{entity.title}</h1>
      <p>Views: {entity.views}</p>
    </div>
  );
}
```

## Return Values

<ResponseField name="entity" type="Entity | null | undefined">
  The current entity. `undefined` while loading, `null` if not found.
</ResponseField>

<ResponseField name="setEntity" type="React.Dispatch">
  Direct state setter for the entity. Use for manual local state overrides.
</ResponseField>

<ResponseField name="updateEntity" type="(props: { update }) => Promise<Entity | undefined>">
  Updates the entity on the server and syncs local state. Accepts `title`, `content`, `attachments`, `keywords`, `location`, `metadata`, and `mentions`.
</ResponseField>

<ResponseField name="deleteEntity" type="() => Promise<void>">
  Deletes the entity and sets local state to `undefined`.
</ResponseField>


# Fetch entity
Source: https://docs.sublay.io/v7/hooks/entities/use-fetch-entity

Fetch a single entity by its Sublay entity ID

<Note>
  **Requires the `entities` bundle.** A project without the entities bundle returns `403 database/tables-not-available`. See [Bundles](/bundles).
</Note>

## Overview

`useFetchEntity` returns a function that fetches a single entity by its Sublay entity ID. Use this for on-demand fetches outside of `EntityProvider`.

## Usage Example

```tsx theme={null}
import { useFetchEntity } from "@sublay/react-js";

function EntityLoader({ entityId }: { entityId: string }) {
  const fetchEntity = useFetchEntity();

  const load = async () => {
    const entity = await fetchEntity({ entityId, include: ["user", "topComment"] });
    console.log(entity);
  };

  return <button onClick={load}>Load Entity</button>;
}
```

## Parameters

<ParamField type="string">
  The Sublay entity ID to fetch.
</ParamField>

<ParamField type="string | string[]">
  Optional. Populate related fields. Accepted values: `"user"`, `"space"`, `"topComment"`, `"saved"`, `"files"`, `"grants"`.
</ParamField>

<SpaceReputationParams />

## Returns

<ResponseField name="Entity" type="Entity">
  The fetched entity. When `spaceReputation` is requested, the embedded author carries an added `spaceReputation` number. See [Entity data model](/data-models/entity) and [Reputation](/data-models/reputation).
</ResponseField>


# Fetch entity by foreign ID
Source: https://docs.sublay.io/v7/hooks/entities/use-fetch-entity-by-foreign-id

Fetch a single entity by its foreign ID

<Note>
  **Requires the `entities` bundle.** A project without the entities bundle returns `403 database/tables-not-available`. See [Bundles](/bundles).
</Note>

## Overview

`useFetchEntityByForeignId` returns a function that fetches an entity using the foreign ID from your system. Optionally auto-creates the entity if it does not yet exist.

## Usage Example

```tsx theme={null}
import { useFetchEntityByForeignId } from "@sublay/react-js";

function ArticleSocial({ articleId }: { articleId: string }) {
  const fetchEntity = useFetchEntityByForeignId();

  const load = async () => {
    const entity = await fetchEntity({
      foreignId: articleId,
      createIfNotFound: true,
    });
    console.log(entity);
  };

  return <button onClick={load}>Load</button>;
}
```

## Parameters

<ParamField type="string">
  The foreign ID to look up. This is the identifier from your own system.
</ParamField>

<ParamField type="boolean">
  If `true`, automatically creates a new entity with this foreign ID when one does not exist.
</ParamField>

<ParamField type="string | string[]">
  Optional. Populate related fields. Accepted values: `"user"`, `"space"`, `"topComment"`, `"saved"`, `"files"`, `"grants"`.
</ParamField>

## Returns

<ResponseField name="Entity" type="Entity">
  The fetched (or newly created) entity. See [Entity data model](/data-models/entity).
</ResponseField>


# Fetch entity by short ID
Source: https://docs.sublay.io/v7/hooks/entities/use-fetch-entity-by-short-id

Fetch a single entity by its auto-generated short ID

<Note>
  **Requires the `entities` bundle.** A project without the entities bundle returns `403 database/tables-not-available`. See [Bundles](/bundles).
</Note>

## Overview

`useFetchEntityByShortId` returns a function that fetches an entity by its `shortId` — the auto-generated short identifier that Sublay assigns to every entity. Short IDs are useful for building readable sharing URLs.

## Usage Example

```tsx theme={null}
import { useFetchEntityByShortId } from "@sublay/react-js";
import { useParams } from "react-router-dom";

function SharePage() {
  const { shortId } = useParams<{ shortId: string }>();
  const fetchEntity = useFetchEntityByShortId();

  const load = async () => {
    const entity = await fetchEntity({ shortId });
    console.log(entity);
  };

  return <button onClick={load}>Load Shared Entity</button>;
}
```

## Parameters

<ParamField type="string">
  The short ID to look up. This is the value from `entity.shortId`.
</ParamField>

<ParamField type="string | string[]">
  Optional. Populate related fields. Accepted values: `"user"`, `"space"`, `"topComment"`, `"saved"`, `"files"`, `"grants"`.
</ParamField>

## Returns

<ResponseField name="Entity" type="Entity">
  The fetched entity. See [Entity data model](/data-models/entity).
</ResponseField>


# Fetch many entities
Source: https://docs.sublay.io/v7/hooks/entities/use-fetch-many-entities

Fetch a paginated, filtered, and sorted list of entities

<Note>
  **Requires the `entities` bundle.** A project without the entities bundle returns `403 database/tables-not-available`. See [Bundles](/bundles).
</Note>

## Overview

`useFetchManyEntities` returns a function that fetches a paginated list of entities with full filtering and sorting support. This is the low-level hook underlying `EntityListProvider`. For continuous-scroll or load-more list UIs, use [`useEntityList`](/hooks/entity-lists/use-entity-list) instead, which wraps this hook with built-in pagination state.

## Usage Example

```tsx theme={null}
import { useFetchManyEntities } from "@sublay/react-js";
import { useEffect, useState } from "react";

function EntityFeed() {
  const fetchEntities = useFetchManyEntities();
  const [entities, setEntities] = useState([]);

  useEffect(() => {
    fetchEntities({
      page: 1,
      limit: 20,
      sortBy: "score",
      spaceId: "space_abc",
      include: ["user"],
    }).then((res) => setEntities(res.data));
  }, []);

  return (
    <ul>
      {entities.map((e) => (
        <li key={e.id}>{e.title}</li>
      ))}
    </ul>
  );
}
```

## Parameters

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Defaults to server default.
</ParamField>

<ParamField type="string">
  Field to sort by. Options: `"createdAt"`, `"top"`, `"hot"`, `"controversial"`, or `"metadata.<property>"` to sort by a metadata field.
</ParamField>

<ParamField type="string">
  Sort by a specific reaction type count. Use with `sortBy: "reaction"`.
</ParamField>

<ParamField type="string">
  Sort direction: `"asc"` or `"desc"`.
</ParamField>

<ParamField type="string">
  Sort algorithm type. Options: `"auto"`, `"numeric"`, `"text"`, `"boolean"`, `"timestamp"`. Used when sorting by a metadata field.
</ParamField>

<ParamField type="string">
  Filter entities to a time window. Options: `"day"`, `"week"`, `"month"`, `"year"`.
</ParamField>

<ParamField type="string">
  Filter to entities associated with a specific source ID.
</ParamField>

<ParamField type="string">
  Filter to entities in a specific space.
</ParamField>

<ParamField type="string">
  Filter to entities created by a specific user.
</ParamField>

<ParamField type="boolean">
  If `true`, return only entities from users the authenticated user follows.
</ParamField>

<ParamField type="object">
  Filter by keywords. See [Entity List Filters](/sdk/entity-lists/filters) for the full filter schema.
</ParamField>

<ParamField type="object">
  Filter by title content. See [Entity List Filters](/sdk/entity-lists/filters).
</ParamField>

<ParamField type="object">
  Filter by body content. See [Entity List Filters](/sdk/entity-lists/filters).
</ParamField>

<ParamField type="object">
  Filter by attachments data. See [Entity List Filters](/sdk/entity-lists/filters).
</ParamField>

<ParamField type="object">
  Filter by geographic proximity. See [Entity List Filters](/sdk/entity-lists/filters).
</ParamField>

<ParamField type="object">
  Filter by metadata fields. See [Entity List Filters](/sdk/entity-lists/filters).
</ParamField>

<ParamField type="&#x22;include-all&#x22; | &#x22;exclude&#x22; | &#x22;only&#x22;">
  Filter by **effective** NSFW status (`entity.nsfw OR its space's nsfwEffective`). `"include-all"` (default) adds no predicate; `"exclude"` drops effective-NSFW entities; `"only"` returns only effective-NSFW entities. On projects without the spaces bundle it applies against the entity's own `nsfw` flag alone. See [Entity NSFW flagging](/data-models/entity#nsfw-flagging).
</ParamField>

<ParamField type="string | string[]">
  Populate related fields. Accepted values: `"user"`, `"space"`, `"topComment"`, `"saved"`, `"files"`, `"grants"`.
</ParamField>

<SpaceReputationParams />

## Returns

<ResponseField name="data" type="Entity[]">
  Array of entities for the current page. When `spaceReputation` is requested, each embedded author carries an added `spaceReputation` number. See [Reputation](/data-models/reputation).
</ResponseField>

<ResponseField name="pagination.page" type="number">
  Current page number.
</ResponseField>

<ResponseField name="pagination.pageSize" type="number">
  Number of results per page.
</ResponseField>

<ResponseField name="pagination.totalPages" type="number">
  Total number of pages matching the filters.
</ResponseField>

<ResponseField name="pagination.totalItems" type="number">
  Total count of entities matching the filters (across all pages).
</ResponseField>

<ResponseField name="pagination.hasMore" type="boolean">
  `true` if there are additional pages available.
</ResponseField>


# Use entities
Source: https://docs.sublay.io/v7/hooks/entities/use-fetch-many-entities-wrapper

Stateful, paginated entity feed with sorting and filtering

<Note>
  **Requires the `entities` bundle.** A project without the entities bundle returns `403 database/tables-not-available`. See [Bundles](/bundles).
</Note>

## Overview

`useFetchManyEntitiesWrapper` is a stateful wrapper around [`useFetchManyEntities`](/hooks/entities/use-fetch-many-entities) that manages pagination, sorting, and list state for you. Use it when you need a custom entity feed outside of `EntityListProvider` — for example, a user profile feed, a filtered search results page, or any custom list with infinite scroll.

All filters and sort options mirror those of `useFetchManyEntities`. Changing any sort option automatically resets the list and re-fetches from page 1.

## Usage Example

```tsx theme={null}
import { useFetchManyEntitiesWrapper } from "@sublay/react-js";

function UserFeed({ userId }: { userId: string }) {
  const {
    entities,
    loading,
    hasMore,
    sortBy,
    setSortBy,
    loadMore,
  } = useFetchManyEntitiesWrapper({
    userId,
    limit: 15,
    defaultSortBy: "createdAt",
    include: ["user"],
  });

  return (
    <div>
      <select value={sortBy} onChange={(e) => setSortBy(e.target.value as any)}>
        <option value="createdAt">Newest</option>
        <option value="top">Top</option>
        <option value="hot">Hot</option>
      </select>
      <ul>
        {entities.map((entity) => (
          <li key={entity.id}>{entity.title}</li>
        ))}
      </ul>
      {hasMore && (
        <button onClick={loadMore} disabled={loading}>
          Load more
        </button>
      )}
    </div>
  );
}
```

## Parameters

<ParamField type="number">
  Number of entities per page. Default: `10`.
</ParamField>

<ParamField type="string | null">
  Filter to entities created by a specific user.
</ParamField>

<ParamField type="string | null">
  Filter to entities associated with a specific source ID.
</ParamField>

<ParamField type="string | null">
  Filter to entities in a specific space.
</ParamField>

<ParamField type="boolean">
  If `true`, return only entities from users the authenticated user follows.
</ParamField>

<ParamField type="EntityIncludeParam">
  Populate related fields. Accepted values: `"user"`, `"space"`, `"topComment"`, `"saved"`, `"files"`, `"grants"`.
</ParamField>

<ParamField type="EntityListSortByOptions">
  Initial sort field. Default: `"createdAt"`.
</ParamField>

<ParamField type="SortByReaction">
  Initial reaction type to sort by when `sortBy` is reaction-based. Default: `"upvote"`.
</ParamField>

<ParamField type="&#x22;asc&#x22; | &#x22;desc&#x22;">
  Initial sort direction. Default: `"desc"`.
</ParamField>

<ParamField type="SortType">
  Initial sort algorithm. Options: `"auto"`, `"numeric"`, `"text"`, `"boolean"`, `"timestamp"`. Used when sorting by a metadata field. Default: `"auto"`.
</ParamField>

<ParamField type="TimeFrame | null">
  Filter entities to a time window. Options: `"day"`, `"week"`, `"month"`, `"year"`.
</ParamField>

<ParamField type="KeywordsFilters | null">
  Filter by keywords. See [Entity List Filters](/sdk/entity-lists/filters).
</ParamField>

<ParamField type="TitleFilters | null">
  Filter by title content. See [Entity List Filters](/sdk/entity-lists/filters).
</ParamField>

<ParamField type="ContentFilters | null">
  Filter by body content. See [Entity List Filters](/sdk/entity-lists/filters).
</ParamField>

<ParamField type="AttachmentsFilters | null">
  Filter by attachments data. See [Entity List Filters](/sdk/entity-lists/filters).
</ParamField>

<ParamField type="LocationFilters | null">
  Filter by geographic proximity. See [Entity List Filters](/sdk/entity-lists/filters).
</ParamField>

<ParamField type="MetadataFilters | null">
  Filter by metadata fields. See [Entity List Filters](/sdk/entity-lists/filters).
</ParamField>

## Returns

<ResponseField name="entities" type="Entity[]">
  The current list of fetched entities. Appended to on each `loadMore` call.
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` while fetching the initial page or loading more.
</ResponseField>

<ResponseField name="hasMore" type="boolean">
  `true` if additional pages are available.
</ResponseField>

<ResponseField name="sortBy" type="EntityListSortByOptions">
  Current sort field.
</ResponseField>

<ResponseField name="sortByReaction" type="SortByReaction">
  Current reaction type used for reaction-based sorting.
</ResponseField>

<ResponseField name="sortDir" type="&#x22;asc&#x22; | &#x22;desc&#x22;">
  Current sort direction.
</ResponseField>

<ResponseField name="sortType" type="SortType">
  Current sort algorithm.
</ResponseField>

<ResponseField name="setSortBy" type="(sortBy: EntityListSortByOptions) => void">
  Change the sort field. Resets the list and re-fetches from page 1.
</ResponseField>

<ResponseField name="setSortByReaction" type="(sortByReaction: SortByReaction) => void">
  Change the reaction type for reaction-based sorting. Resets and re-fetches.
</ResponseField>

<ResponseField name="setSortDir" type="(sortDir: 'asc' | 'desc') => void">
  Change the sort direction. Resets the list and re-fetches from page 1.
</ResponseField>

<ResponseField name="setSortType" type="(sortType: SortType) => void">
  Change the sort algorithm. Resets the list and re-fetches from page 1.
</ResponseField>

<ResponseField name="loadMore" type="() => void">
  Load the next page of entities. Appends to the existing list.
</ResponseField>


# Hooks Reference
Source: https://docs.sublay.io/v7/hooks/overview

Low-level hooks for every Sublay feature

Browse the full reference for all Sublay hooks, organized by feature area. Each hook page documents its props, return values, and usage examples.

For higher-level integration guidance, see the [SDK Reference](/sdk/getting-started).


# Use user
Source: https://docs.sublay.io/v7/hooks/user/use-user

Access and update the authenticated user's own profile

## Overview

`useUser` is the primary hook for interacting with the currently authenticated user's profile. It provides the user's full data (as an `AuthUser`), loading and error states, an `updateUser` action, and derived [suspension](/sdk/moderation/suspensions) state (`isSuspended` / `activeSuspension`).

Updates are applied optimistically — the UI reflects changes immediately, and reverts automatically if the server request fails.

## Usage Example

```tsx theme={null}
import { useUser } from "@sublay/react-js";

function ProfileEditor() {
  const { user, updating, updateUser } = useUser();

  const handleSave = async () => {
    await updateUser({ name: "Jane Doe", bio: "Building cool things." });
  };

  if (!user) return null;

  return (
    <div>
      <p>{user.name}</p>
      <button onClick={handleSave} disabled={updating}>
        Save
      </button>
    </div>
  );
}
```

### Uploading an Avatar

```tsx theme={null}
import { useUser } from "@sublay/react-js";

function AvatarUpload({ file }: { file: File }) {
  const { updateUser } = useUser();

  const handleUpload = async () => {
    await updateUser({
      avatar: {
        file,
        options: { width: 200, height: 200, fit: "cover" },
      },
    });
  };

  return <button onClick={handleUpload}>Upload Avatar</button>;
}
```

## Return Values

<ResponseField name="user" type="AuthUser | null">
  The authenticated user's full profile. Returns `null` while loading or when no user is authenticated. See [User data model](/data-models/user).
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` while the user's profile is being fetched for the first time.
</ResponseField>

<ResponseField name="updating" type="boolean">
  `true` while an `updateUser` call is in progress.
</ResponseField>

<ResponseField name="error" type="string | null">
  Error message if an `updateUser` call fails. `null` when there is no error.
</ResponseField>

<ResponseField name="isSuspended" type="boolean">
  `true` while the authenticated user has an active [suspension](/sdk/moderation/suspensions). Derived from the user's `suspensions` using the same effective definition as the server.
</ResponseField>

<ResponseField name="activeSuspension" type="{ reason: string | null; startDate: string; endDate: string | null } | null">
  The user's effective (furthest-reaching) active suspension, or `null` when they aren't suspended. `endDate: null` means the suspension is indefinite. Bind a "suspended until X" banner or a disabled composer to this. See [Suspensions](/sdk/moderation/suspensions).
</ResponseField>

<ResponseField name="updateUser" type="(update: UpdateUserParams) => Promise<AuthUser>">
  Updates the authenticated user's profile. Applies optimistic updates immediately and reverts on failure.

  <Expandable title="UpdateUserParams fields">
    <ResponseField name="name" type="string | null">
      Display name. Pass `null` to clear.
    </ResponseField>

    <ResponseField name="username" type="string | null">
      Unique username. Pass `null` to clear. Must be available.
    </ResponseField>

    <ResponseField name="bio" type="string">
      Short biography. Limited to 300 characters.
    </ResponseField>

    <ResponseField name="birthdate" type="Date | null">
      Date of birth. Pass `null` to clear.
    </ResponseField>

    <ResponseField name="avatar" type="string | null | { file: File | Blob; options: UploadImageOptions }">
      Avatar image. Pass a URL string, a file object with upload options, or `null` to remove.
    </ResponseField>

    <ResponseField name="banner" type="{ file: File | Blob; options: UploadImageOptions }">
      Banner image. File upload only.
    </ResponseField>

    <ResponseField name="location" type="{ latitude: number; longitude: number } | null">
      User's geographic location. Pass `null` to clear.
    </ResponseField>

    <ResponseField name="metadata" type="Record<string, any>">
      Arbitrary project-specific data. Limited to 10 KB. Visible to other users (embedded in entity and comment data).
    </ResponseField>

    <ResponseField name="secureMetadata" type="Record<string, any>">
      Private custom fields excluded from all client-facing responses, including the authenticated user's own profile. Stored server-side only — use it for data you need to persist but never expose to any client.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="clearError" type="() => void">
  Clears the current error state.
</ResponseField>

## Optimistic Updates

`updateUser` applies changes to local state before the server responds. This makes the UI feel instant. Fields that cannot be optimistically applied (file uploads, location) wait for the server response.

If the server returns an error, the hook automatically reverts the user state to its pre-update value.

<Note>
  File uploads (avatar as a `File`/`Blob`, and banner) are not applied optimistically because the final URL is unknown until the upload completes.
</Note>


# Use user actions
Source: https://docs.sublay.io/v7/hooks/user/use-user-actions

Low-level actions for managing authenticated user state

## Overview

`useUserActions` is a low-level hook that provides direct access to the Redux actions and API mutations for the current user. In most cases you should use [`useUser`](/hooks/user/use-user) instead, which wraps `useUserActions` and provides a higher-level interface.

Use `useUserActions` directly when you need to manually set or clear user state — for example, in a custom authentication flow.

## Usage Example

```tsx theme={null}
import { useUserActions } from "@sublay/react-js";

function CustomAuth() {
  const { setUser, clearUser } = useUserActions();

  const handleExternalLogin = async (token: string) => {
    const userData = await myAuthService.login(token);
    setUser(userData); // Sync the authenticated user into Sublay state
  };

  const handleLogout = () => {
    clearUser();
  };

  return (
    <>
      <button onClick={() => handleExternalLogin("token")}>Login</button>
      <button onClick={handleLogout}>Logout</button>
    </>
  );
}
```

## Return Values

<ResponseField name="setUser" type="(user: AuthUser | null) => void">
  Manually sets the current user in Redux state. Validates that the user object has an `id` before setting — partial or empty objects are silently ignored.
</ResponseField>

<ResponseField name="clearUser" type="() => void">
  Clears the current user from Redux state and resets any error.
</ResponseField>

<ResponseField name="updateUser" type="(params: { projectId: string; userId: string; update: UpdateUserParams; currentUser?: AuthUser }) => Promise<AuthUser>">
  Calls the update user API and manages loading and error state. Applies optimistic updates for non-file fields. Reverts to `currentUser` if the request fails.

  <Expandable title="params">
    <ResponseField name="projectId" type="string">
      The project ID.
    </ResponseField>

    <ResponseField name="userId" type="string">
      The authenticated user's ID.
    </ResponseField>

    <ResponseField name="update" type="UpdateUserParams">
      Fields to update. See [`useUser`](/hooks/user/use-user) for the full `UpdateUserParams` reference.
    </ResponseField>

    <ResponseField name="currentUser" type="AuthUser">
      The current user snapshot used to revert state on failure.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="clearError" type="() => void">
  Clears any error stored in the user slice.
</ResponseField>

<Note>
  Prefer [`useUser`](/hooks/user/use-user) for typical profile management. `useUserActions` is intended for cases where you need direct control over user state, such as custom authentication integrations.
</Note>


# Check username availability
Source: https://docs.sublay.io/v7/hooks/users/use-check-username-availability

Check whether a username is available before setting it

## Overview

`useCheckUsernameAvailability` returns a function that checks whether a given username is available in the project. Use this to validate a username in real time before calling `updateUser`.

## Usage Example

```tsx theme={null}
import { useCheckUsernameAvailability } from "@sublay/react-js";
import { useState } from "react";

function UsernameInput() {
  const checkAvailability = useCheckUsernameAvailability();
  const [available, setAvailable] = useState<boolean | null>(null);

  const handleChange = async (username: string) => {
    if (username.length < 3) return;
    const result = await checkAvailability({ username });
    setAvailable(result.available);
  };

  return (
    <div>
      <input onChange={(e) => handleChange(e.target.value)} />
      {available === true && <span>Available</span>}
      {available === false && <span>Taken</span>}
    </div>
  );
}
```

## Parameters

The hook returns a function. That function accepts:

<ParamField type="string">
  The username to check.
</ParamField>

## Returns

<ResponseField name="available" type="boolean">
  `true` if the username is available, `false` if it is already taken.
</ResponseField>


# Fetch user
Source: https://docs.sublay.io/v7/hooks/users/use-fetch-user

Fetch a user's public profile by their Sublay user ID

## Overview

`useFetchUser` returns a function that fetches a user's public profile by their Sublay user ID. Use this when you have the user's `id` and need to load their profile on demand.

<Note>
  If the profile owner has blocked the signed-in caller, this returns `404` — the
  same response as a user who does not exist. The reverse is not true: a user
  *you* have blocked stays visible, so you keep a way to find and unblock them. Requires the `moderation` bundle.
</Note>

## Usage Example

```tsx theme={null}
import { useFetchUser } from "@sublay/react-js";
import { useState } from "react";

function UserCard({ userId }: { userId: string }) {
  const fetchUser = useFetchUser();
  const [user, setUser] = useState(null);

  const load = async () => {
    const result = await fetchUser({ userId });
    setUser(result);
  };

  return <button onClick={load}>Load Profile</button>;
}
```

## Parameters

The hook returns a function. That function accepts:

<ParamField type="string">
  The Sublay user ID to fetch.
</ParamField>

<ParamField type="string | string[]">
  Optional. Pass `"files"` to populate `avatarFile` and `bannerFile` with full `File` objects.
</ParamField>

<SpaceReputationParams />

## Returns

<ResponseField name="User" type="User">
  The user's public profile. When `spaceReputation` is requested, it carries an added `spaceReputation` number. See [User data model](/data-models/user) and [Reputation](/data-models/reputation).
</ResponseField>


# Fetch user by foreign ID
Source: https://docs.sublay.io/v7/hooks/users/use-fetch-user-by-foreign-id

Fetch a user's public profile by their foreign ID

## Overview

`useFetchUserByForeignId` returns a function that fetches a user's public profile using their `foreignId` — the ID from your own system that was associated with this user during authentication.

Use this when you have your own user ID and need to look up the corresponding Sublay user profile.

<Note>
  If the profile owner has blocked the signed-in caller, this returns `404` — the
  same response as a user who does not exist. The reverse is not true: a user
  *you* have blocked stays visible, so you keep a way to find and unblock them. Requires the `moderation` bundle.
</Note>

## Usage Example

```tsx theme={null}
import { useFetchUserByForeignId } from "@sublay/react-js";

function UserCard({ myUserId }: { myUserId: string }) {
  const fetchUser = useFetchUserByForeignId();

  const load = async () => {
    const user = await fetchUser({ foreignId: myUserId });
    console.log(user);
  };

  return <button onClick={load}>Load Profile</button>;
}
```

## Parameters

The hook returns a function. That function accepts:

<ParamField type="string">
  The foreign ID to look up. This is the identifier from your own system that was passed when the user was created or verified.
</ParamField>

<ParamField type="string | string[]">
  Optional. Pass `"files"` to populate `avatarFile` and `bannerFile` with full `File` objects.
</ParamField>

<SpaceReputationParams />

## Returns

<ResponseField name="User" type="User">
  The user's public profile. When `spaceReputation` is requested, it carries an added `spaceReputation` number. See [User data model](/data-models/user) and [Reputation](/data-models/reputation).
</ResponseField>


# Fetch user by username
Source: https://docs.sublay.io/v7/hooks/users/use-fetch-user-by-username

Fetch a user's public profile by their username

## Overview

`useFetchUserByUsername` returns a function that fetches a user's public profile by their username. Use this for public profile pages where the URL contains a username slug.

<Note>
  If the profile owner has blocked the signed-in caller, this returns `404` — the
  same response as a user who does not exist. The reverse is not true: a user
  *you* have blocked stays visible, so you keep a way to find and unblock them. Requires the `moderation` bundle.
</Note>

## Usage Example

```tsx theme={null}
import { useFetchUserByUsername } from "@sublay/react-js";
import { useEffect, useState } from "react";
import { User } from "@sublay/core";

function ProfilePage({ username }: { username: string }) {
  const fetchUser = useFetchUserByUsername();
  const [user, setUser] = useState<User | null>(null);

  useEffect(() => {
    fetchUser({ username }).then(setUser);
  }, [username]);

  if (!user) return null;
  return <p>{user.name}</p>;
}
```

## Parameters

The hook returns a function. That function accepts:

<ParamField type="string">
  The username to look up.
</ParamField>

<ParamField type="string | string[]">
  Optional. Pass `"files"` to populate `avatarFile` and `bannerFile` with full `File` objects.
</ParamField>

<SpaceReputationParams />

## Returns

<ResponseField name="User" type="User">
  The user's public profile. When `spaceReputation` is requested, it carries an added `spaceReputation` number. See [User data model](/data-models/user) and [Reputation](/data-models/reputation).
</ResponseField>


# Fetch user suggestions
Source: https://docs.sublay.io/v7/hooks/users/use-fetch-user-suggestions

Search for users by a query string

## Overview

`useFetchUserSuggestions` returns a function that searches for users by a query string. This is the underlying hook used by [`useUserMentions`](/hooks/users/use-user-mentions) for `@mention` autocomplete, but it can also be used for any user search or autocomplete UI.

<Note>This hook uses an authenticated request. The user must be signed in.</Note>

## Usage Example

```tsx theme={null}
import { useFetchUserSuggestions } from "@sublay/react-js";
import { useState } from "react";

function UserSearch() {
  const fetchSuggestions = useFetchUserSuggestions();
  const [results, setResults] = useState([]);

  const handleSearch = async (query: string) => {
    const users = await fetchSuggestions({ query });
    setResults(users);
  };

  return (
    <input
      onChange={(e) => handleSearch(e.target.value)}
      placeholder="Search users..."
    />
  );
}
```

## Parameters

The hook returns a function. That function accepts:

<ParamField type="string">
  The search string. Matched against usernames and names.
</ParamField>

<SpaceReputationParams />

## Returns

<ResponseField name="User[]" type="array">
  An array of matching users' public profiles. When `spaceReputation` is requested, each carries an added `spaceReputation` number. See [User data model](/data-models/user) and [Reputation](/data-models/reputation).
</ResponseField>


# Use user mentions
Source: https://docs.sublay.io/v7/hooks/users/use-user-mentions

Detect @mention triggers, fetch user suggestions, and track mentioned users in text input

## Overview

`useUserMentions` manages the full `@mention` flow inside a text input. It monitors the cursor position and content, detects when the user is typing an `@mention`, debounces a search call, and returns suggestions to display. When the user selects a suggestion, it inserts the username into the content and tracks the mention.

This hook is intended to be used alongside a controlled text input where you manage the content and cursor position.

## Usage Example

```tsx theme={null}
import { useUserMentions } from "@sublay/react-js";
import { useState, useRef } from "react";

function CommentInput() {
  const [content, setContent] = useState("");
  const [cursorPosition, setCursorPosition] = useState(0);
  const [isSelectionActive, setIsSelectionActive] = useState(false);
  const inputRef = useRef<HTMLTextAreaElement>(null);

  const {
    isMentionActive,
    loading,
    mentionSuggestions,
    handleMentionClick,
    mentions,
  } = useUserMentions({
    content,
    setContent,
    focus: () => inputRef.current?.focus(),
    cursorPosition,
    isSelectionActive,
  });

  return (
    <div>
      <textarea
        ref={inputRef}
        value={content}
        onChange={(e) => setContent(e.target.value)}
        onSelect={(e) => {
          const target = e.target as HTMLTextAreaElement;
          setCursorPosition(target.selectionStart);
          setIsSelectionActive(target.selectionStart !== target.selectionEnd);
        }}
      />
      {isMentionActive && (
        <ul>
          {loading && <li>Loading...</li>}
          {mentionSuggestions.map((user) => (
            <li key={user.id} onClick={() => handleMentionClick(user)}>
              {user.username}
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}
```

## Props

<ParamField type="string">
  The current text content of the input.
</ParamField>

<ParamField type="(value: string) => void">
  Setter for the content. Called when a mention is selected and the username is inserted.
</ParamField>

<ParamField type="() => void">
  A function that re-focuses the input. Called after a mention is selected.
</ParamField>

<ParamField type="number">
  The current cursor position (character index) within the content.
</ParamField>

<ParamField type="boolean">
  Whether the user has text selected. Mention detection is suppressed while a selection is active.
</ParamField>

<ParamField type="string">
  The character that activates mention mode. Defaults to `"@"`.
</ParamField>

<ParamField type="number">
  Minimum characters after the trigger before fetching suggestions. Defaults to `3`.
</ParamField>

<ParamField type="number">
  Milliseconds to wait after the user stops typing before fetching suggestions. Defaults to `1000`.
</ParamField>

<ParamField type="string">
  Regex pattern (as a string) that the text after the trigger must match. Defaults to `"[\\w.]+"`.
</ParamField>

## Return Values

<ResponseField name="isMentionActive" type="boolean">
  `true` when the cursor is inside a valid mention trigger sequence.
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` while user suggestions are being fetched.
</ResponseField>

<ResponseField name="mentionSuggestions" type="User[]">
  The list of matching users to display as suggestions.
</ResponseField>

<ResponseField name="handleMentionClick" type="(user: User) => void">
  Call this when the user selects a suggestion. Replaces the trigger text in `content` with the user's username, adds the user to `mentions`, and closes the suggestion list.
</ResponseField>

<ResponseField name="mentions" type="Mention[]">
  Accumulated list of confirmed mentions in the current content. Each entry has `id`, `foreignId`, `username`, and `type: "user"`.
</ResponseField>

<ResponseField name="addMention" type="(user: User) => void">
  Manually adds a user to the `mentions` list. Used internally by `handleMentionClick`.
</ResponseField>

<ResponseField name="resetMentions" type="() => void">
  Clears the `mentions` list and resets all mention state. Call this after the content is submitted.
</ResponseField>


# Introduction
Source: https://docs.sublay.io/v7/index

Sublay is infrastructure for user-powered applications — auth, social graph, content, chat, community spaces, and more, pre-built and ready to integrate.

Every product eventually needs users to *do* something — comment on a post, react to content, follow a topic, send a message, join a community. Sometimes that's the core of what you're building. Sometimes it's just one part: a blog, a support page, a changelog with reactions.

The typical answer is a third-party tool. But third-party tools mean your users create *another* account, in someone else's UI, disconnected from your product. The experience fragments — and you lose control.

Sublay is the alternative. It gives you the complete set of social primitives — feeds, comments, chat, notifications, and more — as infrastructure you own. Bring your existing users via a signed JWT, or let Sublay handle auth entirely. Either way: one unified user identity, your design, whether social features are the heart of your product or just one corner of it.

## What's Included

Sublay ships with every building block a user-powered application needs:

<CardGroup>
  <Card title="Auth & Identity" icon="key">
    Built-in email/password auth, OAuth (Google, GitHub, and more), external JWT integration for bringing your own auth system, and multi-account support.
  </Card>

  <Card title="Entities" icon="file-lines">
    The central content unit — posts, articles, listings, anything your users create. An optional bundle (`comments` and `collections` build on it). Comes with votes, reactions, view tracking, file attachments, drafts, and publishing workflows.
  </Card>

  <Card title="Comments" icon="comments">
    Threaded discussions on any entity. Nested replies, votes, emoji reactions, GIF support, @mentions, and moderation built in.
  </Card>

  <Card title="Spaces" icon="layer-group">
    Hierarchical community spaces with membership, role-based permissions, moderation tools, rules, and space-level chat.
  </Card>

  <Card title="Chat" icon="message">
    Real-time 1:1 and group conversations with message reactions, threaded replies, read state, typing indicators, and moderation.
  </Card>

  <Card title="Social Graph" icon="users">
    Unidirectional follows and bidirectional connection requests (friend-style). Full follower/following counts, status checks, and bulk queries.
  </Card>

  <Card title="Collections" icon="bookmark">
    User-owned bookmarking and folder system for saving entities. Sub-collections, entity management, and saved-state checks.
  </Card>

  <Card title="App Notifications" icon="bell">
    In-app notification system for users. Delivered via webhook to your server for push bridging, email relay, or any downstream action.
  </Card>

  <Card title="Semantic Search & AI" icon="magnifying-glass">
    Automatic content embedding for entities, comments, messages, users, and spaces. Enables semantic search across all content types and an AI-powered ask endpoint that synthesizes answers from your data.
  </Card>

  <Card title="Storage" icon="hard-drive">
    File and image uploads with server-side processing. Used for entity attachments, user avatars, banner images, and chat attachments.
  </Card>

  <Card title="Moderation" icon="shield">
    Report flows for entities, comments, and chat messages. Space-level moderation actions, ban management, and report resolution tools.
  </Card>

  <Card title="Reactions" icon="face-smile">
    Emoji reactions on entities and comments. Six reaction types out of the box (like, love, wow, sad, angry, funny), with counts and per-user state.
  </Card>
</CardGroup>

## How It Works

Every Sublay project gets a hosted API endpoint. Your application talks to that endpoint — either through the React/React Native SDK (which handles tokens, state, and real-time automatically) or directly via the REST API.

All data is scoped to your project. Users, entities, conversations, and spaces exist only within your project's namespace. You can have multiple projects — a staging environment, separate apps, or white-labeled products — each fully isolated.

<Note>
  Sublay uses a project-scoped architecture. All API paths include a `projectId`. Your project ID is available in the dashboard.
</Note>

## Auth Flexibility

Sublay does not force you into one authentication model. You choose how users are identified:

* **Built-in auth** — Sublay manages the full user identity: email/password sign-up, password reset, OAuth providers. No external auth system needed.
* **External auth** — Your backend issues a signed JWT, and Sublay automatically creates or matches a user from it. Keep your existing auth stack and add Sublay alongside it.
* **OAuth** — Sign in with Google, GitHub, or other configured providers. Supports linking multiple OAuth identities to a single account.

See [Authentication](/authentication) for a full conceptual overview.

## Get Started

<CardGroup>
  <Card title="SDK Quick Start" icon="rocket" href="/sdk/getting-started">
    Install `@sublay/react-js` or `@sublay/react-native` and get your first feature running in minutes.
  </Card>

  <Card title="Integration Options" icon="plug" href="/integration-options">
    Learn about the SDK, raw REST API, and Redux integration options — and choose the right path for your project.
  </Card>

  <Card title="Authentication" icon="lock" href="/authentication">
    Built-in, external, and OAuth auth models explained. Understand how user identity flows through Sublay.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/getting-started">
    Complete REST API documentation — every endpoint, every field.
  </Card>

  <Card title="Data Models" icon="table" href="/data-models/user">
    TypeScript interfaces for every object your app works with: users, entities, comments, conversations, and more.
  </Card>

  <Card title="UI Components" icon="puzzle-piece" href="/components/overview">
    Pre-built, fully customizable comment sections and notification UI installed directly into your project via CLI.
  </Card>
</CardGroup>


# Integration Options
Source: https://docs.sublay.io/v7/integration-options

The different ways to integrate Sublay — SDK, raw REST API, and Redux store integration.

Sublay exposes its infrastructure through a REST API. On top of that, the React and React Native SDK packages provide a higher-level integration layer that handles token management, state, real-time subscriptions, and type safety automatically.

This page explains your options so you can choose the path that fits your project.

<Warning>
  When using Sublay from a web application in production, whitelist your domain in the project dashboard. Requests from non-whitelisted origins will be rejected.
</Warning>

## Option 1: React / React Native SDK (Recommended)

If your application uses React or React Native, the SDK is the recommended integration path. It wraps the REST API in a set of hooks and context providers that do the heavy lifting:

* **Token lifecycle** — Access tokens are requested, stored, and refreshed automatically. You never manually manage auth headers.
* **Real-time** — The chat system connects via WebSocket automatically when `ChatProvider` is mounted. Message delivery, read state, and typing indicators are handled for you.
* **Optimistic state** — Actions like sending a message or toggling a reaction update local state immediately and sync with the server in the background.
* **Typed interfaces** — Every object your hooks return is typed against the interfaces in `@sublay/core`. You get full autocomplete and type safety across entities, users, conversations, comments, and more.
* **Context providers** — Features like the entity subtree, comment section, conversation, and space are scoped via React context providers, so any component in the subtree can access the full feature state with a single hook call.

<CardGroup>
  <Card title="React (Web)" icon="react" href="/sdk/getting-started">
    Install `@sublay/react-js`. Works with Next.js, Vite, Create React App, or any React web setup.
  </Card>

  <Card title="React Native / Expo" icon="mobile" href="/sdk/getting-started">
    Install `@sublay/react-native` (or `@sublay/expo` for Expo-managed workflows with secure token storage).
  </Card>
</CardGroup>

### SDK Package Reference

| Package                | Platform     | Notes                                                                   |
| ---------------------- | ------------ | ----------------------------------------------------------------------- |
| `@sublay/react-js`     | React web    | Full SDK for browser environments                                       |
| `@sublay/react-native` | React Native | Full SDK with AsyncStorage token storage                                |
| `@sublay/expo`         | Expo         | Same as React Native but uses SecureStore                               |
| `@sublay/core`         | Shared       | Platform-agnostic hooks and types — not imported directly in most cases |

## Option 2: Raw REST API

If your application does not use React, or you need to call Sublay from a server-side context, the REST API is available directly.

All endpoints are under `/v7/:projectId/`. Every request that requires a user identity must include a valid access token in the `Authorization: Bearer <token>` header.

Use cases for direct API access:

* Vue, Angular, Svelte, or other non-React frameworks
* Server-to-server operations (e.g., creating entities on behalf of users, webhook handlers, scheduled jobs)
* Custom SDKs or thin client wrappers
* Testing or exploration with tools like Postman or curl

### Service API Key (Recommended for Server-to-Server)

For server-to-server calls, using a **service API key** is almost always the right approach rather than managing individual user access tokens.

A service API key is generated once from the project dashboard and stored securely on your server. When included in a request, it grants elevated access to the API:

* **No user token required** — the service key bypasses user authentication entirely. You do not need to sign in as a user or manage token refresh on the server.
* **Act on behalf of any user** — many endpoints accept a `userId` body parameter when the request is authenticated with a service key, allowing you to perform actions on behalf of a specific user.
* **Elevated permissions** — the service key bypasses ownership checks, so it can update or delete any content, access draft entities, and read private user fields regardless of which user owns the resource.

Requests with a service key require two headers:

```http theme={null}
Authorization: Bearer <your-service-api-key>
x-sublay-project-id: <your-project-id>
```

<Warning>
  The service API key has full administrative access to your project's data. Never expose it in client-side code, browser environments, or mobile apps. Only use it from your own server.
</Warning>

<Note>
  When using the API from a client-side (browser/mobile) context without a service key, you are responsible for requesting and refreshing user access tokens, maintaining auth state, and handling real-time features (WebSockets) yourself if needed.
</Note>

See [API Reference → Getting Started](/api-reference/getting-started) for authentication details and base URL configuration.

## Option 3: Redux Store Integration

If your React application already has its own Redux store, you can integrate Sublay's state directly into it rather than using the default built-in store.

By default, `SublayProvider` creates an internal Redux store for Sublay's state. If you have an existing store, using two separate Redux stores in one app is not ideal. `SublayIntegrationProvider` lets you pass your own Redux store configuration and mount Sublay's reducers and middleware alongside your own.

This requires:

* Adding `sublayReducers` and `sublayApiReducer` to your `combineReducers` call
* Adding `sublayMiddleware` to your middleware chain
* Using `SublayIntegrationProvider` instead of `SublayProvider`

See [SDK Reference → Redux Integration](/sdk/redux-integration) for the full setup guide.

## Choosing the Right Path

| Scenario                                         | Recommended                                           |
| ------------------------------------------------ | ----------------------------------------------------- |
| Building with React or React Native              | SDK (`@sublay/react-js` or `@sublay/react-native`)    |
| Expo project                                     | `@sublay/expo`                                        |
| Already have a Redux store in React              | SDK + Redux integration (`SublayIntegrationProvider`) |
| Vue, Angular, Svelte, or other frameworks        | REST API with user access tokens                      |
| Server-side / backend operations                 | REST API with service API key                         |
| Webhook handlers, scheduled jobs, data pipelines | REST API with service API key                         |
| Mobile app without React Native                  | REST API with user access tokens                      |


# Interest Matching
Source: https://docs.sublay.io/v7/interest-matching

Match people by what they actually engage with — activity-derived interest facets, decayed over time, matched passively or by topic.

Interest matching connects people by their **activity-derived interests**. As users create and engage with content, Sublay folds that activity into a small set of **interest facets** per user — clusters of related topics, each with a recency-weighted "hotness". The [`POST /match/users`](/v7/api-reference/match/match-users) endpoint then ranks other users against an asker, either passively ("who is like me?") or by an explicit topic ("who is into biotech?").

Unlike a static interests list, facets are built from behavior and **decay over time**, so a match reflects what someone is engaged with *now*, not what they once filled into a profile field.

<Note>
  Interest matching requires a **paid plan**. Free-tier projects cannot use embedding-based features.
</Note>

***

## Prerequisites

Interest matching builds on the semantic-search embedding pipeline, so it has an ordered set of prerequisites:

1. **Paid plan** — embeddings are a paid feature.
2. **`ai-search` bundle** — provides `ContentEmbeddings`, the source of facet building. Interest matching reads and annotates this table (it adds a `facetProcessedAt` marker column), so `ai-search` must be installed **first**. Installing `interest-matching` without it fails fast with `database/bundle-prerequisite-missing`.
3. **`interest-matching` bundle** — provisions the `UserInterestFacets` table (with its vector + btree indexes). Install it from the dashboard Database section, or via the bundle install API.
4. **`interestMatching.enabled`** — the project setting that turns folding and matching on.

***

## How Facets Are Built

Facet building runs inside the existing embedding cron (every few minutes), so there is nothing extra to schedule:

* **Fold-in.** Each newly-embedded, source-clean record is folded as **one unit of mass** into the author's nearest facet (or spawns a new facet if it is far from all existing ones). Multi-chunk content still counts once — long posts do not get extra weight.
* **Decay.** A facet's mass decays with a long half-life (interests move slowly), so recent activity dominates. The current, decayed mass is a facet's **hotness**.
* **Low-signal skip.** Trivial content ("lol", "same") is skipped so it never pollutes a facet.
* **Pruning.** Facets that never reach a significance threshold are garbage-collected after a grace window; a facet that *was* significant is kept even when it later goes cold.

Building is **moderation-, soft-delete-, and DM-safe**: an embedding row surviving admin removal is not treated as live content, and private-DM content never feeds a facet.

***

## Project Settings

Configure the feature through the `interestMatching` block on the project settings (dashboard Settings → project settings update). Every field is optional and paid-plan-guarded; the tuning knobs fall back to sensible platform defaults when unset.

<ParamField type="boolean">
  Master switch. Turns on both cron fold-in and the `/match/users` endpoint.
</ParamField>

<ParamField type="boolean">
  **Gate 1** of the two-gate sample exposure. When on, callers *may* request raw sample content per matched facet by also passing `includeSampleContent: true` (Gate 2) on the request. Both gates must be on for samples to be returned. When off, requesting samples returns `403 match/sample-content-disabled`. Changing this setting invalidates the project cache so the gate takes effect immediately.
</ParamField>

<ParamField type="number">
  Half-life (hours) for facet mass/hotness decay. This is a **distinct** knob from the entity `scoring.halfLifeHours` — interests move far more slowly than trending content, so the default here is much longer (\~60 days).
</ParamField>

<ParamField type="number">
  Cosine distance under which a new record folds into an existing facet instead of spawning a new one. Larger values produce fewer, broader facets.
</ParamField>

<ParamField type="number">
  A facet whose lifetime-peak hotness never reaches this value is treated as never-significant and eligible for pruning.
</ParamField>

<ParamField type="number">
  Grace window (hours) after a facet is created during which it is never pruned, so a fresh facet has time to accumulate before garbage collection.
</ParamField>

<ParamField type="number">
  Threshold for the low-signal filter — content below it is skipped from folding (but still marked, so it never re-drains).
</ParamField>

### Two-gate sample exposure

Sample content — the raw text that illustrates why two people overlap — is exposed only when **both** gates are satisfied:

| Gate 1 (`exposeSampleContent`) | Gate 2 (`includeSampleContent`) | Result                                                       |
| ------------------------------ | ------------------------------- | ------------------------------------------------------------ |
| off                            | off                             | No samples                                                   |
| off                            | on                              | `403 match/sample-content-disabled`                          |
| on                             | off                             | No samples                                                   |
| on                             | on                              | Samples attached (minus removed / soft-deleted / DM content) |

Gate 1 is a project-owner-level consent; Gate 2 is a per-request opt-in. The always-returned match breakdown (scores, facet ids, hotness) never carries readable content on its own.

***

## Accepted Limitations

Interest matching is a lossy, eventually-consistent primitive. Know these v1 tradeoffs:

* **Gradual backfill latency.** Facets are built by the periodic cron, not synchronously on write. A brand-new project (or a burst of new content) takes several cron ticks to reflect fully in match results. Newly-created content is not blended into a live query at match time.
* **Cold-start asymmetry.** A cold user can *ask* (via the bio-vector fallback) but, in v1, is not surfaced as a *candidate* until they have real facets. A rare niche expert with little activity may therefore be hard to find until they accrue facets.
* **Deletion / edits do not retract mass.** Facet mass is additive and decays with time; deleting or editing content does **not** subtract the contribution it already made. Removed/soft-deleted/DM content is excluded from *building new* facets and from *samples*, but past mass stays until it decays. Facets do not carry stable identity across cron runs.

***

## SDKs

* **Node SDK** — [`search.matchUsers`](/v7/node-sdk/search)
* **JavaScript SDK** — [`search.matchUsers`](/v7/js-sdk/search)
* **React / React Native** — the [`useMatchUsers`](/v7/hooks/search/use-match-users) hook


# MCP Server
Source: https://docs.sublay.io/v7/mcp-server

Integrate Sublay documentation into AI tools like Claude Code, Cursor, and Windsurf using the Model Context Protocol.

The Sublay MCP (Model Context Protocol) server gives AI development tools direct access to the Sublay documentation. Once configured, your AI assistant can search and reference the complete docs in real-time — without you having to paste context manually.

## Server URL

```
https://docs.sublay.io/mcp
```

## Available Tools

### search\_sublay\_documentation

Searches across the full Sublay documentation knowledge base to find relevant pages, code examples, API references, and guides.

**Useful for:**

* Answering questions about how Sublay features work
* Finding specific API endpoints or hook signatures
* Understanding integration patterns and configuration options
* Locating code examples for any SDK feature

**Returns:** Contextual content from documentation pages, including titles, descriptions, and direct links.

***

## Installation

### Claude Code

<Steps>
  <Step title="Open MCP settings">
    Run `/mcp` in Claude Code or open the MCP configuration file.
  </Step>

  <Step title="Add the Sublay server">
    Add the following entry:

    ```json theme={null}
    {
      "mcpServers": {
        "sublay": {
          "url": "https://docs.sublay.io/mcp"
        }
      }
    }
    ```
  </Step>

  <Step title="Restart Claude Code">
    The Sublay MCP server will be available in your next session.
  </Step>
</Steps>

### Cursor

<Steps>
  <Step title="Open Cursor settings">
    Go to **Settings → MCP**.
  </Step>

  <Step title="Add the server URL">
    Enter `https://docs.sublay.io/mcp` and save.
  </Step>

  <Step title="Restart Cursor">
    The integration activates on next launch.
  </Step>
</Steps>

### Windsurf

<Steps>
  <Step title="Open Windsurf settings">
    Navigate to the MCP integration section.
  </Step>

  <Step title="Add the server URL">
    Enter `https://docs.sublay.io/mcp` and save.
  </Step>

  <Step title="Restart Windsurf">
    The integration activates on next launch.
  </Step>
</Steps>

***

## Usage

Once installed, your AI assistant uses the MCP server automatically when you ask about Sublay. Example prompts:

* "How do I set up authentication with an external user system in Sublay?"
* "Show me how to use `useEntityList` with filters"
* "What fields does the Space data model have?"
* "How do I configure webhooks for push notifications?"

The assistant retrieves accurate, up-to-date answers directly from the official documentation rather than relying on training data.

***

## Benefits

<CardGroup>
  <Card title="Always Current" icon="arrows-rotate">
    The MCP server always reflects the live documentation — no stale training data.
  </Card>

  <Card title="Accurate Code Examples" icon="code">
    Suggestions are grounded in actual Sublay patterns and API shapes.
  </Card>

  <Card title="No Context Pasting" icon="bolt">
    Skip copying documentation into prompts — the assistant fetches what it needs automatically.
  </Card>

  <Card title="Works Across Tools" icon="plug">
    Any MCP-compatible AI tool can use the same server.
  </Card>
</CardGroup>

***

## Troubleshooting

If the integration is not working:

1. Verify the server URL is entered correctly: `https://docs.sublay.io/mcp`
2. Confirm your AI tool supports MCP (Claude Code, Cursor, and Windsurf all do)
3. Restart the tool after adding the server
4. Check that `https://docs.sublay.io/mcp` is reachable from your network


# Notification Preferences & Mute
Source: https://docs.sublay.io/v7/notification-preferences

Automatic push fan-out for in-app events, per-user type toggles, per-conversation mute, and developer-authored copy templates.

Beyond the manual [`push.send()`](/push-notifications) call, Sublay can **automatically** push in-app events (comments, mentions, follows, chat messages, …) to a user's registered devices. This page covers the surfaces that control that automatic delivery:

* **Per-user preferences** — each user can disable push for specific event types.
* **Per-conversation mute** — a user can silence a single conversation's push for a duration or forever.
* **Per-event copy templates & project-level toggles** — the developer authors the push title/body per event type and can disable an event project-wide, from the dashboard.

<Note>
  **These are per-event-type controls for one signed-in user, and they are not the same thing as turning push off for an account on a device.** A user with no disabled types still receives nothing on a device where their account has been silenced with [`useAccountPushToggle`](/hooks/push/use-account-push-toggle) — that decides whether the account is bound to the device at all, while everything on this page decides which event types a bound account receives. The two compose, and neither overwrites the other.
</Note>

<Note>
  **Requires the `push` bundle.** Automatic push and the preference table live in the `push` bundle. Install it from your project's **Database** page in the [dashboard](https://dash.sublay.io). Chat-message push additionally requires the `chat` bundle; app-notification push requires the `notifications` bundle. See [Bundles](/bundles).
</Note>

## The event palette

Every automatic push is keyed by an **event type**. These are the server's exact type names — the full app-notification set plus the chat `message` event (which is push-only and writes no in-app notification):

`entity-comment`, `comment-reply`, `entity-mention`, `comment-mention`, `entity-reaction`, `comment-reaction`, `entity-reaction-milestone-specific`, `entity-reaction-milestone-total`, `comment-reaction-milestone-specific`, `comment-reaction-milestone-total`, `new-follow`, `connection-request`, `connection-accepted`, `space-membership-approved`, `event-invite`, `event-updated`, `event-cancelled`, `reputation-grant`, `message`.

The same names are used everywhere: a user's `disabledTypes`, the project-level per-event toggle, and the template map all key on this exact list. The SDKs export the list as `PUSH_EVENT_TYPES` (`@sublay/core`, `@sublay/node`, `@sublay/js`).

## Preference & mute model

### Per-user preferences (`disabledTypes`)

Each user has at most one preference row, holding the set of event types they've **opted out** of for push. The model is:

* **Absence of a row = all-on.** A user with no preference row receives push for every enabled event type. Reading preferences for such a user returns `{ "disabledTypes": [] }`.
* **Updating replaces the set.** The update endpoint upserts the whole `disabledTypes` array — send the complete set you want stored, not a delta.
* **Only valid type names are accepted.** Unknown names are rejected server-side.

Disabling a type only suppresses **push** — the in-app [App Notification](/sdk/app-notifications/overview) is still written, so the bell/inbox is unaffected.

### Per-conversation mute (`mutedUntil` / `mutedForever`)

A user can mute a single conversation for a fixed duration or forever. Mute suppresses the `message` push for that conversation only; the message is still delivered, socket-emitted, and available in the conversation as normal.

The client sends a **duration choice**, never a raw timestamp — the server resolves the window from its own clock so client skew can't distort it:

| Choice    | Meaning                     |
| --------- | --------------------------- |
| `8h`      | Muted for 8 hours from now  |
| `24h`     | Muted for 24 hours from now |
| `1w`      | Muted for 1 week from now   |
| `forever` | Muted indefinitely          |
| `null`    | Clear the mute (unmute)     |

Timed mutes expire lazily — once the window passes, push resumes with no user action.

<Warning>
  **"Forever" is an explicit signal, not a magic date.** Internally the server stores "forever" as a far-future sentinel timestamp, but that value **never** reaches clients. At the API boundary the viewer's own member row carries `mutedForever: true` with `mutedUntil: null`. Read the boolean — do **not** string-match a far-future date. The SDKs mirror this exactly.
</Warning>

The viewer's own member row (`currentMember`) is serialized as:

| State         | `mutedForever` | `mutedUntil`       |
| ------------- | -------------- | ------------------ |
| Not muted     | `false`        | `null`             |
| Timed mute    | `false`        | real ISO timestamp |
| Muted forever | `true`         | `null`             |

<Info>
  **Mute state is personal.** A member's `mutedUntil` / `mutedForever` is present **only** on that member's own row. Endpoints that return *other* members' rows (`listMembers`, `changeMemberRole`, `addMember`, the `member:joined` socket broadcast) omit both keys entirely — a user's mute state is never exposed to other participants.
</Info>

## Gating precedence

When an event fires, whether a push is dispatched is decided in this order:

1. **Project-level event disable** (dashboard toggle) — if the developer disabled the event, no one is pushed.
2. **Conversation mute** (chat `message` only) — muted members are dropped.
3. **Per-user type toggle** — users who disabled the type are dropped.
4. **Send** to everyone remaining who has a registered device.

## Copy templates & project-level toggles (dashboard)

The developer authors the push **title/body copy** per event type and can **disable** an event project-wide, from **Settings → Push Notifications** in the [dashboard](https://dash.sublay.io), beside the provider configuration.

* Each event type has an editable template field and a project-level enable toggle.
* A template is a plain-text string with `{variableName}` placeholders. Substitution is plain-text only — no expressions, no markup execution. Unknown tokens render empty.
* If a project configures no template for an event, a shipped default is used. Template edits take effect on the next send.

### Template variable palette

Each event exposes a fixed set of variables its template may interpolate. Values come from the notification metadata (app-notification events) or the message context (`message`). A token that isn't in the event's list renders empty.

| Event type                            | Variables                                                                             |
| ------------------------------------- | ------------------------------------------------------------------------------------- |
| `entity-comment`                      | `initiatorName`, `initiatorUsername`, `entityTitle`, `commentContent`                 |
| `comment-reply`                       | `initiatorName`, `initiatorUsername`, `entityTitle`, `replyContent`                   |
| `entity-mention`                      | `initiatorName`, `initiatorUsername`, `entityTitle`                                   |
| `comment-mention`                     | `initiatorName`, `initiatorUsername`, `entityTitle`, `commentContent`                 |
| `entity-reaction`                     | `initiatorName`, `initiatorUsername`, `entityTitle`, `reactionType`                   |
| `comment-reaction`                    | `initiatorName`, `initiatorUsername`, `entityTitle`, `commentContent`, `reactionType` |
| `entity-reaction-milestone-specific`  | `entityTitle`, `reactionType`, `milestoneCount`                                       |
| `entity-reaction-milestone-total`     | `entityTitle`, `milestoneCount`                                                       |
| `comment-reaction-milestone-specific` | `entityTitle`, `commentContent`, `reactionType`, `milestoneCount`                     |
| `comment-reaction-milestone-total`    | `entityTitle`, `commentContent`, `milestoneCount`                                     |
| `new-follow`                          | `initiatorName`, `initiatorUsername`                                                  |
| `connection-request`                  | `initiatorName`, `initiatorUsername`                                                  |
| `connection-accepted`                 | `initiatorName`, `initiatorUsername`                                                  |
| `space-membership-approved`           | `spaceName`                                                                           |
| `event-invite`                        | `initiatorName`, `initiatorUsername`, `eventTitle`                                    |
| `event-updated`                       | `initiatorName`, `initiatorUsername`, `eventTitle`                                    |
| `event-cancelled`                     | `initiatorName`, `initiatorUsername`, `eventTitle`                                    |
| `reputation-grant`                    | `amount`, `granterName`, `granterUsername`, `note`                                    |
| `message`                             | `senderName`, `senderUsername`, `conversationTitle`, `messageContent`                 |

Example template for `entity-comment`:

```
{initiatorName} commented on {entityTitle}: {commentContent}
```

## Privacy

Muted-conversation content and disabled-type content is **simply not dispatched** — when a mute or a preference suppresses a push, the notification's title/body (which for chat/comments contains a content snippet) is never sent to APNs, FCM, or Web Push at all. Suppression happens before any provider call, so muted/opted-out content never leaves Sublay's infrastructure to a third-party push provider.

## Building a settings UI

The SDKs expose the read/update primitives so you can build a notification-settings screen and per-conversation mute control:

<CardGroup>
  <Card title="useNotificationPreferences" icon="cube" href="/hooks/push/use-notification-preferences">
    Read + update the current user's disabled types (React / RN / Expo)
  </Card>

  <Card title="useMuteConversation" icon="cube" href="/hooks/chat/conversations/use-mute-conversation">
    Set / clear the current user's conversation mute
  </Card>

  <Card title="Node SDK — Push Notifications" icon="node-js" href="/node-sdk/push-notifications">
    `push.getNotificationPreferences` / `updateNotificationPreferences`, `chat.muteConversation`
  </Card>

  <Card title="JS SDK — Push Notifications" icon="js" href="/js-sdk/push-notifications">
    `push.getNotificationPreferences` / `updateNotificationPreferences`, `chat.muteConversation`
  </Card>
</CardGroup>

### API endpoints

<CardGroup>
  <Card title="Mute Conversation" href="/api-reference/chat/conversations/mute-conversation">
    `POST /chat/conversations/:conversationId/mute`
  </Card>

  <Card title="Get Notification Preferences" href="/api-reference/push-notifications/get-preferences">
    `GET /push-notifications/preferences`
  </Card>

  <Card title="Update Notification Preferences" href="/api-reference/push-notifications/update-preferences">
    `PUT /push-notifications/preferences`
  </Card>
</CardGroup>


# Push Notifications
Source: https://docs.sublay.io/v7/push-notifications

Deliver native OS push notifications to your users on iOS, Android, and Web — from a single server-side call.

Push Notifications lets your app deliver native OS push notifications to users on iOS (via APNs), Android (via FCM), and the browser (via Web Push) — all from a single server-side call. Sublay stores each user's registered devices, fans a message out to every platform, and prunes dead tokens automatically — across every account bound to the device, since a token the provider rejects is dead for all of them.

<Note>
  **Requires the `push` bundle.** Install it from your project's **Database** page in the [dashboard](https://dash.sublay.io) before using any push feature. See [Bundles](/bundles) for details.
</Note>

## How It Works

1. **Configure credentials** in the dashboard — paste your APNs `.p8` key, FCM service account JSON, or enable Web Push (keypair generated server-side).
2. **Register devices** — your client app calls `register()` from `usePushRegistration` at a moment that makes sense for your UX (settings screen, first-run prompt, etc.). The SDK handles permission, token retrieval, and server registration.
3. **Send notifications** — your backend calls `sublay.push.send({ userIds, title, body, data })`. Sublay fans the message out to every registered device for those users across all platforms.

## Dashboard Setup

### Installing the bundle

Open **Database → Bundles** in the [dashboard](https://dash.sublay.io) and install `push`. Once provisioning completes, the **Push Notifications** settings page becomes active.

### Configuring providers

Go to **Settings → Push Notifications** in the dashboard. Configure each platform you want to support:

**APNs (iOS)**

| Field      | Description                                                             |
| ---------- | ----------------------------------------------------------------------- |
| Key ID     | The 10-character key identifier from your Apple Developer account       |
| Team ID    | Your Apple Developer team ID                                            |
| Bundle ID  | Your app's bundle identifier (e.g. `com.example.myapp`)                 |
| .p8 key    | Contents of the `.p8` private key file downloaded from Apple            |
| Production | Toggle for sandbox vs. production APNs gateway (defaults to production) |

**FCM (Android)**

Upload or paste your Firebase service account JSON. This is the file downloaded from the Firebase console under **Project Settings → Service Accounts → Generate new private key**.

**Web Push**

No credentials to paste — click **Enable**. Sublay generates a VAPID EC keypair server-side and stores the private key encrypted. Only the public key is returned and displayed; it is also available via the unauthenticated [`GET /vapid-public-key`](/api-reference/push-notifications/get-vapid-public-key) endpoint for use in your service worker.

### Automatic push settings

Sublay can fan a push out **automatically** whenever an in-app notification is created (a new comment, reply, mention, reaction, follow, connection, RSVP-event change, space-membership approval) or a chat message is sent — no `push.send()` call required. The **Settings → Push Notifications** page lets you tune what those automatic pushes look like per event type:

| Setting               | Scope          | Description                                                                                                                                                                    |
| --------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Body template**     | Per event type | The notification body, with a `{variable}` palette specific to each event. Ships with sensible defaults.                                                                       |
| **Title template**    | Per event type | An optional title line, interpolated against the **same** `{variable}` palette as the body. **Ships empty** — an unset title renders as an empty string, so titles are opt-in. |
| **Default delivery**  | Project-wide   | A default `{ sound, channelId, priority }` applied to every automatic push.                                                                                                    |
| **Delivery override** | Per event type | Overrides the project default per field for a single event type. A present field wins; an absent one inherits the default.                                                     |

These settings affect only the **automatic** path. The manual [`push.send()`](#server-sdk--sending-notifications) call already accepts `title`, `sound`, `channelId`, `priority`, and everything else directly.

See [Automatic Pushes](#automatic-pushes) below for the full delivery-config, title-template, and tap-routing contract.

### Test-send UI

The **Push Notifications** settings page includes a **Send Test Push** panel for firing a one-off notification at a single device — the fastest way to verify a provider's credentials before wiring up the SDK. Pick a platform, paste a device token (iOS/Android) or a web push subscription, set a title and body, and click **Send Test Push**.

The catch is getting the token/subscription to paste in. It isn't shown anywhere in the dashboard — it's produced on the receiving device. Here's how to obtain each.

<Warning>
  **"Test push sent successfully" verifies *credentials*, not *delivery*.** A success result means the provider (APNs / FCM / Web Push) *accepted* the message — your keys are valid. It does **not** mean a notification appeared on screen. Rendering is a separate step that depends on the receiving device (a web service worker's `push` handler, and the OS notification settings). If the send is green but nothing shows, see [Troubleshooting](#troubleshooting-a-test-push) below — the problem is almost never the credentials at that point.
</Warning>

#### Web: generating a Subscription JSON

The **Subscription JSON** is created by a browser subscribing to the Push API. You generate it from the DevTools console of a page that (a) is served over HTTPS or `localhost` and (b) has a **service worker registered** (`await navigator.serviceWorker.ready` hangs forever otherwise).

<Steps>
  <Step title="Copy the VAPID public key">
    In the dashboard, go to **Settings → Push Notifications → Push Providers**. The **Web Push** row shows your project's VAPID public key with a copy button. (It's also available programmatically from the unauthenticated [`GET /vapid-public-key`](/api-reference/push-notifications/get-vapid-public-key) endpoint.) The subscription **must** be created with this exact key, or the send fails.
  </Step>

  <Step title="Run the subscribe snippet">
    Open DevTools → Console on your service-worker-enabled page and run:

    ```js theme={null}
    // Paste the EXACT public key from Settings → Push Notifications → Push Providers
    const VAPID_PUBLIC_KEY = 'PASTE_YOUR_VAPID_PUBLIC_KEY';

    function urlBase64ToUint8Array(base64String) {
      const padding = '='.repeat((4 - (base64String.length % 4)) % 4);
      const base64 = (base64String + padding).replace(/-/g, '+').replace(/_/g, '/');
      const raw = atob(base64);
      return Uint8Array.from([...raw].map((c) => c.charCodeAt(0)));
    }

    const reg = await navigator.serviceWorker.ready;

    // Drop any stale subscription bound to a previous key first
    const existing = await reg.pushManager.getSubscription();
    if (existing) await existing.unsubscribe();

    const sub = await reg.pushManager.subscribe({
      userVisibleOnly: true,
      applicationServerKey: urlBase64ToUint8Array(VAPID_PUBLIC_KEY),
    });

    console.log(JSON.stringify(sub.toJSON(), null, 2));
    ```

    The browser prompts for notification permission — click **Allow**. The snippet prints an object like:

    ```json theme={null}
    {
      "endpoint": "https://fcm.googleapis.com/fcm/send/...",
      "keys": { "p256dh": "...", "auth": "..." }
    }
    ```
  </Step>

  <Step title="Paste it into the panel">
    Copy the printed object into **Subscription JSON**, set Platform to **Web (Web Push)**, and send. (`expirationTime` is harmless if included; only `endpoint` and `keys` are read.)
  </Step>
</Steps>

<Note>
  This manual console flow is a **debugging convenience** for the test panel. In a real app you never do this by hand — the SDK's [`usePushRegistration`](/hooks/push/use-push-registration) creates and registers the subscription for you. See the [Web section of the SDK reference](/sdk/push-notifications/overview) for service-worker setup.
</Note>

#### iOS / Android: obtaining a device token

Native device tokens come from the OS (APNs / FCM), surfaced by the SDK's push-token adapter. To capture one for a test, wrap the built-in adapter so it logs the identifier it produces, then register as usual:

```tsx theme={null}
import { usePushRegistration } from "@sublay/core";
import type { PushTokenAdapter } from "@sublay/core";
import { expoPushTokenAdapter } from "@sublay/expo"; // or reactNativePushTokenAdapter

// Wraps the built-in adapter to log the token it retrieves
const debugAdapter: PushTokenAdapter = {
  requestPermission: expoPushTokenAdapter.requestPermission,
  async getDeviceIdentifier(context) {
    const id = await expoPushTokenAdapter.getDeviceIdentifier(context);
    console.log("Push device identifier:", id); // { platform: "ios", token: "..." }
    return id;
  },
};

function DebugRegister() {
  const { register } = usePushRegistration(debugAdapter);
  return <Button title="Register (debug)" onPress={register} />;
}
```

Run the app on a **real device** (simulators/emulators don't receive push on iOS), trigger registration, copy the `token` from the logs, then paste it into the panel with Platform set to **iOS** or **Android**.

<Warning>
  **APNs sandbox vs. production.** A development/debug iOS build talks to the APNs **sandbox** gateway; a TestFlight/App Store build talks to **production**. The **Production** toggle on your APNs provider config must match the build the token came from, or the send is rejected. This is the most common iOS test-push failure.
</Warning>

#### Troubleshooting a test push

<AccordionGroup>
  <Accordion title="Send is green but no notification appears (Web)">
    "Sent successfully" only means Web Push accepted the message. Rendering happens in **your service worker's `push` handler** — Sublay ships no service worker. Check, in order:

    1. **Does your SW render pushes?** Its `push` handler must call `registration.showNotification(...)`. Isolate the rendering step by running this in the page console — it calls `showNotification` directly, bypassing the network:
       ```js theme={null}
       const reg = await navigator.serviceWorker.ready;
       await reg.showNotification("Direct test", { body: "does the OS show this?" });
       ```
       If **this** shows nothing, the problem is OS-level (next point), not your code. If it shows but real pushes don't, your `push` handler is missing or not calling `showNotification`.
    2. **OS notification settings.** Even with `Notification.permission === "granted"`, the OS can suppress everything. On macOS: **System Settings → Notifications → \[your browser]** must be allowed (alert style not "None"), and **Focus / Do Not Disturb** must be off. This silently swallows notifications and is the single most common cause of "green but nothing."
    3. **DevTools "Push" button throws a JSON error.** The DevTools Application → Service Workers "Push" tool sends *plain text*; a handler that calls `event.data.json()` will throw on it. That's a test-tool artifact — real Sublay pushes are JSON. Test with a real send instead.
  </Accordion>

  <Accordion title="permanently_invalid / the subscription is rejected (Web)">
    The push service returned HTTP 410 (Gone). Usual causes:

    * **VAPID key mismatch** — the subscription was created with a different public key than the project's. Re-copy the key from Settings → Push Providers and re-subscribe. Chrome caches the old subscription, so `unsubscribe()` first (the snippet above already does).
    * **Truncated endpoint** — make sure you pasted the *full* `endpoint`, not an abbreviated `https://.../...` copy.
    * **Stale subscription** — regenerate a fresh one if it was minted a while ago.
  </Accordion>

  <Accordion title="Nothing arrives on iOS/Android">
    * Test on a **real device**, not a simulator/emulator.
    * Confirm the **APNs Production toggle matches the build** (sandbox for dev builds, production for TestFlight/App Store).
    * Verify the provider credentials: APNs `bundleId` must match the app exactly; FCM service account must belong to the same Firebase project as the app's `google-services.json` / config.
    * Re-copy the token — device tokens rotate and can go stale.
  </Accordion>
</AccordionGroup>

## Client SDK — Registering Devices

Use `usePushRegistration` with the adapter for your platform. Call `register()` in response to a deliberate user action — not on mount — because requesting OS push permission is a one-shot prompt that users cannot undo.

Once per device is enough. The SDK persists the device identifier and, wherever `usePushRegistration` is mounted, handles an OS token rotation itself, so there is no "call it again on every launch to be safe" step — see [Device Lifecycle](#device-lifecycle).

```tsx theme={null}
// Expo
import { usePushRegistration } from "@sublay/core";
import { expoPushTokenAdapter } from "@sublay/expo";

function SettingsScreen() {
  const { register, registering } = usePushRegistration(expoPushTokenAdapter);
  return <Button onPress={register} loading={registering} title="Enable notifications" />;
}
```

```tsx theme={null}
// Bare React Native
import { usePushRegistration } from "@sublay/core";
import { reactNativePushTokenAdapter } from "@sublay/react-native";

const { register } = usePushRegistration(reactNativePushTokenAdapter);
```

```tsx theme={null}
// Web (browser)
import { usePushRegistration } from "@sublay/core";
import { webPushTokenAdapter } from "@sublay/react-js";

const { register, unregister } = usePushRegistration(webPushTokenAdapter);
```

The web adapter requires a service worker. Register one before calling `register()`. See [SDK Reference → Push Notifications](/sdk/push-notifications/overview) for per-platform setup and [`usePushRegistration`](/hooks/push/use-push-registration) for the full hook API.

## Server SDK — Sending Notifications

Call `client.push.send()` from your backend whenever you want to notify users:

```typescript theme={null}
import { SublayClient } from "@sublay/node";

const sublay = await SublayClient.init({
  projectId: process.env.SUBLAY_PROJECT_ID!,
  apiKey: process.env.SUBLAY_SERVICE_KEY!,
});

const result = await sublay.push.send({
  userIds: ["usr_abc123", "usr_def456"],
  title: "You have a new match!",
  body: "Tap to see who liked your post.",
  data: { screen: "matches" },
});

for (const [userId, devices] of Object.entries(result.results)) {
  if (devices.length === 0) {
    console.log(`${userId} has no registered devices`);
  } else {
    console.log(`${userId}:`, devices);
  }
}
```

A single call fans the notification out to all platforms. Capped at **100 user IDs per request**. See [Node SDK — Push Notifications](/node-sdk/push-notifications) for the full module reference.

<Tip>
  A common pattern is to bridge Sublay's in-app notifications to push: subscribe to the `notification.created` webhook and call `push.send()` when it fires. See [Webhooks → Push Notification Bridge](/webhooks#push-notification-bridge).
</Tip>

## Rich Notification Payloads

Beyond `title`, `body`, and `data`, `push.send()` accepts optional fields for sound, badges, images, grouping, priority, and lifetime. Each maps to the native APNs / FCM / Web Push capability and is **silently ignored on platforms that don't support it** — so you can set `subtitle` (iOS-only) and `channelId` (Android-only) in the same call without branching.

```typescript theme={null}
await sublay.push.send({
  userIds: ["usr_abc123"],
  title: "New message",
  body: "Alice sent you a message",
  data: { conversationId: "conv_xyz789" },
  sound: "notification.wav",   // custom sound
  channelId: "messages",       // Android channel (see below)
  badge: 3,                    // iOS app-icon badge
  tag: "conv_xyz789",          // one entry per conversation, per account
  priority: "high",
});
```

| Field            | Platforms         | Notes                                                                                                                                                                                                   |
| ---------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sound`          | iOS, Android, Web | Filename of a bundled sound. On Android 8+ the **channel** owns the sound — see below.                                                                                                                  |
| `badge`          | iOS               | App-icon badge count. Your backend supplies the number; Sublay tracks no unread state.                                                                                                                  |
| `channelId`      | Android           | Notification channel id. Created client-side.                                                                                                                                                           |
| `priority`       | iOS, Android      | `"high"` (default) wakes the device; `"normal"` is power-considerate.                                                                                                                                   |
| `subtitle`       | iOS               | Line under the title.                                                                                                                                                                                   |
| `imageUrl`       | iOS, Android, Web | Big-picture image. iOS needs a Notification Service Extension — see below.                                                                                                                              |
| `tag`            | Android, Web      | Display-replace key so notifications collapse instead of stacking. Scoped per recipient, so the string the device receives is the one you sent plus a short digest — don't compare it to what you sent. |
| `collapseId`     | iOS, Android      | Transport-level collapse — a newer push supersedes an undelivered one **for the same account**. Scoped per recipient, and folded to a digest when an over-length key would exceed the APNs 64-byte cap. |
| `threadId`       | iOS               | Notification grouping.                                                                                                                                                                                  |
| `ttl`            | iOS, Android      | Time-to-live in **seconds** for offline devices.                                                                                                                                                        |
| `mutableContent` | iOS               | Enables your Notification Service Extension. Set automatically when `imageUrl` is present.                                                                                                              |

### Client-side requirements

Three of these need setup in **your app** — Sublay forwards the field but cannot do this part for you:

<AccordionGroup>
  <Accordion title="Android sound → notification channels">
    On Android 8+ the **notification channel** owns the sound, importance, and vibration — the payload can't override it. Create the channel once in your app (with the bundled sound) and pass its id as `channelId`:

    ```ts theme={null}
    import * as Notifications from "expo-notifications";

    await Notifications.setNotificationChannelAsync("messages", {
      name: "Messages",
      importance: Notifications.AndroidImportance.HIGH,
      sound: "notification.wav", // bundled in the app
    });
    ```

    Then `push.send({ ..., channelId: "messages", sound: "notification.wav" })`. The `sound` field alone is only a pre-Android-8 fallback. Sublay does **not** create channels for you.
  </Accordion>

  <Accordion title="iOS images → Notification Service Extension">
    iOS does not download remote images from the payload on its own. To show `imageUrl` on iOS, add a [Notification Service Extension](https://developer.apple.com/documentation/usernotifications/unnotificationserviceextension) to your app that reads the URL from the notification payload, downloads it, and attaches it. Sublay sets `mutable-content` automatically whenever `imageUrl` is present so the extension is allowed to run. Android and Web render `imageUrl` with no extra work.
  </Accordion>

  <Accordion title="Web rendering → your service worker">
    Sublay ships no service worker — your app's own SW renders web notifications. The server forwards the web-renderable fields (`sound`, `image`, `tag`) in the push JSON; your `push` event handler decides how to display them via `registration.showNotification(...)`.
  </Accordion>
</AccordionGroup>

## Automatic Pushes

Whenever Sublay writes an in-app notification (a new comment, reply, mention, reaction, milestone, follow, connection request/accept, RSVP-event invite/update/cancel, or space-membership approval) or a chat message is sent, it can fan a native push out to the recipient's registered devices **automatically** — you don't call `push.send()` for these. What each automatic push looks like is configured per project on the **Settings → Push Notifications** page.

<Note>
  Everything in this section applies to the **automatic** path only. The manual [`push.send()`](#server-sdk--sending-notifications) call takes `title`, `body`, `data`, `sound`, `channelId`, `priority`, and the [rich fields](#rich-notification-payloads) directly and is unchanged.
</Note>

### Title & body templates

Each event type has a **body template** (shipped with sensible defaults) and an optional **title template**. Both are interpolated against the same per-event `{variable}` palette shown next to each row in the dashboard.

The title template **ships empty** for every event type — an unset title renders as an empty string, which is the historical behavior. Set a title only for the events where you want one; leaving it blank is a no-op.

```
# Example (dashboard, entity-comment)
Title:  New comment
Body:   {initiatorUsername} commented on your post
```

### Delivery: sound, channel & priority

You can set a project-wide **default delivery** block and, optionally, a **per-event override**:

* **Default** — a single `{ sound, channelId, priority }` applied to every automatic push.
* **Override** — a per-event-type `{ sound, channelId, priority }`. Any field you set on the override wins for that event; any field you leave unset inherits the project default. Precedence is **per-event override → project default → none**.

| Field       | Platforms         | Notes                                                                                                                                                            |
| ----------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sound`     | iOS, Android, Web | Filename of a bundled sound. On Android 8+ the notification **channel** owns the sound — see [Android sound → notification channels](#client-side-requirements). |
| `channelId` | Android           | Notification channel id. Created client-side; omitted from the web/iOS payloads.                                                                                 |
| `priority`  | iOS, Android      | `"high"` wakes the device; `"normal"` is power-considerate.                                                                                                      |

These are the same three fields `push.send()` accepts, wired to the automatic path. The other rich fields (`badge`, `imageUrl`, `tag`, etc.) are configurable on the manual path only.

### Tap-routing `data`

Every automatic push carries a flat `data` object of string identifiers so your app's tap handler can deep-link to the right screen. All `data` values are **flat top-level strings** (FCM coerces `data` values with `String()`, so nested objects are not used).

Three keys are on every automatic push:

| Key               | Value                                                                                                                                                                                  |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`            | The event type, e.g. `entity-comment`, `new-follow`, `event-invite`, `message`.                                                                                                        |
| `action`          | A canonical routing hint — one of `open-comment`, `open-entity`, `open-profile`, `open-space`, `open-event`, `open-chat-message`, `open-conversation` (message path), or `do-nothing`. |
| `recipientUserId` | The id of the account this copy of the notification is for. Stamped per device at dispatch time — see below.                                                                           |

Beyond those three keys, each push forwards **every identifier form** for each object the notification references, so you can route on whichever id your app uses (UUID, short id, foreign id, slug, or username). Per referenced object:

| Object                                 | Keys forwarded                                                                    |
| -------------------------------------- | --------------------------------------------------------------------------------- |
| Entity                                 | `entityId`, `entityShortId`, `entityForeignId`                                    |
| Comment                                | `commentId`, `commentForeignId` (comments have no short id)                       |
| Space                                  | `spaceId`, `spaceShortId`, `spaceSlug`                                            |
| RSVP event                             | `eventId`, `eventShortId`                                                         |
| Initiator (the acting user)            | `initiatorId`, `initiatorUsername`, `initiatorForeignId` (users have no short id) |
| Chat message                           | `messageId`, `conversationId` (both are needed to place a message)                |
| Granter (the user who gave reputation) | `granterId`, `granterUsername`, `granterForeignId`                                |
| Connection                             | `connectionId`                                                                    |

Which of those apply depends on the event type:

| Event type(s)                                                                                                                                       | `action`                                                                             | `data` identifiers (beyond `type`/`action`)                                                  |
| --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
| `entity-comment`, `comment-reply`, `comment-mention`, `comment-reaction`, `comment-reaction-milestone-specific`, `comment-reaction-milestone-total` | `open-comment`                                                                       | Entity + Comment + Space keys (+ Initiator, except on milestones)                            |
| `entity-mention`, `entity-reaction`, `entity-reaction-milestone-specific`, `entity-reaction-milestone-total`                                        | `open-entity`                                                                        | Entity + Space keys (+ Initiator, except on milestones)                                      |
| `new-follow`                                                                                                                                        | `open-profile`                                                                       | Initiator keys                                                                               |
| `connection-request`, `connection-accepted`                                                                                                         | `open-profile`                                                                       | `connectionId` + Initiator keys                                                              |
| `space-membership-approved`                                                                                                                         | `open-space`                                                                         | Space keys                                                                                   |
| `event-invite`, `event-updated`, `event-cancelled`                                                                                                  | `open-event`                                                                         | RSVP-event + parent-Space keys + Initiator keys                                              |
| `reputation-grant`                                                                                                                                  | `open-entity` / `open-comment` / `open-chat-message` / `open-profile` / `do-nothing` | Granter keys + whichever target's keys apply (Entity, Comment, or Chat message) + Space keys |
| `message` (chat)                                                                                                                                    | `open-conversation`                                                                  | `conversationId`, `messageId`                                                                |

<Note>
  **Content and RSVP-event notifications also carry the parent space.** A notification *about* an Entity or Comment (a "content notification") or an RSVP-event notification additionally forwards the parent **Space** id set (`spaceId`, `spaceShortId`, `spaceSlug`) when the subject lives in a space, so you can route within a space. Don't confuse the `message` **event type** or an RSVP **Event** (the data model) with the generic idea of a "notification event."
</Note>

<Note>
  **These `data` keys are additive and non-breaking.** Existing tap handlers that ignore unknown keys are unaffected — nothing that was present before was removed or renamed. A key whose underlying value is absent (e.g. a user with no `foreignId`, a space with no `slug`) is simply omitted rather than sent empty.
</Note>

#### `recipientUserId` is a reserved key

One physical device can be signed into several accounts at once, so a single send can deliver the same notification to the same device more than once — once per recipient account. `recipientUserId` names the account each copy belongs to, which is what lets a tap handler switch to the right account before deep-linking.

* **It is stamped per device by the server**, on both the automatic paths and `push.send()`. A value you supply yourself under the same key is **overwritten**: a client routing accounts on it has to be able to trust it absolutely.
* **A device signed into two accounts shows two notifications** for a message both accounts receive — one per account, each naming its own recipient. This is intentional; suppressing the non-foregrounded account's copy is app-side work.
* **Dashboard test sends omit it.** A test send from the dashboard targets a token you paste, not a registered account, so there is no recipient to name.

The chat-message path builds its `data` from the send context rather than notification metadata, so beyond the per-device `recipientUserId` it carries exactly `{ type: "message", action: "open-conversation", conversationId, messageId }`.

## Device Lifecycle

* **Re-registration:** registering the same physical device again (same token or endpoint) **as the same user** updates the existing record instead of duplicating it.
* **Multiple accounts per device:** registering the same device as a *different* user adds a second binding rather than reassigning the first. A device signed into several accounts receives notifications for all of them, each copy carrying its own `recipientUserId`.
* **Stale token cleanup:** a token or subscription permanently rejected by APNs, FCM, or Web Push during a send is automatically deleted — and because a dead token is dead for the whole device, **every** account bound to that token is unbound, not just the one that was being sent to. No separate cleanup pass is needed.
* **Token rotation:** device tokens rotate (reinstall, OS refresh, backup restore), which kills every binding on the old token. The SDK detects this wherever `usePushRegistration` is mounted with an adapter that reports rotations: it records the new identifier, re-binds the **active** account immediately, and marks every other push-enabled account as needing a re-bind, repairing each on its next activation rather than spending its stored credential in the background. Rotation is reported live on Expo and on Android, and on the next page load on Web (which has no in-page rotation event). iOS APNs rotation under bare React Native is not reported by the OS event at all; it is picked up on the next launch instead, because on native the hook also reads the device's current identifier on mount whenever notification permission is already granted. See [Automatic token rotation](/sdk/push-notifications/overview#automatic-token-rotation).
* **Signing out unbinds automatically:** once this device has a stored push identifier, `signOut()`, `removeAccount()` and `signOutAll()` pass its identifier with the sign-out request, and the server deletes that account's push binding in the **same transaction** as the session teardown. If the server refuses the unbind nothing commits — the sign-out fails and the account keeps its credential so the user can retry, rather than being left receiving notifications from an account it can no longer reach. A device with no stored identifier sends none, has no unbind to protect, and signs out best-effort. Other accounts on the device are unaffected.
* **Per-account control:** `unregister()` silences the **active** account on this device as a durable preference, and [`useAccountPushToggle`](/hooks/push/use-account-push-toggle) does the same for any stored account without switching to it. Neither is a logout step — see the [warning on the SDK page](/sdk/push-notifications/overview#turning-push-off).

## References

Everything related to push notifications across the docs:

<CardGroup>
  <Card title="SDK Reference — Push Notifications" icon="mobile-screen-button" href="/sdk/push-notifications/overview">
    Per-platform client setup for Expo, React Native, and Web
  </Card>

  <Card title="usePushRegistration" icon="cube" href="/hooks/push/use-push-registration">
    Request permission, register, and unregister the current user's device
  </Card>

  <Card title="useAccountPushToggle" icon="toggle-on" href="/hooks/push/use-account-push-toggle">
    Per-account push control on a device holding several accounts
  </Card>

  <Card title="Node SDK — Push Notifications" icon="node-js" href="/node-sdk/push-notifications">
    The `push.send()` server module reference
  </Card>

  <Card title="Webhooks — Push Bridge" icon="webhook" href="/webhooks#push-notification-bridge">
    Forward `notification.created` events to push
  </Card>
</CardGroup>

### API Endpoints

<CardGroup>
  <Card title="Register Device" href="/api-reference/push-notifications/register-device">
    `POST /push-notifications/devices`
  </Card>

  <Card title="Deregister Device" href="/api-reference/push-notifications/deregister-device">
    `DELETE /push-notifications/devices`
  </Card>

  <Card title="Send Push" href="/api-reference/push-notifications/send">
    `POST /push-notifications/send`
  </Card>

  <Card title="Get VAPID Public Key" href="/api-reference/push-notifications/get-vapid-public-key">
    `GET /push-notifications/vapid-public-key`
  </Card>
</CardGroup>


# Notifications Hook
Source: https://docs.sublay.io/v7/sdk/app-notifications/hook

Fetch, paginate, and manage app notifications with useAppNotifications

`useAppNotifications` is the primary hook for building a notification feed. It loads notifications, tracks the unread count, handles pagination, and exposes actions for marking notifications as read.

## Basic Usage

```tsx theme={null}
import { useAppNotifications } from "@sublay/react-js";

function NotificationFeed() {
  const {
    appNotifications,
    unreadAppNotificationsCount,
    loading,
    hasMore,
    loadMore,
    markNotificationAsRead,
    markAllNotificationsAsRead,
  } = useAppNotifications({ limit: 20 });

  return (
    <div>
      <p>{unreadAppNotificationsCount} unread</p>
      <button onClick={markAllNotificationsAsRead}>Mark all as read</button>
      {appNotifications.map((n) => (
        <div
          key={n.id}
          style={{ fontWeight: n.isRead ? "normal" : "bold" }}
          onClick={() => markNotificationAsRead({ notificationId: n.id })}
        >
          {n.title ?? n.type}
        </div>
      ))}
      {hasMore && <button onClick={loadMore}>Load more</button>}
    </div>
  );
}
```

## Parameters

<ParamField type="number">
  Number of notifications to load per page. Defaults to `10`.
</ParamField>

<ParamField type="Partial<NotificationTemplates>">
  Optional map of display text templates for each notification type. See [Notification Templates](/sdk/app-notifications/notification-templates).
</ParamField>

## Returns

<ResponseField name="appNotifications" type="UnifiedAppNotification[]">
  The list of notification records. If `notificationTemplates` is provided, each notification is augmented with a `title` and/or `content` field derived from the template.
</ResponseField>

<ResponseField name="unreadAppNotificationsCount" type="number">
  The total number of unread notifications for the current user.
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` while a fetch is in progress.
</ResponseField>

<ResponseField name="hasMore" type="boolean">
  `true` if there are more notifications to load beyond the currently loaded set.
</ResponseField>

<ResponseField name="loadMore" type="() => void">
  Increments the internal page counter, triggering a fetch of the next page and appending results to `appNotifications`.
</ResponseField>

<ResponseField name="markNotificationAsRead" type="({ notificationId: string }) => Promise<void>">
  Marks a single notification as read. Applies an optimistic update immediately before the API call.
</ResponseField>

<ResponseField name="markAllNotificationsAsRead" type="() => Promise<void>">
  Marks all of the current user's notifications as read. Applies an optimistic update immediately.
</ResponseField>

<ResponseField name="resetAppNotifications" type="() => Promise<void>">
  Clears the current notification list and re-fetches from page 1. Useful for pull-to-refresh.
</ResponseField>

<Note>
  The hook is backed by Redux. Notifications are shared globally in the Redux store — multiple instances of the hook in different components will share the same state.
</Note>

## Related

* [Notification Templates](/sdk/app-notifications/notification-templates) — customize display text per type
* [useAppNotifications hook reference](/hooks/app-notifications/use-app-notifications)


# Notification Templates
Source: https://docs.sublay.io/v7/sdk/app-notifications/notification-templates

Customize the display text shown for each notification type

Sublay stores notifications as structured records with typed `metadata` — not pre-rendered strings. Your app controls how each notification type is displayed using **notification templates**.

Templates are passed to `useAppNotifications` via the `notificationTemplates` prop. Each template can define a `title` and/or `content`. Each field accepts either:

* A **string** with `$variable` placeholders that are filled from the notification's metadata, or
* A **function** that receives a typed variables object and returns a string — useful when you need full control, such as translating specific values or applying conditional logic.

## String template example

```tsx theme={null}
import { useAppNotifications } from "@sublay/react-js";

const templates = {
  entityComment: {
    title: "New comment",
    content: "$initiatorName commented on your post",
  },
  commentReply: {
    title: "New reply",
    content: "$initiatorName replied to your comment",
  },
  newFollow: {
    title: "New follower",
    content: "$initiatorName started following you",
  },
  connectionRequest: {
    title: "Connection request",
    content: "$initiatorName wants to connect",
  },
};

function NotificationFeed() {
  const { appNotifications } = useAppNotifications({ notificationTemplates: templates });

  return (
    <ul>
      {appNotifications.map((n) => (
        <li key={n.id}>
          <strong>{n.title}</strong>
          <p>{n.content}</p>
        </li>
      ))}
    </ul>
  );
}
```

## Function template example

Function templates are useful when string interpolation isn't enough — for example, when you need to translate a reaction type value into another language, or apply conditional phrasing.

```tsx theme={null}
const templates = {
  entityReaction: {
    title: ({ initiatorName, reactionType }) => {
      const reactionLabel =
        reactionType === "upvote" ? "me gusta" :
        reactionType === "heart"  ? "corazón"  : reactionType;
      return `${initiatorName} reaccionó con ${reactionLabel} a tu publicación`;
    },
  },
  commentReaction: {
    // Mix string and function in the same template
    title: ({ initiatorName, reactionType }) => {
      const reactionLabel =
        reactionType === "upvote" ? "me gusta" :
        reactionType === "heart"  ? "corazón"  : reactionType;
      return `${initiatorName} reaccionó con ${reactionLabel} a tu comentario`;
    },
    content: "$commentContent",
  },
};
```

TypeScript will infer the exact variables available for each notification type, so you get autocompletion and type safety when destructuring the parameter.

## Template keys and available variables

Each key in `notificationTemplates` corresponds to one notification type. The variables available to both string placeholders and function templates are listed below.

| Template key                       | Notification type                     | Available variables                                                                                    |
| ---------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `entityComment`                    | `entity-comment`                      | `initiatorName`, `initiatorUsername`, `entityTitle`, `entityContent`, `commentContent`                 |
| `commentReply`                     | `comment-reply`                       | `initiatorName`, `initiatorUsername`, `entityTitle`, `entityContent`, `commentContent`, `replyContent` |
| `entityMention`                    | `entity-mention`                      | `initiatorName`, `initiatorUsername`, `entityTitle`, `entityContent`                                   |
| `commentMention`                   | `comment-mention`                     | `initiatorName`, `initiatorUsername`, `entityTitle`, `entityContent`, `commentContent`                 |
| `entityUpvote`                     | `entity-upvote`                       | `initiatorName`, `initiatorUsername`, `entityTitle`, `entityContent`                                   |
| `commentUpvote`                    | `comment-upvote`                      | `initiatorName`, `initiatorUsername`, `entityTitle`, `entityContent`, `commentContent`                 |
| `entityReaction`                   | `entity-reaction`                     | `initiatorName`, `initiatorUsername`, `entityTitle`, `entityContent`, `reactionType`                   |
| `commentReaction`                  | `comment-reaction`                    | `initiatorName`, `initiatorUsername`, `entityTitle`, `entityContent`, `commentContent`, `reactionType` |
| `entityReactionMilestoneSpecific`  | `entity-reaction-milestone-specific`  | `entityTitle`, `entityContent`, `reactionType`, `milestoneCount`                                       |
| `entityReactionMilestoneTotal`     | `entity-reaction-milestone-total`     | `entityTitle`, `entityContent`, `milestoneCount`                                                       |
| `commentReactionMilestoneSpecific` | `comment-reaction-milestone-specific` | `entityTitle`, `entityContent`, `commentContent`, `reactionType`, `milestoneCount`                     |
| `commentReactionMilestoneTotal`    | `comment-reaction-milestone-total`    | `entityTitle`, `entityContent`, `commentContent`, `milestoneCount`                                     |
| `newFollow`                        | `new-follow`                          | `initiatorName`, `initiatorUsername`                                                                   |
| `connectionRequest`                | `connection-request`                  | `initiatorName`, `initiatorUsername`                                                                   |
| `connectionAccepted`               | `connection-accepted`                 | `initiatorName`, `initiatorUsername`                                                                   |
| `spaceMembershipApproved`          | `space-membership-approved`           | `spaceName`, `spaceShortId`, `spaceSlug`                                                               |

<Note>
  All template keys are optional. If a template is not provided for a given notification type, Sublay uses a built-in default string template for that type. You only need to supply the keys you want to customize.
</Note>

## Accessing raw metadata

For building fully custom UIs, access the raw `metadata` directly on each notification. Every notification includes:

* `id` — the notification's unique ID
* `type` — the notification type string
* `isRead` — whether the user has read it
* `action` — a hint string for the action to take on tap (e.g., `"open-entity"`, `"open-comment"`, `"open-profile"`)
* `metadata` — type-specific fields (entity IDs, initiator info, etc.)
* `createdAt` — ISO timestamp


# Overview
Source: https://docs.sublay.io/v7/sdk/app-notifications/overview

In-app notification records triggered by user interactions and system events

App Notifications are persistent, database-backed records delivered to users when activity happens in your app — new comments, replies, mentions, reactions, follows, connection requests, and more. They are distinct from push notifications; they live in the Sublay database and are surfaced through the SDK.

<Note>
  **Requires the `notifications` bundle.** App notifications are only available when the `notifications` bundle is installed on your project. See [Bundles](/bundles) to add it.
</Note>

## How It Works

Sublay automatically creates notification records when relevant events occur (e.g., someone comments on an entity, someone follows a user). Your app polls or fetches those records and displays them in a notification feed. When push delivery is also needed, a webhook fires at the same time so your backend can forward the event to FCM or APNs.

## In This Section

<CardGroup>
  <Card title="Hook" href="/sdk/app-notifications/hook">
    How to use `useAppNotifications` — fetch notifications, unread count, and mark as read
  </Card>

  <Card title="Notification Templates" href="/sdk/app-notifications/notification-templates">
    Customize the display text for each notification type
  </Card>

  <Card title="Webhook Integration" href="/sdk/app-notifications/webhook-integration">
    Forward notifications to push services via webhook
  </Card>
</CardGroup>

## Hooks

<CardGroup>
  <Card title="useAppNotifications" href="/hooks/app-notifications/use-app-notifications">
    Full API reference for `useAppNotifications`
  </Card>
</CardGroup>

## Notification Types

Sublay generates notifications for the following events:

| Type                                  | Trigger                                                       |
| ------------------------------------- | ------------------------------------------------------------- |
| `entity-comment`                      | Someone comments on your entity                               |
| `comment-reply`                       | Someone replies to your comment                               |
| `entity-mention`                      | You are mentioned in an entity                                |
| `comment-mention`                     | You are mentioned in a comment                                |
| `entity-upvote`                       | Someone upvotes your entity                                   |
| `comment-upvote`                      | Someone upvotes your comment                                  |
| `entity-reaction`                     | Someone reacts to your entity                                 |
| `comment-reaction`                    | Someone reacts to your comment                                |
| `entity-reaction-milestone-specific`  | Your entity reaches a milestone for a specific reaction type  |
| `entity-reaction-milestone-total`     | Your entity reaches a total reaction milestone                |
| `comment-reaction-milestone-specific` | Your comment reaches a milestone for a specific reaction type |
| `comment-reaction-milestone-total`    | Your comment reaches a total reaction milestone               |
| `new-follow`                          | Someone follows you                                           |
| `connection-request`                  | Someone sends you a connection request                        |
| `connection-accepted`                 | Someone accepts your connection request                       |
| `space-membership-approved`           | A moderator approves your pending space membership request    |
| `system`                              | A custom message sent from the dashboard                      |


# Webhook Integration
Source: https://docs.sublay.io/v7/sdk/app-notifications/webhook-integration

Forward app notification events to your backend for push delivery

App Notifications in Sublay are in-app records — they appear in a notification feed inside your app. To deliver push notifications (iOS APNs, Android FCM) when users are not actively using the app, you can configure a webhook that fires whenever a notification is created.

## How It Works

<Steps>
  <Step title="Configure a webhook URL in the dashboard">
    In your Sublay project dashboard, go to **Settings → Webhooks** and add a webhook URL pointing to your backend endpoint. Select the **App Notification Created** event.
  </Step>

  <Step title="Receive the event on your backend">
    When Sublay creates an app notification, it sends an HTTP POST to your webhook URL with a JSON payload describing the notification:

    ```json theme={null}
    {
      "type": "app-notification.created",
      "projectId": "your-project-id",
      "data": {
        "projectId": "your-project-id",
        "userId": "recipient-user-id",
        "type": "entity-comment",
        "action": "open-comment",
        "metadata": {
          "entityId": "...",
          "commentId": "...",
          "initiatorId": "...",
          "initiatorName": "Alice"
        }
      }
    }
    ```
  </Step>

  <Step title="Look up the recipient's push token">
    Use `data.userId` to look up the FCM or APNs token stored in your own database for that user.
  </Step>

  <Step title="Send the push notification">
    Use your push provider (Firebase Admin SDK, APNs, Expo Push, etc.) to send a push notification to the device. Build the message text using `data.type` and `data.metadata` from the webhook payload.
  </Step>
</Steps>

## Payload Fields

| Field            | Type     | Description                                                                                                          |
| ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `type`           | `string` | Always `"app-notification.created"`                                                                                  |
| `projectId`      | `string` | The Sublay project ID                                                                                                |
| `data.projectId` | `string` | The Sublay project ID (repeated inside data)                                                                         |
| `data.userId`    | `string` | The recipient's user ID                                                                                              |
| `data.type`      | `string` | The notification type (e.g., `"entity-comment"`)                                                                     |
| `data.action`    | `string` | Navigation hint for the push tap action                                                                              |
| `data.metadata`  | `object` | Type-specific data — see [Notification Templates](/sdk/app-notifications/notification-templates) for fields per type |

<Note>
  This page describes the **bring-your-own-provider** bridge: you store the push
  tokens in your own backend and dispatch through your own provider. Sublay can
  also do this for you — the [`push` bundle](/push-notifications) stores each
  user's registered devices per account and dispatches to APNs, FCM and Web Push
  itself, in which case no webhook bridge is needed.
</Note>


# Built-in Auth
Source: https://docs.sublay.io/v7/sdk/authentication/built-in

Email/password sign-up, sign-in, and sign-out flows

Sublay's built-in authentication lets you register and sign in users with an email address and password without building your own auth backend. The SDK's `useAuth` hook exposes all the actions you need.

## Sign Up

Call `signUpWithEmailAndPassword` with at minimum an `email` and `password`. Additional profile fields are optional.

```tsx theme={null}
import { useAuth } from "@sublay/react-js";

function SignUpForm() {
  const { signUpWithEmailAndPassword } = useAuth();

  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const form = e.currentTarget;
    try {
      await signUpWithEmailAndPassword({
        email: form.email.value,
        password: form.password.value,
        name: form.name.value,
      });
      // User is now signed in
    } catch (err) {
      console.error(err);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <input name="name" placeholder="Name" />
      <input name="email" type="email" placeholder="Email" />
      <input name="password" type="password" placeholder="Password" />
      <button type="submit">Sign Up</button>
    </form>
  );
}
```

### Optional Profile Fields

You can pass additional profile data at registration time:

| Field            | Type                                      | Description                                       |
| ---------------- | ----------------------------------------- | ------------------------------------------------- |
| `name`           | `string`                                  | Display name                                      |
| `username`       | `string`                                  | Unique username within the project                |
| `avatar`         | `string`                                  | URL of avatar image                               |
| `bio`            | `string`                                  | Short bio text                                    |
| `location`       | `{ latitude: number; longitude: number }` | Geographic location                               |
| `birthdate`      | `Date`                                    | Date of birth                                     |
| `metadata`       | `Record<string, any>`                     | Public custom data                                |
| `secureMetadata` | `Record<string, any>`                     | Private custom data (not returned to other users) |
| `avatarFile`     | `File \| Blob`                            | Upload an avatar image directly                   |
| `bannerFile`     | `File \| Blob`                            | Upload a profile banner image                     |

<Note>
  If you supply both `avatar` (URL) and `avatarFile` (file upload), the file
  takes precedence and the URL is ignored.
</Note>

## Sign In

```tsx theme={null}
import { useAuth } from "@sublay/react-js";

function SignInForm() {
  const { signInWithEmailAndPassword } = useAuth();

  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const form = e.currentTarget;
    try {
      await signInWithEmailAndPassword({
        email: form.email.value,
        password: form.password.value,
      });
    } catch (err) {
      console.error(err);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <input name="email" type="email" placeholder="Email" />
      <input name="password" type="password" placeholder="Password" />
      <button type="submit">Sign In</button>
    </form>
  );
}
```

## The Account Limit

A device stores at most **5 accounts** ([Multi-Account](/sdk/authentication/multi-account)). Both calls above refuse a sixth, throwing an `Error` whose message is exported as `ACCOUNT_LIMIT_MESSAGE`:

```tsx theme={null}
import { useAuth, ACCOUNT_LIMIT_MESSAGE } from "@sublay/react-js";

try {
  await signInWithEmailAndPassword({ email, password });
} catch (err) {
  if (err instanceof Error && err.message === ACCOUNT_LIMIT_MESSAGE) {
    setError("You're signed in to 5 accounts. Sign out of one to continue.");
  } else {
    setError("Incorrect email or password.");
  }
}
```

|                        | Sign-up                                             | Sign-in                                                                        |
| ---------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------ |
| Checked                | Before the request — normally no account is created | After the request, on the account the server resolved                          |
| Already-stored account | n/a (a sign-up is always new)                       | **Succeeds** — re-authenticating an account you already store is never blocked |

<Note>
  Sign-in is deliberately checked *after* the network call. Comparing the typed email against the stored accounts first would be faster and wrong: it would refuse users whose stored email is out of date, absent, or capitalised differently, with no way through.
</Note>

<Warning>
  **One sign-up case does leave a user record behind.** The pre-request check can only use the accounts stored when the call left. If the fifth slot fills while your sign-up is in flight — another tab, or a second sign-in racing this one — the account has already been created on the server by the time the limit is discovered. The SDK signs that session straight back out, but the **user record persists**, so retrying the same email after freeing a slot fails with "email already in use". Sign in with it instead.
</Warning>

A refusal leaves the currently active account signed in, leaves the accounts map untouched, signs the server-side session created by the refused attempt back out, and sets `accountLimitReached` — see [Reaching the account limit](/sdk/authentication/multi-account#reaching-the-account-limit).

## Sign Out

`signOut` revokes the current session's entire token family on the server and clears local auth state. Once this device has a stored push identifier it also asks the server to unbind that account's push notifications, in the same transaction as the session teardown.

```tsx theme={null}
import { useAuth } from "@sublay/react-js";

function SignOutButton() {
  const { signOut } = useAuth();

  return (
    <button onClick={() => signOut().catch(showError)}>Sign Out</button>
  );
}
```

`signOut` **rejects** when the server refuses that unbind, and in that case nothing was torn down on either side — the session survives so the user can retry. Its signature is `() => Promise<void>`, so nothing warns you at compile time; without the `catch` the rejection is unhandled and your UI reports a sign-out that did not happen. Every other failure — no network, a throttled or otherwise rejected request, a device that never registered for push — still signs out locally, because a user must always be able to sign out. See [`useAuth`](/hooks/auth/use-auth).

## Change Password

Users who signed up with email/password can change their password while authenticated. The current password must be provided for verification.

**A password change ends every *other* session for that user**, so their other devices must sign in again with the new password. The session making the call survives — the server reads which session is asking off the access token the request already carries, so nothing extra is sent. It also removes that user's push bindings on every other device while keeping this one's, which the hook arranges by sending the device identifier it already holds. See [`useAuth`](/hooks/auth/use-auth) and [Change Password](/api-reference/auth/change-password).

```tsx theme={null}
import { useAuth } from "@sublay/react-js";

function ChangePasswordForm() {
  const { changePassword } = useAuth();

  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const form = e.currentTarget;
    try {
      await changePassword({
        password: form.current.value,
        newPassword: form.next.value,
      });
    } catch (err) {
      console.error(err);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <input name="current" type="password" placeholder="Current password" />
      <input name="next" type="password" placeholder="New password" />
      <button type="submit">Change Password</button>
    </form>
  );
}
```

## Password Reset

Users who forget their password can request a reset email. Sublay sends a link to the registered email address. The link expires after 1 hour.

Completing the reset revokes **every** session for that user and removes **every** push binding they hold, on every device — including the one they are standing on. They sign in again everywhere, and each device re-binds for push on its own once it is next opened. The reset itself is completed by the page the link points to, which collects the new password and calls the [Reset Password](/api-reference/auth/reset-password) endpoint — there is no React hook for that step.

```tsx theme={null}
import { useRequestPasswordReset } from "@sublay/react-js";

function ForgotPasswordForm() {
  const requestPasswordReset = useRequestPasswordReset();

  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const form = e.currentTarget;
    const result = await requestPasswordReset({ email: form.email.value });
    console.log(result.message);
    // Always returns a success message to prevent email enumeration
  };

  return (
    <form onSubmit={handleSubmit}>
      <input name="email" type="email" placeholder="Email" />
      <button type="submit">Send Reset Link</button>
    </form>
  );
}
```

<Note>
  The API always responds with a success message regardless of whether the email
  address is registered, to prevent user enumeration.
</Note>

## Auth State

Check whether the SDK has finished initializing and whether a user is currently signed in:

```tsx theme={null}
import { useAuth } from "@sublay/react-js";

function AuthGuard({ children }: { children: React.ReactNode }) {
  const { initialized, accessToken } = useAuth();

  if (!initialized) return <p>Loading...</p>;
  if (!accessToken) return <p>Please sign in.</p>;

  return <>{children}</>;
}
```

## Email Verification

After sign-up, you can prompt users to verify their email address. Sublay sends a short-lived token (5 minutes) via email. There are two delivery modes: a **code** the user types back into your app, or a **link** they click to verify automatically.

### Send a verification email

`mode` is always required, and it determines what else you need to pass:

```tsx theme={null}
import { useSendVerificationEmail } from "@sublay/react-js";

function VerifyEmailPrompt() {
  const sendVerificationEmail = useSendVerificationEmail();

  return (
    <button
      onClick={() =>
        sendVerificationEmail({
          mode: "code",
          tokenFormat: "numeric",
          tokenLength: 6,
        })
      }
    >
      Send verification email
    </button>
  );
}
```

```tsx theme={null}
// 6-digit numeric code — easy for users to type
await sendVerificationEmail({ mode: "code", tokenFormat: "numeric", tokenLength: 6 });

// A code using the full hex charset — tokenLength isn't allowed here, since
// hex ignores it and always produces a fixed 64-character token
await sendVerificationEmail({ mode: "code", tokenFormat: "hex" });

// Clickable link — verifies automatically when opened. tokenFormat/tokenLength
// are optional for links, since the token is never read by a human
await sendVerificationEmail({
  mode: "link",
  redirectUrl: "https://yourapp.com/email-verified",
});
```

| Option        | Type                                              | Required                                                                                                                           | Description                                                                |
| ------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `mode`        | `"code" \| "link"`                                | always                                                                                                                             | Whether to send a code to enter, or a link to click                        |
| `tokenFormat` | `"hex" \| "numeric" \| "alpha" \| "alphanumeric"` | when `mode: "code"` (optional, defaults to `"hex"`, for `mode: "link"`)                                                            | Character set for the token                                                |
| `tokenLength` | `number` (4–12)                                   | when `mode: "code"` and `tokenFormat` isn't `"hex"` (not allowed when it is `"hex"`; optional for `mode: "link"`, defaults to `6`) | Length of the token                                                        |
| `redirectUrl` | `string`                                          | never                                                                                                                              | Where to redirect after link verification (only valid with `mode: "link"`) |

TypeScript enforces this combination at compile time — `sendVerificationEmail({ mode: "code" })` or `sendVerificationEmail({ mode: "code", tokenFormat: "numeric" })` (missing `tokenLength`) won't type-check.

### Verify with a code

When using `mode: "code"`, collect the token from the user and call `useVerifyEmail`:

```tsx theme={null}
import { useVerifyEmail } from "@sublay/react-js";

function VerifyCodeForm() {
  const verifyEmail = useVerifyEmail();
  const [code, setCode] = useState("");

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    try {
      await verifyEmail({ token: code });
      // user.isVerified is now true in the local Redux store
    } catch (err) {
      console.error(err);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        value={code}
        onChange={(e) => setCode(e.target.value)}
        placeholder="Enter code"
      />
      <button type="submit">Verify</button>
    </form>
  );
}
```

On success, `user.isVerified` is updated immediately in the local Redux store — no refetch needed.

### Link mode

When using `mode: "link"`, the email contains a button the user clicks. The server verifies the token and either:

* Redirects to the `redirectUrl` you provided with `?verified=true` appended, or
* Renders a hosted success page if no `redirectUrl` was given.

The `user.isVerified` field will be `true` the next time the user's session is loaded (e.g. on next sign-in or token refresh). There is no SDK callback for link-mode verification since it happens outside the app's JS context.

<Note>
  The verification token is valid for 5 minutes and can only be used once.
  Calling `sendVerificationEmail` while a previous token is still valid will
  generate a new token — the old one remains valid until it expires or the new
  one is used.
</Note>

## See Also

* [`useAuth` hook reference](/hooks/auth/use-auth)
* [`useRequestPasswordReset` hook reference](/hooks/auth/use-request-password-reset)
* [`useSendVerificationEmail` hook reference](/hooks/auth/use-send-verification-email)
* [`useVerifyEmail` hook reference](/hooks/auth/use-verify-email)
* [Sign Up API reference](/api-reference/auth/sign-up)
* [Sign In API reference](/api-reference/auth/sign-in)


# External Auth
Source: https://docs.sublay.io/v7/sdk/authentication/external

Integrating your own auth system via signed JWT

If you already have a user authentication system (such as Clerk, Auth0, Firebase Auth, or your own backend), you can integrate it with Sublay without requiring users to create a separate Sublay account. Your backend signs a JWT with a project-specific private key; the SDK exchanges that JWT for Sublay tokens.

## How It Works

<Steps>
  <Step title="Your backend signs a JWT">
    After your own auth system verifies the user, your server signs a JWT using
    your Sublay project's RSA private key. The token identifies the user by
    their ID in your system.
  </Step>

  <Step title="The SDK exchanges the JWT">
    Call `verifyExternalUser` (available via the `useAuth` hook or directly) with
    the signed JWT. Sublay verifies the signature, looks up or creates the user,
    and returns Sublay access and refresh tokens.
  </Step>

  <Step title="The user is authenticated">
    From this point, the user is signed into Sublay and all SDK hooks work
    normally. Token refresh is handled automatically.
  </Step>
</Steps>

## JWT Requirements

Your backend must sign the JWT using **RS256** (RSA 256-bit) with your project's private key. The payload must include:

| Claim      | Description                                                  |
| ---------- | ------------------------------------------------------------ |
| `sub`      | The user's ID in your system (becomes `foreignId` in Sublay) |
| `iss`      | Your Sublay project ID                                       |
| `userData` | Object with optional profile fields (see below)              |

### `userData` fields

All fields in `userData` are optional. If a user already exists and any field has changed, Sublay updates the stored value.

| Field            | Type     | Description                        |
| ---------------- | -------- | ---------------------------------- |
| `email`          | `string` | User's email address               |
| `name`           | `string` | Display name                       |
| `username`       | `string` | Unique username within the project |
| `avatar`         | `string` | URL of avatar image                |
| `bio`            | `string` | Short bio text                     |
| `location`       | object   | `{ latitude, longitude }`          |
| `birthdate`      | `string` | ISO 8601 date string               |
| `metadata`       | object   | Public custom data                 |
| `secureMetadata` | object   | Private custom data                |

## Backend Example (Node.js)

```ts theme={null}
import jwt from "jsonwebtoken";
import fs from "fs";

const privateKey = fs.readFileSync("sublay-private-key.pem");

function createSublayJwt(userId: string, userData: object) {
  return jwt.sign(
    {
      sub: userId,
      iss: "your-sublay-project-id",
      userData,
    },
    privateKey,
    { algorithm: "RS256", expiresIn: "5m" }
  );
}
```

<Warning>
  Keep your RSA private key on your server. Never expose it to the client.
  The JWT should be generated server-side and passed to the frontend at
  sign-in time.
</Warning>

## Frontend Integration

Pass the signed JWT directly to `SublayProvider` (or `SublayIntegrationProvider` if you manage your own Redux store) via the `signedToken` prop. The SDK exchanges the token automatically on initialization — no manual API calls required.

<CodeGroup>
  ```tsx Standard setup theme={null}
  import { SublayProvider } from "@sublay/react-js";

  function App() {
    // Fetch or derive the signed JWT from your own auth system
    const signedToken = useMyAuthSystem().sublayJwt;

    return (
      <SublayProvider projectId="your-project-id" signedToken={signedToken}>
        <YourApp />
      </SublayProvider>
    );
  }
  ```

  ```tsx Integration mode (own Redux store) theme={null}
  import { SublayIntegrationProvider } from "@sublay/react-js";

  function App() {
    // Fetch or derive the signed JWT from your own auth system
    const signedToken = useMyAuthSystem().sublayJwt;

    return (
      <Provider store={yourStore}>
        <SublayIntegrationProvider projectId="your-project-id" signedToken={signedToken}>
          <YourApp />
        </SublayIntegrationProvider>
      </Provider>
    );
  }
  ```
</CodeGroup>

Whenever `signedToken` changes (e.g., after a new user signs in), the SDK re-initializes auth with the updated token automatically.

<Tip>
  The `verify-external-user` exchange happens inside the provider — you never
  need to call the endpoint manually. The provider creates the user if they do
  not exist, updates their profile if any `userData` fields have changed, and
  handles token refresh from that point forward.
</Tip>

## The Account Limit

A device stores at most **5 accounts** ([Multi-Account](/sdk/authentication/multi-account)). If the verified token identifies a **sixth**, distinct user, the exchange is refused: the session Sublay just created is signed back out, the stored accounts are left untouched, and the app renders signed-out with `accountLimitReached` set.

```tsx theme={null}
import { useAccounts } from "@sublay/react-js";

function AccountLimitBanner() {
  const { accountLimitReached, accounts } = useAccounts();
  if (!accountLimitReached) return null;
  return <p>This device already holds {accounts.length} accounts. Sign out of one to continue.</p>;
}
```

Two consequences specific to this integration:

* **A `signedToken` for an already-stored user is never refused.** The check is keyed on the user id Sublay resolves from the token, not on anything in `userData`, so returning users sign in normally at the limit.
* **The refusal is not silent, and it does not fall back.** Because the provider exchanges the token on every launch, a refused exchange would otherwise repeat invisibly forever — or quietly restore some *other* stored account instead. Instead the SDK surfaces the reason and sets `accountLimitReached`. The auth gate still opens, so the app renders normally in its signed-out state rather than hanging.
* **The refusal is not recorded as a sign-out.** Nobody signed out — an admission was refused — so the selection is left exactly where it was and `signedOut` is not set. The next launch therefore behaves as it would have without the refused attempt, rather than reproducing the same dead end forever. See [Reaching the account limit](/sdk/authentication/multi-account#reaching-the-account-limit).

Apps in integration mode that never store multiple accounts cannot hit this: the limit is only reached once five distinct users have been admitted on the same device.

## User Identity

When a user signs in via external auth, Sublay stores the `sub` claim as `foreignId` on the user record and creates a `UserIdentity` entry with `provider: "external"`. On subsequent sign-ins, the user is looked up by identity first, then by `foreignId` as a fallback, then by email.

## See Also

* [Verify External User API reference](/api-reference/auth/verify-external-user)
* [Authentication overview](/sdk/authentication/overview)


# Multi-Account
Source: https://docs.sublay.io/v7/sdk/authentication/multi-account

Managing multiple user accounts in a single app instance

Sublay stores up to **5 accounts at once** in a single app instance. Users can add new accounts, switch between them, and remove individual accounts without losing session data for the others.

## Architecture

Each signed-in account is stored in the Redux `accounts` map, keyed by user ID. The `activeAccountId` field tracks which account is currently active, and the map is persisted by the `AccountManager` your platform package mounts — see [Where accounts are stored](#where-accounts-are-stored).

When the user switches accounts, the SDK exchanges the target account's stored refresh token for a live session **before** it tears the current one down. If that fails — an expired or revoked stored token, for example — the switch **rejects** and the account you were using stays signed in; see [When a transition fails](#when-a-transition-fails).

## Hooks

| Hook                                                          | Purpose                                                      |
| ------------------------------------------------------------- | ------------------------------------------------------------ |
| `useAccounts`                                                 | Read the list of accounts and the active account             |
| `useAddAccount`                                               | Clear current auth state to allow signing into a new account |
| `useSwitchAccount`                                            | Switch the active session to a different stored account      |
| `useRemoveAccount`                                            | Sign out and remove one account from the stored list         |
| `useSignOutAll`                                               | Sign out all accounts simultaneously                         |
| [`useAccountPushToggle`](/hooks/push/use-account-push-toggle) | Turn push on or off per account on this device               |

## Reading Account State

```tsx theme={null}
import { useAccounts } from "@sublay/react-js";

function AccountList() {
  const { accounts, activeAccount, accountCount } = useAccounts();

  return (
    <div>
      <p>Active: {activeAccount?.name ?? "None"}</p>
      <p>Total accounts: {accountCount}</p>
      <ul>
        {accounts.map((account) => (
          <li key={account.id}>{account.name ?? account.email}</li>
        ))}
      </ul>
    </div>
  );
}
```

Each account in `accounts` is a `StoredAccount`: the profile summary — `id`, `name`, `username`, `email`, `avatar` — plus two credential markers, `tokenExpiresAt` and `needsReauth`, and one notification marker, `needsPushRebind`.

`username`, `email` and `avatar` may be `null`, and `username` may be absent entirely on an entry stored by an older SDK version — absent means *unknown*, not "the user has no username".

### Knowing which stored accounts still work

A stored account can stop working while it sits in the switcher. The two markers let you show that before the user taps it, and you need both:

| Marker           | Kind                                                                                                                | What it catches                                                                                                                                                                                                                                                                          |
| ---------------- | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tokenExpiresAt` | Proactive — decoded from the stored refresh token's `exp` claim, no network call                                    | The token simply aged out. `0` means the expiry could not be read from the token, and sorts as already-expired                                                                                                                                                                           |
| `needsReauth`    | Reactive — set when a transition into that account is actually refused, by a switch or by the restore at app launch | Everything expiry cannot see: reuse detection, a password change, a remote sign-out-all, an admin revocation. All of those kill the token family while `exp` is still far in the future. It is also set without a network call when the stored entry carries no usable credential at all |

```tsx theme={null}
const needsSignIn = (account) =>
  account.needsReauth || account.tokenExpiresAt <= Date.now();
```

`needsReauth` clears the moment the account is successfully activated again — by a switch that works, or by signing into it afresh. A switch that failed because the request never reached the server does **not** set it: a flaky network is not a dead account.

A third marker, `needsPushRebind`, is about notifications rather than credentials — see [Push Notifications Per Account](#push-notifications-per-account).

Neither marker is a guarantee. `needsReauth: false` with a future expiry means *nothing has gone wrong that the SDK knows of*, so a switch can still fail — and when it does, the entry stays in the map precisely so you can render a re-auth affordance for it. See [When a transition fails](#when-a-transition-fails).

## Where Accounts Are Stored

Persistence is owned by an `AccountManager` component that each platform package mounts inside its provider. It carries that platform's storage adapter, which is why `@sublay/core`'s own providers cannot supply one.

| Platform package       | Backing store                                                                |
| ---------------------- | ---------------------------------------------------------------------------- |
| `@sublay/react-js`     | `localStorage`                                                               |
| `@sublay/react-native` | Keychain (`react-native-keychain`)                                           |
| `@sublay/expo`         | `expo-secure-store`, one encrypted value **per account** plus an index value |

### The five-account limit is a real limit, not an approximation

Expo's SecureStore documents a **2048-byte ceiling per value**, and a whole account map does not reliably fit inside one. `@sublay/expo` therefore writes one value per account behind a small index value, so five accounts fit comfortably with each value well inside the limit.

If a single account entry ever did exceed the budget, the adapter sheds `avatar` first, then `email`, and logs what it dropped — those are the two unbounded fields. `id`, `name`, `username`, the refresh token and the two re-auth markers are never shed: an entry missing those would load but be unusable, or would silently claim to be healthy.

<Note>
  **Upgrading keeps your users signed in.** A value written by a previous release — the whole map as one value — is converted to the new layout the first time the app loads it, with the accounts and the active selection intact. The conversion runs once and is invisible: later launches read the new layout directly. A stored value that is *not* a recognizable account map (corrupt bytes, a truncated write) is still read as signed-out rather than guessed at, so those rare installs sign in again once. React Native (Keychain) and web (`localStorage`) have no comparable limit, never changed layout, and are unaffected.
</Note>

### Integration mode persists too

Apps that bring their own Redux store use `SublayIntegrationProvider`. **Import it from your platform package, not from `@sublay/core`** — core's version has no `AccountManager` and therefore no storage, so the account map would live only in memory and multi-account would not survive a relaunch. See [Redux Integration](/sdk/redux-integration).

## Adding a New Account

Calling `addAccount` clears the current auth state, which causes the app to display the sign-in UI. The previously stored accounts remain in the accounts map and are not affected. After the user signs in to the new account, it is added to the map automatically.

It clears the **session** and nothing else: the account the user came from stays selected, and `signedOut` is untouched. So abandoning the flow — backing out and quitting — leaves them where they were, and the next launch restores that account. On the web this also means opening the flow says nothing to the app's other tabs, which keep their sessions.

```tsx theme={null}
import { useAddAccount } from "@sublay/react-js";

function AddAccountButton() {
  const { addAccount, canAddAccount } = useAddAccount();

  return (
    <button onClick={addAccount} disabled={!canAddAccount}>
      Add Account
    </button>
  );
}
```

`canAddAccount` is `false` when 5 accounts are already stored.

## Switching Accounts

```tsx theme={null}
import { useAccounts, useSwitchAccount } from "@sublay/react-js";

function AccountSwitcher() {
  const { accounts, activeAccount } = useAccounts();
  const { switchAccount, isSwitching, error } = useSwitchAccount();

  return (
    <ul>
      {accounts.map((account) => (
        <li key={account.id}>
          {account.name}
          {account.id !== activeAccount?.id && (
            <button
              onClick={() =>
                switchAccount({ userId: account.id }).catch(() => {
                  /* `error` below carries the reason; you stay signed in
                     where you were. */
                })
              }
              disabled={isSwitching}
            >
              Switch
            </button>
          )}
        </li>
      ))}
      {error && <p>{error}</p>}
    </ul>
  );
}
```

Switching is asynchronous, and the order is deliberate: the SDK exchanges the target account's stored refresh token for a live session **first**, and only once that succeeds does it clear the current session, select the target and install the new tokens. A target whose credential is dead therefore costs you nothing — the switch rejects and the account you were using is still signed in.

## Removing an Account

```tsx theme={null}
import { useAccounts, useRemoveAccount } from "@sublay/react-js";

function RemoveAccountButton({ userId }: { userId: string }) {
  const { removeAccount, isRemoving, error } = useRemoveAccount();

  return (
    <>
      <button
        onClick={() =>
          removeAccount({ userId }).catch(() => {
            /* `error` below carries the reason; nothing was torn down. */
          })
        }
        disabled={isRemoving}
      >
        Remove Account
      </button>
      {error && <p>{error}</p>}
    </>
  );
}
```

When the removed account is the currently active one, **the session ends and no account is left active** — the remaining accounts stay in the map, but the SDK does not sign the user into one of them. Render your own next screen (an account picker, or your sign-in UI) when `activeAccount` is `null`.

Removing, signing out and deleting an account all leave `activeAccount` as `null` rather than landing the user inside a different identity, so your app owns what comes next.

Removing an account sends a sign-out request that revokes the refresh token family **and** unbinds that account's push notifications on this device, in a single server transaction.

<Warning>
  **Removal is atomic once push is involved.** When this device has a stored push identifier, the request asks for an unbind — and if the server refuses it, **nothing is torn down**. The account keeps its entry and its credential, `removeAccount` **rejects**, and `error` carries the reason so the user can retry. `await removeAccount(...)` therefore needs a `catch`.

  The strictness is **scoped to a server refusal of the unbind itself** — `auth/device-deregistration-failed` or `auth/sign-out-failed`. Anything that never reached the sign-out handler is best-effort: no network, a throttled request, a body the server rejected. An offline user can still remove an account locally, and a device with no stored push identifier has nothing for the guarantee to protect. A `200` carrying `auth/push-unbind-status-unknown` is a success, not a refusal: the server signed the account out without attempting an unbind because it could not determine whether the project has push devices, so the removal completes and the SDK warns.
</Warning>

## Signing Out All Accounts

```tsx theme={null}
import { useSignOutAll } from "@sublay/react-js";

function SignOutAllButton() {
  const { signOutAll } = useSignOutAll();

  const handleClick = () =>
    signOutAll().catch((err) => {
      // Some accounts were kept — see the warning below.
      showError(err);
    });

  return <button onClick={handleClick}>Sign Out All Accounts</button>;
}
```

`signOutAll` sends a sign-out request for every stored account's refresh token — each one revoking that account's token family and unbinding its push on this device — and then clears local auth state.

<Warning>
  **A partial failure keeps the accounts it could not sign out.** When the requests carry this device's push identifier, accounts whose request **succeeded** are removed and accounts whose unbind the server **refused** are kept with their credentials intact; the call then **rejects** with how many failed, so the user can retry. The live session ends either way — an access token is transient, not the credential the guarantee is about.

  Same scoping as removal: a transport failure is not a refusal, so an offline `signOutAll` still clears local state and resolves, and neither is a `200` reporting a skipped unbind. With no push identifier on the device nothing is at stake either.
</Warning>

## When a Transition Fails

Every path that establishes a session for a stored account — `switchAccount`, and the automatic restore at app launch — has to exchange that account's stored refresh token for a live access token. That exchange can fail: the token expired, the server revoked it, or the stored entry is unusable.

**`switchAccount` rejects, and nothing else changes.** The target's credential is proven out of band *before* the current session is torn down, so a failure is a complete no-op against what you were using:

* The previously active account is **still active, with a live session** — same tokens, same user, same cached data. Nothing was signed out.
* **Both account entries survive.** The account that failed to restore stays in the map, which is what lets you render a "session expired — sign in again" affordance for it, and its `needsReauth` marker is set when the server was the one that refused.
* If **nothing was active** when the transition was attempted — the picker state the user lands in after signing out — nothing is selected and the app is marked signed out, so the next launch does not silently activate a different account.

```tsx theme={null}
import { AccountTransitionError } from "@sublay/react-js";

try {
  await switchAccount({ userId });
} catch (err) {
  // The switch did not happen and the account you were using is still signed
  // in. `error` is also set on the hook.
  if (err instanceof AccountTransitionError && err.credentialRejected) {
    promptSignIn(userId);   // the credential is dead
  } else {
    showRetry();            // the request never got an answer
  }
}
```

### Telling a dead account from a dead network

`AccountTransitionError` is the typed error an account-transition failure rejects with — from
`switchAccount`, `removeAccount` and `activateStoredAccount` alike, and from
[`setAccountPushEnabled`](/hooks/push/use-account-push-toggle) for the one failure it shares
(`accountNotFound`). It extends `Error`, so
`message` and `instanceof Error` work as usual, and it carries **two independent boolean
discriminants**, because the three failures it covers call for three different responses.

Check with `instanceof` before reading those flags, because not every rejection is one:
`removeAccount` rejects with the **underlying error, unchanged**, when the server refuses to unbind
the account's push notifications — that is the atomic-removal refusal described under
[Removing an Account](#removing-an-account), and it is reported as the server sent it.
`switchAccount` and `removeAccount` also throw a plain `Error` when no `projectId` is configured.

<ResponseField name="AccountTransitionError.credentialRejected" type="boolean">
  `true` when the **server refused** the stored credential — expired, revoked, reuse-detected,
  invalidated by a password change or a remote sign-out-all — or when the stored entry carries no
  usable credential at all. This is the only case in which `needsReauth` is set on that account.

  `false` when the exchange never got an answer, or the rotated successor could not be persisted.
  Nothing is marked, and the same account may well work on the next attempt.
</ResponseField>

<ResponseField name="AccountTransitionError.accountNotFound" type="boolean">
  `true` when the operation named an **account that is not in the stored map at all** — a stale id,
  typically from a switcher rendered off a snapshot the map has since moved past.

  Nothing was attempted and nothing was marked: no network call went out, no session was touched,
  `signedOut` is left exactly as it was, and re-authenticating would not help, because there is no
  entry to authenticate. Refresh your account list from `useAccounts()` rather than prompting a
  sign-in.

  The two flags are never both `true` — an account that is not stored has no credential to have
  been refused — and both are `false` for a transport failure.
</ResponseField>

<ResponseField name="AccountTransitionError.message" type="string">
  The server's reason when it gave one, otherwise `ACCOUNT_TRANSITION_FAILED_MESSAGE`. Both the
  class and that constant are exported, so you never have to match on a string you do not own.
</ResponseField>

Prompting a re-auth on every rejection is the mistake these discriminators exist to prevent: it
tells a user on a train that their account is dead, and it does so every time they lose signal.

```tsx theme={null}
try {
  await switchAccount({ userId });
} catch (err) {
  if (err instanceof AccountTransitionError) {
    if (err.accountNotFound) refreshAccountList();  // stale id — nothing happened
    else if (err.credentialRejected) promptSignIn(userId);  // the credential is dead
    else showRetry();                               // the request never got an answer
  }
}
```

<Note>
  A switch still costs exactly **one** token exchange. The refresh endpoint
  rotates the token presented to it, so validating first replaces the old
  post-swap refresh rather than adding a second call.
</Note>

**`removeAccount` rejects** on the same terms, and so do `signOutAll` and `useAuth().requestNewAccessToken`. None of the four signatures marks them as fallible, so nothing warns you at compile time — `await` them inside a `try`/`catch`, or an unhandled rejection surfaces as a React Native redbox or a browser `unhandledrejection`.

**At app launch**, the two failures part company:

* **The server refused the stored credential.** The app lands **signed out with the account entries intact** — never silently switched into a different account — and that account is marked `needsReauth`, so the switcher can label it without the user having to discover it by tapping.
* **The server was never reached.** Nothing is torn down, nothing is marked, and the account stays selected. Opening the app on a train does not sign anyone out; the session is restored on the next launch, or sooner by the automatic refresh on the first request that takes a `401`/`403`.

See [Durable signed-out state](#durable-signed-out-state).

## Durable Signed-Out State

"No account is active" has two meanings, and the SDK tells them apart across relaunches:

| Situation                                                                                                                  | `activeAccount` | `signedOut` | What happens on the next launch                                                                |
| -------------------------------------------------------------------------------------------------------------------------- | --------------- | ----------- | ---------------------------------------------------------------------------------------------- |
| Nothing has ever been selected                                                                                             | `null`          | `false`     | The first stored account is selected and restored                                              |
| The user deliberately signed out, removed the active account, deleted it, or a stored credential was **refused** at launch | `null`          | `true`      | **Nothing is auto-selected.** The app renders signed-out, and the user picks from the switcher |
| A launch could not reach the server                                                                                        | unchanged       | unchanged   | The stored account stays selected and its session is restored                                  |

`signedOut` is read from `useAccounts()` and is persisted alongside the account map, so it survives a relaunch. It clears the moment any account is successfully activated.

```tsx theme={null}
const { accounts, activeAccount, signedOut } = useAccounts();

if (!activeAccount && signedOut && accounts.length > 0) {
  return <AccountPicker accounts={accounts} />;
}
```

## Push Notifications Per Account

Every signed-in account on a device is bound to that device **separately**, so a device holding four accounts receives push for all four — and a message that reaches two of them arrives as **two notifications**, each stamped with its own `recipientUserId`. Read that key in your tap handler before routing, or a tap lands in the wrong session; see [the SDK push page](/sdk/push-notifications/overview#the-notification-data-payload).

### Each account has its own switch

```tsx theme={null}
import { useAccountPushToggle } from "@sublay/react-js";

const { setAccountPushEnabled, isAccountPushEnabled } = useAccountPushToggle();

// Works on a background account — no switching required.
await setAccountPushEnabled({ userId: "other-account-id", enabled: false });
```

The preference is **durable**. An account silenced on this device stays silenced across switches and relaunches — including through the refresh-token rotation that rebuilds its stored entry on every launch — until it is turned back on. It is stored per account in the account map, alongside the credential, and merged rather than overwritten every time that entry is rebuilt. See [`useAccountPushToggle`](/hooks/push/use-account-push-toggle).

<Warning>
  **`register()` turns push on for every stored account that has never expressed a preference.** Permission is a device-level grant, so the call records what it enabled for the whole device: an account you deliberately silenced keeps its `false`, but the four other accounts that were never asked all become enabled. If your UI implies per-account opt-in, follow the first `register()` with explicit toggles.

  The account the call was made from is bound immediately. The others are marked as needing a re-bind and are bound the next time the user switches into each — see [When notifications are paused](#when-notifications-are-paused). Nothing is ever bound for an account that has *not* expressed a preference: a plain sign-in on a device that already holds a push identifier creates no binding.
</Warning>

### Signing out unbinds automatically

Once this device has a stored push identifier, `signOut()`, `removeAccount()` and `signOutAll()` each send it with their sign-out request, and the server removes that account's push binding in the same transaction as the session teardown. Either both happen or neither does, and "neither" is reported rather than swallowed — see the warnings above. Devices with no stored identifier send none, have no unbind to protect, and sign out best-effort.

The identifier is **device** state and does not imply that the signing-out account ever opted into push. On native, `usePushRegistration` records one on mount for any device that already holds OS notification permission — that is what lets an app upgrading from an older SDK release still unbind the bindings it created back then. When the account had no binding the unbind removes nothing, and the sign-out is indistinguishable from one that carried no identifier at all. A device whose notification permission was never granted stores nothing and sends nothing.

The permission check is bypassed **exactly once per device**, on the first mount that reads an identifier, and only on a device that already has at least one stored account and no identifier yet. Turning notifications off in system settings does not invalidate a push token or remove a binding — the provider still accepts the notification, the OS simply does not show it, and the server prunes a token only when it reports the app uninstalled. So a device that registered on an older SDK release and has since revoked permission would otherwise hold a binding that nothing could reach: no identifier means no unbind on sign-out, and re-enabling notifications later would deliver that account's notifications to a device nobody is signed into. The one-time read closes that. It cannot prompt (only adapters that read a value the OS already holds participate — web never does), and the SDK records that it has run, so it does not repeat on later launches. A device whose account storage was empty the first time the SDK ran is never eligible: it cannot be carrying a binding from an older release.

Do **not** call `usePushRegistration().unregister()` in a logout flow. It is a durable per-account preference, so using it as cleanup permanently silences that account's next session, and sign-out already unbinds. See [Turning push off](/sdk/push-notifications/overview#turning-push-off).

### When notifications are paused

When the OS rotates the device's push token, every binding on the old token is dead. As long as `usePushRegistration` is mounted with an adapter that reports rotations, the SDK notices and records the new identifier. The **active** account is re-bound on the spot.

Mount that hook **at your app root**, not on the settings screen that calls `register()`: rotation handling lives exactly as long as the hook is mounted, so a screen-scoped mount only covers the seconds that screen is open and a rotation anywhere else in the app is missed. See [`usePushRegistration`](/hooks/push/use-push-registration). Every other push-enabled account is **marked** as needing a re-bind and repaired the next time the user switches into it, using the live session that switch establishes.

The marking is deliberate rather than a shortcut. Re-binding a background account would mean spending its stored refresh token on a one-time-use exchange, in the background, for an account the user is not looking at — and an interruption in the middle of that exchange locks the account out permanently. The cost is that a push-enabled account nobody opens goes quiet after a rotation until it is next opened, which is what the marker is for:

```tsx theme={null}
const { accounts } = useAccounts();

accounts.map((account) => (
  <AccountRow
    key={account.id}
    account={account}
    note={account.needsPushRebind ? "Notifications paused — open to resume" : null}
  />
));
```

`needsPushRebind` clears as soon as the account is re-bound. It is **not** `needsReauth` and the two should not read the same in your UI: `needsReauth` means the credential is dead and the user must sign in again, while `needsPushRebind` means the account works perfectly and is merely quiet. It is only ever raised for accounts that explicitly enabled push — an account that never asked for notifications has none to pause.

See [Automatic token rotation](/hooks/push/use-push-registration#automatic-token-rotation) for which platforms report a rotation at all.

## Reaching the Account Limit

Signing in a **sixth** account is refused, with an error that names the cause: this device already remembers the maximum number of accounts, and signing out of one is what frees a slot. The limit is never raised and no account is evicted to make room — a map that fills up means users are being signed in without ever being signed out.

A refusal at the cap does **not** persist a signed-out state. The selection is left exactly where it was, so the next launch is unaffected by the refused attempt and the user is never parked in a state they cannot get out of. `accountLimitReached` stays raised for your UI to read, and switching back into an account that already has an entry works even when the current selection has no live session.

### How the refusal reaches you

Every sign-in path is covered, but they cannot all report the same way:

| Entry point                   | How the limit surfaces                                                                                                                                                                  | When                                                                                                                                                                                                        |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `signUpWithEmailAndPassword`  | The call **rejects**                                                                                                                                                                    | Before any network call — a sign-up is a new account by definition. If the map fills *while the request is in flight*, the refusal comes after it instead, and the created user record persists (see below) |
| `signInWithEmailAndPassword`  | The call **rejects**                                                                                                                                                                    | After authentication, once the server has said which account this is                                                                                                                                        |
| External auth (`signedToken`) | The app **renders** signed-out with the flag set — the session is gone, but the selection stands and `signedOut` is not written; the reason rides the rejected `auth/initialize` action | After the token is verified                                                                                                                                                                                 |
| OAuth (web and Expo)          | `accountLimitReached` only — **nothing throws**                                                                                                                                         | After the provider returns                                                                                                                                                                                  |

The rejecting calls throw an `Error` whose message is exported as `ACCOUNT_LIMIT_MESSAGE`, so you can recognise the case without matching on a string you do not own:

```tsx theme={null}
import { useAuth, ACCOUNT_LIMIT_MESSAGE } from "@sublay/react-js";

const { signInWithEmailAndPassword } = useAuth();

try {
  await signInWithEmailAndPassword({ email, password });
} catch (err) {
  if (err instanceof Error && err.message === ACCOUNT_LIMIT_MESSAGE) {
    // Offer to sign out of one of the stored accounts.
  }
}
```

Every path also sets `accountLimitReached`, so a single piece of UI can cover all four.

<Note>
  **Signing back in to an account you already store always works, even at the limit.** The check is keyed on the account id the server resolves, not on the email you typed — so an account whose stored email is out of date, absent (accounts admitted through external auth may have no email), or capitalised differently signs in normally. This is also why email sign-in is checked *after* the network call rather than before it: the alternative would lock people out of their own accounts.
</Note>

### Why OAuth cannot throw

`handleOAuthRedirect` — the synchronous core both `@sublay/react-js` and `@sublay/expo` drive their OAuth return through — takes the tokens straight from the redirect. (On the web, `handleOAuthCallback` parses the callback page's URL and hands off to it; on Expo the redirect is resolved inline and calls it directly, so that package's `handleOAuthCallback` is only a no-op compatibility shim.) It returns as soon as the redirect's tokens are read — before your app knows *whose* they are — and on the web the page that called `initiateOAuth` no longer exists by then. There is no promise left to reject, so both OAuth paths report the limit through `accountLimitReached` instead. The hook's own `error` string stays reserved for failures the provider reported.

### What is left behind

No session, ever: a refused sign-in really did create one on the server, and the SDK signs it back out immediately. Nothing in the map either — the stored accounts are untouched and the active account never points at an account that is not stored.

**One exception, and it is a user record rather than a session.** A sign-up refused *before* the request creates nothing at all. A sign-up whose fifth slot filled *while the request was in flight* is refused after it, so the account exists on the server: its session is destroyed, but the user record stays and the email is taken. Retrying that email after freeing a slot fails as "already in use" — sign in with it instead.

What changes locally depends on the path:

* **Sign-up, email sign-in and external verification** are refused *before* the SDK touches your session, so whatever account was active stays signed in.
* **OAuth** cannot be: the redirect hands over tokens before identity is known, so the previous session is already gone by the time the limit is discovered. The **selection is left exactly as it was** — nothing writes `activeAccountId` on this path — while the session behind it is **not** re-established. So whichever account the map already named stays named, the app renders signed-out with that account selected, and the user signs in again from the picker. This holds whether or not the flow was started from `addAccount()`, because that call leaves the selection alone too. If nothing was selected before the flow, nothing is selected after it; the refusal neither creates a selection nor clears one.

### Three signals for the account cap

Three related but distinct values answer three different questions. None replaces another:

| Value                                        | Where from                          | Kind      | Question it answers                                                                                                                                   |
| -------------------------------------------- | ----------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `canAddAccount`                              | `useAddAccount()`                   | Predicate | **Is there room right now?** Derived from the map size on every render, and it knows no user id. Use it to enable or disable an "Add account" button. |
| `wouldExceedAccountLimit(accounts, userId?)` | Bare function export                | Predicate | **Would admitting *this id* be a sixth account?** The exact rule the SDK's own refusal gates use, over a raw accounts map.                            |
| `accountLimitReached`                        | `useAccounts()` / `useAddAccount()` | Event     | **Did an admission just get refused?** Latched until the next successful admission or any removal. Use it to render the error after the fact.         |

Use `canAddAccount` to keep the user from starting a sign-in that cannot succeed, and `accountLimitReached` to cover the sign-ins that start anyway — a direct sign-in that never went through `addAccount()`, an OAuth return, or a map that filled in another tab while the request was in flight.

<ResponseField name="wouldExceedAccountLimit" type="(accounts: Record<string, AccountEntry>, userId?: string | null) => boolean">
  `true` when admitting `userId` into `accounts` would exceed the 5-account
  limit. Pure and read-only — it takes the raw map (from `selectAccounts`, or
  from your own store in [integration mode](/sdk/redux-integration)) and
  computes; it dispatches nothing.

  **An id already in the map is never an admission**, so this returns `false`
  for it even at the cap. That is the whole reason it exists alongside
  `canAddAccount`: re-authenticating an account this device already stores has
  to work at the limit, or a user with five accounts could never sign back into
  any of them. `canAddAccount` cannot express that — it knows no id.

  Omit `userId` for the sign-up case, where the answer is unconditional: a
  sign-up creates a person who by definition is not in the map.

  ```tsx theme={null}
  import { useSublaySelector, selectAccounts, wouldExceedAccountLimit } from "@sublay/react-js";

  const accounts = useSublaySelector(selectAccounts);

  // A "sign back in" row in your own picker, for an account you already store:
  const blocked = wouldExceedAccountLimit(accounts, account.id); // false — always allowed
  ```
</ResponseField>

### When `accountLimitReached` clears

It clears on the next successful admission and on any removal — but **not synchronously**. The clear rides the effect that records a successful admission into the account map, so it lands **one render after** the call that triggered it resolves.

That makes it correct to *render* and wrong to *sample*:

```tsx theme={null}
// ⛔ Reads the value from before the effect flushed — possibly a `true` left
//    over from an earlier, unrelated refusal.
await signInWithEmailAndPassword({ email, password });
if (accountLimitReached) showCapError();

// ✅ The next render has the settled value.
if (accountLimitReached) return <CapError />;
```

The rule is general: **never read this flag synchronously right after triggering an action — read it through the hook's normal render cycle.** It is not only the clear that settles late. The flag is *set* at three different moments depending on the entry point: synchronously at the pre-flight gate, after the network round trip at the post-authentication gate, and — on the OAuth path — after a round trip the SDK does not await, because `handleOAuthRedirect` dispatches its completion thunk without one and returns before the cap has been evaluated. So an eager read can observe a stale value from either side.

Re-authenticating into an account the device already stores is one example worth naming, because it looks exempt: that path never trips the cap check, so nothing sets the flag on it — yet a stale `true` from an earlier refusal survives until that re-auth's admission lands, one render later. Rendering from the flag gets the settled value in every one of these cases; sampling it gets whichever moment you happened to land in.

## Controlling SDK Error Logging

The SDK logs handled failures with `console.error`. Apps whose crash reporters treat `console.error` as a signal — or that simply want a quieter console — can change the level:

```ts theme={null}
import { setSublayLogLevel } from "@sublay/react-js";

setSublayLogLevel("silent"); // "error" (default) | "warn" | "silent"
```

This is a **bare setter, not a provider prop**, deliberately: the setting is process-global, and a prop would be silently last-mount-wins in apps that mount two providers. It is also coarse — it silences *all* SDK logging, unexpected failures included. Errors are still returned to and surfaced by the calling hooks; only the console output changes.

## Composing Your Own Account UI

If the built-in hooks do not fit, the transition primitives are exported directly:

| Export                                                                                                              | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `activateStoredAccount`                                                                                             | The full transition: validate a stored account's credential, then tear down and swap the session over. A plain function, callable outside React. Takes `dispatch` **and `getState`** — it reads the target's stored entry and writes the rotated successor back through the same persist path every other rotation uses. Rejects without touching anything when the credential is dead.                                                                                     |
| `resetAccountScopedState`                                                                                           | Redux action that returns every account-scoped feature slice to its initial state. Subscribe your own slices to it.                                                                                                                                                                                                                                                                                                                                                         |
| `resetAuth` / `clearUser`                                                                                           | The auth and user teardown actions.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `selectAccounts`, `selectActiveAccountId`, `selectSignedOut`, `selectAccountLimitReached`, `selectDeviceIdentifier` | Selectors over the accounts slice.                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `wouldExceedAccountLimit`                                                                                           | The cap predicate for a *specific* user id, over a raw accounts map — `false` for an id already stored, because signing back in is not an admission. See [Three signals for the account cap](#three-signals-for-the-account-cap).                                                                                                                                                                                                                                           |
| `setSignedOut`                                                                                                      | Records that ending the session was deliberate. The three actions above clear the *session*; none of them touches the accounts slice, so a hand-rolled teardown that omits `setSignedOut(true)` leaves `signedOut: false` with an account still selected — and the next launch reads that as "nothing has ever been picked", restores the account and signs the app back in. `setActiveAccount` clears it again on the next activation, so nothing has to unset it by hand. |
| `AccountTransitionError`, `ACCOUNT_TRANSITION_FAILED_MESSAGE`                                                       | What a failed transition rejects with, and its default message. `credentialRejected` separates a dead account from a failed request, and `accountNotFound` separates both from a stale id that names no stored account — see [Telling a dead account from a dead network](#telling-a-dead-account-from-a-dead-network).                                                                                                                                                     |

The raw `setActiveAccount`, `upsertAccount` and `removeAccount` reducers are deliberately **not** exported. They only mutate local state: dispatching `setActiveAccount` can point the active id at an account that is not in the map, and dispatching `removeAccount` drops an account without signing it out server-side. Use `activateStoredAccount` and the `useRemoveAccount` hook instead — they perform the whole flow.

`accountNeedsReauth(entry)`, `accountNeedsPushRebind(entry)` and `isAccountPushEnabled(entry)` are exported for reading those fields off a raw `AccountEntry`, since absent and `false` do not always mean the same thing there. `isAccountPushEnabled` is **reported state** — the value a per-account switch renders as `checked`, with an absent preference reading as enabled. It is not the rule the SDK uses to decide whether to create a binding; that one requires an explicit opt-in and is internal, so no binding is ever created for an account that never asked.

## One Project Per App

One Sublay project per app is the supported shape. Account storage, the auth gate and the credential slot are one set of module-level singletons, so a second provider mounted for a *different* project id does not get its own world — it takes over the shared one, and the non-last project's account switching stops working while a rotated refresh token can be written under the wrong project's key, locking that account out permanently.

Rather than let that happen quietly, mounting a second provider for a different project **throws immediately**, with a message naming both project ids. Remounting the *same* project — a hot reload, a provider that unmounts and mounts again, two providers for one project — is fine and is not affected.

If you need to talk to two projects, run two apps, or drive the second project through [`@sublay/js`](/js-sdk/overview) or your own backend rather than mounting a second provider.

## See Also

* [`useAccounts` hook reference](/hooks/auth/use-accounts)
* [`useAddAccount` hook reference](/hooks/auth/use-add-account)
* [`useSwitchAccount` hook reference](/hooks/auth/use-switch-account)
* [`useRemoveAccount` hook reference](/hooks/auth/use-remove-account)
* [`useSignOutAll` hook reference](/hooks/auth/use-sign-out-all)
* [`useAccountPushToggle` hook reference](/hooks/push/use-account-push-toggle)


# OAuth
Source: https://docs.sublay.io/v7/sdk/authentication/oauth

Google, GitHub, Apple, and Facebook OAuth provider integration

Sublay supports OAuth 2.0 sign-in with Google, GitHub, Apple, and Facebook. The flow is redirect-based: the user is sent to the provider's authorization page and returns to a callback URL in your app with tokens embedded in the URL fragment.

<Note>
  OAuth providers must be configured in the Sublay dashboard before use. Each
  provider requires a client ID, client secret, and a list of allowed redirect
  URIs.
</Note>

## Web Integration

The `useOAuthSignIn` hook (from `@sublay/react-js`) handles the full web OAuth flow.

```tsx theme={null}
import { useOAuthSignIn } from "@sublay/react-js";
```

### Initiating Sign-In

Call `initiateOAuth` with the provider name and the URL your app will redirect back to after authentication.

```tsx theme={null}
import { useOAuthSignIn } from "@sublay/react-js";

function SignInWithGoogle() {
  const { initiateOAuth, isLoading, error } = useOAuthSignIn();

  const handleClick = async () => {
    // The user will be redirected to Google's authorization page.
    // isLoading stays true during the redirect.
    await initiateOAuth("google", "https://yourapp.com/auth/callback");
  };

  return (
    <button onClick={handleClick} disabled={isLoading}>
      {isLoading ? "Redirecting..." : "Sign in with Google"}
    </button>
  );
}
```

Supported provider values: `"google"`, `"github"`, `"apple"`, `"facebook"`.

### Handling the Callback

On the page your app redirects back to, call `handleOAuthCallback` once on mount. It reads the tokens from the URL fragment, stores them in the SDK, and cleans the URL.

```tsx theme={null}
import { useEffect } from "react";
import { useOAuthSignIn } from "@sublay/react-js";
import { useNavigate } from "react-router-dom";

function AuthCallbackPage() {
  const { handleOAuthCallback, error } = useOAuthSignIn();
  const navigate = useNavigate();

  useEffect(() => {
    const success = handleOAuthCallback();
    if (success) {
      navigate("/dashboard");
    }
  }, []);

  if (error) return <p>Authentication failed: {error}</p>;

  return <p>Authenticating...</p>;
}
```

`handleOAuthCallback` returns `true` if tokens were found in the URL fragment and `false` otherwise. If the provider returned an error (for example, the user denied access), the error is surfaced through the `error` field.

### Linking an Additional Provider

Authenticated users can link additional OAuth providers to their account using `linkOAuthProvider`. This requires the user to already be signed in.

```tsx theme={null}
import { useOAuthSignIn } from "@sublay/react-js";

function LinkGitHubButton() {
  const { linkOAuthProvider } = useOAuthSignIn();

  return (
    <button onClick={() => linkOAuthProvider("github", "https://yourapp.com/settings/callback")}>
      Connect GitHub
    </button>
  );
}
```

The callback page logic is identical for both sign-in and link flows — `handleOAuthCallback` handles both cases.

## Expo Integration

`@sublay/expo` ships its own `useOAuthSignIn` hook with the **same API** as the web hook (`initiateOAuth`, `linkOAuthProvider`, `handleOAuthCallback`, `isLoading`, `error`). Instead of a full-page redirect, it opens the Sublay-brokered consent screen in the system browser and returns to your app through a custom-scheme deep link.

<Note>
  Deep links don't work reliably in **Expo Go**. You need a [custom dev client](https://docs.expo.dev/develop/development-builds/introduction/) (`npx expo run:ios` / `npx expo run:android`) or an [EAS Build](https://docs.expo.dev/build/introduction/).
</Note>

### Setup

<Steps>
  <Step title="Install the peer dependencies">
    The Expo hook relies on `expo-web-browser` (to open the auth session) and `expo-linking` (to parse the return URL).

    ```bash theme={null}
    npx expo install expo-web-browser expo-linking
    ```
  </Step>

  <Step title="Register a URL scheme">
    Add a custom `scheme` to your `app.json` (or `app.config.js`). This is the scheme your `redirectAfterAuth` deep link uses.

    ```json app.json theme={null}
    {
      "expo": {
        "scheme": "myapp"
      }
    }
    ```
  </Step>

  <Step title="Allow the redirect URI in the dashboard">
    In your Sublay project's OAuth provider settings, add the exact deep link you'll pass as `redirectAfterAuth` (e.g. `myapp://auth/callback`) to the provider's **Allowed Redirect URIs**.
  </Step>
</Steps>

### Initiating Sign-In

`redirectAfterAuth` is **required** on mobile — there is no `window.location` to fall back to. Pass the deep link you registered above.

```tsx theme={null}
import { useOAuthSignIn } from "@sublay/expo";

function SignInWithGoogle() {
  const { initiateOAuth, isLoading, error } = useOAuthSignIn();

  const handlePress = () =>
    initiateOAuth({
      provider: "google",
      redirectAfterAuth: "myapp://auth/callback",
    });

  return (
    <Button
      title={isLoading ? "Signing in..." : "Sign in with Google"}
      onPress={handlePress}
      disabled={isLoading}
    />
  );
}
```

On a successful return, tokens are parsed from the deep link and stored automatically. There is **no separate callback page** — the result is resolved inline. `handleOAuthCallback` exists for API parity but is a no-op that always returns `false`, so you never need to call it on mobile.

If the user cancels or dismisses the browser, the flow resolves quietly: `isLoading` resets to `false` and `error` stays `null`. `error` is only set on a server failure, a provider `error` in the redirect, or when no tokens are returned.

### Linking an Additional Provider

`linkOAuthProvider` works exactly like the web flow and requires the user to already be signed in.

```tsx theme={null}
import { useOAuthSignIn } from "@sublay/expo";

function LinkGitHubButton() {
  const { linkOAuthProvider } = useOAuthSignIn();

  return (
    <Button
      title="Connect GitHub"
      onPress={() =>
        linkOAuthProvider({
          provider: "github",
          redirectAfterAuth: "myapp://settings",
        })
      }
    />
  );
}
```

### Persistence

Tokens dispatched by the hook are picked up by the `SublayProvider`'s account manager and written to `SecureStore`, so the session survives app relaunches automatically. You don't need to add any storage code.

### Web vs. Expo at a glance

|                       | Web (`@sublay/react-js`)                        | Expo (`@sublay/expo`)                             |
| --------------------- | ----------------------------------------------- | ------------------------------------------------- |
| Browser handoff       | Full-page redirect via `window.location`        | System browser via `expo-web-browser`             |
| `redirectAfterAuth`   | Optional (defaults to current URL)              | **Required** (a custom-scheme deep link)          |
| Callback handling     | Call `handleOAuthCallback` on the callback page | Resolved inline; `handleOAuthCallback` is a no-op |
| Token persistence     | `localStorage`                                  | `SecureStore`                                     |
| Account limit reached | `accountLimitReached` (never throws)            | `accountLimitReached` (never throws)              |

### The Account Limit

A device stores at most **5 accounts** ([Multi-Account](/sdk/authentication/multi-account)). Signing in a sixth through OAuth is refused — but **on both platforms the limit surfaces as state, not as a thrown error**, unlike email sign-up/sign-in and external auth, which reject the call.

Read it from `useAccounts` (or `useAddAccount`) rather than from the hook's `error` field, which stays reserved for failures the provider itself reported:

```tsx theme={null}
import { useOAuthSignIn, useAccounts } from "@sublay/react-js";

function OAuthCallbackPage() {
  const { handleOAuthCallback, error } = useOAuthSignIn();
  const { accountLimitReached } = useAccounts();

  useEffect(() => {
    handleOAuthCallback();
  }, []);

  if (accountLimitReached) return <p>You're signed in to 5 accounts already. Sign out of one to add another.</p>;
  if (error) return <p>{error}</p>;
  return <p>Signing you in...</p>;
}
```

**Why it cannot throw.** `handleOAuthCallback` is synchronous and shared by both platform packages. It returns as soon as it has read the redirect's tokens — before your app knows whose they are — and on the web the page that called `initiateOAuth` was torn down by the redirect, so there is no promise left to reject. Making it reject would mean changing the shape of a function both packages depend on.

**What happens instead.** The identity is resolved, found to be new, and refused. The session that was just created is signed back out on the server, so nothing is orphaned, and the account that was active before is re-*selected* — but its session is **not** re-established, because the redirect had already replaced its tokens before the identity was known. The app renders signed-out with that account selected and the user picks it again from the switcher. Starting the flow from `addAccount()` changes nothing here — that call leaves the selection in place — so the account the user came from is the one restored. Only a device with no account selected at all stays on the sign-in screen.

An OAuth sign-in for an account the device **already stores** is never refused — the check is keyed on the resolved account id.

## How Tokens Are Returned

After the provider callback, Sublay redirects to your `redirectAfterAuth` URL with tokens in the **URL fragment** (not query parameters):

```
https://yourapp.com/auth/callback#accessToken=...&refreshToken=...
```

Fragments are not sent to servers and do not appear in server access logs, which prevents token leakage. `handleOAuthCallback` extracts them automatically.

## Managing Linked Identities

Use `useOAuthIdentities` to list and unlink OAuth identities on the current user's account.

```tsx theme={null}
import { useOAuthIdentities } from "@sublay/react-js";

function LinkedAccounts() {
  const { identities, fetchIdentities, unlinkIdentity, isLoading } = useOAuthIdentities();

  useEffect(() => {
    fetchIdentities();
  }, []);

  return (
    <ul>
      {identities.map((identity) => (
        <li key={identity.id}>
          {identity.provider} — {identity.email}
          <button onClick={() => unlinkIdentity(identity.id)}>Unlink</button>
        </li>
      ))}
    </ul>
  );
}
```

<Warning>
  Unlinking an identity is blocked if it is the last identity on the account and
  the user has no password set. This prevents the user from being locked out.
</Warning>

## See Also

* [`useOAuthIdentities` hook reference](/hooks/auth/use-oauth-identities)
* [OAuth Authorize API reference](/api-reference/oauth/authorize)
* [OAuth Link API reference](/api-reference/oauth/link)
* [List Identities API reference](/api-reference/oauth/list-identities)
* [Unlink Identity API reference](/api-reference/oauth/unlink-identity)


# Apple
Source: https://docs.sublay.io/v7/sdk/authentication/oauth-providers/apple

Set up Sign in with Apple: Services ID, key, Team ID, and Key ID

Apple is the most involved of the four providers because it doesn't hand you a simple client secret. Instead you create a **Services ID** (your client ID) and a **Sign in with Apple key** (a `.p8` file), and Sublay uses that key — together with your Team ID and Key ID — to generate and rotate Apple's short-lived client secret for you.

<Note>
  New to the overall flow? Read [Configuring OAuth
  Providers](/sdk/authentication/oauth-providers/overview) first — it explains
  the redirect chain and the Sublay callback URL that every step below refers to.
</Note>

By the end you'll have four values to paste into the Sublay dashboard:

| Sublay field                   | Comes from                  |
| ------------------------------ | --------------------------- |
| **Client ID**                  | Your Services ID identifier |
| **Team ID**                    | Your Apple Developer team   |
| **Key ID**                     | Your Sign in with Apple key |
| **Private Key (.p8 contents)** | The key file you download   |

Everything happens in [developer.apple.com](https://developer.apple.com) under **Certificates, Identifiers & Profiles**. You need a paid Apple Developer account.

## Step 1 — Note your Team ID

Your **Team ID** is the 10-character string shown in the top-right of the Apple Developer portal (next to your team name), and on the **Membership** page. Keep it handy — it goes straight into the Sublay form.

## Step 2 — Enable Sign in with Apple on your App ID

<Steps>
  <Step title="Open your App ID">
    Under **Identifiers**, select your app's App ID (the one matching your app's bundle identifier). If you don't have one yet, create it with the **+** button.
  </Step>

  <Step title="Enable the capability">
    Check the **Sign in with Apple** capability, then **Save**. You can ignore the "Edit / Configure" button next to it — that's only for grouping multiple App IDs under one primary, which a standard setup doesn't need.
  </Step>
</Steps>

## Step 3 — Create a Services ID (your Client ID)

The Services ID is a separate identifier from your App ID, and its identifier string becomes your **Client ID** in Sublay.

<Steps>
  <Step title="Register a new Services ID">
    Go to **Identifiers**, click the **+**, choose **Services IDs**, and continue.
  </Step>

  <Step title="Name and identify it">
    Give it a description (e.g. `MyApp Sign in with Apple`) and an identifier in reverse-domain style. It **must be different** from your App ID — for example, if your App ID is `com.example.myapp`, use `com.example.myapp.signin`.

    <Warning>
      Whatever you enter as the **Identifier** is your Sublay **Client ID**. Copy
      it down.
    </Warning>
  </Step>

  <Step title="Register">
    Click **Continue**, then **Register**. This only creates the Services ID — you configure Sign in with Apple on it in the next step.
  </Step>
</Steps>

## Step 4 — Configure web authentication on the Services ID

<Steps>
  <Step title="Open the Services ID and enable the capability">
    Switch the Identifiers filter (top-right) to **Services IDs**, open the one you just created, check the **Sign in with Apple** checkbox, and click **Configure**.
  </Step>

  <Step title="Set the primary App ID">
    In the **Web Authentication Configuration** dialog, set **Primary App ID** to the App ID from Step 2.
  </Step>

  <Step title="Register the Sublay domain and return URL">
    Fill in the two boxes:

    * **Domains and Subdomains:** `api.sublay.io`
    * **Return URLs:** `https://api.sublay.io/v7/oauth/callback`

    Click **Next**, then **Done**, then **Continue**, then **Save**.
  </Step>
</Steps>

<Note>
  Apple may prompt you to verify the domain by hosting a file on it. Because the
  return URL lives on Sublay's domain (`api.sublay.io`), not yours, you can't host
  that file — and for the basic sign-in redirect you don't need to. If Apple
  blocks the save with a verification error rather than saving cleanly, stop and
  contact Sublay support, since that's on the Sublay side.
</Note>

## Step 5 — Create a Sign in with Apple key

This produces the `.p8` private key and its Key ID.

<Steps>
  <Step title="Register a new key">
    Go to **Keys**, click the **+**, and give the key a name (e.g. `MyApp Sign in with Apple Key`).
  </Step>

  <Step title="Enable Sign in with Apple only">
    Check the **Enable** box on the **Sign in with Apple** row, click its **Configure** button, and select your App ID as the primary. Do **not** enable APNs on this key.

    <Note>
      Apple's "maximum of 2" limit applies only to **APNs (push) keys** — a Sign
      in with Apple key does not count against it, as long as you leave the APNs
      box unchecked. Keep auth and push keys separate so you can rotate or revoke
      one without affecting the other.
    </Note>
  </Step>

  <Step title="Download the key and note the Key ID">
    Click **Continue**, then **Register**, then **Download**. The `.p8` file can only be downloaded **once** — store it securely. Note the **Key ID** (a 10-character string) shown on the key's page.
  </Step>
</Steps>

## Step 6 — Fill in the Sublay dashboard

In your project dashboard, open **Settings → OAuth Providers → Add Provider → Apple**, and complete the modal:

| Field                          | Value                                                                                                                                                              |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Client ID**                  | Your Services ID identifier (e.g. `com.example.myapp.signin`) — **not** the App ID                                                                                 |
| **Team ID**                    | The 10-character Team ID from Step 1                                                                                                                               |
| **Key ID**                     | The 10-character Key ID from Step 5                                                                                                                                |
| **Private Key (.p8 contents)** | The **full** contents of the `.p8` file, including the `-----BEGIN PRIVATE KEY-----` and `-----END PRIVATE KEY-----` lines                                         |
| **Allowed Redirect URIs**      | Your app's return URL(s) — the `redirectAfterAuth` you pass in code (e.g. `https://yourapp.com/auth/callback` for web, or `myapp://auth/callback` for Expo/native) |
| **Scopes**                     | Leave the defaults (`name`, `email`)                                                                                                                               |

Click **Add Provider** to save and enable it.

<Warning>
  Open the `.p8` in a plain text editor and paste the **entire** file, including
  the `BEGIN`/`END` lines. If you lose the file you can't re-download it — you'd
  have to create a new key and update the Key ID and Private Key here.
</Warning>

## Common pitfalls

* **Services ID vs. App ID** — the Client ID is the **Services ID**, not the App ID. They must be different identifiers.
* **Redirect URI mismatch** — the value in your code, in Allowed Redirect URIs, and (on Apple's side) the Return URL must all agree exactly.
* **Name only arrives once** — Apple returns the user's name only on their **first** authorization, never again. Sublay captures it then; there's nothing to configure, but don't be surprised if a re-auth carries no name.

## See Also

* [Configuring OAuth Providers](/sdk/authentication/oauth-providers/overview) — the shared setup overview
* [OAuth](/sdk/authentication/oauth) — the runtime sign-in code


# Facebook
Source: https://docs.sublay.io/v7/sdk/authentication/oauth-providers/facebook

Create a Meta app with Facebook Login and paste the App ID and secret into Sublay

Facebook is one of the simpler providers: you create an app in the Meta developer console, add the **Facebook Login** product, register Sublay's callback URL, and copy two values — the **App ID** and **App Secret** — into the Sublay dashboard. The only real gotcha is Meta's **Development vs. Live** mode, which controls whether anyone other than you can actually sign in.

<Note>
  New to the overall flow? Read [Configuring OAuth
  Providers](/sdk/authentication/oauth-providers/overview) first — it explains
  the redirect chain and the Sublay callback URL that every step below refers to.
</Note>

By the end you'll have two values to paste into the Sublay dashboard:

| Sublay field      | Comes from                |
| ----------------- | ------------------------- |
| **Client ID**     | Your app's **App ID**     |
| **Client Secret** | Your app's **App Secret** |

<Warning>
  In Meta's console these are called **App ID** and **App Secret**, but in the
  Sublay modal they go in the **Client ID** and **Client Secret** fields
  respectively. Sublay uses the generic OAuth names for every provider.
</Warning>

Everything on the provider side happens at [developers.facebook.com](https://developers.facebook.com). You need a Facebook account with developer access (accept the developer terms if prompted).

## Step 1 — Create a Facebook app

<Steps>
  <Step title="Start the create-app wizard">
    Go to **My Apps → Create App**. Meta's wizard is **use-case based**, so it asks what you want your app to do rather than for an app "type".
  </Step>

  <Step title="Choose a use case that enables Facebook Login">
    Pick the use case for **authenticating and requesting data from users** — the option that includes **Facebook Login**. (Meta relabels these periodically; choose whichever one lists Facebook Login as an included product.) Give the app a name and continue through to create it.
  </Step>
</Steps>

## Step 2 — Add the Facebook Login product

If the wizard didn't already attach it, add **Facebook Login** to your app from the products list in the left-hand sidebar (**Add Product → Facebook Login → Set up**). You do **not** need the iOS/Android/Web platform quickstarts — the web OAuth redirect flow is all Sublay uses.

## Step 3 — Register the Sublay callback URL

This is the single most important step, and the same value for every provider.

<Steps>
  <Step title="Open Facebook Login settings">
    In the sidebar, go to **Facebook Login → Settings**.
  </Step>

  <Step title="Add the Sublay redirect URI">
    In **Valid OAuth Redirect URIs**, add this exact string:

    ```
    https://api.sublay.io/v7/oauth/callback
    ```

    This is **Sublay's** endpoint, not your app's — the provider hands the user back to Sublay, and Sublay forwards them to your app afterward.
  </Step>

  <Step title="Confirm OAuth login is enabled">
    On the same page, make sure **Client OAuth Login** and **Web OAuth Login** are toggled **on**. Then **Save Changes**.
  </Step>
</Steps>

<Warning>
  Do **not** put your own app's return URL here. Your app's return URL
  (`redirectAfterAuth`) belongs in the **Allowed Redirect URIs** field of the
  Sublay dashboard, covered in Step 5 — not in Meta's console.
</Warning>

## Step 4 — Get your App ID and App Secret

<Steps>
  <Step title="Open Basic settings">
    Go to **App settings → Basic**.
  </Step>

  <Step title="Copy the App ID">
    The **App ID** is shown at the top. This becomes your Sublay **Client ID**.
  </Step>

  <Step title="Reveal and copy the App Secret">
    Click **Show** next to **App Secret** (you may be asked to re-enter your password). This becomes your Sublay **Client Secret**. Treat it like a password — never commit it or expose it in client-side code.
  </Step>
</Steps>

## Step 5 — Fill in the Sublay dashboard

In your project dashboard, open **Settings → OAuth Providers → Add Provider → Facebook**, and complete the modal:

| Field                     | Value                                                                                                                                                              |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Client ID**             | Your Facebook **App ID** from Step 4                                                                                                                               |
| **Client Secret**         | Your Facebook **App Secret** from Step 4                                                                                                                           |
| **Allowed Redirect URIs** | Your app's return URL(s) — the `redirectAfterAuth` you pass in code (e.g. `https://yourapp.com/auth/callback` for web, or `myapp://auth/callback` for Expo/native) |
| **Scopes**                | Leave the defaults (`email`, `public_profile`)                                                                                                                     |

Click **Add Provider** to save and enable it.

<Note>
  `email` and `public_profile` are Facebook's standard permissions and are
  granted without App Review. Leave the scopes untouched for a standard setup —
  the defaults are exactly what Sublay needs to create a user.
</Note>

## Step 6 — Switch the app to Live mode

A brand-new Facebook app starts in **Development mode**. In that state, **only** people with a role on the app — admins, developers, and testers — can sign in. Everyone else gets an error.

To let the public sign in, flip the app to **Live** using the toggle at the top of the dashboard. Meta gates this behind a few requirements:

* A **Privacy Policy URL** set under **App settings → Basic**.
* **Business verification** for your account, in some cases.
* Meta's standard checks may prompt for additional details before the toggle activates.

<Note>
  You can test the whole flow end to end while the app is still in
  **Development** mode — just sign in with an account that has a role on the app.
  Switch to **Live** only when you're ready for real users.
</Note>

## Common pitfalls

* **App ID / App Secret vs. Client ID / Client Secret** — the names differ between Meta and Sublay. App ID → Client ID, App Secret → Client Secret.
* **Wrong redirect URI** — `https://api.sublay.io/v7/oauth/callback` goes in Meta's **Valid OAuth Redirect URIs**; your app's return URL goes in Sublay's **Allowed Redirect URIs**. Swapping them is the most common failure.
* **Only I can sign in** — the app is still in **Development** mode. Add the person as a tester, or switch the app to **Live**.
* **Redirect URI mismatch** — the value in your code, in Sublay's Allowed Redirect URIs, and (on Meta's side) the Valid OAuth Redirect URIs must all agree exactly.

## See Also

* [Configuring OAuth Providers](/sdk/authentication/oauth-providers/overview) — the shared setup overview
* [OAuth](/sdk/authentication/oauth) — the runtime sign-in code


# GitHub
Source: https://docs.sublay.io/v7/sdk/authentication/oauth-providers/github

Create a GitHub OAuth App and paste the client ID and secret into Sublay

GitHub is the simplest of the four providers: you register an **OAuth App**, GitHub hands you a **Client ID** and a **Client Secret**, and you paste both into the Sublay dashboard. There's no key file or token signing to deal with — unlike Apple.

<Note>
  New to the overall flow? Read [Configuring OAuth
  Providers](/sdk/authentication/oauth-providers/overview) first — it explains
  the redirect chain and the Sublay callback URL that every step below refers to.
</Note>

By the end you'll have two values to paste into the Sublay dashboard:

| Sublay field      | Comes from                                           |
| ----------------- | ---------------------------------------------------- |
| **Client ID**     | Shown on your OAuth App's page after you register it |
| **Client Secret** | Generated on the same page (shown only once)         |

Everything happens in [github.com](https://github.com) under **Settings → Developer settings**. Any GitHub account works — no paid plan required.

## Step 1 — Create a GitHub OAuth App

<Steps>
  <Step title="Open the OAuth Apps page">
    Go to **Settings → Developer settings → OAuth Apps**, then click **New OAuth App** (or **Register a new application** if it's your first one).

    <Warning>
      Make sure you're creating an **OAuth App**, not a **GitHub App** — they're
      two different things listed side by side in Developer settings, and only the
      OAuth App gives you the simple Client ID / Client Secret pair Sublay expects.
    </Warning>
  </Step>

  <Step title="Fill in the application details">
    Complete the form:

    | Field                          | Value                                                                                     |
    | ------------------------------ | ----------------------------------------------------------------------------------------- |
    | **Application name**           | Anything your users will recognize (e.g. `MyApp`) — it's shown on GitHub's consent screen |
    | **Homepage URL**               | Your app or site (e.g. `https://yourapp.com`)                                             |
    | **Authorization callback URL** | `https://api.sublay.io/v7/oauth/callback`                                                 |

    <Warning>
      The **Authorization callback URL** is Sublay's endpoint, **not** your app's.
      GitHub sends the user back to Sublay first, and Sublay then redirects to your
      app. Enter `https://api.sublay.io/v7/oauth/callback` exactly.
    </Warning>
  </Step>

  <Step title="Register the application">
    Click **Register application**. GitHub creates the app and takes you to its settings page, where the **Client ID** is displayed. Copy it down.
  </Step>
</Steps>

## Step 2 — Generate a client secret

On the OAuth App's settings page, click **Generate a new client secret**.

<Warning>
  GitHub shows the client secret **only once**, immediately after generating it.
  Copy it right away — if you navigate away without saving it, you'll have to
  generate a new one and update Sublay with the new value.
</Warning>

You now have both values you need: the **Client ID** and the **Client Secret**.

## Step 3 — Fill in the Sublay dashboard

In your project dashboard, open **Settings → OAuth Providers → Add Provider → GitHub**, and complete the modal:

| Field                     | Value                                                                                                                                                              |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Client ID**             | The Client ID from Step 1                                                                                                                                          |
| **Client Secret**         | The client secret you generated in Step 2                                                                                                                          |
| **Allowed Redirect URIs** | Your app's return URL(s) — the `redirectAfterAuth` you pass in code (e.g. `https://yourapp.com/auth/callback` for web, or `myapp://auth/callback` for Expo/native) |
| **Scopes**                | Leave the default (`user:email`)                                                                                                                                   |

Click **Add Provider** to save and enable it.

<Note>
  The default `user:email` scope is what lets Sublay read the signed-in user's
  email address — GitHub won't return a user's email if it's marked private
  unless this scope is requested. Leave it as-is for a standard setup.
</Note>

## Common pitfalls

* **Two different redirect URLs** — the **Authorization callback URL** on GitHub is Sublay's `https://api.sublay.io/v7/oauth/callback`, while the **Allowed Redirect URIs** in the Sublay dashboard are your *own* app's return URLs. Don't put your app URL on GitHub or the Sublay URL in the Allowed Redirect URIs.
* **OAuth App vs. GitHub App** — you want an **OAuth App**. A GitHub App is a different product and won't work here.
* **The secret is shown once** — if you lose it, generate a new client secret and update the value in Sublay; the old one stops working.
* **Redirect URI mismatch** — the value in your code, in Allowed Redirect URIs, must match exactly (a trailing-slash difference will fail).
* **Org-owned apps may need approval** — you can create the OAuth App under your personal account or under an organization. If you create it under an org (or it's later transferred to one), an org owner may need to approve it before sign-in works for that org's members.

## See Also

* [Configuring OAuth Providers](/sdk/authentication/oauth-providers/overview) — the shared setup overview
* [OAuth](/sdk/authentication/oauth) — the runtime sign-in code


# Google
Source: https://docs.sublay.io/v7/sdk/authentication/oauth-providers/google

Create an OAuth 2.0 client in the Google Cloud Console and wire it into Sublay

Google is the most straightforward of the four providers: you create an **OAuth 2.0 client** in the Google Cloud Console, register Sublay's callback URL, and copy the resulting **Client ID** and **Client secret** into the Sublay dashboard. There are no keys to download or secrets to rotate.

<Note>
  New to the overall flow? Read [Configuring OAuth
  Providers](/sdk/authentication/oauth-providers/overview) first — it explains
  the redirect chain and the Sublay callback URL that every step below refers to.
</Note>

By the end you'll have two values to paste into the Sublay dashboard:

| Sublay field      | Comes from                   |
| ----------------- | ---------------------------- |
| **Client ID**     | Your OAuth 2.0 client ID     |
| **Client Secret** | Your OAuth 2.0 client secret |

Everything happens in [console.cloud.google.com](https://console.cloud.google.com). Any Google account works — no paid developer account is required.

## Step 1 — Create or select a project

At the top of the Google Cloud Console, use the project picker to **create a new project** (or select an existing one). All of the credentials below live inside this project.

## Step 2 — Configure the OAuth consent screen

Google won't let you create credentials until the consent screen exists. This is the screen users see when they authorize your app.

<Steps>
  <Step title="Open the consent screen">
    Go to **APIs & Services → OAuth consent screen**. Choose **User Type: External** so any Google user can sign in, then **Create**.
  </Step>

  <Step title="Fill in the app details">
    Enter an **App name**, a **User support email**, and a **Developer contact email**. The rest can be left blank for a basic setup.
  </Step>

  <Step title="Leave scopes at the defaults">
    You don't need to add any scopes here. Sublay requests `openid`, `email`, and `profile`, which Google treats as **non-sensitive** — they require no Google verification. Save and continue.
  </Step>

  <Step title="Decide who can sign in">
    While the app is in **Testing** mode, only Google accounts you add under **Test users** can sign in. To allow any Google user, click **Publish app** (**Back to testing** returns you to the restricted state). Publishing an app that uses only these non-sensitive scopes does **not** trigger Google's verification review.
  </Step>
</Steps>

## Step 3 — Create an OAuth 2.0 client ID

<Steps>
  <Step title="Start a new credential">
    Go to **APIs & Services → Credentials**, click **Create Credentials**, and choose **OAuth client ID**.
  </Step>

  <Step title="Choose the application type">
    Set **Application type** to **Web application**. This is correct even for mobile and Expo apps — the sign-in happens through Sublay's server-side redirect flow, so Google only ever talks to Sublay's web endpoint, not your app directly.
  </Step>

  <Step title="Register the Sublay callback URL">
    Under **Authorized redirect URIs**, click **Add URI** and enter, exactly:

    ```
    https://api.sublay.io/v7/oauth/callback
    ```

    <Warning>
      This is **Sublay's** endpoint, not your app's return URL. Google sends the
      user back to Sublay here, and Sublay then forwards them to your app. Do
      **not** put your own app's URL in this box.
    </Warning>

    You can leave **Authorized JavaScript origins** empty — this redirect flow doesn't use it. (If a field forces a value, `https://api.sublay.io` is the origin to use.)
  </Step>

  <Step title="Create and copy the credentials">
    Click **Create**. Google shows your **Client ID** and **Client secret** — copy both. If you need them again later, download the credentials JSON from the client's detail page (the **Client ID** stays visible there, but the secret may not be shown inline again).
  </Step>
</Steps>

## Step 4 — Fill in the Sublay dashboard

In your project dashboard, open **Settings → OAuth Providers → Add Provider → Google**, and complete the modal:

| Field                     | Value                                                                                                                                                              |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Client ID**             | The OAuth 2.0 client ID from Step 3                                                                                                                                |
| **Client Secret**         | The OAuth 2.0 client secret from Step 3                                                                                                                            |
| **Allowed Redirect URIs** | Your app's return URL(s) — the `redirectAfterAuth` you pass in code (e.g. `https://yourapp.com/auth/callback` for web, or `myapp://auth/callback` for Expo/native) |
| **Scopes**                | Leave the defaults (`openid`, `email`, `profile`)                                                                                                                  |

Click **Add Provider** to save and enable it.

<Note>
  **Allowed Redirect URIs** is a different thing from the callback URL you
  registered in Google. In Google you registered where the provider returns the
  user **to Sublay**; here you list where Sublay returns the user **to your app**.
  Add every URL you'll use — production, staging, and local development.
</Note>

## Common pitfalls

* **Wrong URL in Google** — the **Authorized redirect URI** in Google must be `https://api.sublay.io/v7/oauth/callback`, not your app's URL. Your app's URL goes in Sublay's **Allowed Redirect URIs** field instead.
* **Redirect URI mismatch** — the `redirectAfterAuth` in your code and an entry in Sublay's **Allowed Redirect URIs** must match exactly, character for character (a trailing slash mismatch will fail).
* **Stuck in Testing mode** — if sign-in works for you but not for other users, your consent screen is still in **Testing** and they aren't on the test-user list. Publish the app to open it up.
* **Wrong application type** — pick **Web application**, not "Android", "iOS", or "Desktop", even for a mobile app. Sublay handles the redirect server-side.

## See Also

* [Configuring OAuth Providers](/sdk/authentication/oauth-providers/overview) — the shared setup overview
* [OAuth](/sdk/authentication/oauth) — the runtime sign-in code


# Configuring OAuth Providers
Source: https://docs.sublay.io/v7/sdk/authentication/oauth-providers/overview

Register your app with Google, GitHub, Apple, or Facebook and wire the credentials into the Sublay dashboard

Before your users can sign in with `useOAuthSignIn`, each provider has to be configured once in two places: the **provider's own developer console** (where you register your app and get credentials) and the **Sublay dashboard** (where you paste those credentials in). This page explains the parts that are identical for every provider. The per-provider pages then walk you through each console step by step.

<Note>
  This page covers the one-time **setup**. For the runtime code — the sign-in
  button, the callback page, linking and unlinking identities — see
  [OAuth](/sdk/authentication/oauth).
</Note>

## The redirect chain

The single most important thing to understand is that there are **two different redirect URLs**, and mixing them up is the most common reason setup fails.

When a user signs in, the browser hops through three places:

```
Your app  →  the provider (Google/Apple/…)  →  Sublay  →  your app
```

1. Your app hands off to the provider's authorization page.
2. The provider sends the user **back to Sublay** — never straight back to you.
3. Sublay processes the result and redirects to **your app** with tokens in the URL fragment.

That means:

| Redirect URL            | Where it goes        | Where you register it                               |
| ----------------------- | -------------------- | --------------------------------------------------- |
| **Provider callback**   | Back to **Sublay**   | In the **provider's console**                       |
| **`redirectAfterAuth`** | Back to **your app** | In the **Sublay dashboard** (Allowed Redirect URIs) |

### The Sublay callback URL

Every provider console asks for a callback / redirect / return URL. For **all four providers** it is the same value:

```
https://api.sublay.io/v7/oauth/callback
```

Register that exact string in the provider's console. It is Sublay's endpoint, not yours — the provider talks to Sublay, and Sublay forwards the user to your app afterward.

## Step 1 — Register your app with the provider

Each provider hands you a **Client ID** and, for most providers, a **Client Secret**. Pick your provider and follow its walkthrough:

<CardGroup>
  <Card title="Apple" href="/sdk/authentication/oauth-providers/apple">
    Services ID, Sign in with Apple key (.p8), Team ID, and Key ID.
  </Card>

  <Card title="Google" href="/sdk/authentication/oauth-providers/google">
    OAuth 2.0 client in the Google Cloud Console.
  </Card>

  <Card title="GitHub" href="/sdk/authentication/oauth-providers/github">
    A GitHub OAuth App with a client ID and secret.
  </Card>

  <Card title="Facebook" href="/sdk/authentication/oauth-providers/facebook">
    A Facebook app with Facebook Login enabled.
  </Card>
</CardGroup>

## Step 2 — Configure the provider in the Sublay dashboard

In your project dashboard, open **Settings → OAuth Providers**, click **Add Provider**, choose the provider, and fill in the modal.

For **Google, GitHub, and Facebook** the fields are:

| Field                     | What to enter                                                                |
| ------------------------- | ---------------------------------------------------------------------------- |
| **Client ID**             | The client ID from the provider console                                      |
| **Client Secret**         | The client secret from the provider console                                  |
| **Allowed Redirect URIs** | Your app's return URLs — see below                                           |
| **Scopes**                | Pre-filled with sensible defaults; leave as-is unless you know you need more |

**Apple is the exception.** Apple has no static client secret — Sublay generates one on the fly by signing a token with your key. So the Apple modal replaces "Client Secret" with **Team ID**, **Key ID**, and **Private Key (.p8 contents)**. See the [Apple page](/sdk/authentication/oauth-providers/apple) for exactly what goes where.

### Allowed Redirect URIs

This field is your app's return address — the same value you pass as `redirectAfterAuth` when you call `initiateOAuth` in code. Sublay only redirects back to URLs on this list, so it must match what your app sends **exactly**, character for character (a trailing slash mismatch will fail).

Add every URL you'll use — production, staging, local development, and any deep links:

* **Web** — a full HTTPS URL, e.g. `https://yourapp.com/auth/callback`
* **Expo / native** — your custom-scheme deep link, e.g. `myapp://auth/callback`

Each entry must be a valid URL. For local web development, `http://localhost:3000/auth/callback` is fine.

### Scopes

Scopes control what profile data the provider returns. Sublay pre-fills each provider with the defaults it needs to create a user (name and email in most cases), so you can leave them untouched for a standard setup. Add more only if your provider requires additional scopes for data you specifically need.

## Step 3 — Enable and test

Saving the provider enables it. Wire up the sign-in button as shown in [OAuth](/sdk/authentication/oauth) and run the flow end to end. If something fails, the two usual culprits are:

1. **A redirect URI mismatch** — the value in your code, the Allowed Redirect URIs list, and (on the provider side) the registered callback URL must all agree.
2. **A missing provider callback** — confirm `https://api.sublay.io/v7/oauth/callback` is registered in the provider's console.

## See Also

* [OAuth](/sdk/authentication/oauth) — the runtime code (sign-in, callback, linking)
* [`useOAuthSignIn` hook reference](/hooks/auth/use-oauth-sign-in)
* [`useOAuthIdentities` hook reference](/hooks/auth/use-oauth-identities)


# Overview
Source: https://docs.sublay.io/v7/sdk/authentication/overview

Auth state, sign-up/in/out, and the token model

Sublay supports three authentication modes that can be used independently or together in the same project: built-in email/password auth, external auth via signed JWTs from your own auth system, and OAuth (Google, GitHub, Apple, Facebook). The SDK handles token storage, refresh, and multi-account state automatically.

## In This Section

<CardGroup>
  <Card title="Built-in Auth" icon="lock" href="/sdk/authentication/built-in">
    Register and sign in users with email and password. Sublay manages the credentials, tokens, and password reset flow.
  </Card>

  <Card title="External Auth" icon="code" href="/sdk/authentication/external">
    Bring your own auth system. Sign a JWT with your project's private key and exchange it for Sublay tokens.
  </Card>

  <Card title="OAuth" icon="key" href="/sdk/authentication/oauth">
    Let users sign in with Google, GitHub, Apple, or Facebook using a redirect-based OAuth 2.0 flow.
  </Card>

  <Card title="Multi-Account" icon="users" href="/sdk/authentication/multi-account">
    Allow users to be signed into multiple accounts simultaneously and switch between them.
  </Card>
</CardGroup>

## Token Model

Sublay uses a two-token system:

* **Access token** — A short-lived JWT (30 minutes) included in API requests as a `Bearer` token. The SDK manages this automatically and refreshes it in the background.
* **Refresh token** — A long-lived JWT (30 days) used to obtain new access tokens. Stored locally by the SDK's AccountManager. Refresh tokens rotate on every use; reuse of a revoked token invalidates the entire session family.

You do not need to manage tokens directly. The `useAuth` hook exposes them if needed for advanced use cases.

## Core Hook

The `useAuth` hook is the primary interface for authentication state and actions:

```tsx theme={null}
import { useAuth } from "@sublay/react-js";

function AuthExample() {
  const {
    initialized,
    accessToken,
    signInWithEmailAndPassword,
    signOut,
  } = useAuth();

  if (!initialized) return <p>Loading...</p>;
  if (!accessToken) return <p>Not signed in.</p>;

  return (
    // `signOut` rejects when the server refuses the push unbind — nothing was
    // torn down, so surface it and let the user retry.
    <button onClick={() => signOut().catch(showError)}>Sign out</button>
  );
}
```

<Note>
  `initialized` is `false` until the SDK has attempted to restore a session from
  the stored refresh token. Always check `initialized` before rendering
  auth-dependent UI.
</Note>


# Conversations
Source: https://docs.sublay.io/v7/sdk/chat/conversations

Create, list, and manage direct and group conversations

This guide covers how to work with conversations: listing the user's conversations, creating new ones, fetching a single conversation, and managing members.

## Listing Conversations

`useConversations` fetches the authenticated user's conversation list with cursor-based pagination. The list is sorted by most recent activity.

```tsx theme={null}
import { useConversations } from "@sublay/react-js";

function ConversationList() {
  const { conversations, loading, hasMore, loadMore } = useConversations();

  return (
    <div>
      {conversations.map((convo) => (
        <div key={convo.id}>
          <strong>{convo.name ?? "Direct Message"}</strong>
          <span>{convo.unreadCount > 0 ? `${convo.unreadCount} unread` : ""}</span>
        </div>
      ))}
      {hasMore && (
        <button onClick={loadMore} disabled={loading}>
          Load more
        </button>
      )}
    </div>
  );
}
```

To filter by conversation type, pass a `types` array:

```tsx theme={null}
// Only show direct and group conversations (no space chats)
const { conversations } = useConversations({ types: ["direct", "group"] });
```

Each item in the list is a `ConversationPreview` — a `Conversation` extended with `unreadCount` and a truncated `lastMessage`.

<Note>
  The list is **live**. It reorders on new messages, inserts conversations as they're created or added (including ones paginated out that receive a new message), removes conversations you leave or that are deleted, and self-heals on socket reconnect — across direct, group, and space chats. You don't need to refetch it manually. See [Real-time › Live Conversation List](/sdk/chat/real-time#live-conversation-list).
</Note>

See [`useConversations`](/hooks/chat/conversations/use-conversations) for the full API.

## Creating a Direct Conversation

Use `useCreateDirectConversation` to start a 1:1 conversation with another user. If a direct conversation between the two users already exists, the server returns the existing one.

```tsx theme={null}
import { useCreateDirectConversation } from "@sublay/react-js";

function StartChat({ userId }: { userId: string }) {
  const createDirect = useCreateDirectConversation();

  const handleClick = async () => {
    const conversation = await createDirect({ userId });
    // Navigate to the conversation view
  };

  return <button onClick={handleClick}>Send a message</button>;
}
```

See [`useCreateDirectConversation`](/hooks/chat/conversations/use-create-direct-conversation).

## Creating a Group Conversation

Group conversations are created via `useConversations`, which exposes a `createGroup` function:

```tsx theme={null}
import { useConversations } from "@sublay/react-js";

function NewGroupButton() {
  const { createGroup } = useConversations();

  const handleCreate = async () => {
    const conversation = await createGroup({
      name: "Project Team",
      metadata: { color: "#4f46e5" },
    });
    // Navigate to the new group
  };

  return <button onClick={handleCreate}>New Group</button>;
}
```

After creation, the new conversation is prepended to the conversation list in Redux state.

## Accessing a Single Conversation

`useConversation` fetches full details for one conversation and provides `update` and `deleteConversation` actions:

```tsx theme={null}
import { useConversation } from "@sublay/react-js";

function ConversationHeader({ conversationId }: { conversationId: string }) {
  const { conversation, loading, update } = useConversation({ conversationId });

  if (loading || !conversation) return <div>Loading...</div>;

  return (
    <div>
      <h2>{conversation.name ?? "Direct Message"}</h2>
      <button onClick={() => update({ name: "New Name" })}>Rename</button>
    </div>
  );
}
```

The conversation is fetched once on mount if not already in Redux state. Real-time `conversation:updated` socket events keep it current automatically.

See [`useConversation`](/hooks/chat/conversations/use-conversation).

## Managing Members

`useConversationMembers` loads the member list and exposes add, remove, leave, and role-change actions:

```tsx theme={null}
import { useConversationMembers } from "@sublay/react-js";

function MemberList({ conversationId }: { conversationId: string }) {
  const { members, addMember, removeMember, changeRole, leave } =
    useConversationMembers({ conversationId });

  return (
    <ul>
      {members.map((member) => (
        <li key={member.userId}>
          {member.user?.name} — {member.role}
          <button onClick={() => removeMember({ userId: member.userId })}>
            Remove
          </button>
        </li>
      ))}
    </ul>
  );
}
```

See [`useConversationMembers`](/hooks/chat/conversations/use-conversation-members).

## Space Conversations

Every Space has a single associated conversation. Use `useFetchSpaceConversation` to retrieve it:

```tsx theme={null}
import { useFetchSpaceConversation } from "@sublay/react-js";

function SpaceChat({ spaceId }: { spaceId: string }) {
  const { conversation, loading } = useFetchSpaceConversation({ spaceId });

  if (!conversation) return null;

  // Use conversation.id with message hooks
}
```

See [`useFetchSpaceConversation`](/hooks/chat/conversations/use-fetch-space-conversation).

## Next Steps

<CardGroup>
  <Card title="Messages" icon="message" href="/sdk/chat/messages">
    Send and receive messages in a conversation
  </Card>

  <Card title="Real-time" icon="bolt" href="/sdk/chat/real-time">
    Typing indicators, unread counts, read receipts
  </Card>
</CardGroup>


# Messages
Source: https://docs.sublay.io/v7/sdk/chat/messages

Send, load, edit, delete, and react to messages in a conversation

This guide covers working with messages inside a conversation: loading the message history, sending new messages, editing and deleting messages, and toggling emoji reactions.

## Loading Messages

`useLiveChatMessages` fetches paginated messages for a conversation. Messages are stored in Redux and kept in sync by the `ChatProvider` socket.

<Note>`useChatMessages` was renamed to `useLiveChatMessages`. The old name still works as a deprecated alias.</Note>

```tsx theme={null}
import { useLiveChatMessages } from "@sublay/react-js";

function MessageList({ conversationId }: { conversationId: string }) {
  const { messages, loading, hasMore, loadOlder } = useLiveChatMessages({
    conversationId,
  });

  return (
    <div>
      {hasMore && (
        <button onClick={loadOlder} disabled={loading}>
          Load older messages
        </button>
      )}
      {messages.map((msg) => (
        <div key={msg.id}>
          <strong>{msg.user?.name}</strong>: {msg.content}
        </div>
      ))}
    </div>
  );
}
```

Messages are sorted oldest-first in the returned array. `loadOlder` fetches messages older than the oldest currently loaded.

To include attached files in the response, pass `includeFiles: true`:

```tsx theme={null}
const { messages } = useLiveChatMessages({ conversationId, includeFiles: true });
```

See [`useLiveChatMessages`](/hooks/chat/messages/use-live-chat-messages).

### Filtered / read-only queries

`useLiveChatMessages` is the live conversation stream and intentionally takes no `filters`. To fetch a **filtered** or read-only list of messages — for example, only messages that have replies — use [`useFetchManyChatMessagesWrapper`](/hooks/chat/messages/use-fetch-many-chat-messages), which keeps results in local state and never receives live socket traffic:

```tsx theme={null}
import { useFetchManyChatMessagesWrapper } from "@sublay/react-js";

const { messages, loading, hasMore, loadMore, refetch } =
  useFetchManyChatMessagesWrapper({
    conversationId,
    filters: { hasReplies: true },
  });
```

See [`useFetchManyChatMessages`](/hooks/chat/messages/use-fetch-many-chat-messages).

## Sending Messages

`useSendMessage` returns an async function that sends a message and performs an optimistic insert — the message appears immediately in the UI with a temporary ID, then the temporary entry is replaced by the server-confirmed message.

```tsx theme={null}
import { useSendMessage } from "@sublay/react-js";

function MessageInput({ conversationId }: { conversationId: string }) {
  const send = useSendMessage({ conversationId });
  const [text, setText] = useState("");

  const handleSend = async () => {
    if (!text.trim()) return;
    await send({ content: text });
    setText("");
  };

  return (
    <div>
      <input value={text} onChange={(e) => setText(e.target.value)} />
      <button onClick={handleSend}>Send</button>
    </div>
  );
}
```

### Message Content Options

`useSendMessage` accepts a rich set of parameters:

| Parameter         | Type                  | Description                                   |
| ----------------- | --------------------- | --------------------------------------------- |
| `content`         | `string`              | Plain text content                            |
| `gif`             | `GifData`             | GIF attachment                                |
| `mentions`        | `Mention[]`           | User mentions embedded in the message         |
| `metadata`        | `Record<string, any>` | Arbitrary key-value data                      |
| `quotedMessageId` | `string \| null`      | ID of the message being quoted/replied to     |
| `parentMessageId` | `string \| null`      | ID of the parent message (for thread replies) |
| `files`           | `File[]`              | File attachments (triggers multipart upload)  |

### Sending with Files

When `files` is provided, the hook automatically switches to a multipart form upload:

```tsx theme={null}
const handleSendWithFile = async (file: File) => {
  await send({
    content: "Check this out",
    files: [file],
  });
};
```

See [`useSendMessage`](/hooks/chat/messages/use-send-message).

## Editing Messages

`useEditMessage` returns a function that takes `conversationId`, `messageId`, and updated content fields. The Redux store is updated immediately on success.

```tsx theme={null}
import { useEditMessage } from "@sublay/react-js";

function EditableMessage({ conversationId, messageId }) {
  const edit = useEditMessage();

  const handleEdit = async (newContent: string) => {
    await edit({ conversationId, messageId, content: newContent });
  };

  // ...
}
```

See [`useEditMessage`](/hooks/chat/messages/use-edit-message).

## Deleting Messages

`useDeleteMessage` performs a soft delete. The message is removed from the local Redux store immediately; on the server, it is soft-deleted (content cleared, `userDeletedAt` set).

```tsx theme={null}
import { useDeleteMessage } from "@sublay/react-js";

function MessageActions({ conversationId, messageId }) {
  const deleteMsg = useDeleteMessage();

  return (
    <button onClick={() => deleteMsg({ conversationId, messageId })}>
      Delete
    </button>
  );
}
```

See [`useDeleteMessage`](/hooks/chat/messages/use-delete-message).

## Reactions

`useToggleReaction` adds or removes an emoji reaction on a message. The response includes updated `reactionCounts` and `userReactions`:

```tsx theme={null}
import { useToggleReaction } from "@sublay/react-js";

function ReactionBar({ conversationId, messageId, reactionCounts, userReactions }) {
  const toggle = useToggleReaction();

  return (
    <div>
      {["👍", "❤️", "😂"].map((emoji) => (
        <button
          key={emoji}
          onClick={() => toggle({ conversationId, messageId, emoji })}
          style={{ fontWeight: userReactions.includes(emoji) ? "bold" : "normal" }}
        >
          {emoji} {reactionCounts[emoji] ?? 0}
        </button>
      ))}
    </div>
  );
}
```

See [`useToggleReaction`](/hooks/chat/messages/use-toggle-reaction).

## Next Steps

<CardGroup>
  <Card title="Real-time" icon="bolt" href="/sdk/chat/real-time">
    Typing indicators, unread counts, and read receipts
  </Card>

  <Card title="Threads" icon="code-branch" href="/sdk/chat/threads">
    Threaded replies on messages
  </Card>
</CardGroup>


# Overview
Source: https://docs.sublay.io/v7/sdk/chat/overview

Real-time 1:1 and group messaging with reactions, threading, and typing indicators

Sublay Chat lets you embed full-featured messaging directly into your application. It supports direct (1:1) conversations, group conversations, and per-space chat channels. All conversations are real-time, backed by Socket.io, with read receipts, typing indicators, reaction support, and threaded replies.

<Note>
  **Requires the `chat` bundle.** Chat is only available when the `chat` bundle is installed on your project. See [Bundles](/bundles) to add it.
</Note>

## In This Section

<CardGroup>
  <Card title="Setup" href="/sdk/chat/setup">
    Add `ChatProvider` to your component tree to initialize the socket connection
  </Card>

  <Card title="Conversations" href="/sdk/chat/conversations">
    Create direct and group conversations, manage members, and render a live conversation list that reorders, inserts, and removes in real time
  </Card>

  <Card title="Messages" href="/sdk/chat/messages">
    Send, edit, delete, and react to messages with optimistic UI updates
  </Card>

  <Card title="Real-time" href="/sdk/chat/real-time">
    Socket events, typing indicators, unread counts, and read receipts
  </Card>

  <Card title="Threads" href="/sdk/chat/threads">
    Threaded replies to messages for focused side-conversations
  </Card>
</CardGroup>

## Architecture

Chat is built around a two-level provider hierarchy:

```
ChatProvider          — one per app; owns the socket connection
  └── Your UI         — conversation list, conversation views, etc.
```

`ChatProvider` establishes the Socket.io connection and maintains global state (unread counts, message store, and the live conversation list). Individual components then use the hooks directly — there is no second-level context required for basic usage. The conversation list stays current in real time and reconciles with the server on reconnect, so consumers never have to poll or refetch it manually.

For space chat, use `useFetchSpaceConversation` to retrieve the conversation associated with a space, then interact with it using the same hooks used for any other conversation.

## Conversation Types

| Type     | Description                                |
| -------- | ------------------------------------------ |
| `direct` | 1:1 conversation between two users         |
| `group`  | Multi-user conversation created explicitly |
| `space`  | Conversation automatically tied to a Space |

## Next Steps

Start with [Chat Setup](/sdk/chat/setup) to add `ChatProvider` to your app.


# Real-time Features
Source: https://docs.sublay.io/v7/sdk/chat/real-time

Typing indicators, unread counts, and marking conversations as read

`ChatProvider` handles all real-time communication automatically. This guide explains what happens behind the scenes and which hooks you use to expose real-time state in your UI.

## How Real-time Works

`ChatProvider` opens a single Socket.io connection for the authenticated user. All components using chat hooks share this one connection. The provider listens for server events and updates Redux state, so any component reading from the hooks will re-render with up-to-date data.

### Socket Events Handled Automatically

| Event                  | What the SDK does                                                                                                                                                                                                                                                                                                                                                                    |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `message:created`      | Appends message to the conversation's store; reorders the conversation to the top of the list and increments unread if the conversation is not currently active. If the conversation isn't in the loaded list (e.g. paginated out, or brand new), it's fetched and inserted automatically                                                                                            |
| `message:updated`      | Updates the message's content in the store                                                                                                                                                                                                                                                                                                                                           |
| `message:deleted`      | Marks the message as soft-deleted in the store                                                                                                                                                                                                                                                                                                                                       |
| `message:removed`      | Sets `moderationStatus: "removed"` on the message                                                                                                                                                                                                                                                                                                                                    |
| `message:reaction`     | Updates `reactionCounts` and `userReactions` on the message                                                                                                                                                                                                                                                                                                                          |
| `message:grant`        | A [reputation grant](/data-models/reputation-grant) landed on the message. Updates the message's `grants` summary in the store. The payload carries `{ messageId, conversationId, grant, summary }`, and `summary` is `{ total, count }` **only** — `viewerTotal` is per-viewer, so the SDK derives it from `grant.senderId` and `grant.amount`. Negative grants are never broadcast |
| `thread:reply_count`   | Updates `threadReplyCount` on the parent message                                                                                                                                                                                                                                                                                                                                     |
| `typing:start`         | Adds the user to the typing list for that conversation                                                                                                                                                                                                                                                                                                                               |
| `typing:stop`          | Removes the user from the typing list                                                                                                                                                                                                                                                                                                                                                |
| `conversation:updated` | Merges the updated conversation fields into the store                                                                                                                                                                                                                                                                                                                                |
| `conversation:created` | Inserts a newly created conversation (a new DM, group, or one you were added to) into the conversation list                                                                                                                                                                                                                                                                          |
| `member:left`          | When it's the current user leaving or being removed, removes the conversation from the list                                                                                                                                                                                                                                                                                          |
| `conversation:deleted` | Removes the conversation from the list                                                                                                                                                                                                                                                                                                                                               |

## Live Conversation List

The conversation list returned by `useConversations` is fully live — you do not need to refetch it manually:

* **Reorders** to the top when a new message arrives in any conversation, across direct, group, and space chats.
* **Inserts** new conversations as they appear — a DM someone starts with you, a group you're added to, or a paginated-out conversation that just received a message.
* **Removes** conversations you leave, are removed from, or that are deleted.
* **Self-heals on reconnect.** After a dropped socket reconnects, the list and unread counts reconcile against the server automatically, correcting anything missed while offline (deep pagination resets to the first page).

## Connection State

Use `useChatSocket` to read whether the socket is connected:

```tsx theme={null}
import { useChatSocket } from "@sublay/react-js";

function ConnectionStatus() {
  const { connected } = useChatSocket();
  return <span>{connected ? "Connected" : "Reconnecting..."}</span>;
}
```

See [`useChatSocket`](/hooks/chat/use-chat-socket).

## Unread Counts

`ChatProvider` fetches unread counts on mount and keeps them in sync via socket events, including for conversations not currently loaded in the list. Counts also reconcile against the server on socket reconnect.

```tsx theme={null}
import { useTotalUnreadCount, useUnreadConversationCount } from "@sublay/react-js";

function ChatBadge() {
  const total = useTotalUnreadCount();
  const withUnread = useUnreadConversationCount();

  return (
    <div>
      <span>{total} unread messages</span>
      <span>{withUnread} conversations with unread messages</span>
    </div>
  );
}
```

* [`useTotalUnreadCount`](/hooks/chat/use-total-unread-count) — sum of all unread messages
* [`useUnreadConversationCount`](/hooks/chat/use-unread-conversation-count) — number of conversations that have at least one unread message

<Note>
  When an event touches a conversation not currently loaded in the list (e.g. paginated out), both `useTotalUnreadCount` and `useUnreadConversationCount` reconcile automatically against the server's authoritative unread summary — no manual refresh or remount is required.
</Note>

## Read Receipts

Mark a conversation as read by calling `useMarkConversationAsRead`. This clears the unread count in Redux immediately (optimistic) and sends the mark-as-read request to the server.

```tsx theme={null}
import { useMarkConversationAsRead } from "@sublay/react-js";

function ConversationView({ conversationId, messages }) {
  const mark = useMarkConversationAsRead({ conversationId });

  // Mark as read when the latest message becomes visible
  useEffect(() => {
    const lastMessage = messages[messages.length - 1];
    if (lastMessage) {
      mark({ messageId: lastMessage.id });
    }
  }, [messages]);
}
```

See [`useMarkConversationAsRead`](/hooks/chat/use-mark-conversation-as-read).

## Typing Indicators

`useTypingIndicator` manages both sending typing events to other users and receiving typing events from them.

```tsx theme={null}
import { useTypingIndicator } from "@sublay/react-js";

function MessageInput({ conversationId }) {
  const { typingUsers, startTyping, stopTyping } = useTypingIndicator({
    conversationId,
  });

  return (
    <div>
      {typingUsers.length > 0 && (
        <p>{typingUsers.length} person(s) typing...</p>
      )}
      <input
        onChange={() => startTyping()}
        onBlur={stopTyping}
      />
    </div>
  );
}
```

### Sender Protocol

* Call `startTyping()` on each keystroke. The hook throttles the emit to every 2 seconds internally — you do not need to debounce.
* Call `stopTyping()` when the user sends the message, clears the input, or blurs the field.
* The hook emits `typing:stop` automatically on unmount if the user was typing.

### Receiver Side

`typingUsers` is an array of user IDs currently typing in this conversation. The current user is excluded. Each typing user is auto-removed after 5 seconds of inactivity (no keep-alive event from the server).

See [`useTypingIndicator`](/hooks/chat/use-typing-indicator).

## Reporting Messages

Users can report messages for moderation review:

```tsx theme={null}
import { useCreateReport } from "@sublay/react-js";

function MessageMenu({ messageId }) {
  const report = useCreateReport({ type: "message" });

  return (
    <button onClick={() => report({ targetId: messageId, reason: "spam" })}>
      Report
    </button>
  );
}
```

Message reports use the same hook as entity and comment reports. `targetId` is
the message id — the conversation is resolved server-side.

See [`useCreateReport`](/hooks/reports/use-create-report).


# Chat Setup
Source: https://docs.sublay.io/v7/sdk/chat/setup

Add ChatProvider to your app to enable real-time messaging

`ChatProvider` is the root component for the entire chat system. It establishes and manages the Socket.io connection, fetches initial unread counts, and provides the shared socket instance to all hooks that need it.

<Note>
  `ChatProvider` must be placed inside `SublayProvider` and above any component that uses chat hooks.
</Note>

## Adding ChatProvider

<Steps>
  <Step title="Import and wrap your app">
    Place `ChatProvider` inside `SublayProvider` but outside your conversation UI:

    ```tsx theme={null}
    import { SublayProvider, ChatProvider } from "@sublay/react-js";

    function App() {
      return (
        <SublayProvider projectId="your-project-id">
          <ChatProvider>
            <YourApp />
          </ChatProvider>
        </SublayProvider>
      );
    }
    ```
  </Step>

  <Step title="Authentication">
    `ChatProvider` only connects the socket when a user is authenticated. If no access token is available, no connection is attempted. The socket reconnects automatically when the user signs in and disconnects when they sign out.
  </Step>
</Steps>

## What ChatProvider Does

When a user is authenticated, `ChatProvider`:

1. **Opens a Socket.io connection** to the Sublay server, authenticated with the user's access token
2. **Fetches initial unread counts** (total unread messages and count of conversations with unread messages) so badges are accurate before the conversation list is loaded
3. **Listens for real-time events** — new messages, message edits, deletions, reactions, typing indicators, and conversation updates
4. **Updates Redux state** automatically as events arrive, so all components using chat hooks stay in sync

## Token Rotation

When the access token rotates (e.g. after a refresh), `ChatProvider` updates the socket's auth credentials and forces a re-handshake. The socket is not torn down — room memberships are preserved.

## Checking Connection State

Use [`useChatSocket`](/hooks/chat/use-chat-socket) to read the connection state in your UI:

```tsx theme={null}
import { useChatSocket } from "@sublay/react-js";

function ConnectionBadge() {
  const { connected } = useChatSocket();
  return <span>{connected ? "Online" : "Connecting..."}</span>;
}
```

## Unread Counts

Two hooks expose the unread counts fetched on mount:

* [`useTotalUnreadCount`](/hooks/chat/use-total-unread-count) — total number of unread messages across all conversations
* [`useUnreadConversationCount`](/hooks/chat/use-unread-conversation-count) — number of conversations with at least one unread message

These are useful for badges in navigation:

```tsx theme={null}
import { useTotalUnreadCount } from "@sublay/react-js";

function NavBadge() {
  const unread = useTotalUnreadCount();
  if (unread === 0) return null;
  return <span className="badge">{unread}</span>;
}
```

## Next Steps

<CardGroup>
  <Card title="Conversations" icon="comments" href="/sdk/chat/conversations">
    Create and list conversations
  </Card>

  <Card title="Messages" icon="message" href="/sdk/chat/messages">
    Send and receive messages
  </Card>
</CardGroup>


# Message Threads
Source: https://docs.sublay.io/v7/sdk/chat/threads

Threading replies under a parent message

Threads allow users to reply to a specific message in a focused side-conversation without cluttering the main message stream. Each top-level message can have replies, and the `threadReplyCount` field on the message shows how many replies exist.

## How Threads Work

* Any message can be the root of a thread (a `parentMessageId` of `null`).
* Thread replies have `parentMessageId` set to the root message's ID.
* Threads are one level deep — replies cannot have their own threads.
* The `threadReplyCount` on a root message is updated in real-time via the `thread:reply_count` socket event.

## Using useMessageThread

`useMessageThread` is a convenience hook that combines message loading and sending for a specific message thread:

```tsx theme={null}
import { useMessageThread } from "@sublay/react-js";

function ThreadPanel({
  conversationId,
  messageId,
}: {
  conversationId: string;
  messageId: string;
}) {
  const { replies, loading, hasMore, loadMore, sendReply } = useMessageThread({
    conversationId,
    messageId,
  });
  const [text, setText] = useState("");

  const handleReply = async () => {
    if (!text.trim()) return;
    await sendReply({ content: text });
    setText("");
  };

  return (
    <div>
      <h3>Thread</h3>
      {replies.map((reply) => (
        <div key={reply.id}>
          <strong>{reply.user?.name}</strong>: {reply.content}
        </div>
      ))}
      {hasMore && <button onClick={loadMore}>Load more</button>}
      <input
        value={text}
        onChange={(e) => setText(e.target.value)}
        placeholder="Reply..."
      />
      <button onClick={handleReply}>Reply</button>
    </div>
  );
}
```

Replies are loaded in ascending order (oldest first) and `loadMore` fetches newer replies.

See [`useMessageThread`](/hooks/chat/messages/use-message-thread).

## Using useLiveChatMessages Directly

For more control, use `useLiveChatMessages` with a `parentId` to load thread replies:

```tsx theme={null}
import { useLiveChatMessages, useSendMessage } from "@sublay/react-js";

const { messages: replies, loading, hasMore, loadOlder } = useLiveChatMessages({
  conversationId,
  parentId: messageId,   // pass parentId to load thread replies
});

const send = useSendMessage({ conversationId });

// Send a thread reply
await send({
  content: "My reply",
  parentMessageId: messageId,
});
```

## Showing the Reply Count

The root message object includes a `threadReplyCount` field. Use it to render a "View thread" button:

```tsx theme={null}
function Message({ message, onOpenThread }) {
  return (
    <div>
      <p>{message.content}</p>
      {message.threadReplyCount > 0 && (
        <button onClick={() => onOpenThread(message.id)}>
          {message.threadReplyCount}{" "}
          {message.threadReplyCount === 1 ? "reply" : "replies"}
        </button>
      )}
    </div>
  );
}
```

`threadReplyCount` is kept in sync automatically by `ChatProvider` when a new reply is sent by any participant.


# Managing Collections
Source: https://docs.sublay.io/v7/sdk/collections/managing-collections

Navigating, creating, and managing the collection hierarchy

## Overview

The `useCollections` hook gives you a navigable view of the user's collection tree. It automatically fetches the root collection on mount and loads sub-collections as you navigate deeper.

## Setting Up

`useCollections` requires a logged-in user. It reads the user and project context from the nearest `SublayProvider`.

```tsx theme={null}
import { useCollections } from "@sublay/react-js";

function CollectionsPanel() {
  const {
    currentCollection,
    subCollections,
    loading,
    openCollection,
    goBack,
    goToRoot,
    createCollection,
    updateCollection,
    deleteCollection,
    addToCollection,
    removeFromCollection,
  } = useCollections();

  if (loading) return <p>Loading...</p>;
  if (!currentCollection) return null;

  return (
    <div>
      <h2>{currentCollection.name}</h2>
      <ul>
        {subCollections.map((col) => (
          <li key={col.id} onClick={() => openCollection(col)}>
            {col.name} ({col.entityCount} items)
          </li>
        ))}
      </ul>
      {currentCollection.parentId && (
        <button onClick={goBack}>Back</button>
      )}
    </div>
  );
}
```

## Navigating the Tree

The hook maintains a navigation stack. Calling `openCollection` pushes a collection onto the stack and fetches its sub-collections. `goBack` pops the stack; `goToRoot` resets to the root.

```tsx theme={null}
// Navigate into a sub-collection
openCollection(subCollection);

// Go up one level
goBack();

// Jump back to the root
goToRoot();
```

## Creating Sub-collections

`createCollection` creates a new sub-collection inside the current collection.

```tsx theme={null}
await createCollection({ collectionName: "To Read" });
```

<Note>You cannot create a collection at the root of `useCollections` — there is no concept of "creating inside root" vs "creating inside a sub-collection" from the hook's perspective. The current collection is always the parent.</Note>

## Renaming a Collection

```tsx theme={null}
await updateCollection({
  collectionId: collection.id,
  update: { name: "New Name" },
});
```

The root collection cannot be renamed.

## Deleting a Collection

```tsx theme={null}
await deleteCollection({ collection });
```

The root collection cannot be deleted. When a collection is deleted, the navigation state automatically moves back to the parent.

## Saving and Removing Entities

`addToCollection` saves an entity into the current collection. `removeFromCollection` removes it.

```tsx theme={null}
// Save entity to the currently viewed collection
await addToCollection({ entityId: entity.id });

// Remove entity from the currently viewed collection
await removeFromCollection({ entityId: entity.id });
```

## Checking If an Entity Is Saved

`isEntitySaved` queries whether a specific entity is saved anywhere in the user's collections. Optionally pass a `collectionId` to check a specific folder.

```tsx theme={null}
const result = await isEntitySaved({ entityId: entity.id });
// result.saved — true if saved in any collection
// result.collections — list of { id, name } for each collection containing it

const specificResult = await isEntitySaved({ entityId: entity.id, collectionId: collection.id });
// specificResult.inSpecificCollection — true if in that specific collection
```

## Displaying Collection Entities

Use [useCollectionEntitiesWrapper](/hooks/collections/use-collection-entities-wrapper) to fetch the paginated list of entities saved in a collection.

```tsx theme={null}
import { useCollectionEntitiesWrapper } from "@sublay/react-js";

function CollectionFeed({ collectionId }) {
  const { entities, loading, hasMore, loadMore } = useCollectionEntitiesWrapper({
    collectionId,
    defaultSortBy: "added",
  });

  return (
    <ul>
      {entities.map((entity) => (
        <li key={entity.id}>{entity.title}</li>
      ))}
      {hasMore && <button onClick={loadMore}>Load more</button>}
    </ul>
  );
}
```


# Overview
Source: https://docs.sublay.io/v7/sdk/collections/overview

Personal hierarchical bookmark system for saving entities

## What Are Collections?

Collections are a personal bookmarking system built into Sublay. Each authenticated user has a private library of named folders — called collections — where they can save entities for later reference.

<Note>
  **Requires the `collections` bundle.** Collections are only available when the `collections` bundle is installed on your project. See [Bundles](/bundles) to add it.
</Note>

Collections are hierarchical: every user starts with a root collection and can create unlimited sub-collections nested inside it or inside each other.

<Note>Collections are private. They belong to and are only visible to the user who created them.</Note>

## How It Works

1. **Root collection** — automatically created the first time a user accesses their collections. Acts as the top-level folder and cannot be renamed or deleted.
2. **Sub-collections** — folders created inside the root or inside other sub-collections. Can be renamed and deleted.
3. **Entities** — saved into the current collection. The same entity can appear in multiple collections.

## Hooks

<CardGroup>
  <Card title="useCollections" href="/hooks/collections/use-collections">
    Navigate the collection hierarchy and perform CRUD operations on the current collection context.
  </Card>

  <Card title="useCollectionsActions" href="/hooks/collections/use-collections-actions">
    Lower-level actions for fetching, creating, updating, and deleting collections.
  </Card>

  <Card title="useCollectionEntitiesWrapper" href="/hooks/collections/use-collection-entities-wrapper">
    Fetch paginated entities saved in a specific collection with sort and load-more support.
  </Card>
</CardGroup>

<Note>
  To check whether a specific entity is saved in any of the user's collections, see [useIsEntitySaved](/hooks/entities/use-is-entity-saved) in the entities section.
</Note>

## Data Model

See [Collection](/data-models/collection) for the full field reference.


# Comment Section
Source: https://docs.sublay.io/v7/sdk/comments/comment-section

CommentSectionProvider setup and the useCommentSection hook reference

`CommentSectionProvider` loads and manages all comment state for a given entity. Descendant components access this state through `useCommentSection`.

## Setting Up CommentSectionProvider

Identify the target entity with one of four mutually exclusive props:

```tsx theme={null}
import { CommentSectionProvider } from "@sublay/react-js";

// By foreign ID (most common — links to your own content)
<CommentSectionProvider foreignId="your-article-id" createIfNotFound>
  <CommentList />
</CommentSectionProvider>

// By Sublay entity ID
<CommentSectionProvider entityId="ent_abc123">
  <CommentList />
</CommentSectionProvider>

// By short ID
<CommentSectionProvider shortId="x7k2m">
  <CommentList />
</CommentSectionProvider>

// By passing the entity object directly (no fetch needed)
<CommentSectionProvider entity={myEntity}>
  <CommentList />
</CommentSectionProvider>
```

## Provider Props Reference

<ParamField type="string">
  Sublay entity ID. Mutually exclusive with `foreignId`, `shortId`, and `entity`.
</ParamField>

<ParamField type="string">
  Your system's ID for the entity.
</ParamField>

<ParamField type="string">
  Auto-generated short ID.
</ParamField>

<ParamField type="Entity">
  A pre-fetched entity object. Skips the entity fetch.
</ParamField>

<ParamField type="boolean">
  Only valid with `foreignId`. Auto-creates the entity if it doesn't exist yet.
</ParamField>

<ParamField type="number">
  Comments per page. Default: `15`.
</ParamField>

<ParamField type="string">
  Initial sort order: `"top"` (default), `"createdAt"`, or `"controversial"`. `"new"`/`"old"` are deprecated aliases for `"createdAt"` (removed in v8).
</ParamField>

<ParamField type="&#x22;asc&#x22; | &#x22;desc&#x22;">
  Initial sort direction for `sortBy: "createdAt"`. Default: `"desc"` (newest first).
</ParamField>

<ParamField type="string">
  If provided, fetches this comment and its parent and injects it into the tree. Useful for deep-linking to a specific comment.
</ParamField>

<ParamField type="Record<string, function>">
  Optional callback functions for handling UI interactions:

  * `loginRequiredCallback()` — called when a non-authenticated user tries to comment
  * `usernameRequiredCallback()` — called when the user has no username set
  * `commentTooShortCallback()` — called when the submitted comment is too short
</ParamField>

<ParamField type="{ user?: string; space?: string }">
  Override the trigger characters for mentions. Defaults: `{ user: "@", space: "#" }`.
</ParamField>

## Accessing State with `useCommentSection`

```tsx theme={null}
import { useCommentSection } from "@sublay/react-js";

function CommentList() {
  const {
    comments,
    newComments,
    loading,
    hasMore,
    loadMore,
    sortBy,
    setSortBy,
    createComment,
  } = useCommentSection();

  return (
    <>
      <select value={sortBy} onChange={(e) => setSortBy(e.target.value as any)}>
        <option value="top">Top</option>
        <option value="createdAt">New</option>
      </select>
      {loading && <p>Loading...</p>}
      {[...newComments, ...comments].map((c) => (
        <CommentItem key={c.id} comment={c} />
      ))}
      {hasMore && <button onClick={loadMore}>Load more</button>}
    </>
  );
}
```

## `useCommentSection` Return Values

<ResponseField name="entity" type="Entity | null | undefined">
  The entity these comments belong to.
</ResponseField>

<ResponseField name="comments" type="Comment[]">
  Paginated root-level comments (not newly submitted ones).
</ResponseField>

<ResponseField name="newComments" type="Comment[]">
  Comments submitted in this session. Displayed separately from paginated results, sorted newest-first.
</ResponseField>

<ResponseField name="entityCommentsTree" type="EntityCommentsTree">
  The full comment tree as a flat map keyed by comment ID. Used for building threaded reply UIs.
</ResponseField>

<ResponseField name="highlightedComment" type="{ comment: Comment; parentComment: Comment | null } | null">
  The highlighted comment (and its parent, if any) when `highlightedCommentId` is set.
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` while the initial comment load is in progress.
</ResponseField>

<ResponseField name="hasMore" type="boolean">
  `true` when more pages are available.
</ResponseField>

<ResponseField name="submittingComment" type="boolean">
  `true` while a `createComment` call is in flight.
</ResponseField>

<ResponseField name="loadMore" type="() => void">
  Loads the next page of comments.
</ResponseField>

<ResponseField name="sortBy" type="CommentsSortByOptions | null">
  Current sort: `"createdAt"`, `"top"`, or `"controversial"`. (`"new"`/`"old"` are deprecated aliases for `"createdAt"`.)
</ResponseField>

<ResponseField name="setSortBy" type="(newSortBy: CommentsSortByOptions) => void">
  Changes the sort order and resets to page 1.
</ResponseField>

<ResponseField name="sortDir" type="&#x22;asc&#x22; | &#x22;desc&#x22;">
  Current sort direction for `sortBy: "createdAt"`.
</ResponseField>

<ResponseField name="setSortDir" type="(newSortDir: &#x22;asc&#x22; | &#x22;desc&#x22;) => void">
  Changes the sort direction and resets to page 1.
</ResponseField>

<ResponseField name="createComment" type="(props) => Promise<Comment | undefined>">
  Submits a new comment. Applies an optimistic placeholder immediately. Accepts:

  * `parentId` — reply to a specific comment ID
  * `content` — text content
  * `gif` — GIF data object
  * `mentions` — array of `Mention` objects
  * `autoReaction` — automatically react with this reaction type after creating (e.g. `"upvote"`)
</ResponseField>

<ResponseField name="updateComment" type="(props: { commentId: string; content: string }) => Promise<void>">
  Updates a comment's text content.
</ResponseField>

<ResponseField name="deleteComment" type="(props: { commentId: string }) => Promise<void>">
  Marks a comment as deleted (Reddit-style placeholder). The comment remains in the tree with its content hidden.
</ResponseField>

<ResponseField name="selectedComment" type="Comment | null">
  Currently selected/focused comment. Managed via `setSelectedComment`.
</ResponseField>

<ResponseField name="setSelectedComment" type="(comment: Comment | null) => void">
  Set or clear the selected comment.
</ResponseField>

<ResponseField name="repliedToComment" type="Partial<Comment> | null">
  The comment currently being replied to.
</ResponseField>

<ResponseField name="setRepliedToComment" type="(comment: Comment | null) => void">
  Set the comment to reply to.
</ResponseField>

<ResponseField name="showReplyBanner" type="boolean">
  Whether to show a reply indicator UI banner.
</ResponseField>

<ResponseField name="setShowReplyBanner" type="({ newState }: { newState: boolean }) => void">
  Show or hide the reply banner.
</ResponseField>

<ResponseField name="pushMention" type="User | null">
  A user to auto-insert as a mention in the next comment. Set by `handleShallowReply`.
</ResponseField>

<ResponseField name="handleDeepReply" type="(comment: Comment) => void">
  Sets the reply target for a deep reply (reply appears nested under the parent comment).
</ResponseField>

<ResponseField name="handleShallowReply" type="(comment: Comment) => void">
  Sets the reply target for a shallow reply (reply appears at root level with an `@mention`).
</ResponseField>


# Overview
Source: https://docs.sublay.io/v7/sdk/comments/overview

Threaded comment sections using CommentSectionProvider and useCommentSection

Comments in Sublay are threaded discussions attached to entities. They support replies (nested or flat), reactions, GIF attachments, user mentions, space mentions, sorting, and pagination.

<Note>
  **Requires the `comments` bundle.** Comments are only available when the `comments` bundle is installed on your project. See [Bundles](/bundles) to add it.
</Note>

<Tip>
  **Don't want to build your own comment UI from scratch?** Sublay ships ready-made comment components — fully featured, themeable, and installed directly into your codebase via the CLI as editable source code. Skip straight to the [Components section](/components/overview) to get up and running in minutes.
</Tip>

## The Provider Pattern

The comment system uses a `CommentSectionProvider` + `useCommentSection` pair. Wrap your comment UI with `CommentSectionProvider` to load comments for an entity, then access all comment state and actions from any descendant with `useCommentSection`.

```tsx theme={null}
import { CommentSectionProvider } from "@sublay/react-js";

function ArticlePage({ articleId }: { articleId: string }) {
  return (
    <CommentSectionProvider foreignId={articleId} createIfNotFound>
      <CommentList />
      <CommentInput />
    </CommentSectionProvider>
  );
}
```

## What the Provider Manages

* **Loading comments** — fetches the first page on mount and provides `loadMore` for pagination
* **Comment tree** — maintains a `entityCommentsTree` with comments and their replies organized as a map
* **New comments** — tracks freshly submitted comments separately from paginated ones
* **Highlighted comment** — fetches and highlights a specific comment (e.g., from a deep link)
* **Reply state** — tracks which comment is being replied to and shows/hides the reply banner
* **CRUD actions** — `createComment`, `updateComment`, `deleteComment` with optimistic updates
* **Sort** — `sortBy`/`setSortBy` for switching between `"createdAt"`, `"top"`, and `"controversial"` (`"new"`/`"old"` are deprecated aliases for `"createdAt"`), plus `sortDir`/`setSortDir` (`"asc"`/`"desc"`) for the `"createdAt"` direction

## In This Section

<CardGroup>
  <Card title="Comment Section" href="/sdk/comments/comment-section">
    Full guide to CommentSectionProvider props and the useCommentSection hook values.
  </Card>
</CardGroup>

## Pre-Built Comment Components

If you'd rather not wire up your own comment UI, Sublay provides two production-ready comment components installed via the CLI directly into your project as editable source code.

<CardGroup>
  <Card title="Threaded Comments" href="/components/components/threaded/overview">
    A classic threaded comment section with nested replies, reactions, and sorting. Ideal for blogs, docs, and long-form content.
  </Card>

  <Card title="Social Comments" href="/components/components/social/overview">
    A flat social-style comment feed with inline replies and a familiar social media feel. Great for feeds, posts, and community content.
  </Card>
</CardGroup>

Both components are built on top of `CommentSectionProvider` and `useCommentSection` — the same primitives documented here — so you can customize them as deeply as needed after installation.

## Comment Data Model

See the [Comment data model](/data-models/comment) for the full field reference.


# Drafts & Publishing
Source: https://docs.sublay.io/v7/sdk/entities/drafts-and-publishing

Create entities as drafts and publish them when ready

Sublay supports a draft/publish workflow for entities. An entity created with `isDraft: true` is stored but not publicly visible. When the creator is ready, they publish it and it becomes visible to others.

## Creating a Draft

Pass `isDraft: true` to `useCreateEntity`:

```tsx theme={null}
import { useCreateEntity } from "@sublay/react-js";

function NewPostEditor() {
  const createEntity = useCreateEntity();

  const saveDraft = async () => {
    const draft = await createEntity({
      title: "My Post",
      content: "Work in progress...",
      isDraft: true,
    });
    console.log("Draft saved:", draft.id);
  };

  return <button onClick={saveDraft}>Save Draft</button>;
}
```

## Listing the Current User's Drafts

Use `useFetchDrafts` to retrieve all unpublished drafts for the authenticated user:

```tsx theme={null}
import { useFetchDrafts } from "@sublay/react-js";
import { useEffect, useState } from "react";

function DraftsList() {
  const fetchDrafts = useFetchDrafts();
  const [drafts, setDrafts] = useState([]);

  useEffect(() => {
    fetchDrafts({ page: 1, limit: 20 }).then((res) => setDrafts(res.data));
  }, []);

  return (
    <ul>
      {drafts.map((d) => (
        <li key={d.id}>{d.title || "Untitled draft"}</li>
      ))}
    </ul>
  );
}
```

`useFetchDrafts` parameters:

| Param      | Type                 | Description                                       |
| ---------- | -------------------- | ------------------------------------------------- |
| `page`     | `number`             | Page number for pagination                        |
| `limit`    | `number`             | Results per page                                  |
| `sourceId` | `string`             | Filter by source ID                               |
| `spaceId`  | `string`             | Filter by space                                   |
| `include`  | `string \| string[]` | Populate related data (`"user"`, `"space"`, etc.) |

Returns a paginated response: `{ data: Entity[], pagination: { page, pageSize, totalPages, totalItems, hasMore } }`.

## Publishing a Draft

Use `usePublishDraft` to publish an existing draft:

```tsx theme={null}
import { usePublishDraft } from "@sublay/react-js";

function DraftItem({ entityId }: { entityId: string }) {
  const publishDraft = usePublishDraft();

  const handlePublish = async () => {
    const published = await publishDraft({ entityId });
    console.log("Published:", published.isDraft); // false
  };

  return <button onClick={handlePublish}>Publish</button>;
}
```

After publishing, `entity.isDraft` is `false` and the entity is publicly visible.

<Note>
  Only the entity's creator can publish their own drafts. The request requires an authenticated user.
</Note>


# Overview
Source: https://docs.sublay.io/v7/sdk/entities/overview

The central content unit in Sublay — posts, articles, products, listings, and anything else your app centers around

<Note>
  **Requires the `entities` bundle.** A project without the entities bundle returns `403 database/tables-not-available` for entity endpoints. `comments` and `collections` build on entities and require it too. See [Bundles](/bundles).
</Note>

An **entity** is the central content unit in Sublay. It represents whatever your app centers around — a blog post, a product listing, a forum thread, a photo, or any other item that users react to, comment on, collect or vote on.

Entities can be:

* Created from scratch in Sublay or linked to existing items in your system via a `foreignId`
* Organized into [Spaces](/sdk/spaces/overview) for community-based content
* Published immediately or saved as **drafts** for later publishing
* Enriched with file attachments, images, keywords, mentions, location, and custom metadata

## How Entities Work

The standard pattern for working with a single entity is via the `EntityProvider` + `useEntity` pair. Wrap a component tree with `EntityProvider` to load and provide entity state, then access that state from any child component using `useEntity`.

For browsing lists of entities, use `EntityListProvider` + `useEntityList`. See [Entity Lists](/sdk/entity-lists/overview).

## In This Section

<CardGroup>
  <Card title="EntityProvider & useEntity" href="/sdk/entities/provider-and-hook">
    Load a single entity by ID, foreign ID, or short ID. Access its state and perform updates and deletes from any child component.
  </Card>

  <Card title="Drafts & Publishing" href="/sdk/entities/drafts-and-publishing">
    Create entities as drafts, list the current user's drafts, and publish them when ready.
  </Card>
</CardGroup>

## Hooks

<CardGroup>
  <Card title="useCreateEntity" href="/hooks/entities/use-create-entity">
    Create a new entity with optional file and image uploads.
  </Card>

  <Card title="useUpdateEntity" href="/hooks/entities/use-update-entity">
    Update an entity's title, content, keywords, attachments, or metadata.
  </Card>

  <Card title="useDeleteEntity" href="/hooks/entities/use-delete-entity">
    Delete an entity.
  </Card>
</CardGroup>

## The `include` Parameter

All fetch hooks accept an optional `include` parameter that populates related data:

| Value          | What it adds                                                                                                          |
| -------------- | --------------------------------------------------------------------------------------------------------------------- |
| `"user"`       | The entity author's `User` object                                                                                     |
| `"space"`      | The associated `Space` object                                                                                         |
| `"topComment"` | The top-voted comment on this entity                                                                                  |
| `"saved"`      | `isSaved: boolean` for the current authenticated user                                                                 |
| `"files"`      | System-managed `File` objects attached to this entity                                                                 |
| `"grants"`     | The entity's [reputation-grant summary](/data-models/reputation-grant#grantsummary) — `{ total, count, viewerTotal }` |

```tsx theme={null}
const entity = await fetchEntity({ entityId, include: ["user", "topComment"] });
```

## Entity Data Model

See the [Entity data model](/data-models/entity) for the complete field reference.


# EntityProvider & useEntity
Source: https://docs.sublay.io/v7/sdk/entities/provider-and-hook

Load a single entity and access its state and actions from any child component

`EntityProvider` is the standard way to load and work with a single entity. Wrap a component tree with it, then use `useEntity` in any descendant to access the entity's data and actions.

## Setting Up EntityProvider

`EntityProvider` accepts one of four mutually exclusive identifier props:

<Steps>
  <Step title="By Sublay entity ID">
    ```tsx theme={null}
    import { EntityProvider } from "@sublay/react-js";

    <EntityProvider entityId="ent_abc123">
      <EntityDetail />
    </EntityProvider>
    ```
  </Step>

  <Step title="By foreign ID">
    Use this when your entity is linked to an item in your own system. Pass `createIfNotFound` to auto-create the entity if it doesn't exist yet.

    ```tsx theme={null}
    <EntityProvider foreignId="my-system-id-456" createIfNotFound>
      <EntityDetail />
    </EntityProvider>
    ```
  </Step>

  <Step title="By short ID">
    Short IDs are auto-generated by Sublay and are useful for short sharing URLs.

    ```tsx theme={null}
    <EntityProvider shortId="x7k2m">
      <EntityDetail />
    </EntityProvider>
    ```
  </Step>

  <Step title="By passing an entity object">
    If you already have the full entity object (e.g., from a list), pass it directly to skip the initial fetch.

    ```tsx theme={null}
    <EntityProvider entity={myEntity}>
      <EntityDetail />
    </EntityProvider>
    ```
  </Step>
</Steps>

<Note>
  `EntityProvider` renders `null` if none of the identifier props are provided. Exactly one must be present.
</Note>

## Accessing Entity State with `useEntity`

Inside any child of `EntityProvider`, call `useEntity()` to access the entity and its actions:

```tsx theme={null}
import { useEntity } from "@sublay/react-js";

function EntityDetail() {
  const { entity, updateEntity, deleteEntity } = useEntity();

  if (!entity) return <p>Loading...</p>;

  return (
    <div>
      <h1>{entity.title}</h1>
      <p>{entity.content}</p>
      <button onClick={() => deleteEntity()}>Delete</button>
    </div>
  );
}
```

## `useEntity` Return Values

<ResponseField name="entity" type="Entity | null | undefined">
  The loaded entity. `undefined` while loading, `null` if not found.
</ResponseField>

<ResponseField name="setEntity" type="React.Dispatch<SetStateAction<Entity | null | undefined>>">
  Direct state setter. Use this if you need to manually update the local entity state.
</ResponseField>

<ResponseField name="updateEntity" type="(props: { update: UpdateEntityUpdate }) => Promise<Entity | undefined>">
  Updates the entity and syncs the new state locally. Accepts:

  * `title` — new title
  * `content` — new content
  * `attachments` — array of attachment objects
  * `keywords` — array of keyword strings
  * `location` — `{ latitude, longitude }`
  * `metadata` — arbitrary JSON object
  * `mentions` — array of `Mention` objects
</ResponseField>

<ResponseField name="deleteEntity" type="() => Promise<void>">
  Deletes the entity and sets local state to `undefined`.
</ResponseField>

## EntityProvider Props Reference

<ParamField type="string">
  Sublay entity ID. Mutually exclusive with `foreignId`, `shortId`, and `entity`.
</ParamField>

<ParamField type="string">
  Your system's ID for this entity. Mutually exclusive with the others.
</ParamField>

<ParamField type="string">
  Auto-generated short identifier. Mutually exclusive with the others.
</ParamField>

<ParamField type="Entity">
  A pre-fetched entity object. Pass this to avoid a redundant fetch. Mutually exclusive with the others.
</ParamField>

<ParamField type="boolean">
  Only valid with `foreignId`. If `true`, the entity is automatically created when it doesn't exist yet. Useful for "entity-per-resource" patterns.
</ParamField>


# Fetching Entities
Source: https://docs.sublay.io/v7/sdk/entity-lists/fetch-entities

Loading, paginating, sorting, and managing entities in a list

`useEntityList` is the main hook for building entity feeds. Each list is identified by a `listId`, allowing multiple independent lists on the same page.

## Basic Setup

```tsx theme={null}
import { useEntityList } from "@sublay/react-js";
import { useEffect } from "react";

function Feed() {
  const { entities, loading, hasMore, fetchEntities, loadMore } = useEntityList({
    listId: "main-feed",
  });

  useEffect(() => {
    fetchEntities(
      {},                         // filters (empty = no filters)
      { sortBy: "hot" },          // sort config
      { limit: 20, include: ["user"] } // list config
    );
  }, []);

  return (
    <>
      {loading && <p>Loading...</p>}
      {entities.map((entity) => (
        <div key={entity.id}>{entity.title}</div>
      ))}
      {hasMore && (
        <button onClick={loadMore} disabled={loading}>
          Load more
        </button>
      )}
    </>
  );
}
```

## `fetchEntities` Signature

```ts theme={null}
fetchEntities(
  filters: Partial<EntityListFilters>,
  sort?: Partial<EntityListSort>,
  config?: EntityListConfig,
  options?: EntityListFetchOptions
) => void
```

### Filters

| Param                | Type                                   | Description                                            |
| -------------------- | -------------------------------------- | ------------------------------------------------------ |
| `timeFrame`          | `"day" \| "week" \| "month" \| "year"` | Filter by age                                          |
| `userId`             | `string`                               | Filter to a specific user's entities                   |
| `followedOnly`       | `boolean`                              | Only show entities from users the current user follows |
| `keywordsFilters`    | `KeywordsFilters`                      | Filter by keywords                                     |
| `titleFilters`       | `TitleFilters`                         | Filter by title content                                |
| `contentFilters`     | `ContentFilters`                       | Filter by body content                                 |
| `attachmentsFilters` | `AttachmentsFilters`                   | Filter by attachments data                             |
| `locationFilters`    | `LocationFilters`                      | Filter by geographic proximity                         |
| `metadataFilters`    | `MetadataFilters`                      | Filter by metadata fields                              |

### Sort config

| Param            | Type                                                                                 | Description                   |
| ---------------- | ------------------------------------------------------------------------------------ | ----------------------------- |
| `sortBy`         | `"createdAt" \| "hot" \| "top" \| "controversial" \| "metadata.field"`               | Sort algorithm                |
| `sortByReaction` | `"upvote" \| "downvote" \| "like" \| "love" \| "wow" \| "sad" \| "angry" \| "funny"` | Used when `sortBy` is `"top"` |
| `sortDir`        | `"asc" \| "desc"`                                                                    | Sort direction                |
| `sortType`       | `"auto" \| "numeric" \| "text" \| "boolean" \| "timestamp"`                          | Type hint for metadata sorts  |

### List config

| Param      | Type                 | Description                                                                                  |
| ---------- | -------------------- | -------------------------------------------------------------------------------------------- |
| `limit`    | `number`             | Results per page. Default: `10`                                                              |
| `sourceId` | `string`             | Filter to a specific source section                                                          |
| `spaceId`  | `string`             | Filter to a specific space                                                                   |
| `include`  | `string \| string[]` | Populate related data: `"user"`, `"space"`, `"topComment"`, `"saved"`, `"files"`, `"grants"` |

### Fetch options

| Param              | Type      | Description                                            |
| ------------------ | --------- | ------------------------------------------------------ |
| `fetchImmediately` | `boolean` | Skip debounce and fetch right away                     |
| `clearImmediately` | `boolean` | Clear the current list before fetching                 |
| `resetFilters`     | `boolean` | Reset all filters to defaults before applying new ones |
| `resetSort`        | `boolean` | Reset sort to defaults before applying new sort        |

## Infinite Scroll

Call `loadMore()` to append the next page. The hook tracks pagination state internally.

```tsx theme={null}
<button onClick={loadMore} disabled={loading || !hasMore}>
  Load More
</button>
```

`hasMore` reflects the value returned by the server, based on the total item count.

## Creating Entities Within a List

`createEntity` creates an entity and automatically inserts it into the list:

```tsx theme={null}
const { createEntity } = useEntityList({ listId: "my-feed" });

await createEntity({
  title: "New Post",
  content: "Hello!",
  insertPosition: "first", // "first" or "last"
});
```

## Deleting Entities From a List

`deleteEntity` removes an entity from both the server and the local list state:

```tsx theme={null}
const { deleteEntity } = useEntityList({ listId: "my-feed" });

await deleteEntity({ entityId: "ent_abc123" });
```

## Sorting by Metadata

You can sort by any metadata field using the `metadata.fieldName` syntax:

```tsx theme={null}
fetchEntities(
  {},
  { sortBy: "metadata.price", sortType: "numeric", sortDir: "asc" }
);
```

<Note>
  Metadata field names must contain only alphanumeric characters and underscores.
</Note>


# Filters
Source: https://docs.sublay.io/v7/sdk/entity-lists/filters

Complete filter reference for entity list queries

Filters are passed as the first argument to `fetchEntities`. They narrow down which entities are returned without affecting the sort order.

```tsx theme={null}
fetchEntities(
  {
    followedOnly: true,
    keywordsFilters: { includes: ["react"] },
    metadataFilters: { includes: { category: "tutorial" } },
  },
  { sortBy: "createdAt" }
);
```

***

## `timeFrame`

Limits results to entities created within a recent window.

| Value     | Description   |
| --------- | ------------- |
| `"day"`   | Last 24 hours |
| `"week"`  | Last 7 days   |
| `"month"` | Last 30 days  |
| `"year"`  | Last 365 days |

```tsx theme={null}
fetchEntities({ timeFrame: "week" }, { sortBy: "top" });
```

***

## `userId`

Filters to entities created by a specific user.

```tsx theme={null}
fetchEntities({ userId: "user_abc123" }, { sortBy: "createdAt" });
```

***

## `followedOnly`

When `true`, returns only entities from users the authenticated user follows.

```tsx theme={null}
fetchEntities({ followedOnly: true }, { sortBy: "hot" });
```

***

## `keywordsFilters`

Filters by the entity's `keywords` array.

```ts theme={null}
interface KeywordsFilters {
  includes?: string[];       // Entity must include ALL of these keywords
  doesNotInclude?: string[]; // Entity must not include ANY of these keywords
}
```

```tsx theme={null}
// Entities tagged with both "react" and "typescript"
fetchEntities({ keywordsFilters: { includes: ["react", "typescript"] } }, { sortBy: "createdAt" });

// Exclude entities tagged "archived"
fetchEntities({ keywordsFilters: { doesNotInclude: ["archived"] } }, { sortBy: "hot" });
```

***

## `titleFilters`

Filters by the entity's `title` field.

```ts theme={null}
interface TitleFilters {
  hasTitle?: boolean;                // Only entities that have (or don't have) a title
  includes?: string | string[];      // Title must contain this text (case-insensitive)
  doesNotInclude?: string | string[]; // Title must not contain this text
}
```

```tsx theme={null}
fetchEntities({ titleFilters: { includes: "product launch" } }, { sortBy: "createdAt" });
```

***

## `contentFilters`

Filters by the entity's `content` field.

```ts theme={null}
interface ContentFilters {
  hasContent?: boolean;
  includes?: string | string[];
  doesNotInclude?: string | string[];
}
```

***

## `attachmentsFilters`

Filters by whether the entity has attachments.

```ts theme={null}
interface AttachmentsFilters {
  hasAttachments?: boolean;
}
```

```tsx theme={null}
// Only entities with attachments
fetchEntities({ attachmentsFilters: { hasAttachments: true } }, { sortBy: "createdAt" });
```

***

## `locationFilters`

Filters to entities within a geographic radius.

```ts theme={null}
interface LocationFilters {
  latitude: number;
  longitude: number;
  radius: number;  // in meters
}
```

```tsx theme={null}
fetchEntities(
  {
    locationFilters: {
      latitude: 37.7749,
      longitude: -122.4194,
      radius: 10000, // 10 km
    },
  },
  { sortBy: "createdAt" }
);
```

***

## `metadataFilters`

Filters by fields inside the entity's `metadata` object.

```ts theme={null}
interface MetadataFilters {
  includes?: Record<string, unknown>;        // All key-value pairs must match exactly
  includesAny?: Record<string, unknown>[];   // At least one object in the array must match
  doesNotInclude?: Record<string, unknown>;  // None of these key-value pairs may match
  exists?: string[];                         // These metadata keys must exist
  doesNotExist?: string[];                   // These metadata keys must not exist
}
```

```tsx theme={null}
// Only "tutorial" category entities
fetchEntities(
  { metadataFilters: { includes: { category: "tutorial" } } },
  { sortBy: "hot" }
);

// Entities that have a "price" metadata key
fetchEntities(
  { metadataFilters: { exists: ["price"] } },
  { sortBy: "createdAt" }
);

// Entities in either "news" or "announcements" category
fetchEntities(
  {
    metadataFilters: {
      includesAny: [{ category: "news" }, { category: "announcements" }],
    },
  },
  { sortBy: "hot" }
);
```

***

## `nsfwFilter`

Filters by an entity's **effective** NSFW status — `entity.nsfw OR its space's nsfwEffective` (which itself folds in the space's whole ancestor chain). On projects without the spaces bundle it applies against the entity's own `nsfw` flag alone.

| Value           | Description                                                                       |
| --------------- | --------------------------------------------------------------------------------- |
| `"include-all"` | **Default.** No NSFW predicate — all entities returned regardless of NSFW status. |
| `"exclude"`     | Drops effective-NSFW entities.                                                    |
| `"only"`        | Returns only effective-NSFW entities.                                             |

```tsx theme={null}
// Hide NSFW content from the feed
fetchEntities({ nsfwFilter: "exclude" }, { sortBy: "hot" });
```

Sublay only labels (`nsfw`) and filters (`nsfwFilter`) NSFW content — it does not blur, age-gate, or store a per-viewer preference. Presentation is your app's responsibility. See [Entity NSFW flagging](/data-models/entity#nsfw-flagging).

***

## Combining Filters

All filters can be combined. An entity must satisfy all specified conditions.

```tsx theme={null}
fetchEntities(
  {
    timeFrame: "week",
    keywordsFilters: { includes: ["design"] },
    metadataFilters: { includes: { status: "published" } },
    attachmentsFilters: { hasAttachments: true },
  },
  { sortBy: "top" },
  { limit: 20, include: ["user"] }
);
```


# Infusing Data
Source: https://docs.sublay.io/v7/sdk/entity-lists/infuse-data

Merging Sublay entity data with data from your own backend

**Data infusion** lets you merge Sublay entity data with records from your own system at the point of display. This is useful when your entities are linked to content in your own database (via `foreignId`) and you want to render a combined view without duplicating data in Sublay.

## How It Works

Pass an `infuseData` function to `useEntityList`. For each entity that has a `foreignId`, the hook calls your function with that `foreignId` and merges the result into the entity under an `infusion` key.

Results are cached by `foreignId` — each external record is only fetched once per list instance.

## Usage Example

```tsx theme={null}
import { useEntityList } from "@sublay/react-js";
import { useEffect } from "react";

async function fetchProductDetails(productId: string) {
  const res = await fetch(`/api/products/${productId}`);
  if (!res.ok) return null;
  return res.json(); // { price, stock, category, ... }
}

function ProductFeed() {
  const { infusedEntities, fetchEntities, hasMore, loadMore } = useEntityList({
    listId: "products",
    infuseData: fetchProductDetails,
  });

  useEffect(() => {
    fetchEntities({}, { sortBy: "createdAt" }, { limit: 20 });
  }, []);

  return (
    <ul>
      {infusedEntities.map((entity) => (
        <li key={entity.id}>
          <strong>{entity.title}</strong>
          {/* infusion fields from your own backend */}
          <span>${entity.infusion.price}</span>
          <span>{entity.infusion.stock} in stock</span>
        </li>
      ))}
    </ul>
  );
}
```

## `infuseData` Signature

```ts theme={null}
infuseData: (foreignId: string) => Promise<Record<string, any> | null>
```

* Called once per unique `foreignId` in the current list
* Return `null` if the record is not found — the entity will still be included with an empty `infusion: {}` object
* Errors thrown inside `infuseData` are caught and logged; the entity is included with empty infusion data

## `infusedEntities` vs `entities`

`useEntityList` returns two arrays:

| Property          | Type                                             | Description                             |
| ----------------- | ------------------------------------------------ | --------------------------------------- |
| `entities`        | `Entity[]`                                       | Raw entities from Sublay                |
| `infusedEntities` | `(Entity & { infusion: Record<string, any> })[]` | Entities merged with your external data |

Use `infusedEntities` when rendering — it always has the same length as `entities` and contains an `infusion` object on each item (empty if no `foreignId` or if `infuseData` returned `null`).

<Note>
  If `infuseData` is not passed to `useEntityList`, `infusedEntities` will be an empty array. Always use `entities` when you do not need infusion.
</Note>


# Overview
Source: https://docs.sublay.io/v7/sdk/entity-lists/overview

Paginated, filtered, sorted feeds of entities with infinite scroll support

Entity Lists is the system for building feeds, search results, and any paginated collection of entities. It handles pagination state, sorting, filtering, and infinite scroll through a Redux-backed architecture.

## The Core Hook

The primary entry point is `useEntityList`. You call it with a unique `listId` — this is how multiple independent lists can exist on the same page without conflicting state.

```tsx theme={null}
import { useEntityList } from "@sublay/react-js";

function Feed() {
  const { entities, loading, hasMore, fetchEntities, loadMore } = useEntityList({
    listId: "main-feed",
  });

  useEffect(() => {
    fetchEntities({}, { sortBy: "hot" }, { limit: 20 });
  }, []);

  return (
    <div>
      {entities.map((entity) => <EntityCard key={entity.id} entity={entity} />)}
      {hasMore && <button onClick={loadMore}>Load more</button>}
    </div>
  );
}
```

## In This Section

<CardGroup>
  <Card title="Fetching Entities" href="/sdk/entity-lists/fetch-entities">
    How to call `fetchEntities`, paginate with `loadMore`, and create or delete entities within a list.
  </Card>

  <Card title="Infusing Data" href="/sdk/entity-lists/infuse-data">
    Merge Sublay entities with data from your own system using the `infuseData` callback.
  </Card>

  <Card title="Filters" href="/sdk/entity-lists/filters">
    Complete reference for keywords, title, content, metadata, attachments, and location filters.
  </Card>
</CardGroup>

## Hooks

<CardGroup>
  <Card title="useEntityList" href="/hooks/entity-lists/use-entity-list">
    Main hook for consuming and managing a paginated entity list.
  </Card>

  <Card title="useEntityListActions" href="/hooks/entity-lists/use-entity-list-actions">
    Low-level actions hook for fetch, create, and delete operations.
  </Card>

  <Card title="useInfusedData" href="/hooks/entity-lists/use-infused-data">
    Merges entity arrays with data from your own backend.
  </Card>
</CardGroup>


# Events Overview
Source: https://docs.sublay.io/v7/sdk/events/overview

Create, list, and manage events with the React SDK

The Events SDK exposes the full events surface as React hooks: creating and editing events (with inline cover/gallery upload), listing them with a paginated wrapper, the RSVP lifecycle, and host/invite management. Hooks authenticate as the **logged-in user** — the server derives who is acting from the token, so you never pass an actor `userId` (the only `userId` arguments are targets, on the host/invite hooks).

All hooks are importable from `@sublay/react-js`, `@sublay/react-native`, and `@sublay/expo`.

<Note>
  Unlike entities, **events have no Redux store**. State is local: load a single
  event with [`EventProvider` / `useEvent`](/sdk/events/provider-and-hook), and
  paginate lists with [`useFetchManyEventsWrapper`](/hooks/events/use-fetch-many-events-wrapper).
</Note>

Requires the `events` bundle on the project. Space-scoping needs `spaces`, images need `files-images`, and notifications need `notifications`.

## Hooks at a glance

| Hook                                                                                                  | Purpose                                                     |
| ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| [`useCreateEvent`](/hooks/events/use-create-event)                                                    | Create an event (with optional inline cover/gallery).       |
| [`useFetchEvent`](/hooks/events/use-fetch-event)                                                      | Fetch a single event by ID.                                 |
| [`useFetchManyEvents`](/hooks/events/use-fetch-many-events)                                           | One-shot list query (low-level).                            |
| [`useFetchManyEventsWrapper`](/hooks/events/use-fetch-many-events-wrapper)                            | Stateful, paginated list with sort + load-more.             |
| [`useUpdateEvent`](/hooks/events/use-update-event)                                                    | Edit an event; replace cover, append/remove gallery images. |
| [`useDeleteEvent`](/hooks/events/use-delete-event)                                                    | Delete an event.                                            |
| [`useCancelEvent`](/hooks/events/use-cancel-event)                                                    | Cancel an event.                                            |
| [`useSetRsvp`](/hooks/events/use-set-rsvp)                                                            | Set/change an RSVP.                                         |
| [`useWithdrawRsvp`](/hooks/events/use-withdraw-rsvp)                                                  | Withdraw an RSVP.                                           |
| [`useAddHost`](/hooks/events/use-add-host) / [`useRemoveHost`](/hooks/events/use-remove-host)         | Manage hosts.                                               |
| [`useAddInvite`](/hooks/events/use-add-invite) / [`useRemoveInvite`](/hooks/events/use-remove-invite) | Manage invites.                                             |
| [`useFetchInvitees`](/hooks/events/use-fetch-invitees)                                                | Host-only invitee list.                                     |
| [`useFetchEventRsvps`](/hooks/events/use-fetch-event-rsvps)                                           | Named guest list.                                           |
| [`EventProvider` / `useEvent`](/sdk/events/provider-and-hook)                                         | Load one event into context with bound actions.             |

## Creating an event

`useCreateEvent` returns a callable. Cover and gallery uploads are inline — pass a `cover` and/or `gallery` and the hook sends `multipart/form-data` automatically. The logged-in user is auto-added as a host.

```tsx theme={null}
import { useCreateEvent } from "@sublay/react-js";

function NewEventButton() {
  const createEvent = useCreateEvent();

  const handleCreate = async (coverFile: File) => {
    const event = await createEvent({
      title: "Launch Party",
      type: "physical",
      startTime: "2026-09-01T18:00:00.000Z",
      venueName: "The Loft",
      address: "123 Main St, New York, NY",
      capacity: 100,
      cover: {
        file: coverFile,
        options: { mode: "original-aspect", sizes: { full: 1600 }, format: "webp" },
      },
    });
    console.log("Created:", event.id);
  };
}
```

The required location fields follow `type`: `online` needs `url`; `physical` needs `address` or `location`; `hybrid` needs both. See [`useCreateEvent`](/hooks/events/use-create-event) for the full parameter list.

## Listing events

Use `useFetchManyEventsWrapper` for a ready-made paginated list with sort state and `loadMore`. Visibility is enforced server-side, so the list only contains events the current user may see.

```tsx theme={null}
import { useFetchManyEventsWrapper } from "@sublay/react-js";

function UpcomingEvents() {
  const { events, loading, hasMore, loadMore, sortBy, setSortBy } =
    useFetchManyEventsWrapper({
      timeWindow: "upcoming",
      limit: 20,
      include: "userRsvp",
    });

  return (
    <div>
      <button onClick={() => setSortBy(sortBy === "startTime" ? "going" : "startTime")}>
        Sort: {sortBy}
      </button>
      {events.map((e) => (
        <article key={e.id}>
          <h3>{e.title}</h3>
          <p>{e.rsvpCounts.going} going · your RSVP: {e.userRsvp ?? "none"}</p>
        </article>
      ))}
      {hasMore && <button disabled={loading} onClick={loadMore}>Load more</button>}
    </div>
  );
}
```

## RSVPing

```tsx theme={null}
import { useSetRsvp, useWithdrawRsvp } from "@sublay/react-js";

function RsvpButtons({ eventId }: { eventId: string }) {
  const setRsvp = useSetRsvp();
  const withdrawRsvp = useWithdrawRsvp();

  return (
    <div>
      <button onClick={() => setRsvp({ eventId, status: "going" })}>Going</button>
      <button onClick={() => setRsvp({ eventId, status: "maybe" })}>Maybe</button>
      <button onClick={() => withdrawRsvp({ eventId })}>Withdraw</button>
    </div>
  );
}
```

Both return the updated [Event](/data-models/event) with refreshed `rsvpCounts` and the caller's `userRsvp`. RSVPs close at `startTime`, are rejected on cancelled events, reject `maybe` when `allowMaybe` is `false`, and reject `going` at capacity.

## See Also

* [EventProvider & useEvent](/sdk/events/provider-and-hook)
* [Event data model](/data-models/event)
* [Events Hooks reference](/hooks/events/use-create-event)
* [Events API reference](/api-reference/events/create-event)


# EventProvider & useEvent
Source: https://docs.sublay.io/v7/sdk/events/provider-and-hook

Load a single event into React context with bound RSVP and management actions

`EventProvider` loads one event and exposes it — plus bound actions — to descendants via `useEvent`. It's the simplest way to build an event detail page: the provider fetches the event (or accepts a pre-fetched one), and `useEvent` gives you the event state and callbacks that keep it in sync.

There is no Redux store behind this — state is local to the provider. For lists, use [`useFetchManyEventsWrapper`](/hooks/events/use-fetch-many-events-wrapper) instead.

## EventProvider

Identify the event by `eventId`, or pass a pre-fetched `event` object to skip the initial fetch.

```tsx theme={null}
import { EventProvider } from "@sublay/react-js";

// By ID (fetches the event)
<EventProvider eventId="evt_abc123" include="user,files,userRsvp">
  <EventDetail />
</EventProvider>

// Pre-fetched object (no fetch — useful for SSR or when already loaded)
<EventProvider event={myEvent}>
  <EventDetail />
</EventProvider>
```

### Props

<ParamField type="string">
  UUID of the event to load. Use this or `event`.
</ParamField>

<ParamField type="Event">
  A pre-fetched event object. Skips the initial fetch. Use this or `eventId`.
</ParamField>

<ParamField type="string | string[]">
  Associations to expand on the fetch, e.g. `"user,files,userRsvp"`. Only used with `eventId`.
</ParamField>

<Note>`EventProvider` renders `null` if neither `eventId` nor a valid `event` is provided.</Note>

## useEvent

Call `useEvent` inside a descendant of `EventProvider`.

```tsx theme={null}
import { useEvent } from "@sublay/react-js";

function EventDetail() {
  const {
    event,
    setEvent,
    updateEvent,
    deleteEvent,
    cancelEvent,
    setRsvp,
    withdrawRsvp,
  } = useEvent();

  if (event === undefined) return <p>Loading…</p>;
  if (event === null) return <p>Event not found.</p>;

  return (
    <div>
      <h1>{event.title}</h1>
      <p>{event.rsvpCounts.going} going · your RSVP: {event.userRsvp ?? "none"}</p>
      <button onClick={() => setRsvp("going")}>Going</button>
      <button onClick={() => withdrawRsvp()}>Withdraw</button>
      <button onClick={() => cancelEvent()}>Cancel event</button>
    </div>
  );
}
```

## Return Values

<ResponseField name="event" type="Event | null | undefined">
  The loaded event. `undefined` while loading, `null` if not found or inaccessible.
</ResponseField>

<ResponseField name="setEvent" type="React.Dispatch<SetStateAction<Event | null | undefined>>">
  Directly set the event state. Useful for optimistic local updates.
</ResponseField>

<ResponseField name="updateEvent" type="(props: { update }) => Promise<Event | undefined>">
  Update the event's mutable fields. Host-only. Updates local state on success.
</ResponseField>

<ResponseField name="deleteEvent" type="() => Promise<void>">
  Delete the event. Host-only. Clears local state on success.
</ResponseField>

<ResponseField name="cancelEvent" type="() => Promise<Event | undefined>">
  Cancel the event (`status: "cancelled"`). Host-only.
</ResponseField>

<ResponseField name="setRsvp" type="(status: RsvpStatus) => Promise<Event | undefined>">
  Set/change the caller's RSVP (`"going" | "maybe" | "not_going"`). Capacity-checked for `going`.
</ResponseField>

<ResponseField name="withdrawRsvp" type="() => Promise<Event | undefined>">
  Withdraw the caller's RSVP.
</ResponseField>

<Note>
  These bound actions wrap the standalone hooks and handle errors internally
  (logging and returning `undefined`). For host/invite management
  (`useAddHost`, `useAddInvite`, …) and guest-list reads, use the standalone
  hooks alongside the provider.
</Note>

## See Also

* [Events Overview](/sdk/events/overview)
* [Event data model](/data-models/event)
* [useEvent hook reference](/hooks/events/use-event)


# Getting Started
Source: https://docs.sublay.io/v7/sdk/getting-started

Install the Sublay SDK and add SublayProvider to your app

Sublay's SDK is distributed through the `@sublay` family of packages. The React web package (`@sublay/react-js`) is the starting point for most projects.

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @sublay/react-js@beta
  ```

  ```bash yarn theme={null}
  yarn add @sublay/react-js@beta
  ```

  ```bash pnpm theme={null}
  pnpm add @sublay/react-js@beta
  ```
</CodeGroup>

For React Native or Expo projects, install the platform-specific package instead:

<CodeGroup>
  ```bash React Native theme={null}
  npm install @sublay/react-native@beta
  ```

  ```bash Expo theme={null}
  npm install @sublay/expo@beta
  ```
</CodeGroup>

## Wrap Your App with SublayProvider

`SublayProvider` is the root provider that must wrap your entire application (or the portion of it that uses Sublay features). It initializes the Redux store, bootstraps auth state, and makes the `projectId` available to all child hooks and components.

```tsx theme={null}
import { SublayProvider } from "@sublay/react-js";

function App() {
  return (
    <SublayProvider projectId="your-project-id">
      {/* your app */}
    </SublayProvider>
  );
}
```

### Props

<ParamField type="string">
  Your Sublay project ID. Found in the Sublay dashboard under project settings.
</ParamField>

<ParamField type="string | null">
  A signed JWT from your own auth system, used for external authentication mode. Pass `null` or omit when not using external auth. See [External Auth](/sdk/authentication/external).
</ParamField>

## Choosing an Authentication Mode

After wrapping with `SublayProvider`, users are unauthenticated by default. You can authenticate them using any combination of:

<CardGroup>
  <Card title="Built-in Auth" icon="lock" href="/sdk/authentication/built-in">
    Sign up and sign in with email and password. Sublay manages credentials and sessions.
  </Card>

  <Card title="External Auth" icon="code" href="/sdk/authentication/external">
    Pass a signed JWT from your own auth system via the `signedToken` prop.
  </Card>

  <Card title="OAuth" icon="key" href="/sdk/authentication/oauth">
    Let users sign in with Google, GitHub, Apple, or Facebook.
  </Card>

  <Card title="Multi-Account" icon="users" href="/sdk/authentication/multi-account">
    Support multiple simultaneous signed-in accounts with account switching.
  </Card>
</CardGroup>

## Checking Auth State

Use the `useAuth` hook for auth actions and `useUser` to access the current user anywhere inside `SublayProvider`:

```tsx theme={null}
import { useAuth, useUser } from "@sublay/react-js";

function Header() {
  const { initialized, signOut } = useAuth();
  const { user } = useUser();

  if (!initialized) return <p>Loading...</p>;
  if (!user) return <p>Not signed in.</p>;

  return (
    <div>
      <p>Signed in as {user.username}</p>
      {/* `signOut` rejects when the server refuses to unbind this device's
          push — nothing is torn down, so surface it and let the user retry. */}
      <button onClick={() => signOut().catch(showError)}>Sign out</button>
    </div>
  );
}
```

<Note>
  `initialized` is `false` until the SDK has attempted to restore a session from storage. Always check `initialized` before rendering auth-dependent UI to avoid flash-of-unauthenticated-content.
</Note>

## Redux Store

`SublayProvider` automatically creates and manages an isolated Redux store. You do not need to configure Redux to use Sublay.

If your application already has its own Redux store, we strongly recommend using `SublayIntegrationProvider` instead — running two separate Redux stores in the same app is a common source of subtle bugs. See [Redux Integration](/sdk/redux-integration) for setup details.

## What's Next

<CardGroup>
  <Card title="Authentication" icon="lock" href="/sdk/authentication/overview">
    Configure how users sign in to your application
  </Card>

  <Card title="Entities" icon="file" href="/sdk/entities/overview">
    Attach social features to your app's content
  </Card>

  <Card title="Spaces" icon="users" href="/sdk/spaces/overview">
    Build community spaces with membership and moderation
  </Card>

  <Card title="Chat" icon="comments" href="/sdk/chat/overview">
    Add real-time 1:1 and group conversations
  </Card>
</CardGroup>


# Overview
Source: https://docs.sublay.io/v7/sdk/moderation/overview

Content reporting and moderation tools at the project and space level

## Overview

Sublay provides a two-tier moderation system:

1. **Project-level moderation** — Users with project-level admin permissions can moderate any content across the entire project, regardless of which space it belongs to. This is typically used by the platform owner or trust-and-safety team.

2. **Space-level moderation** — Users with `admin` or `moderator` roles within a specific space can moderate content in that space only. Their capabilities are scoped to their space — they cannot view or act on reports from other spaces.

Both tiers share the same reporting flow. The difference is in who can act on reports and what scope they have access to.

Beyond acting on individual pieces of content, moderators can also **[suspend a user](/sdk/moderation/suspensions)** — an enforced, platform-wide timeout that blocks all participation writes while leaving reads, sign-in, and account self-management open.

<Note>
  **Requires the `moderation` bundle.** Reports, suspensions, and **user blocking** are only available when the `moderation` bundle is installed on your project. See [Bundles](/bundles) to add it.
</Note>

## Blocking

Beyond moderator-driven reporting and suspensions, the moderation bundle also provides **end-user blocking** — a user-to-user safety primitive. Any user can block any other user (no prior interaction required), and Sublay reliably severs interaction between them across every relevant surface.

Blocking is **not a moderator action** — it is exposed to your app's end users, alongside follows and connections, through the same SDK surfaces (React/React Native/Expo hooks, the node SDK, and the js SDK). Sublay ships the *capability and enforcement*; your app builds the block button/menu UI. See the [`useBlockManager`](/sdk/relationships/use-block-manager) hook to wire up a block/unblock toggle.

<Note>
  Blocking ships with the moderation bundle because app stores check for **reporting, blocking, and moderation together** — it is the trust & safety package an app installs to be app-store compliant. A project without the moderation bundle has neither reporting nor blocking.
</Note>

### What a block does

When user A blocks user B, the effects are **mutual** (both directions) unless noted, and the block is **silent** — B is never notified and can never tell they've been blocked (see [Non-disclosure](#non-disclosure) below).

| Surface                         | Effect of a block                                                                                                                                                                                                                                                                          |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Follows**                     | Any existing follow in either direction is removed immediately. Neither can follow the other going forward.                                                                                                                                                                                |
| **Connections**                 | Any existing connection is removed and any pending request in either direction is cancelled. Neither can send a new request to the other.                                                                                                                                                  |
| **Direct messages (1:1)**       | Neither can start a new 1:1 conversation with the other. An existing 1:1 is frozen — history is retained and remains readable, but no new messages, edits, reactions, or deletes go through in either direction.                                                                           |
| **Group / space conversations** | Untouched. Both remain members of any shared group/space conversation and continue to see each other's messages there.                                                                                                                                                                     |
| **Content interaction**         | Neither can comment on, reply to, quote, or react to the other's posts or comments.                                                                                                                                                                                                        |
| **Content lists**               | Posts and comments authored by a block-edged user are hidden from the other's feeds and threads by default. An app may opt in to re-show **only** content the viewer themselves blocked (see [content-list opt-in](#content-list-opt-in)).                                                 |
| **Mentions**                    | Neither can mention the other; a mention does not notify or resolve to the blocked user. Pre-existing mentions are left in place but stop notifying.                                                                                                                                       |
| **Notifications**               | No notifications flow between the two users in either direction, for any reason.                                                                                                                                                                                                           |
| **Discovery**                   | Each user is excluded from the other's user suggestions, search results, interest matches, and follower/following/connection lists (and their counts).                                                                                                                                     |
| **Profile (asymmetric)**        | The **blocked** user can no longer view the **blocker's** profile — it presents as not found. The blocker retains access to the blocked user's profile and manages the block from their block list. This is the one asymmetric surface, so the blocker always keeps a way back to unblock. |

Unblocking lifts the barrier immediately but **restores nothing** — removed follows and connections stay gone and must be re-established from scratch; a frozen 1:1 conversation simply becomes usable again.

### Content-list opt-in

Post and comment list endpoints (and their SDK equivalents) accept a `blockedFilter` parameter. It defaults to `"exclude"` (hide block-edged authors). Setting it to `"include-outbound-blocked"` re-includes content authored **only** by users the viewer themselves blocked — their own "view anyway" affordance. It can **never** surface content from users who blocked the viewer, and interaction remains blocked regardless of whether the content is shown. See [Fetch Many Entities](/api-reference/entities/fetch-many-entities) and [Fetch Many Comments](/api-reference/comments/fetch-many-comments).

### Non-disclosure

A block is invisible to the blocked user. There is no notification, no "you have been blocked" state, and no distinguishable error — a blocked interaction fails exactly like ordinary unavailability (user/content not found or unavailable), never revealing that a block exists, who set it, or in which direction it runs. The block-status read is **outbound-only**: a user can only ever learn whether *they* block someone, never whether someone blocks *them*. A user's block list is private to that user.

### Block SDK surfaces

* **React / React Native / Expo hooks:** [`useBlockManager`](/hooks/blocks/use-block-manager), [`useBlockUser`](/hooks/blocks/use-block-user), [`useUnblockUser`](/hooks/blocks/use-unblock-user), [`useFetchBlockStatus`](/hooks/blocks/use-fetch-block-status), [`useFetchBlockedUsers`](/hooks/blocks/use-fetch-blocked-users).
* **Node SDK** (act-on-behalf via `actingUserId`): `createBlock`, `deleteBlock`, `fetchBlockStatus`, `fetchBlockedUsers` on the [`users`](/v7/node-sdk/users) module.
* **JS SDK** (token-derived actor): `createBlock`, `deleteBlock`, `fetchBlockStatus`, `fetchBlockedUsers` on the [`users`](/v7/js-sdk/users) module.
* **REST:** [Block User](/api-reference/users/blocks/block-user), [Unblock User](/api-reference/users/blocks/unblock-user), [Get Block Status](/api-reference/users/blocks/get-block-status), [Fetch Blocked Users](/api-reference/blocks/fetch-blocks).

## Reporting Flow

<Steps>
  <Step title="User submits a report">
    Call [`useCreateReport`](/hooks/reports/use-create-report) with the target ID and a reason key. If the target has already been reported, the user's report is appended to the existing report record.
  </Step>

  <Step title="Report is associated with a space">
    The server automatically determines which space the reported content belongs to. Reports with no space (content outside a space) are visible only to project-level moderators.
  </Step>

  <Step title="Moderator reviews pending reports">
    A moderator fetches pending reports with [`useFetchModeratedReports`](/hooks/reports/use-fetch-moderated-reports):

    * **Project-level moderators** see all reports across the entire project.
    * **Space-level moderators** see only reports for content within their space.
  </Step>

  <Step title="Moderator takes action">
    Use [`useHandleSpaceEntityReport`](/hooks/reports/use-handle-space-entity-report) or [`useHandleSpaceCommentReport`](/hooks/reports/use-handle-space-comment-report) to remove content, ban the author, or dismiss the report. Space-level moderators can only act on content within their space.
  </Step>
</Steps>

## Moderation Tiers

### Project-Level Moderation

Project-level moderation is handled through the **Sublay Dashboard** — no code integration is required. Platform owners and trust-and-safety teams can log into the dashboard to review and act on reports across the entire project.

* Managed entirely from the Sublay Dashboard
* Access to all reports, regardless of space
* Can remove any entity or comment in the project
* Can ban any user from any space
* Suitable for platform-wide policy enforcement

### Space-Level Moderation

Space-level moderation must be **integrated in your application**. Users with an `admin` or `moderator` role within a specific space can be given a moderation UI inside your app using the hooks below. Their capabilities are scoped to that space — they cannot view or act on reports from other spaces.

* Built into your app using the provided hooks
* Can only view reports for content within their space
* Can remove entities, comments, and chat messages within their space
* Can ban users from their space only
* Cannot access reports or take action in other spaces

## Report Reasons

Reports must use one of these keys — the API rejects anything else with
`report/invalid-body`. Use `other` together with the free-text `details` field
for anything the list doesn't cover.

| Key                    | Label                                   |
| ---------------------- | --------------------------------------- |
| `spam`                 | It's spam                               |
| `inappropriateContent` | Contains inappropriate content          |
| `harassment`           | It's harassment or bullying             |
| `misinformation`       | Spreads false information               |
| `hateSpeech`           | Contains hate speech or symbols         |
| `violence`             | Promotes violence or dangerous behavior |
| `illegalActivity`      | Promotes illegal activity               |
| `selfHarm`             | Promotes self-harm or suicide           |
| `other`                | Other                                   |

Import reason keys from `@sublay/core`:

```ts theme={null}
import { reportReasons } from "@sublay/core";
// { spam: "It's spam", inappropriateContent: "Contains inappropriate content", ... }
```

## Hooks

The hooks below are used for **space-level moderation** integrated in your app. Project-level moderation does not require any hooks — it is handled through the Sublay Dashboard.

<CardGroup>
  <Card title="useCreateReport" href="/hooks/reports/use-create-report">
    Submit a report against an entity, comment, or chat message.
  </Card>

  <Card title="useFetchModeratedReports" href="/hooks/reports/use-fetch-moderated-reports">
    Fetch pending reports for spaces the current user moderates.
  </Card>

  <Card title="useHandleSpaceEntityReport" href="/hooks/reports/use-handle-space-entity-report">
    Action an entity report as a space moderator.
  </Card>

  <Card title="useHandleSpaceCommentReport" href="/hooks/reports/use-handle-space-comment-report">
    Action a comment report as a space moderator.
  </Card>

  <Card title="useHandleSpaceChatReport" href="/hooks/reports/use-handle-space-chat-report">
    Action a chat message report as a space moderator.
  </Card>
</CardGroup>

## Related

* [Blocking](#blocking) — End-user user-to-user blocking (via [`useBlockManager`](/sdk/relationships/use-block-manager))
* [Suspensions](/sdk/moderation/suspensions) — Platform-wide user timeouts that block participation writes
* [Space Moderation](/sdk/spaces/moderation) — Direct moderation of entities and comments within a space (without the reporting flow)
* [Space Rules](/sdk/spaces/rules) — Define community rules that appear alongside moderation decisions


# Suspensions
Source: https://docs.sublay.io/v7/sdk/moderation/suspensions

Platform-wide user suspensions — the enforced timeout for participation

## Overview

A **suspension** puts a user in a platform-wide timeout. While an active suspension is in place, the user **cannot participate** — every content and participation write is blocked server-side — but they can still **sign in, read everything, and manage their own account**. It's the "you're in timeout" model (Reddit / Discord / StackOverflow), not an eviction.

Suspensions are set by project owners and admins from the [Sublay Dashboard](#dashboard-flow), or automatically by the report-handling flow. They are platform-wide and distinct from [space membership moderation](/sdk/spaces/membership) (space bans), which is scoped to a single space and set by space admins.

<Note>
  **Requires the `moderation` bundle.** Suspensions are only available when the `moderation` bundle is installed on your project. On projects without it, suspensions are never queried and writes are never blocked on this basis. See [Bundles](/bundles) to add it.
</Note>

## What a suspension blocks

While a user has an active suspension, **every authenticated participation and content write is blocked** — it's a denylist-by-default. This includes:

* Creating, updating, or deleting comments — including editing or deleting your own
* Adding or removing reactions — on comments and entities
* Creating, updating, or deleting entities, and publishing drafts
* Creating or joining spaces
* Creating events and RSVP'ing
* Chat: creating conversations, sending messages, reacting to messages, reporting messages
* Collections writes (create, add entity, update, delete)
* Following, requesting a connection, and accepting or declining a connection
* Standalone file and image uploads
* Filing reports

## What stays open

Reads, sign-in, and account self-management are **never** blocked by a suspension:

* All reads (GET requests) — public **and** member-only content
* Sign in, refresh token, sign out, change password, account-deletion request/confirm
* Editing your own profile and deleting your own account
* Marking notifications read / mark-all-read
* Registering/deregistering push tokens and updating notification preferences
* Linking/unlinking OAuth identities
* Chat: marking as read and muting conversations

Because a suspended user can still sign in and read, they can see the suspension reason and end date and appeal — which is why sign-in stays open by design.

## The blocked-write response contract

A blocked write returns HTTP **`403`** with this body:

```json theme={null}
{
  "error": "This account is suspended and cannot perform this action.",
  "code": "user/suspended",
  "reason": "Repeated spam",
  "endDate": "2026-08-01T00:00:00.000Z"
}
```

| Field     | Type               | Description                                                      |
| --------- | ------------------ | ---------------------------------------------------------------- |
| `error`   | `string`           | Human-readable message.                                          |
| `code`    | `"user/suspended"` | Stable discriminator — always this value for a suspension block. |
| `reason`  | `string \| null`   | The reason the moderator gave, or `null`.                        |
| `endDate` | `string \| null`   | ISO end date, or `null` for an **indefinite** suspension.        |

The `reason` and `endDate` are taken from the user's **effective** suspension (see below).

## Effective suspension

Multiple active suspensions can coexist on one user (for example, a manual suspension and a report-driven auto-suspension). The **effective** suspension is the **furthest-reaching active row** — an indefinite suspension (`endDate: null`) reaches the furthest and always wins the tie-break. A user is considered suspended while **any** active suspension exists.

"Active" means `startDate ≤ now` and (`endDate ≥ now` or `endDate` is `null`).

## SDK: consuming suspension state

The `@sublay/core` SDK **only consumes** the current user's own suspension state — it does not suspend or lift (that's the [dashboard's](#dashboard-flow) job). There are two surfaces.

### Ambient state — `useUser`

[`useUser`](/hooks/user/use-user) exposes derived `isSuspended` and `activeSuspension` fields, computed from the authenticated user's `suspensions` using the same effective definition as the server. Bind your "you're suspended until X" banner or disabled composer to these.

```tsx theme={null}
import { useUser } from "@sublay/react-js";

function Composer() {
  const { isSuspended, activeSuspension } = useUser();

  if (isSuspended) {
    return (
      <SuspendedBanner
        reason={activeSuspension?.reason}
        endDate={activeSuspension?.endDate} // null = indefinite
      />
    );
  }

  return <MessageInput />;
}
```

`activeSuspension` is `{ reason, startDate, endDate } | null` — the furthest-reaching active suspension, or `null` when the user isn't suspended.

### Reactive error — `SuspendedError`

If a write is attempted anyway (for example, a suspension lands mid-session), the blocked `403 user/suspended` response is surfaced as a typed, catchable `SuspendedError` carrying `reason` and `endDate`. The SDK discriminates this response **before** its generic 403 → token-refresh handling, so a blocked write is **not** silently retried and does **not** trigger a spurious token refresh.

```tsx theme={null}
import { useCreateComment } from "@sublay/react-js";
import { SuspendedError, isSuspendedError } from "@sublay/core";

async function submit() {
  try {
    await createComment({ content: "…" });
  } catch (err) {
    if (isSuspendedError(err)) {
      // err.reason, err.endDate (null = indefinite)
      showSuspendedState(err.reason, err.endDate);
      return;
    }
    throw err;
  }
}
```

Use `isSuspendedError(err)` (or `err instanceof SuspendedError`) to narrow. Both `SuspendedError` and `isSuspendedError` are exported from `@sublay/core`.

## Dashboard flow

Suspending and lifting are done from the **Sublay Dashboard** by project owners and admins — no code integration is required.

* **View.** A user's suspensions are shown on their profile in the Users view — active ones prominently (reason, until-when, who set it), past ones as history. Indefinite suspensions (`endDate: null`) show as active.
* **Suspend.** Suspend a user with a reason and an optional expiration. Leaving the expiration empty creates an indefinite suspension.
* **Lift.** Lifting a suspension **expires** it in place (it isn't deleted — the audit trail is preserved). Because multiple active suspensions can coexist, lifting one active row may leave others in place. A **"lift all active"** action fully un-suspends the user by clearing every active row at once.

<Note>
  Suspension has retroactive bite: enabling it can block users who were suspended before enforcement existed. Lifting is the escape hatch and ships alongside it.
</Note>

## What suspension deliberately does not do

* **Reads are never blocked** — a suspended user can read everything they could before.
* **Sign-in is never blocked** — so the user can see the reason/end date and appeal.
* **There is no per-app or per-severity configuration.** Suspension is a single, fixed behavior: block participation writes, allow reads and account self-management. There is no advisory level, no read-blocking mode, and no `mute` vs `ban` severity.

## Related

* [useUser hook](/hooks/user/use-user) — `isSuspended` / `activeSuspension`
* [User data model](/data-models/user) — the `Suspension` shape on `AuthUser`
* [Moderation overview](/sdk/moderation/overview) — reporting and content moderation
* [Space membership](/sdk/spaces/membership) — space-scoped bans (a separate axis)


# Push Notifications
Source: https://docs.sublay.io/v7/sdk/push-notifications/overview

Register the current user's device for native push from your client app

This page covers **registering devices from your client SDK**. For the full feature overview — dashboard setup, server-side sending, and device lifecycle — see [Push Notifications](/push-notifications).

<Note>
  **Requires the `push` bundle** and configured provider credentials (APNs, FCM, or Web Push) in the dashboard. See the [feature overview](/push-notifications#dashboard-setup) for setup.
</Note>

## Registering Devices

Use `usePushRegistration` with the adapter for your platform. Call `register()` in response to a deliberate user action — not on mount — because requesting OS push permission is a one-shot prompt that users cannot undo.

You only need to call it **once per device**, not on every launch. The SDK stores the device identifier and keeps the bindings in step on its own: wherever `usePushRegistration` is mounted, it watches for OS token rotations, re-binds the active account onto the new token and marks the other push-enabled accounts for repair on their next activation. See [Automatic token rotation](#automatic-token-rotation).

```tsx theme={null}
// Expo
import { usePushRegistration } from "@sublay/core";
import { expoPushTokenAdapter } from "@sublay/expo";

function SettingsScreen() {
  const { register, registering } = usePushRegistration(expoPushTokenAdapter);
  return <Button onPress={register} loading={registering} title="Enable notifications" />;
}
```

```tsx theme={null}
// Bare React Native
import { usePushRegistration } from "@sublay/core";
import { reactNativePushTokenAdapter } from "@sublay/react-native";

const { register } = usePushRegistration(reactNativePushTokenAdapter);
```

```tsx theme={null}
// Web (browser)
import { usePushRegistration } from "@sublay/core";
import { webPushTokenAdapter } from "@sublay/react-js";

const { register, unregister } = usePushRegistration(webPushTokenAdapter);
```

The web adapter requires a service worker. Register one before calling `register()`. The public VAPID key your service worker needs is available from the unauthenticated [`GET /vapid-public-key`](/api-reference/push-notifications/get-vapid-public-key) endpoint.

## The Notification `data` Payload

Every push Sublay delivers carries a flat `data` object of string values. Your tap handler reads it to decide where to navigate — the full key list for automatic notifications is on the [feature overview](/push-notifications#tap-routing-data).

One key matters specifically to multi-account apps:

| Key               | Value                                                       |
| ----------------- | ----------------------------------------------------------- |
| `recipientUserId` | The id of the account this copy of the notification is for. |

A single physical device can be signed into several accounts at once, and each signed-in account is bound to the device separately. When a notification is sent to more than one of them, the device receives **one notification per account**, each stamped with its own `recipientUserId`. Read it before routing, so a tap on a notification for a background account switches to that account rather than opening the wrong session's screen:

```tsx theme={null}
import { AccountTransitionError } from "@sublay/react-js";

async function handleNotificationTap(data: Record<string, string>) {
  if (data.recipientUserId && data.recipientUserId !== user?.id) {
    // Bring the account this notification belongs to into focus first.
    try {
      await switchAccount({ userId: data.recipientUserId });
    } catch (err) {
      // The switch rejected, so you are still in the previous account and
      // navigating now would open the wrong session's screen. Stay put and
      // tell the user what to do about it.
      if (err instanceof AccountTransitionError && err.credentialRejected) {
        promptSignIn(data.recipientUserId);
      } else {
        showRetry();
      }
      return;
    }
  }
  navigateTo(data);
}
```

`switchAccount` **rejects** when the target account's stored credential cannot be exchanged, and
it changes nothing when it does — you stay signed in where you were. Without the `catch` the
rejection is unhandled and the deep link is silently dropped, which reads to the user as a
notification that does nothing. See [Telling a dead account from a dead
network](/sdk/authentication/multi-account#telling-a-dead-account-from-a-dead-network).

<Note>
  **`recipientUserId` is reserved and server-stamped.** It is added per device at dispatch time, on both the automatic notification paths and server-side `push.send()` calls. If your backend puts a value under the same key in `data`, the server's value **wins** — an account-routing key has to be trustworthy. Dashboard test sends carry no `recipientUserId`, because they target a pasted token rather than a registered account.
</Note>

## Turning Push Off

`unregister()` unbinds the **currently active account** from this device and records that as a **durable preference** for that account. The account stays silenced across switches and relaunches until something turns it back on.

```tsx theme={null}
const { unregister } = usePushRegistration(webPushTokenAdapter);

// A "push notifications" switch in your settings screen.
async function handleDisablePush() {
  await unregister();
}
```

<Warning>
  **Do not call `unregister()` in your logout flow.** It is a user-facing preference, not a cleanup step, and using it as one is harmful in two ways:

  1. **Signing out already deregisters.** Once this device has a stored push identifier, `signOut()`, `removeAccount()` and `signOutAll()` send it with the sign-out request, and the server deletes the push binding in the *same transaction* as the session teardown — atomically, or not at all, with a failure reported rather than swallowed. There is nothing left for `unregister()` to clean up.
  2. **It permanently silences the account.** Because the flag is durable, an `unregister()` at logout means the next time that user signs in they get **no notifications at all**, with no obvious cause and nothing in your UI that turned it off.

  Wire `unregister()` to a notification switch the user controls, and nothing else.
</Warning>

Other accounts bound to the same device are unaffected, and the device identifier itself is kept — it is device state shared by every stored account, not account state.

## Per-Account Push Control

One physical device can hold several signed-in accounts, and **each account controls its push on this device independently**. `useAccountPushToggle` sets that preference for *any* stored account, including ones the user is not currently signed into:

```tsx theme={null}
import { useAccounts, useAccountPushToggle } from "@sublay/react-js";

function PerAccountPushSettings() {
  const { accounts } = useAccounts();
  const { setAccountPushEnabled, isAccountPushEnabled, isUpdating } =
    useAccountPushToggle();

  return accounts.map((account) => (
    <Switch
      key={account.id}
      checked={isAccountPushEnabled(account.id)}
      disabled={isUpdating}
      onChange={(enabled) =>
        setAccountPushEnabled({ userId: account.id, enabled }).catch(() => {
          // Rejects when the binding change fails; the stored preference is
          // left as it was and `error` from the hook carries the reason.
        })
      }
    />
  ));
}
```

Silencing a background account unbinds it server-side without switching to it. See [`useAccountPushToggle`](/hooks/push/use-account-push-toggle) for the full reference.

<Note>
  **This is not the same thing as [notification preferences](/notification-preferences).** The per-account toggle decides *whether an account is bound to this device at all*; [`useNotificationPreferences`](/hooks/push/use-notification-preferences) decides *which event types* the signed-in user receives. An account silenced here receives nothing on this device regardless of its per-event-type settings, and its preferences are untouched — they apply again the moment it is turned back on.
</Note>

<Warning>
  **`register()` turns push on for every stored account that has never expressed a preference.** Permission is a device-level grant, so a device already holding four other signed-in accounts enables all of them, not just the one the user was looking at when they tapped the button. An account that was deliberately silenced stays silenced. Turn individual accounts back off with the toggle above.

  The account `register()` was called from is bound immediately; the others are marked for a re-bind and bound the next time the user switches into each. An account that has *not* expressed a preference is never bound — signing in on a device that already holds a push identifier creates no binding on its own.
</Warning>

## Automatic Token Rotation

Device push tokens rotate — on reinstall, on an OS-initiated refresh, after a backup restore. When that happens every binding on the old token is dead.

The SDK handles this without the app doing anything. `usePushRegistration` subscribes to the platform's token-change signal — mounted whenever the adapter offers one, so an app whose adapter omits it subscribes to nothing — and on a change it records the new identifier, re-binds the **active** account on the spot, and **marks** every other push-enabled account as needing a re-bind. Each marked account is repaired the next time the user switches into it, from the live session that switch establishes. Silenced accounts stay silenced.

Marking rather than re-binding is what keeps a background account safe: re-binding one would mean spending its stored refresh token on a one-time-use exchange while nobody is looking at it, and an interruption mid-exchange locks that account out for good. The marker is durable and readable as `needsPushRebind` — see [When notifications are paused](/sdk/authentication/multi-account#when-notifications-are-paused).

| Platform     | How rotation is detected                                                                                                                                                                                                                                                                      |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Expo         | `expo-notifications`' token listener. Rotation-only: it fires when the OS hands over a new token, never merely because something subscribed                                                                                                                                                   |
| React Native | Firebase `onTokenRefresh`, also rotation-only. Android is covered. On iOS the event carries an FCM token while the adapter registers APNs, so APNs rotation is not reported by it at all; the mount-time read below picks it up on the next launch, or a `register()` / `unregister()` sooner |
| Web          | No in-page event exists (`pushsubscriptionchange` fires inside *your* service worker), so the SDK compares the browser's existing subscription against the stored one on mount. It never re-subscribes and never prompts                                                                      |

On the two native platforms the SDK additionally reads the device's current push identifier **once on mount**, so a device whose token never rotates is not left with a server-side binding it has no local identifier to unbind. It does this only when the device already holds OS notification permission — with one exception: the very first such read on a device ignores permission, because revoking notifications never removes an existing binding and a device upgrading from a release that stored no identifier would otherwise be unable to unbind one. Reading the permission status never prompts, and neither does the read itself. Web needs no equivalent: its mount-time comparison already covers it. See [Reading the current identifier on mount](/hooks/push/use-push-registration#reading-the-current-identifier-on-mount-native).

Nothing here asks the user for anything — receiving a refreshed token is not a permission prompt, and neither is reading a permission the device already granted.

## Next Steps

<CardGroup>
  <Card title="Feature Overview" icon="bell" href="/push-notifications">
    Dashboard setup, sending, and device lifecycle
  </Card>

  <Card title="usePushRegistration" icon="cube" href="/hooks/push/use-push-registration">
    The full hook API and platform adapters
  </Card>

  <Card title="useAccountPushToggle" icon="toggle-on" href="/hooks/push/use-account-push-toggle">
    Per-account push control on a shared device
  </Card>

  <Card title="Multi-Account" icon="users" href="/sdk/authentication/multi-account">
    How push interacts with several signed-in accounts
  </Card>
</CardGroup>


# Overview
Source: https://docs.sublay.io/v7/sdk/reactions/overview

The 8-type reaction system for entities and comments

Sublay supports 8 distinct reaction types on both entities and comments. Each reaction type has a defined impact on the author's reputation score.

<Note>
  **Requires the `reactions` bundle.** Reactions are only available when the `reactions` bundle is installed on your project. See [Bundles](/bundles) to add it.
</Note>

## Reaction Types

| Type       | Reputation Impact |
| ---------- | :---------------: |
| `upvote`   |         +1        |
| `downvote` |         -1        |
| `like`     |         +1        |
| `love`     |         +2        |
| `wow`      |         +1        |
| `sad`      |         0         |
| `angry`    |         0         |
| `funny`    |         +1        |

Each entity and comment stores a `reactionCounts` object with a count for each type, and a `userReaction` field with the authenticated user's current reaction (or `null`).

## The Toggle Pattern

The recommended way to work with reactions is `useReactionToggle`. It manages optimistic updates, handles toggling (selecting the same reaction again removes it), and reverts state on server errors.

```tsx theme={null}
import { useReactionToggle } from "@sublay/react-js";

function ReactionButton({ entity }) {
  const { currentReaction, reactionCounts, toggleReaction, loading } = useReactionToggle({
    targetType: "entity",
    targetId: entity.id,
    initialReaction: entity.userReaction,
    initialReactionCounts: entity.reactionCounts,
  });

  return (
    <button
      onClick={() => toggleReaction({ reactionType: "upvote" })}
      disabled={loading}
    >
      {reactionCounts.upvote ?? 0} Upvotes
      {currentReaction === "upvote" ? " (active)" : ""}
    </button>
  );
}
```

## Hooks

<CardGroup>
  <Card title="useReactionToggle" href="/hooks/reactions/use-reaction-toggle">
    Manage reaction state with optimistic updates and toggle behavior. The recommended hook for reaction UIs.
  </Card>

  <Card title="useAddReaction" href="/hooks/reactions/use-add-reaction">
    Low-level hook to add a reaction to an entity or comment.
  </Card>

  <Card title="useRemoveReaction" href="/hooks/reactions/use-remove-reaction">
    Low-level hook to remove the authenticated user's reaction.
  </Card>

  <Card title="useFetchEntityReactions" href="/hooks/reactions/use-fetch-entity-reactions">
    Fetch a paginated list of reactions on an entity, optionally filtered by type.
  </Card>

  <Card title="useFetchCommentReactions" href="/hooks/reactions/use-fetch-comment-reactions">
    Fetch a paginated list of reactions on a comment, optionally filtered by type.
  </Card>
</CardGroup>


# Redux Integration
Source: https://docs.sublay.io/v7/sdk/redux-integration

Merge Sublay's Redux state into your existing store using SublayIntegrationProvider

By default, `SublayProvider` creates and manages its own isolated Redux store. This is the recommended approach for most projects — no Redux configuration required.

If your application already has its own Redux store, we strongly recommend merging Sublay's state into it using `SublayIntegrationProvider`. Running two separate Redux stores in the same React app is a common source of subtle bugs: React-Redux binds components to the nearest `<Provider>` in the tree, so hooks can silently read from the wrong store depending on where components are rendered.

## When to Use This

**If your app already has a Redux store, use `SublayIntegrationProvider`.** This is the right path for virtually every app in that situation. The standalone `SublayProvider` is only appropriate for apps that don't use Redux at all.

The standalone provider creates its own internal store. When that coexists with your app's store, React-Redux binds components to whichever `<Provider>` is closest in the tree — which means hooks silently read from the wrong store depending on where a component is rendered. These bugs are hard to spot and hard to trace.

The only reason to use `SublayProvider` alongside an existing Redux store is if you have a specific, deliberate reason to keep the two stores completely separate and you fully understand the implications. For nearly everyone, that's not the case.

## Setup

Integration mode requires three changes to your existing store and one change to your provider setup.

<Steps>
  <Step title="Add Sublay reducers to your store">
    Import `sublayReducers` and `sublayApiReducer` from `@sublay/react-js` and add them to your store's `reducer` map. The keys must be exactly `sublay` and `sublayApi` — the SDK's internal selectors depend on these names.

    ```ts theme={null}
    import { configureStore } from "@reduxjs/toolkit";
    import {
      sublayReducers,
      sublayApiReducer,
      sublayMiddleware,
    } from "@sublay/react-js";
    import yourReducer from "./yourSlice";

    const store = configureStore({
      reducer: {
        // Your own reducers
        yourFeature: yourReducer,

        // Sublay — keys must be exactly these
        sublay: sublayReducers,
        sublayApi: sublayApiReducer,
      },
      middleware: (getDefaultMiddleware) =>
        getDefaultMiddleware().concat(...sublayMiddleware),
    });

    export default store;
    export type RootState = ReturnType<typeof store.getState>;
    export type AppDispatch = typeof store.dispatch;
    ```
  </Step>

  <Step title="Replace SublayProvider with SublayIntegrationProvider">
    Use `SublayIntegrationProvider` instead of `SublayProvider`. This provider does not create a Redux store — it expects your own `<Provider>` to already be in the tree above it.

    <Warning>
      **Import it from your platform package** — `@sublay/react-js`,
      `@sublay/react-native` or `@sublay/expo` — **not from `@sublay/core`.**

      Account persistence is carried by an `AccountManager` component that only
      the platform packages can supply, because the storage adapter is
      platform-specific. Core's own `SublayIntegrationProvider` has no
      `AccountManager`: it works, but the account map lives only in memory, so
      stored accounts (and the per-device push state that rides on the same
      map) do not survive a relaunch. The platform packages' version wraps
      core's and mounts the right adapter for you.
    </Warning>

    ```tsx theme={null}
    import { Provider } from "react-redux";
    import { SublayIntegrationProvider } from "@sublay/react-js";
    import store from "./store";

    function App() {
      return (
        <Provider store={store}>
          <SublayIntegrationProvider projectId="your-project-id">
            {/* your app */}
          </SublayIntegrationProvider>
        </Provider>
      );
    }
    ```
  </Step>
</Steps>

## Props

`SublayIntegrationProvider` accepts the same props as `SublayProvider`:

<ParamField type="string">
  Your Sublay project ID.
</ParamField>

<ParamField type="string | null">
  A signed JWT for external authentication mode. See [External Auth](/sdk/authentication/external).
</ParamField>

## Exports Reference

All integration exports are available from `@sublay/react-js`:

| Export                                                                                                              | Type            | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------------------------------------------------------------------------------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sublayReducers`                                                                                                    | `Reducer`       | Combined reducer for all Sublay feature slices. Mount under the `sublay` key.                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `sublayApiReducer`                                                                                                  | `Reducer`       | RTK Query API reducer. Mount under the `sublayApi` key.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `sublayMiddleware`                                                                                                  | `Middleware[]`  | Every middleware Sublay requires — the RTK Query middleware that drives cache invalidation and subscriptions, plus the SDK's own. Spread it into your middleware chain; the pieces are not published individually.                                                                                                                                                                                                                                                                                                                     |
| `sublayApi`                                                                                                         | `Api`           | The RTK Query API object itself — distinct from the `sublayApi` *reducer key* it is mounted under. Use `sublayApi.util` for cache operations such as `resetApiState()`.                                                                                                                                                                                                                                                                                                                                                                |
| `SublayIntegrationProvider`                                                                                         | `React.FC`      | Context provider for integration mode.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `resetAccountScopedState`                                                                                           | `ActionCreator` | Dispatched by the SDK on every account change. Subscribe your own slices to it — see below.                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `resetAuth` / `clearUser`                                                                                           | `ActionCreator` | The auth and current-user teardown actions.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `activateStoredAccount`                                                                                             | `function`      | Validates a stored account's credential, then tears the current session down and makes that account active. Takes `dispatch` **and `getState`** — both are required. Rejects with an `AccountTransitionError` when the credential cannot be exchanged, leaving the live session, the selection and both entries untouched; the only writes a failure makes are a `needsReauth` mark on the target when the credential was refused, and `signedOut` when no account was active. A plain function, callable from a thunk or effect body. |
| `AccountTransitionError`                                                                                            | `class`         | What `activateStoredAccount` rejects with, and what the `switchAccount` / `removeAccount` hooks reject with too. Two independent discriminants: `credentialRejected` separates a dead account from a failed request, and `accountNotFound` marks an id that is not in the stored map at all — a stale id, where nothing was attempted and a re-auth would not help. See [Telling a dead account from a dead network](/sdk/authentication/multi-account#telling-a-dead-account-from-a-dead-network).                                    |
| `ACCOUNT_TRANSITION_FAILED_MESSAGE`                                                                                 | `string`        | The default message on that error, for matching or re-use in your own copy.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `ACCOUNT_LIMIT_MESSAGE`                                                                                             | `string`        | The message the sign-in paths reject with when the device already remembers `MAX_ACCOUNTS` accounts.                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `setSignedOut`                                                                                                      | `ActionCreator` | Records that ending the session was deliberate. Dispatch `setSignedOut(true)` in a hand-rolled teardown — the three teardown actions above only clear the session, so without it the next launch reads "nothing was ever selected", re-activates the account and signs the app back in. `setActiveAccount` clears it again on the next activation.                                                                                                                                                                                     |
| `setSublayLogLevel`                                                                                                 | `function`      | Sets SDK console logging to `"error"` (default), `"warn"` or `"silent"`. Process-global; not a provider prop.                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `selectAccounts`, `selectActiveAccountId`, `selectSignedOut`, `selectAccountLimitReached`, `selectDeviceIdentifier` | `Selector`      | Selectors over the accounts slice.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `MAX_ACCOUNTS`                                                                                                      | `number`        | The stored-account limit (5).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `wouldExceedAccountLimit`                                                                                           | `function`      | `(accounts, userId?) => boolean` — whether admitting `userId` into a raw accounts map would exceed `MAX_ACCOUNTS`. The exact rule the SDK's own refusal gates apply, including its one exception: an id already in the map is **not** an admission, so it answers `false` even at the cap. Pure and read-only. See [Three signals for the account cap](/sdk/authentication/multi-account#three-signals-for-the-account-cap).                                                                                                           |
| `isAccountPushEnabled`                                                                                              | `function`      | Reads an account entry's per-device push preference **for display**. Use it rather than testing `entry.pushEnabled`: an absent flag means "never expressed a preference", which reads as enabled. It is what a per-account switch renders as `checked`, and is not the rule the SDK uses to decide whether to create a binding — that one requires an explicit opt-in and is internal, so no binding is ever created for an account that has not asked for one.                                                                        |
| `accountNeedsReauth`                                                                                                | `function`      | Reads an account entry's "this credential is dead" marker — set when a transition into that account was refused, and set without a network call when the entry carries no usable credential at all.                                                                                                                                                                                                                                                                                                                                    |
| `accountNeedsPushRebind`                                                                                            | `function`      | Reads an account entry's "notifications are paused until this account is next opened" marker. Distinct from `accountNeedsReauth` — see [`useAccounts`](/hooks/auth/use-accounts).                                                                                                                                                                                                                                                                                                                                                      |
| `AccountStorage`                                                                                                    | `type`          | The storage contract an `AccountManager` implements. See [The storage contract](#the-storage-contract) for what an implementation must guarantee.                                                                                                                                                                                                                                                                                                                                                                                      |

<Note>
  The raw `setActiveAccount`, `upsertAccount` and `removeAccount` reducers are
  deliberately **not** exported. They only mutate local state: `setActiveAccount`
  can point the active id at an account that is not in the map, and
  `removeAccount` drops an account without signing it out server-side. Use
  `activateStoredAccount` and the `useRemoveAccount` hook, which perform the
  whole flow.
</Note>

## The Storage Contract

`AccountStorage` is the interface an `AccountManager` implements, and the platform packages
supply one each. If you write your own, three rules govern it:

```ts theme={null}
interface AccountStorage {
  getAccountMap(projectId: string): Promise<AccountMap | null>;
  setAccountMap(projectId: string, map: AccountMap): Promise<void>;
  deleteAccountMap(projectId: string): Promise<void>;
}
```

* **`getAccountMap` is tolerant.** An unreadable, corrupt or unrecognized store resolves `null`
  rather than throwing. Nothing useful can be done with a read failure at the call sites, and a
  throw takes the whole bootstrap down.
* **`setAccountMap` and `deleteAccountMap` must reject when the write does not land.** Logging the
  failure on the way out is fine; resolving anyway is not. The SDK awaits these writes and treats a
  resolved promise as "this is durably stored" — most consequentially for a rotated refresh token,
  where believing a failed write means re-presenting a revoked token and destroying that account's
  whole token family.
* **No locking of your own is needed.** Core serializes every call per `projectId`.

One project per app is the supported shape, and account storage enforces it: mounting a second
provider for a *different* project id throws at mount, with a message naming both project ids. See
[One project per app](/sdk/authentication/multi-account#one-project-per-app).

## Clearing Your Own State on an Account Change

Sublay dispatches `resetAccountScopedState` on **every** path that changes the active account — switching, removing, signing out, deleting an account, adding one, a direct sign-in while another account is active, and cross-tab sync. Its own feature slices return to their initial state on it.

If you keep account-scoped data in your own slices, subscribe to the same signal instead of re-deriving when an account changed:

```ts theme={null}
import { resetAccountScopedState } from "@sublay/react-js";

const yourFeatureSlice = createSlice({
  name: "yourFeature",
  initialState,
  reducers: { /* ... */ },
  extraReducers: (builder) => {
    builder.addCase(resetAccountScopedState, () => initialState);
  },
});
```

RTK Query caches are handled separately by `sublayApi.util.resetApiState()`, which the SDK dispatches alongside.

## State Shape

When integrated, Sublay occupies two top-level keys in your store:

```ts theme={null}
{
  sublay: {
    auth: { ... },          // Auth tokens, current user, initialization state
    accounts: { ... },      // Multi-account list, active account, signedOut,
                            // accountLimitReached
    user: { ... },          // Current user profile
    appNotifications: { ... },
    collections: { ... },
    entityLists: { ... },
    spaceLists: { ... },
    chat: { ... },
    tables: { ... },
  },
  sublayApi: { ... },      // RTK Query cache (collections, entity lists, etc.)
  
  // Your own slices
  yourFeature: { ... },
}
```

<Note>
  The `sublay` and `sublayApi` keys are required by Sublay's internal selectors. Mounting the reducers under different keys will cause the SDK to malfunction.
</Note>

## TypeScript

Sublay exports `SublayState` if you need to type a state slice that references Sublay's shape:

```ts theme={null}
import type { SublayState } from "@sublay/react-js";

interface RootState {
  sublay: SublayState;
  sublayApi: unknown; // RTK Query manages this type internally
  yourFeature: YourFeatureState;
}
```


# Overview
Source: https://docs.sublay.io/v7/sdk/relationships/overview

Add follows and connections to your app with Sublay's social graph hooks

Sublay provides two distinct social relationship systems: **Follows** (one-directional) and **Connections** (mutual/bidirectional). You can use one or both depending on the social model your app needs.

<Note>
  **Requires the `follows` and/or `connections` bundles.** Follows need the `follows` bundle and connections need the `connections` bundle — install whichever you use. See [Bundles](/bundles) to add them.
</Note>

## Follows

Follows are one-directional. A user can follow another user without requiring approval or reciprocation — similar to Twitter or Instagram's follow model.

## Connections

Connections are bidirectional and require mutual acceptance — similar to LinkedIn. One user sends a request; the other must accept before a connection is established. Connections go through several states: `none`, `pending-sent`, `pending-received`, `connected`, `declined-sent`, `declined-received`.

## Choosing Between Follows and Connections

|                       | Follows                          | Connections                           |
| --------------------- | -------------------------------- | ------------------------------------- |
| **Direction**         | One-way                          | Mutual                                |
| **Approval required** | No                               | Yes                                   |
| **Use case**          | Content feeds, creator audiences | Professional networks, friend systems |
| **State**             | Following / not following        | None → Pending → Connected / Declined |

## Blocking

User-to-user **blocking** severs interaction between two users across every Sublay surface (follows, connections, DMs, content, mentions, notifications, discovery, and profiles). Blocking is a trust & safety primitive that ships with the **moderation bundle**, not the follows/connections bundles — see [Moderation — Blocking](/sdk/moderation/overview#blocking) for the full enforcement behavior and the [`useBlockManager`](/sdk/relationships/use-block-manager) hook.

## In This Section

<CardGroup>
  <Card title="useFollowManager" href="/sdk/relationships/use-follow-manager">
    High-level hook for toggling follow state on a profile
  </Card>

  <Card title="useConnectionManager" href="/sdk/relationships/use-connection-manager">
    High-level hook that manages the full connection lifecycle
  </Card>

  <Card title="useBlockManager" href="/sdk/relationships/use-block-manager">
    High-level hook for toggling block state on a profile
  </Card>
</CardGroup>

## Hooks

<CardGroup>
  <Card title="useFollowUser (+ more)" href="/hooks/follows/use-follow-user">
    All individual follow hooks for custom UIs
  </Card>

  <Card title="useRequestConnection (+ more)" href="/hooks/connections/use-request-connection">
    All individual connection hooks for custom UIs
  </Card>
</CardGroup>


# useBlockManager
Source: https://docs.sublay.io/v7/sdk/relationships/use-block-manager

High-level hook for managing block state with a single user

`useBlockManager` is a convenience hook for building block/unblock buttons on a user profile. It automatically loads the current block status on mount and exposes a `toggleBlock` function that handles both blocking and unblocking.

Blocking is a trust & safety primitive shipped as part of the **moderation bundle** — the same package that provides reporting and suspensions. See [Moderation — Blocking](/sdk/moderation/overview#blocking) for the full enforcement behavior.

<Note>
  **Requires the `moderation` bundle.** Blocking is available in any project that has the moderation bundle installed. See [Bundles](/bundles) to add it.
</Note>

## Usage Example

```tsx theme={null}
import { useBlockManager } from "@sublay/react-js";

function BlockButton({ userId }: { userId: string }) {
  const { isBlocked, isLoading, toggleBlock } = useBlockManager({ userId });

  if (isLoading) return <button disabled>...</button>;

  return (
    <button onClick={toggleBlock}>
      {isBlocked ? "Unblock" : "Block"}
    </button>
  );
}
```

## Parameters

<ParamField type="string">
  The ID of the user to block or unblock. The hook will not run if this equals the current user's ID.
</ParamField>

## Returns

<ResponseField name="isBlocked" type="boolean | null">
  Whether the current user blocks the target user. `null` while the initial status check is in progress.
</ResponseField>

<ResponseField name="isLoading" type="boolean">
  `true` while the initial block status is being fetched.
</ResponseField>

<ResponseField name="toggleBlock" type="() => Promise<void>">
  Blocks the user if not currently blocked, or unblocks if currently blocked. No-ops if loading or if `userId` equals the current user's ID.
</ResponseField>

<Note>
  The current user must be signed in for this hook to function. The hook performs no action if the `userId` matches the authenticated user's own ID.
</Note>

## Related

* [useBlockUser](/hooks/blocks/use-block-user)
* [useUnblockUser](/hooks/blocks/use-unblock-user)
* [useFetchBlockStatus](/hooks/blocks/use-fetch-block-status)
* [useFetchBlockedUsers](/hooks/blocks/use-fetch-blocked-users)


# useConnectionManager
Source: https://docs.sublay.io/v7/sdk/relationships/use-connection-manager

High-level hook for managing the full connection lifecycle with a single user

`useConnectionManager` is the recommended way to implement connection UIs. It loads the connection status with a specific user on mount and exposes named actions for every state transition: send, accept, decline, withdraw, and disconnect.

## Usage Example

```tsx theme={null}
import { useConnectionManager } from "@sublay/react-js";

function ConnectionButton({ userId }: { userId: string }) {
  const {
    connectionStatus,
    isLoading,
    sendConnectionRequest,
    acceptConnectionRequest,
    declineConnectionRequest,
    withdrawConnectionRequest,
    disconnectUser,
  } = useConnectionManager({ userId });

  if (isLoading) return <button disabled>Loading...</button>;

  switch (connectionStatus) {
    case "none":
      return <button onClick={() => sendConnectionRequest()}>Connect</button>;
    case "pending-sent":
      return <button onClick={withdrawConnectionRequest}>Withdraw Request</button>;
    case "pending-received":
      return (
        <>
          <button onClick={acceptConnectionRequest}>Accept</button>
          <button onClick={declineConnectionRequest}>Decline</button>
        </>
      );
    case "connected":
      return <button onClick={disconnectUser}>Disconnect</button>;
    case "declined-sent":
      return <span>Request Declined</span>;
    case "declined-received":
      return <button onClick={() => sendConnectionRequest()}>Connect Again</button>;
  }
}
```

## Parameters

<ParamField type="string">
  The ID of the user whose connection relationship to manage.
</ParamField>

## Returns

<ResponseField name="connectionStatus" type="ConnectionStatus">
  The current relationship state. One of: `"none"` | `"pending-sent"` | `"pending-received"` | `"connected"` | `"declined-sent"` | `"declined-received"`.
</ResponseField>

<ResponseField name="connectionId" type="string | null">
  The ID of the active connection record, if one exists.
</ResponseField>

<ResponseField name="connectionData" type="object">
  Additional metadata about the connection.

  <Expandable title="properties">
    <ResponseField name="connectionId" type="string | null">
      ID of the connection record.
    </ResponseField>

    <ResponseField name="connectedAt" type="string | undefined">
      ISO timestamp when the connection was established.
    </ResponseField>

    <ResponseField name="requestedAt" type="string | undefined">
      ISO timestamp when the request was originally sent.
    </ResponseField>

    <ResponseField name="respondedAt" type="string | undefined">
      ISO timestamp when the request was responded to (accept or decline).
    </ResponseField>

    <ResponseField name="createdAt" type="string | undefined">
      ISO timestamp when the connection record was created.
    </ResponseField>

    <ResponseField name="type" type="&#x22;sent&#x22; | &#x22;received&#x22; | undefined">
      Direction of the pending or declined request from the current user's perspective.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="isLoading" type="boolean">
  `true` while the initial status is being fetched.
</ResponseField>

<ResponseField name="sendConnectionRequest" type="(message?: string) => Promise<void>">
  Sends a connection request to the target user. Accepts an optional message string. Only active when status is `"none"` or `"declined-received"`.
</ResponseField>

<ResponseField name="acceptConnectionRequest" type="() => Promise<void>">
  Accepts an incoming connection request. Only active when status is `"pending-received"`.
</ResponseField>

<ResponseField name="declineConnectionRequest" type="() => Promise<void>">
  Declines an incoming connection request. Only active when status is `"pending-received"`.
</ResponseField>

<ResponseField name="withdrawConnectionRequest" type="() => Promise<void>">
  Withdraws a pending outgoing request. Only active when status is `"pending-sent"`.
</ResponseField>

<ResponseField name="disconnectUser" type="() => Promise<void>">
  Removes an established connection. Only active when status is `"connected"`.
</ResponseField>

<ResponseField name="removeConnectionSmart" type="() => Promise<void>">
  Removes the connection regardless of current state (withdraw, decline, or disconnect) by user ID. Useful as a generic "remove" action when the exact state doesn't matter.
</ResponseField>

<ResponseField name="refreshConnectionStatus" type="() => Promise<void>">
  Re-fetches the connection status from the server.
</ResponseField>

<Note>
  The current user must be signed in. The hook performs no action if `userId` matches the authenticated user's own ID.
</Note>

## Related

* [useRequestConnection](/hooks/connections/use-request-connection)
* [useAcceptConnection](/hooks/connections/use-accept-connection)
* [useDeclineConnection](/hooks/connections/use-decline-connection)
* [useFetchConnectionStatus](/hooks/connections/use-fetch-connection-status)


# useFollowManager
Source: https://docs.sublay.io/v7/sdk/relationships/use-follow-manager

High-level hook for managing follow state with a single user

`useFollowManager` is a convenience hook for building follow/unfollow buttons on a user profile. It automatically loads the current follow status on mount and exposes a `toggleFollow` function that handles both following and unfollowing.

## Usage Example

```tsx theme={null}
import { useFollowManager } from "@sublay/react-js";

function FollowButton({ userId }: { userId: string }) {
  const { isFollowing, isLoading, toggleFollow } = useFollowManager({ userId });

  if (isLoading) return <button disabled>...</button>;

  return (
    <button onClick={toggleFollow}>
      {isFollowing ? "Unfollow" : "Follow"}
    </button>
  );
}
```

## Parameters

<ParamField type="string">
  The ID of the user to follow or unfollow. The hook will not run if this equals the current user's ID.
</ParamField>

## Returns

<ResponseField name="isFollowing" type="boolean | null">
  Whether the current user is following the target user. `null` while the initial status check is in progress.
</ResponseField>

<ResponseField name="isLoading" type="boolean">
  `true` while the initial follow status is being fetched.
</ResponseField>

<ResponseField name="toggleFollow" type="() => Promise<void>">
  Follows the user if not currently following, or unfollows if currently following. No-ops if loading or if `userId` equals the current user's ID.
</ResponseField>

<Note>
  The current user must be signed in for this hook to function. The hook performs no action if the `userId` matches the authenticated user's own ID.
</Note>

## Related

* [useFollowUser](/hooks/follows/use-follow-user)
* [useUnfollowUserByUserId](/hooks/follows/use-unfollow-user-by-user-id)
* [useFetchFollowStatus](/hooks/follows/use-fetch-follow-status)


# Reputation Grants Overview
Source: https://docs.sublay.io/v7/sdk/reputation/overview

Give, list, and display reputation grants with the React SDK

Reputation in Sublay is normally *earned* — posting, commenting, receiving reactions. **Grants** are the other half: reputation deliberately *given*, by one user to another. They are the primitive behind tipping, bounties, best-answer awards, and peer recognition.

The React SDK exposes the user-facing half of that surface: sending a grant as the logged-in user, and reading grants back. Hooks authenticate as the **logged-in user** — the server derives the sender from the token, so you never pass an actor `userId`.

Minting (creating reputation from nothing, or destroying it) is service-key-only and lives in [`@sublay/node`](/v7/node-sdk/reputation).

All hooks are importable from `@sublay/react-js`, `@sublay/react-native`, and `@sublay/expo`.

Requires the `reputation` bundle on the project. See [Bundles](/bundles) and the [Reputation](/data-models/reputation) model.

## Hooks at a glance

| Hook                                                                                                | Purpose                                                      |
| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| [`useCreateReputationGrant`](/hooks/reputation/use-create-reputation-grant)                         | Transfer reputation from the logged-in user to another user. |
| [`useFetchManyReputationGrants`](/hooks/reputation/use-fetch-many-reputation-grants)                | One-shot list query (low-level).                             |
| [`useFetchManyReputationGrantsWrapper`](/hooks/reputation/use-fetch-many-reputation-grants-wrapper) | Stateful, paginated list with `loadMore` and `refresh`.      |

There is **no Redux store and no provider** for grants. Lists are local state held by the wrapper hook, and per-item totals ride along on the items themselves.

## Sending a grant

`useCreateReputationGrant` returns a callable. The sender's bucket is debited and the recipient's bucket for the same space is credited; the recipient is notified.

```tsx theme={null}
import { useCreateReputationGrant } from "@sublay/react-js";

function RewardButton({ answer }) {
  const createReputationGrant = useCreateReputationGrant();

  const handleReward = async () => {
    await createReputationGrant({
      recipientId: answer.userId,
      amount: 50,
      spaceId: answer.spaceId,          // omit for the project-general bucket
      note: "Best answer",
      targetType: "comment",
      targetId: answer.id,
    });
  };

  return <button onClick={handleReward}>Reward 50</button>;
}
```

Two rules are worth internalizing before you build a UI around this:

* **The sender chooses which of their buckets pays, never where it lands.** The reputation always arrives in the recipient's bucket for the same space. Reputation never crosses between the project-general bucket and a space bucket.
* **The target is an annotation.** It says what the grant was *for*, not who gets paid or from which bucket. It doesn't even have to be authored by the recipient.

If the sender's chosen bucket is short, the request rejects with `409 reputation-grant/insufficient-reputation` and nothing moves. A `spaceId` naming no space rejects earlier still, with `404 reputation-grant/space-not-found`. Grant creation is **not idempotent** — guard your button against double-submits, because a retry moves the points twice.

## Showing totals on an item

Ask for the grants summary inline rather than fetching a list you then have to sum. Entities and comments take a `grants` token in `include`; chat messages take an `includeGrants` boolean:

```tsx theme={null}
const { entities } = useFetchManyEntitiesWrapper({ include: ["user", "grants"] });

entities.map((e) => (
  <span key={e.id}>
    {e.grants?.total} points from {e.grants?.count} people
    {e.grants?.viewerTotal ? ` · you gave ${e.grants.viewerTotal}` : ""}
  </span>
));
```

`viewerTotal` is an **amount, not a flag** — a user may grant the same item more than once. The server returns a zero-filled summary rather than omitting the key on a project with no grants, so `grants` being `undefined` always means "nobody asked for it".

## Listing grants

Use the wrapper for a ready-made paginated list. Exactly one filter shape per query — by recipient, by sender, or by target:

```tsx theme={null}
import { useFetchManyReputationGrantsWrapper } from "@sublay/react-js";

function WhoRewardedThis({ commentId }) {
  const { grants, summary, loading, hasMore, loadMore } =
    useFetchManyReputationGrantsWrapper({
      targetType: "comment",
      targetId: commentId,
      include: ["user"],
      limit: 20,
    });

  return (
    <>
      <h4>{summary?.total ?? 0} points from {summary?.count ?? 0} people</h4>
      {grants.map((g) => (
        <div key={g.id}>
          {g.sender?.name ?? "Someone"} gave {g.amount}
          {g.note ? ` — "${g.note}"` : ""}
        </div>
      ))}
      {hasMore && <button disabled={loading} onClick={loadMore}>Load more</button>}
    </>
  );
}
```

`summary` is only returned on the target shape — it is exactly the block a standalone "who rewarded this" view needs, so you don't have to fetch the parent item just to print the totals.

<Warning>
  **Grants on chat messages are private to their conversation.** Every shape asks the same question — can the logged-in user see the message? With `targetType: "chat-message"` the list is populated only for a member of that conversation, and having left it still counts; everyone else gets an empty list and a zero summary rather than an error. The `recipientId` / `senderId` shapes run that same test per row, so a user's own "reputation I received" feed *does* carry the grants made on messages in their own conversations, while a caller outside the conversation loses those rows from the list and from `pagination.totalItems` together. On either shape, the grants on a message moderation has removed are hidden — from members of the conversation too.
</Warning>

<Note>
  **Only positive grants come back, and lists are never block-filtered.** Negative grants (your app's moderation deductions) are invisible on every SDK read surface. And unlike entity or comment feeds, grant lists apply no block exclusion — so the amounts you render always add up to the total you render beside them.
</Note>

## Grants in chat

A grant landing on a chat message is broadcast live to everyone in the conversation, the same way message reactions are. `ChatProvider` handles the [`message:grant`](/sdk/chat/real-time) event for you: the message's `grants` summary updates in the store and your components re-render.

Load messages with `includeGrants: true` so each message carries a baseline summary — without it, `viewerTotal` starts at `0` and only reflects grants seen live in that session.

```tsx theme={null}
const { messages } = useLiveChatMessages({ conversationId, includeGrants: true });
```

## When users can't grant directly

A project can switch **user-initiated grants off** from **Settings → SDK** in the dashboard. The switch is the project setting `settings.reputationGrants.allowUserInitiated`: only an explicit `false` closes the endpoint to user tokens, an absent key means grants are allowed, and the stored value survives unrelated settings updates so it changes only when that key is explicitly sent. When it's off, `useCreateReputationGrant` rejects with `403 reputation-grant/user-grants-disabled`, and grants must be routed through your backend with a service key instead — a *mediated transfer*, which behaves identically to a user grant (same bucket routing, same balance check) but lets you enforce your own rules first: caps, cooldowns, daily limits, eligibility. Sublay imposes none of those itself.

## See Also

* [ReputationGrant data model](/data-models/reputation-grant)
* [Reputation data model](/data-models/reputation)
* [Create Reputation Grant API](/api-reference/reputation-grants/create-reputation-grant)
* [Node SDK reputation module](/v7/node-sdk/reputation)
* [JS SDK reputation module](/v7/js-sdk/reputation)


# Ask Content
Source: https://docs.sublay.io/v7/sdk/search/ask

AI-powered question answering over your project's embedded content

`useAskContent` lets users ask natural language questions and receive AI-generated answers grounded in your project's actual content. The answer streams token by token via SSE, and once streaming completes, a list of source records is provided.

## Usage Example

```tsx theme={null}
import { useAskContent } from "@sublay/react-js";

function AskBox() {
  const { answer, sources, streaming, loading, error, ask, reset } = useAskContent();

  const handleAsk = () => {
    ask({
      query: "What are the most common questions about billing?",
      sourceTypes: ["entity", "comment"],
      limit: 5,
    });
  };

  return (
    <div>
      <button onClick={handleAsk} disabled={loading || streaming}>Ask</button>
      <button onClick={reset}>Clear</button>

      {loading && <p>Thinking...</p>}
      {answer && <p>{answer}{streaming && "▋"}</p>}

      {sources.length > 0 && (
        <ul>
          {sources.map((s) => (
            <li key={s.record.id}>
              [{s.sourceType}] {s.record.id}
            </li>
          ))}
        </ul>
      )}
      {error && <p style={{ color: "red" }}>{error}</p>}
    </div>
  );
}
```

## Parameters (`ask` function)

<ParamField type="string">
  The natural language question to answer.
</ParamField>

<ParamField type="(&#x22;entity&#x22; | &#x22;comment&#x22; | &#x22;message&#x22;)[]">
  Limit the content types searched for context. Defaults to all types.
</ParamField>

<ParamField type="string">
  Scope the context lookup to a specific space.
</ParamField>

<ParamField type="boolean">
  Only applies with `spaceId`. When `true`, the context lookup also covers every space nested under it — the whole subtree at any depth — so you can ask across a community and all of its channels at once. Ignored without `spaceId`.
</ParamField>

<ParamField type="string">
  Scope the context lookup to a specific conversation.
</ParamField>

<ParamField type="number">
  Maximum number of source records to retrieve and use as context.
</ParamField>

## Returns

<ResponseField name="answer" type="string">
  The AI-generated answer. Grows incrementally as tokens arrive during streaming.
</ResponseField>

<ResponseField name="sources" type="ContentSearchResult[]">
  The source records that were used as context for the answer. Populated after streaming completes.

  <Expandable title="ContentSearchResult properties">
    <ResponseField name="sourceType" type="&#x22;entity&#x22; | &#x22;comment&#x22; | &#x22;message&#x22;">
      The type of the source record.
    </ResponseField>

    <ResponseField name="similarity" type="number">
      Cosine similarity score (0–1) for this source.
    </ResponseField>

    <ResponseField name="record" type="Entity | Comment | ChatMessage">
      The full source record.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="streaming" type="boolean">
  `true` while the SSE stream is open and tokens are arriving.
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` from when `ask()` is called until the first token arrives (or an error occurs).
</ResponseField>

<ResponseField name="error" type="string | null">
  Error message if the request failed.
</ResponseField>

<ResponseField name="ask" type="(props) => void">
  Initiates the AI question. Cancels any in-flight stream before starting a new one.
</ResponseField>

<ResponseField name="reset" type="() => void">
  Aborts any in-flight stream and clears all state.
</ResponseField>

<Note>
  `useAskContent` uses the Fetch API with `ReadableStream` and `TextDecoder` for SSE. In React Native, install `react-native-fetch-api`, `web-streams-polyfill@^3`, `react-native-polyfill-globals`, and `text-encoding`, then call the targeted sub-polyfills once at app startup:

  ```ts theme={null}
  import { polyfill as polyfillEncoding } from "react-native-polyfill-globals/src/encoding";
  import { polyfill as polyfillReadableStream } from "react-native-polyfill-globals/src/readable-stream";
  import { polyfill as polyfillFetch } from "react-native-polyfill-globals/src/fetch";

  polyfillEncoding();
  polyfillReadableStream();
  polyfillFetch(); // last, so it wins over the built-in fetch
  ```

  Prefer these over the all-in-one `polyfillGlobals()`, which also pulls in the native `react-native-get-random-values` and forces a development-client rebuild. Pin `web-streams-polyfill` to v3 — v4 removed the `ponyfill/es6` subpath `react-native-polyfill-globals` requires.
</Note>

## Related

* [useSearchContent](/hooks/search/use-search-content) — non-AI semantic search
* [Search & AI overview](/sdk/search/overview)


# Overview
Source: https://docs.sublay.io/v7/sdk/search/overview

Semantic search and AI-powered Q&A over your project content

Sublay's Search & AI features use vector embeddings to power natural language search and question answering across all content in your project — entities, comments, chat messages, users, and spaces.

<Note>
  **Requires the `ai-search` bundle.** Semantic search and the AI ask endpoint are only available when the `ai-search` bundle is installed on your project. See [Bundles](/bundles) to add it.
</Note>

<Note>
  Semantic search and AI features require embeddings to be enabled for your project. Configure this in the Sublay dashboard under **Settings → Semantic Search / AI**.
</Note>

## Search

Search returns the most semantically similar records to a given query. Results include a `similarity` score alongside the matched record.

## AI Q\&A

`useAskContent` lets users ask natural language questions and receive synthesized answers generated from your project's content. The response streams token by token via SSE (Server-Sent Events) and includes source citations.

## In This Section

<CardGroup>
  <Card title="Semantic Search" href="/sdk/search/semantic-search">
    Search entities, comments, messages, users, and spaces by natural language query
  </Card>

  <Card title="Ask" href="/sdk/search/ask">
    Ask a question and stream a generated answer with source links
  </Card>
</CardGroup>

## Hooks

<CardGroup>
  <Card title="useSearchContent" href="/hooks/search/use-search-content">
    Search entities, comments, and messages by natural language
  </Card>

  <Card title="useSearchUsers" href="/hooks/search/use-search-users">
    Find users by name, bio, or other profile text
  </Card>

  <Card title="useSearchSpaces" href="/hooks/search/use-search-spaces">
    Find spaces by name, description, or topic
  </Card>

  <Card title="useAskContent" href="/hooks/search/use-ask-content">
    Ask a question and receive a streamed, cited answer
  </Card>
</CardGroup>


# Semantic Search
Source: https://docs.sublay.io/v7/sdk/search/semantic-search

Search content, users, and spaces with natural language queries

Sublay provides three semantic search hooks — one for content (entities, comments, messages), one for users, and one for spaces. All three return results ranked by semantic similarity to the query.

## useSearchContent

Search across entities, comments, and chat messages. You can filter by `sourceTypes` to target only specific content types, or scope results to a specific space or conversation.

```tsx theme={null}
import { useSearchContent } from "@sublay/react-js";

function ContentSearch() {
  const { results, loading, search, reset } = useSearchContent();

  const handleSearch = async () => {
    await search({
      query: "posts about TypeScript best practices",
      sourceTypes: ["entity"],
      limit: 10,
    });
  };

  return (
    <div>
      <button onClick={handleSearch}>Search</button>
      {results.map((r) => (
        <div key={r.record.id}>
          [{r.sourceType}] {r.record.id} — similarity: {r.similarity.toFixed(2)}
        </div>
      ))}
    </div>
  );
}
```

### Parameters (`search` function)

<ParamField type="string">
  The natural language search query.
</ParamField>

<ParamField type="(&#x22;entity&#x22; | &#x22;comment&#x22; | &#x22;message&#x22;)[]">
  Limit results to specific content types. Defaults to all types.
</ParamField>

<ParamField type="string">
  Scope results to a specific space.
</ParamField>

<ParamField type="boolean">
  Only applies with `spaceId`. When `true`, results also cover every space nested under it — the whole subtree at any depth — not just the named space. Ignored without `spaceId`.
</ParamField>

<ParamField type="string">
  Scope results to a specific conversation (for messages).
</ParamField>

<ParamField type="number">
  Maximum number of results to return.
</ParamField>

### Returns

<ResponseField name="results" type="ContentSearchResult[]">
  Ranked results.

  <Expandable title="ContentSearchResult properties">
    <ResponseField name="sourceType" type="&#x22;entity&#x22; | &#x22;comment&#x22; | &#x22;message&#x22;">
      The type of the matched record.
    </ResponseField>

    <ResponseField name="similarity" type="number">
      Cosine similarity score (0–1). Higher is more similar.
    </ResponseField>

    <ResponseField name="record" type="Entity | Comment | ChatMessage">
      The full matched record.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` while a search is in progress.
</ResponseField>

<ResponseField name="error" type="string | null">
  Error message if the search failed.
</ResponseField>

<ResponseField name="search" type="(props) => Promise<void>">
  Executes the search and updates `results`.
</ResponseField>

<ResponseField name="reset" type="() => void">
  Clears results and error state.
</ResponseField>

***

## useSearchUsers

Search for users by natural language query — matches against name, username, bio, and other profile text.

```tsx theme={null}
import { useSearchUsers } from "@sublay/react-js";

function UserSearch() {
  const { results, search } = useSearchUsers();

  return (
    <button onClick={() => search({ query: "designers in Berlin", limit: 5 })}>
      Search Users
    </button>
  );
}
```

### Parameters (`search` function)

<ParamField type="string">
  The natural language search query.
</ParamField>

<ParamField type="number">
  Maximum number of results to return.
</ParamField>

### Returns

<ResponseField name="results" type="UserSearchResult[]">
  Ranked user results.

  <Expandable title="UserSearchResult properties">
    <ResponseField name="similarity" type="number">
      Cosine similarity score (0–1).
    </ResponseField>

    <ResponseField name="record" type="User">
      The matched user profile. See [User data model](/data-models/user).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="loading" type="boolean" />

<ResponseField name="error" type="string | null" />

<ResponseField name="search" type="(props) => Promise<void>" />

<ResponseField name="reset" type="() => void" />

***

## useSearchSpaces

Search for spaces by name, description, or topic.

```tsx theme={null}
import { useSearchSpaces } from "@sublay/react-js";

function SpaceSearch() {
  const { results, search } = useSearchSpaces();

  return (
    <button onClick={() => search({ query: "open source communities", limit: 5 })}>
      Find Spaces
    </button>
  );
}
```

### Parameters (`search` function)

<ParamField type="string">
  The natural language search query.
</ParamField>

<ParamField type="number">
  Maximum number of results to return.
</ParamField>

### Returns

<ResponseField name="results" type="SpaceSearchResult[]">
  Ranked space results.

  <Expandable title="SpaceSearchResult properties">
    <ResponseField name="similarity" type="number">
      Cosine similarity score (0–1).
    </ResponseField>

    <ResponseField name="record" type="Space">
      The matched space. See [Space data model](/data-models/space).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="loading" type="boolean" />

<ResponseField name="error" type="string | null" />

<ResponseField name="search" type="(props) => Promise<void>" />

<ResponseField name="reset" type="() => void" />


# Membership
Source: https://docs.sublay.io/v7/sdk/spaces/membership

Join and leave spaces, manage members, handle approval workflows, and assign roles

Each space has its own membership list. Members can be regular users, moderators, or admins. Spaces can require join approval, and moderators/admins can approve, decline, ban, or unban members.

## Joining and Leaving

The simplest membership operations are exposed directly from `useSpace`:

```tsx theme={null}
import { useSpace } from "@sublay/react-js";

function MembershipButton() {
  const { isMember, isPending, joinSpace, leaveSpace } = useSpace();

  if (isPending) return <p>Waiting for approval...</p>;
  if (isMember) return <button onClick={leaveSpace}>Leave</button>;
  return <button onClick={joinSpace}>Join</button>;
}
```

When a space has `requireJoinApproval: true`, `joinSpace()` creates a `pending` membership that must be approved by a moderator or admin before the user becomes `active`.

## Fetching Members

Use standalone hooks to fetch member lists:

```tsx theme={null}
import { useFetchSpaceMembers, useFetchSpaceTeam } from "@sublay/react-js";

// Paginated list of all members
const fetchMembers = useFetchSpaceMembers();
const { data, pagination } = await fetchMembers({ spaceId, page: 1, limit: 20 });
// data: SpaceMemberWithUser[]

// All admins + moderators (no pagination)
const fetchTeam = useFetchSpaceTeam();
const { data } = await fetchTeam({ spaceId });
// data: SpaceMemberWithUser[]
```

## Checking Membership Status

Check the current user's membership without loading the full space:

```tsx theme={null}
import { useCheckMyMembership } from "@sublay/react-js";

const checkMembership = useCheckMyMembership();
const result = await checkMembership({ spaceId });
// result: { isMember, role, status, joinedAt, permissions }
```

## Approving and Declining Requests

Moderators and admins can process pending membership requests:

```tsx theme={null}
import { useApproveMember, useDeclineMember } from "@sublay/react-js";

const approve = useApproveMember();
const decline = useDeclineMember();

await approve({ spaceId, memberId });
await decline({ spaceId, memberId });
```

<Note>Both `useApproveMember` and `useDeclineMember` require the caller to be a moderator or admin of the space.</Note>

## Role Management

Admins can change a member's role:

```tsx theme={null}
import { useUpdateMemberRole } from "@sublay/react-js";

const updateRole = useUpdateMemberRole();
await updateRole({ spaceId, memberId, role: "moderator" });
// Valid roles: "admin" | "moderator" | "member"
```

## Banning and Unbanning

Moderators can ban and unban members:

```tsx theme={null}
import { useBanMember, useUnbanMember } from "@sublay/react-js";

const banMember = useBanMember();
const unban = useUnbanMember();

await banMember({ spaceId, memberId });
await unban({ spaceId, memberId });
```

<Warning>Banning a member sets their status to `"banned"`. Moderators can only ban regular members. Admins can ban moderators and regular members. Only the space creator can ban admins.</Warning>

## Sub-space Cascade

When a child space is created, all admins and moderators of the parent space are automatically added to the child space with their same roles. This ensures governance cascades to sub-communities without manual setup.

## Hook Reference

| Hook                                                            | Description                               |
| --------------------------------------------------------------- | ----------------------------------------- |
| [`useFetchSpaceMembers`](/hooks/spaces/use-fetch-space-members) | Paginated list of space members           |
| [`useFetchSpaceTeam`](/hooks/spaces/use-fetch-space-team)       | All admins and moderators (no pagination) |
| [`useCheckMyMembership`](/hooks/spaces/use-check-my-membership) | Current user's membership status          |
| [`useApproveMember`](/hooks/spaces/use-approve-member)          | Approve a pending join request            |
| [`useDeclineMember`](/hooks/spaces/use-decline-member)          | Decline a pending join request            |
| [`useUpdateMemberRole`](/hooks/spaces/use-update-member-role)   | Change a member's role                    |
| [`useBanMember`](/hooks/spaces/use-ban-member)                  | Ban a member from the space               |
| [`useUnbanMember`](/hooks/spaces/use-unban-member)              | Unban a banned member                     |
| [`useJoinSpace`](/hooks/spaces/use-join-space)                  | Join a space                              |
| [`useLeaveSpace`](/hooks/spaces/use-leave-space)                | Leave a space                             |


# Moderation
Source: https://docs.sublay.io/v7/sdk/spaces/moderation

Moderate content and handle reports within a space

Space moderators and admins can review and act on content in their space. Moderation includes directly approving or removing entities and comments, as well as handling reports submitted by members — on entities, comments, and chat messages in space conversations.

## Direct Moderation

Moderators can act on specific entities or comments without a report being filed:

```tsx theme={null}
import { useModerateSpaceEntity, useModerateSpaceComment } from "@sublay/react-js";

const moderateEntity = useModerateSpaceEntity();
const moderateComment = useModerateSpaceComment();

// Approve or remove an entity
await moderateEntity({ spaceId, entityId, action: "approve" });
await moderateEntity({ spaceId, entityId, action: "remove" });

// Approve or remove a comment
await moderateComment({ spaceId, commentId, action: "approve" });
await moderateComment({ spaceId, commentId, action: "remove" });
```

<Note>Both hooks require the caller to be a moderator or admin of the space.</Note>

## Handling Reports

When members report content, moderators receive those reports and can resolve them:

```tsx theme={null}
import {
  useHandleSpaceEntityReport,
  useHandleSpaceCommentReport,
  useHandleSpaceChatReport,
} from "@sublay/react-js";

const handleEntityReport = useHandleSpaceEntityReport();
const handleCommentReport = useHandleSpaceCommentReport();
const handleChatReport = useHandleSpaceChatReport();

// `actions` is an array — you can combine a removal with a ban in one call.
await handleEntityReport({
  spaceId,
  reportId,
  entityId,
  actions: ["dismiss"],
  summary: "No violation found",
});

await handleCommentReport({
  spaceId,
  reportId,
  commentId,
  actions: ["remove-comment"],
  summary: "Removed for harassment",
});

await handleChatReport({
  spaceId,
  reportId,
  messageId,
  actions: ["remove-message", "ban-user"],
  userId: offendingUserId, // the ban target
  summary: "Removed and banned",
});
```

Each target type has its own removal action — `remove-entity`, `remove-comment`,
`remove-message` — alongside the shared `ban-user` and `dismiss`.

<Note>
  `ban-user` is **space-scoped**: it bans the user from this space only.
  Project-wide suspension is a dashboard action — a space moderator cannot
  suspend someone across the whole project.
</Note>

## Fetching Reports

Use `useFetchModeratedReports` to retrieve pending reports for a space:

```tsx theme={null}
import { useFetchModeratedReports } from "@sublay/react-js";

const fetchReports = useFetchModeratedReports();
const reports = await fetchReports({ spaceId });
```

<Tip>Reports appear in the list until they are resolved. Filter by `status: "pending"` in your UI to show actionable items.</Tip>

## Chat Moderation

Spaces with integrated chat also support message moderation via the API. See the [Space Chat API](/api-reference/spaces/chat/get-space-conversation) for details on moderating chat messages within a space.

## Hook Reference

| Hook                                                                            | Description                            |
| ------------------------------------------------------------------------------- | -------------------------------------- |
| [`useModerateSpaceEntity`](/hooks/spaces/use-moderate-space-entity)             | Approve or remove an entity in a space |
| [`useModerateSpaceComment`](/hooks/spaces/use-moderate-space-comment)           | Approve or remove a comment in a space |
| [`useFetchModeratedReports`](/hooks/reports/use-fetch-moderated-reports)        | Fetch pending content reports          |
| [`useHandleSpaceEntityReport`](/hooks/reports/use-handle-space-entity-report)   | Resolve a reported entity              |
| [`useHandleSpaceCommentReport`](/hooks/reports/use-handle-space-comment-report) | Resolve a reported comment             |


# Overview
Source: https://docs.sublay.io/v7/sdk/spaces/overview

Build community spaces with membership, moderation, rules, and optional chat

Spaces are community containers where users can gather, post content, and interact under customizable rules. Each space has its own membership system, permission levels, moderation tools, and optionally an integrated chat conversation.

<Note>
  **Requires the `spaces` bundle.** Spaces are only available when the `spaces` bundle is installed on your project (space-level chat additionally needs the `chat` bundle). See [Bundles](/bundles) to add it.
</Note>

## In This Section

<CardGroup>
  <Card title="Provider & Hook" href="/sdk/spaces/provider-and-hook">
    Load a space into context and access its state and operations
  </Card>

  <Card title="Membership" href="/sdk/spaces/membership">
    Join/leave spaces, approval workflows, role management
  </Card>

  <Card title="Moderation" href="/sdk/spaces/moderation">
    Approve or remove content, handle member and content reports
  </Card>

  <Card title="Rules" href="/sdk/spaces/rules">
    Create and display community rules for members
  </Card>

  <Card title="Space Lists" href="/sdk/spaces/space-lists">
    Browse and paginate spaces with filtering and sorting
  </Card>
</CardGroup>

## Core Architecture

Spaces follow the provider + hook pattern used throughout Sublay. Wrap your space UI with a `SpaceProvider` and access everything via `useSpace`.

```tsx theme={null}
import { SpaceProvider, useSpace } from "@sublay/react-js";

function SpacePage() {
  return (
    <SpaceProvider spaceId="space-uuid">
      <SpaceContent />
    </SpaceProvider>
  );
}

function SpaceContent() {
  const { space, isMember, canPost, joinSpace } = useSpace();

  if (!space) return <div>Loading...</div>;

  return (
    <div>
      <h1>{space.name}</h1>
      {!isMember && (
        <button onClick={joinSpace}>Join Space</button>
      )}
    </div>
  );
}
```

## Permission Model

Each space has two independent permission settings:

* **`readingPermission`** — `"anyone"` or `"members"`. Controls who can see content.
* **`postingPermission`** — `"anyone"`, `"members"`, or `"admins"`. Controls who can post.

When the current user is authenticated and is a member, `useSpace` exposes their resolved permissions (`canPost`, `canRead`, `canModerate`, `isAdmin`, `isModerator`).

Separately, each space has a **`visibility`** setting — `"public"` (default), `"unlisted"`, or `"private"` — that controls whether the space is *listed and discoverable*, independent of the permission model above. `"unlisted"` hides a space from discovery and search but keeps it reachable by direct link; it is **not access control** (use `readingPermission` to gate content). `"private"` currently behaves like `"unlisted"`. See the [Space data model](/data-models/space#visibility).

## Hierarchy

Spaces can be nested up to 10 levels deep. A child space is created by passing a `parentSpaceId` to `useCreateSpace`. Only admins of the parent space can create child spaces. Parent admins and moderators are automatically cascaded into new child spaces with their existing roles.

## What's Next

Start with the [Provider & Hook](/sdk/spaces/provider-and-hook) to learn how to set up a space in your component tree, then explore membership and moderation features.


# SpaceProvider & useSpace
Source: https://docs.sublay.io/v7/sdk/spaces/provider-and-hook

Load a space into React context and access its state, permissions, and operations

The `SpaceProvider` and `useSpace` hook are the primary way to work with a single space in your app. The provider fetches and manages the space data; the hook exposes everything to your components.

## SpaceProvider

Place `SpaceProvider` anywhere in your tree where space data is needed. You can identify the space by UUID, shortId, or slug — or skip the fetch entirely by passing a pre-fetched space object directly.

```tsx theme={null}
import { SpaceProvider } from "@sublay/react-js";

// By UUID
<SpaceProvider spaceId="space-uuid">
  <SpaceContent />
</SpaceProvider>

// By shortId
<SpaceProvider shortId="abc123">
  <SpaceContent />
</SpaceProvider>

// By slug
<SpaceProvider slug="my-community">
  <SpaceContent />
</SpaceProvider>

// Pre-fetched object (no fetch needed — useful for SSR or when the space is already loaded)
<SpaceProvider space={mySpace}>
  <SpaceContent />
</SpaceProvider>
```

### Props

<ParamField type="string">
  UUID of the space to load. Use this, `shortId`, or `slug`.
</ParamField>

<ParamField type="string">
  Short identifier of the space. Use this, `spaceId`, or `slug`.
</ParamField>

<ParamField type="string">
  URL slug of the space. Use this, `spaceId`, or `shortId`.
</ParamField>

<ParamField type="SpaceDetailed">
  A pre-fetched space object. Skips the initial fetch if provided. Useful for SSR or when the space is already loaded in a parent component.
</ParamField>

<ParamField type="&#x22;files&#x22; | string[]">
  Optional. Pass `"files"` to include avatar and banner file data in the fetched space.
</ParamField>

<Note>`SpaceProvider` renders `null` if none of `spaceId`, `shortId`, `slug`, or `space` is provided.</Note>

## useSpace

`useSpace` must be called inside a descendant of `SpaceProvider`.

```tsx theme={null}
import { useSpace } from "@sublay/react-js";

function SpaceContent() {
  const {
    space,
    isMember,
    isAdmin,
    isModerator,
    canPost,
    canModerate,
    membershipStatus,
    isPending,
    isBanned,
    breadcrumb,
    parentSpace,
    childSpaces,
    joinSpace,
    leaveSpace,
    updateSpace,
    deleteSpace,
    loading,
    error,
  } = useSpace();
}
```

## Return Values

### Space State

<ResponseField name="space" type="SpaceDetailed | null | undefined">
  The loaded space object. `undefined` while loading, `null` if not found.
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` while the space is being fetched.
</ResponseField>

<ResponseField name="error" type="string | null">
  Error message if the fetch failed.
</ResponseField>

### Membership & Permissions

<ResponseField name="isMember" type="boolean">
  `true` if the current user has an active membership in this space.
</ResponseField>

<ResponseField name="isAdmin" type="boolean">
  `true` if the current user is an admin of this space.
</ResponseField>

<ResponseField name="isModerator" type="boolean">
  `true` if the current user is a moderator of this space.
</ResponseField>

<ResponseField name="canPost" type="boolean">
  `true` if the current user can post entities in this space, based on the space's `postingPermission` and the user's membership status.
</ResponseField>

<ResponseField name="canModerate" type="boolean">
  `true` if the current user can perform moderation actions in this space.
</ResponseField>

<ResponseField name="membershipStatus" type="&#x22;pending&#x22; | &#x22;active&#x22; | &#x22;banned&#x22; | null">
  The current user's raw membership status. `null` if not a member.
</ResponseField>

<ResponseField name="isPending" type="boolean">
  `true` if the user's join request is awaiting approval.
</ResponseField>

<ResponseField name="isBanned" type="boolean">
  `true` if the user is banned from this space.
</ResponseField>

### Hierarchy

<ResponseField name="breadcrumb" type="SpacePreview[]">
  Ordered list of ancestor spaces from root to direct parent. Empty for root-level spaces.
</ResponseField>

<ResponseField name="parentSpace" type="SpacePreview | null">
  Preview of the immediate parent space. `null` for root spaces.
</ResponseField>

<ResponseField name="childSpaces" type="SpacePreview[]">
  Previews of direct child spaces (up to 10 returned by the API).
</ResponseField>

### Operations

<ResponseField name="joinSpace" type="() => Promise<void>">
  Join the current space. If the space requires approval, the membership enters `pending` status.
</ResponseField>

<ResponseField name="leaveSpace" type="() => Promise<void>">
  Leave the current space.
</ResponseField>

<ResponseField name="updateSpace" type="(props: { update }) => Promise<SpaceDetailed | undefined>">
  Update space settings. Only available to admins.
</ResponseField>

<ResponseField name="deleteSpace" type="() => Promise<void>">
  Delete the space and all associated data. Only available to admins.
</ResponseField>

<ResponseField name="setSpace" type="React.Dispatch">
  Directly set the space state. Useful for optimistic local updates.
</ResponseField>

## Example: Space Page with Membership Button

```tsx theme={null}
import { SpaceProvider, useSpace } from "@sublay/react-js";

function SpacePage({ spaceId }: { spaceId: string }) {
  return (
    <SpaceProvider spaceId={spaceId}>
      <SpaceHeader />
    </SpaceProvider>
  );
}

function SpaceHeader() {
  const { space, isMember, isPending, joinSpace, leaveSpace, loading } = useSpace();

  if (loading) return <p>Loading...</p>;
  if (!space) return <p>Space not found.</p>;

  return (
    <div>
      <h1>{space.name}</h1>
      <p>{space.description}</p>
      <p>{space.membersCount} members</p>
      {!isMember && !isPending && (
        <button onClick={joinSpace}>Join</button>
      )}
      {isPending && <p>Waiting for approval...</p>}
      {isMember && (
        <button onClick={leaveSpace}>Leave</button>
      )}
    </div>
  );
}
```

## See Also

* [Space data model](/data-models/space)
* [Membership guide](/sdk/spaces/membership)
* [useSpace hook reference](/hooks/spaces/use-space)


# Rules
Source: https://docs.sublay.io/v7/sdk/spaces/rules

Create and manage community rules visible to all space members

Spaces can define community rules — titled and optionally described guidelines that are publicly visible to all users. Rules are ordered and can be reordered by admins. They are read-only for regular members.

## Fetching Rules

Rules are publicly readable without authentication:

```tsx theme={null}
import { useFetchManyRules, useFetchRule } from "@sublay/react-js";

// Fetch all rules for a space
const fetchRules = useFetchManyRules();
const { data: rules, count } = await fetchRules({ spaceId });

// Fetch a single rule by ID
const fetchRule = useFetchRule();
const rule = await fetchRule({ spaceId, ruleId });
```

## Creating Rules

Only space admins can create rules:

```tsx theme={null}
import { useCreateRule } from "@sublay/react-js";

const createRule = useCreateRule();
const newRule = await createRule({
  spaceId,
  title: "Be respectful",
  description: "Treat all members with kindness and respect.",
});
```

## Updating and Deleting Rules

```tsx theme={null}
import { useUpdateRule, useDeleteRule } from "@sublay/react-js";

const updateRule = useUpdateRule();
const deleteRule = useDeleteRule();

await updateRule({
  spaceId,
  ruleId,
  title: "Updated Title",
  description: "Updated description text.",
});

await deleteRule({ spaceId, ruleId });
```

## Reordering Rules

Admins can reorder rules by providing a new ordered array of rule IDs:

```tsx theme={null}
import { useReorderRules } from "@sublay/react-js";

const reorderRules = useReorderRules();
await reorderRules({
  spaceId,
  ruleIds: ["rule-id-1", "rule-id-3", "rule-id-2"],
});
```

The `order` field on each rule reflects its position in the list. Rules are typically displayed in ascending order.

## Rule Data Shape

Each rule returned by the API has the following fields:

| Property         | Type             | Description                                  |
| ---------------- | ---------------- | -------------------------------------------- |
| `id`             | `string`         | Unique rule identifier.                      |
| `spaceId`        | `string`         | The space this rule belongs to.              |
| `title`          | `string`         | Short rule title.                            |
| `description`    | `string \| null` | Optional detailed description.               |
| `order`          | `number`         | Sort position within the space's rule list.  |
| `lastApprovedBy` | `string \| null` | ID of the admin who last approved this rule. |
| `createdAt`      | `Date`           | Creation timestamp.                          |
| `updatedAt`      | `Date`           | Last update timestamp.                       |

## Hook Reference

| Hook                                                            | Description                    |
| --------------------------------------------------------------- | ------------------------------ |
| [`useFetchManyRules`](/hooks/spaces/rules/use-fetch-many-rules) | Fetch all rules for a space    |
| [`useFetchRule`](/hooks/spaces/rules/use-fetch-rule)            | Fetch a single rule            |
| [`useCreateRule`](/hooks/spaces/rules/use-create-rule)          | Create a new rule (admin only) |
| [`useUpdateRule`](/hooks/spaces/rules/use-update-rule)          | Update a rule (admin only)     |
| [`useDeleteRule`](/hooks/spaces/rules/use-delete-rule)          | Delete a rule (admin only)     |
| [`useReorderRules`](/hooks/spaces/rules/use-reorder-rules)      | Reorder rules (admin only)     |


# Space Lists
Source: https://docs.sublay.io/v7/sdk/spaces/space-lists

Browse, search, and paginate spaces with filtering and sorting

The `useSpaceList` hook provides a Redux-backed, paginated list of spaces with support for filtering, sorting, and search. It is designed for discovery pages, community browsers, and admin dashboards.

## Basic Usage

```tsx theme={null}
import { useSpaceList } from "@sublay/react-js";
import { useEffect } from "react";

function SpaceDirectory() {
  const {
    spaces,
    loading,
    hasMore,
    fetchSpaces,
    loadMore,
  } = useSpaceList({ listId: "directory" });

  useEffect(() => {
    fetchSpaces({ sortBy: "newest" });
  }, []);

  return (
    <div>
      {spaces.map((space) => (
        <div key={space.id}>{space.name}</div>
      ))}
      {hasMore && (
        <button onClick={loadMore} disabled={loading}>
          Load more
        </button>
      )}
    </div>
  );
}
```

## Filtering and Sorting

```tsx theme={null}
// Search by name
fetchSpaces({ sortBy: "newest", searchName: "gaming" });

// Search across all fields (name, slug, description)
fetchSpaces({ sortBy: "newest", searchAny: "design" });

// Filter to spaces the current user is a member of
fetchSpaces({ sortBy: "newest", memberOf: true });

// Fetch only child spaces of a parent
fetchSpaces({ sortBy: "newest", parentSpaceId: "parent-space-id" });

// Fetch top-level spaces only
fetchSpaces({ sortBy: "newest", parentSpaceId: null });
```

### Sort Options

| Value            | Description                 |
| ---------------- | --------------------------- |
| `"newest"`       | Most recently created first |
| `"members"`      | Most members first          |
| `"alphabetical"` | Sorted by name, A–Z         |

## Creating and Deleting from a List

`useSpaceList` also exposes create and delete operations that automatically update the list state:

```tsx theme={null}
const { createSpace, deleteSpace } = useSpaceList({ listId: "my-list" });

// Create a new space and insert it into the list
const newSpace = await createSpace({
  name: "New Community",
  readingPermission: "anyone",
  postingPermission: "members",
  requireJoinApproval: true,
  insertPosition: "first", // or "last"
});

// Delete a space and remove it from the list
await deleteSpace({ spaceId: "space-id" });
```

## Multiple Independent Lists

Each `useSpaceList` call uses a `listId` to maintain independent Redux state. You can have multiple lists on the same page without interference:

```tsx theme={null}
const allSpaces = useSpaceList({ listId: "all" });
const mySpaces = useSpaceList({ listId: "my-spaces" });

// Both lists are independent
allSpaces.fetchSpaces({ sortBy: "newest" });
mySpaces.fetchSpaces({ sortBy: "newest", memberOf: true });
```

## Return Values

<ResponseField name="spaces" type="Space[]">
  The current page of loaded spaces.
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` while fetching.
</ResponseField>

<ResponseField name="hasMore" type="boolean">
  `true` if there are more pages to load.
</ResponseField>

<ResponseField name="fetchSpaces" type="function">
  Trigger a new fetch with the given filters and configuration. Resets to page 1.
</ResponseField>

<ResponseField name="loadMore" type="function">
  Fetch the next page of results and append to the current list.
</ResponseField>

<ResponseField name="createSpace" type="function">
  Create a new space and insert it into the list.
</ResponseField>

<ResponseField name="deleteSpace" type="function">
  Delete a space and remove it from the list.
</ResponseField>

## Hook Reference

| Hook                                                               | Description                                                |
| ------------------------------------------------------------------ | ---------------------------------------------------------- |
| [`useSpaceList`](/hooks/space-lists/use-space-list)                | Main hook for paginated space lists                        |
| [`useSpaceListActions`](/hooks/space-lists/use-space-list-actions) | Low-level list actions (used internally by `useSpaceList`) |
| [`useFetchManySpaces`](/hooks/spaces/use-fetch-many-spaces)        | One-off fetch of multiple spaces                           |
| [`useFetchUserSpaces`](/hooks/spaces/use-fetch-user-spaces)        | Fetch spaces the current user is a member of               |


# Overview
Source: https://docs.sublay.io/v7/sdk/storage/overview

Upload, retrieve, and manage files and images in Sublay

## Overview

Sublay's storage system lets you upload files and images on behalf of authenticated users. Uploaded assets are stored in managed cloud storage and served through a proxy URL so direct storage credentials are never exposed to the client.

<Note>
  **Requires the `files-images` bundle.** File and image uploads are only available when the `files-images` bundle is installed on your project. See [Bundles](/bundles) to add it.
</Note>

Files can be optionally associated with an entity, comment, or space, enabling cascade deletion when the parent object is removed.

## Upload Modes

Sublay provides two hooks for uploading assets:

* **Image upload** — server-side processing with automatic variant generation (resizing, format conversion, EXIF stripping). Returns named variants for responsive display.
* **File upload** — generic upload for documents, videos, and other files. No server-side processing — the file is stored as-is and a proxy URL is returned.

## Image Processing Modes

When uploading images, you choose a **processing mode** that defines how variants are generated:

| Mode                        | Description                                                                            |
| --------------------------- | -------------------------------------------------------------------------------------- |
| `exact-dimensions`          | Each variant has an explicit `{ width, height }`. Use for fixed-size crops.            |
| `aspect-ratio-width-based`  | All variants share an aspect ratio; you specify widths. Heights are computed.          |
| `aspect-ratio-height-based` | All variants share an aspect ratio; you specify heights. Widths are computed.          |
| `original-aspect`           | Preserves the source aspect ratio; you specify the longest-edge size for each variant. |
| `multi-aspect-ratio`        | Multiple aspect ratios combined with explicit sizes.                                   |

## File Size Limits

| Upload type         | Limit |
| ------------------- | ----- |
| Image upload        | 50 MB |
| Generic file upload | 50 MB |

## Hooks

<CardGroup>
  <Card title="useUploadImage" href="/hooks/storage/use-upload-image">
    Upload and process an image with automatic variant generation.
  </Card>

  <Card title="useUploadFile" href="/hooks/storage/use-upload-file">
    Upload a generic file and receive a proxy URL.
  </Card>
</CardGroup>

## API Reference

* [Upload Image](/api-reference/storage/upload-image) — `POST /v7/:projectId/storage/images`
* [Upload File](/api-reference/storage/upload-file) — `POST /v7/:projectId/storage`
* [Fetch File](/api-reference/storage/fetch-file) — `GET /v7/:projectId/storage/:fileId`
* [Delete File](/api-reference/storage/delete-file) — `DELETE /v7/:projectId/storage/:fileId`


# Overview
Source: https://docs.sublay.io/v7/sdk/tables/overview

Read and write your project's custom-table rows from React and React Native with useTable

Custom tables let your project provision its own database tables alongside Sublay's built-in models — the app-specific data that doesn't fit a built-in feature. In React and React Native, you access a custom table's rows through the **`useTable`** hook. For the full feature overview — the `custom_` naming model, managed columns, soft-delete, and the dashboard editor — see [Custom Tables](/v7/custom-tables).

<Note>
  `@sublay/core` is hook-only — there is no imperative `client.table(...)` in the
  React SDK. `useTable` is the custom-table surface. For an imperative, server-
  side client use [`@sublay/node`](/v7/node-sdk/tables); for browser/vanilla JS,
  use [`@sublay/js`](/v7/js-sdk/tables).
</Note>

## The hook

`useTable(name)` returns the table's rows plus loading state, query controls (page, sort, filters, soft-delete visibility), and row CRUD actions. The query knobs are held in the Redux store keyed by table name, so multiple components reading the same table share one view.

```tsx theme={null}
import { useTable } from "@sublay/react-js";

interface EventRow {
  id: string;
  name: string;
  capacity: number;
  createdAt: string;
}

function EventsTable() {
  const { rows, loading, setSort, setFilters, createRow } =
    useTable<EventRow>("Events");

  if (loading) return <Spinner />;

  return (
    <>
      <button onClick={() => setSort("capacity", "desc")}>Sort by capacity</button>
      {rows.map((e) => (
        <div key={e.id}>{e.name} — {e.capacity}</div>
      ))}
      <button onClick={() => createRow({ name: "New event", capacity: 50 })}>
        Add
      </button>
    </>
  );
}
```

The `name` you pass is the **logical** table name — Sublay applies the `custom_` prefix for you. `useTable` is re-exported from both `@sublay/react-js` and `@sublay/react-native`.

## Reads, filters, and soft delete

Rows come back already paginated, sorted, and filtered according to the table's stored view. Adjust the view with `setPage`, `setSort`, `setFilters`, and `setIncludeDeleted`. Filters are `{ column, operator, value }` clauses (AND-combined) using the operators `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `contains`, `like`, `isNull`.

On a **paranoid** table, soft-deleted rows are hidden by default; call `setIncludeDeleted(true)` to surface them, and `restoreRow(id)` to bring one back. `deleteRow(id)` soft-deletes on a paranoid table (pass `{ force: true }` to hard-delete) and hard-deletes otherwise.

## Hooks

<CardGroup>
  <Card title="useTable" href="/v7/hooks/tables/use-table">
    Full reference — props, return values, and the CRUD actions.
  </Card>
</CardGroup>

<Warning>
  Row CRUD on the `/db` surface is currently **open** — identity is captured but
  not enforced. See the [security note](/v7/custom-tables#security-open-row-crud)
  before storing access-controlled data in custom tables.
</Warning>


# Current User
Source: https://docs.sublay.io/v7/sdk/users/current-user

Reading and updating the authenticated user's own profile

The Current User section covers everything related to the authenticated user's own data — reading their profile state and updating it. This is distinct from [User Profiles](/sdk/user-profiles/overview), which covers fetching other users' public profiles.

## Hooks

<CardGroup>
  <Card title="useUser" href="/hooks/user/use-user">
    Access the authenticated user's full profile state, including loading and error states. Provides an `updateUser` action for modifying profile data.
  </Card>
</CardGroup>

## What the Current User Can Do

The authenticated user can update their own profile fields:

* **Name** — display name shown across the platform
* **Username** — unique handle (subject to availability)
* **Avatar** — profile picture, uploaded as a file or set as a URL
* **Banner** — profile banner image (file upload only)
* **Bio** — short biography, up to 300 characters
* **Birthdate** — optional date of birth
* **Location** — optional geographic location (latitude/longitude)
* **Metadata** — arbitrary JSON data for project-specific user properties
* **Secure Metadata** — same as metadata but excluded from other users' views

## User State

The `useUser` hook returns an `AuthUser` object which contains the complete profile of the authenticated user, including fields that are not exposed in public profiles. See the [User data model](/data-models/user) for the full field reference.

<Note>
  The `AuthUser` type includes `authMethods` (e.g., `["password", "google"]`) and `suspensions` — fields only available for the authenticated user's own profile.
</Note>

`useUser` also derives `isSuspended` and `activeSuspension` from the user's suspensions, so you can render a suspended state ambiently. See [Suspensions](/sdk/moderation/suspensions) for the full enforcement behavior and the catchable `SuspendedError`.


# User Profiles
Source: https://docs.sublay.io/v7/sdk/users/user-profiles

Fetch and search public profiles of other users in your project

User Profiles covers fetching and searching for other users' public profiles. This is distinct from [Current User](/sdk/current-user/overview), which covers the authenticated user's own data.

All hooks in this section return `User` objects — the public-facing profile type. Unlike `AuthUser`, `User` omits private fields such as `email`, `secureMetadata`, `isVerified`, `isActive`, and `lastActive`.

## Hooks

<CardGroup>
  <Card title="useFetchUser" href="/hooks/users/use-fetch-user">
    Fetch a user's public profile by their Sublay user ID.
  </Card>

  <Card title="useFetchUserByForeignId" href="/hooks/users/use-fetch-user-by-foreign-id">
    Fetch a user's public profile by their foreign ID (from your own system).
  </Card>

  <Card title="useFetchUserByUsername" href="/hooks/users/use-fetch-user-by-username">
    Fetch a user's public profile by their username.
  </Card>

  <Card title="useFetchUserSuggestions" href="/hooks/users/use-fetch-user-suggestions">
    Search for users by a query string. Useful for autocomplete and user lookup.
  </Card>

  <Card title="useCheckUsernameAvailability" href="/hooks/users/use-check-username-availability">
    Check whether a username is available before setting it.
  </Card>

  <Card title="useUserMentions" href="/hooks/users/use-user-mentions">
    Full mention flow: detects `@` triggers, fetches suggestions, inserts the username into content, and tracks mentioned users.
  </Card>
</CardGroup>

## The `include` Parameter

Several hooks accept an optional `include` parameter. Passing `"files"` (or `["files"]`) instructs the server to populate the user's `avatarFile` and `bannerFile` fields with full `File` objects instead of returning only the IDs.

```tsx theme={null}
const user = await fetchUser({ userId, include: "files" });
// user.avatarFile is now populated
```

## User vs AuthUser

| Field                                     | `User` (public) | `AuthUser` (self only) |
| ----------------------------------------- | :-------------: | :--------------------: |
| `id`, `name`, `username`, `avatar`, `bio` |        ✓        |            ✓           |
| `email`                                   |        —        |            ✓           |
| `secureMetadata`                          |        —        |            ✓           |
| `authMethods`                             |        —        |            ✓           |
| `suspensions`                             |        —        |            ✓           |
| `isVerified`, `isActive`, `lastActive`    |        —        |            ✓           |

See the [User data model](/data-models/user) for the complete field reference.


# Overview
Source: https://docs.sublay.io/v7/sdk/workspaces/overview

Build SaaS/team workspaces with invitations, per-member authority, and self-nesting

[Workspaces](/data-models/workspace) give your app the B2B/SaaS collaboration layer: an account/team that people are invited into, with granular per-member authority and optional self-nesting (org → client → project). Unlike [Spaces](/sdk/spaces/overview) (a community shape), Workspaces is **invite-only** with an owner apex and a capability/permission model.

<Note>
  **Requires the `workspaces` bundle.** See [Bundles](/bundles) to add it.
</Note>

The React/React Native surface is a set of plain hooks re-exported from `@sublay/core` (there is **no** `WorkspaceProvider` and **no** Redux slice — the list uses the [Wrapper pattern](/hooks/workspaces/use-fetch-many-workspaces-wrapper), matching house style).

## Key concepts

* **[capabilities vs permissions](/data-models/workspace-member#the-two-arrays-capabilities-vs-permissions)** — Sublay enforces the closed `capabilities` vocabulary; it is blind to your opaque `permissions`.
* **[Ownership](/data-models/workspace#ownership)** — one owner per workspace (the creator); ancestor owners are gods over descendants.
* **[Reach & the wall/door rule](/data-models/workspace#reach-and-the-wall-door-rule)** — strict per-node by default; opt-in downward reach via the child-owned `inheritsFromParent` flag.
* **[Invitations](/data-models/workspace-invitation#acceptance-model)** — identity-matched + verified-email, **no token**.

## Project settings

Three project-level settings configure this bundle. They live under `workspaces` in your project's `settings` blob — set them in the dashboard under **Settings → project settings**, or via the update-project-settings endpoint. All three are **absent by default**, and absent means the strict behavior in the table below.

```json Project settings theme={null}
{
  "workspaces": {
    "inviteAcceptUrl": "https://app.example.com/invites",
    "inheritsDefault": false,
    "inheritEnforced": false
  }
}
```

| Setting                      | Type      | Default  | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ---------------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `workspaces.inviteAcceptUrl` | `string`  | *(none)* | The page in **your** app that surfaces workspace invitations. Invitation emails deep-link to it, with a fixed `?workspaceInviteId=<id>` appended (any query string you already have on the URL is preserved). **Required before any invitation can be created** — see the warning below.                                                                                                                                                                                                                                                                                                    |
| `workspaces.inheritsDefault` | `boolean` | `false`  | The [`inheritsFromParent`](/data-models/workspace#reach-and-the-wall-door-rule) flag new workspaces are **born with**. `false` (the default) means every workspace starts **sealed** — no downward reach. Set it to `true` if your product wants an org's authority to flow into sub-workspaces by default. This is read at create time only; it is never accepted from client input — sending `inheritsFromParent` on [Create Workspace](/api-reference/workspaces/create-workspace) is a `400`, not a silent override — and changing it does not retroactively alter existing workspaces. |
| `workspaces.inheritEnforced` | `boolean` | `false`  | Locks `inheritsFromParent` to the project default so workspace **owners cannot flip it**. While `true`, [`useUpdateWorkspaceInheritFlag`](/hooks/workspaces/use-update-workspace-inherit-flag) fails with `403 workspace/inherit-enforced`. Use it when the wall/door policy is a product decision rather than a per-team one.                                                                                                                                                                                                                                                              |

<Warning>
  **Set `workspaces.inviteAcceptUrl` before you ship invitations.** It has no default, so a freshly added bundle has none — and an invitation is delivered as an email whose only call to action is that deep-link.

  Because of that, [Create Invite](/api-reference/workspaces/invitations/create-invite) and [Resend Invite](/api-reference/workspaces/invitations/resend-invite) **refuse outright** when it is unset, with `409 workspace/missing-invite-accept-url`. This applies **even when the invitee already has an account** — the in-app inbox is not a substitute for the emailed link, so the invite surface behaves the same for every invitee. Nothing is persisted and no email or webhook is emitted on the refusal; configure the setting and retry the identical request.
</Warning>

<Note>
  The accept link carries **nothing secret**. Acceptance is identity-matched — the signed-in caller must *be* the invitation's target and have a verified email — so there is no token to leak and no domain allowlist to maintain. The email is a plain nudge into your app. See the [acceptance model](/data-models/workspace-invitation#acceptance-model).
</Note>

## What a client app can do

**All 21 workspace endpoints are callable from a browser or mobile app with a normal signed-in user's bearer token** — including every management operation: editing a workspace, deleting it, transferring ownership, flipping the inherit flag, editing a member's capabilities/rank, removing a member, offboarding across a subtree, and the full invite lifecycle (create, list, revoke, resend). Every one of these is exposed as a `@sublay/core` hook and as a `@sublay/js` function. **A members-management panel needs no server-side code and no hand-rolled `fetch`.**

With a client token, every endpoint in the bundle resolves the actor from that token and authorizes the action against **that user's own standing** on the workspace. Most routes enforce this in guard middleware ahead of the controller; the self-scoped ones (create a workspace, list your own, leave, accept or decline an invite, read your own invites or your own authority) carry no guard middleware and authorize inside the controller instead. The one endpoint that does not require a token at all is the single-workspace read, [`GET /workspaces/:id`](/api-reference/workspaces/fetch-workspace) — it takes an *optional* token and returns the workspace when visibility permits. Everything else requires a signed-in user, and whether the call then succeeds depends on their standing:

| Rule                 | Meaning                                                                                                                                                                                                                                                                                                           |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Owner-only**       | The caller must be the workspace's own owner, or an owner of an ancestor workspace. Not a capability — no capability grants it.                                                                                                                                                                                   |
| **Capability-gated** | The caller's [resolved capability set](/hooks/workspaces/use-fetch-workspace-authority) (direct + reach + ownership) must contain the named capability, e.g. `invite`, `remove-member`, `edit-workspace`.                                                                                                         |
| **Rank-bounded**     | On top of a capability, the caller may only act on members ranked strictly below them, and may only grant capabilities/permissions they themselves hold ([no-escalation](/data-models/workspace-member#no-privilege-escalation)).                                                                                 |
| **Visibility**       | The caller must be able to see the workspace / its roster at all. This gates three reads — the single workspace, the roster, and one member's standing. **Any relation** to the workspace (owner, ancestor-owner, member, reach-holder) satisfies it. It does *not* gate the authority read (see the note below). |
| **Self-service**     | Anyone signed in can do it for themselves — accept/decline an invite addressed to them, leave a workspace, read their own authority.                                                                                                                                                                              |

<Note>
  **The authority read is the one read visibility does not gate.** [`GET /workspaces/:id/authority/me`](/api-reference/workspaces/fetch-authority) is mounted with authentication only — any signed-in user may call it for any workspace id. It returns `404` only when the workspace does not exist; a signed-in stranger gets `200` with `reasons: []` and empty `capabilities` / `permissions`, which is the correct "you have no standing here" answer for a UI gate. The consequence is that the route confirms a workspace *exists* to any signed-in user.

  Its sibling read, one member's standing ([`GET /workspaces/:id/members/:userId`](/api-reference/workspaces/members/fetch-member-standing)), *is* visibility-gated and deliberately `404`s instead, so it never leaks existence. Do not assume the two behave alike.
</Note>

<Warning>
  **Seeing the roster and seeing people's *authority* are two different tiers.** Any relation may read the roster and one member's standing — who is there, their `reasons`, `title` and `metadata`. But the authority-bearing fields — **`capabilities`, `permissions`, `rank`, `relativeRank`** — are **omitted** (absent, not `null`) unless the caller holds one of the four people-operating capabilities (`invite`, `remove-member`, `edit-member-access`, `edit-member-profile`) or is the `owner` / an `ancestor-owner`.

  A caller **always** sees their own — their own roster row, their own standing, and the [authority read](/api-reference/workspaces/fetch-authority), which is inherently a self read and never fenced. So a plain member can always discover their own access; they just cannot enumerate everyone else's. A service/master key acting as **itself** is never fenced; one that **names** an `actingUserId` is fenced exactly as that user is — see [Acting on behalf of a user](#acting-on-behalf-of-a-user). Type all four fields as optional on client surfaces. (`relativeRank` is fenced *with* `rank` because it is `rank` minus a number the caller already knows — leaking it would leak `rank` exactly.)

  **The gate is answered per node, not once per request.** Every row a response returns is judged against your **resolved** standing on the workspace *that row belongs to* — including capabilities [reaching](/data-models/workspace#reach-and-the-wall-door-rule) in through an unbroken open inherit chain, and ownership from any ancestor, but not authority a **sealed** node blocks. The place this bites is [`include=descendants`](/api-reference/workspaces/members/list-members) on the roster: a `descendant-member` row is judged on its own node, so holding `invite` on a parent does not unfence a sealed child's ranks and capabilities. Being allowed to *see* a descendant's roster (sealing) and being allowed to see its members' **authority** (the fence) are two tiers, and passing the first does not pass the second.
</Warning>

<Note>
  **What actually needs a service key: acting on behalf of a *different* user.** Nearly every endpoint accepts an actor field, `actingUserId`, so a service/master key can perform an action *as* some named user. That parameter is **[node SDK](/node-sdk/workspaces) only** — `@sublay/core` and `@sublay/js` never expose it, because a client's actor is always the token's own user. (There is no client-side strip: a call that hand-writes `actingUserId` past the types is bound by the same rule as any user token — naming a user other than the token's own is rejected with a `403`.) This is the *only* difference in reach between the client SDKs and the node SDK for this bundle; it is **not** a restriction on which operations a client may perform. The rule that governs it is [below](#acting-on-behalf-of-a-user).

  Note that a **target**-identifying `userId` is a different thing and is fully available on the client: the invitee `userId` on [`useCreateWorkspaceInvite`](/hooks/workspaces/use-create-workspace-invite), and the `targetUserId` path param on the member hooks.
</Note>

## Acting on behalf of a user

One rule governs every workspace endpoint, with no exceptions:

<Info>
  **If a request acts as Bob, then for all intents and purposes it *is* Bob.** Reads and writes alike. The credential decides only *whether* you may name someone other than yourself — never how much authority you get once you have.
</Info>

A service or master key therefore has exactly two modes:

| Mode               | Wire shape               | Authority                                                                                                                         |
| ------------------ | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| **The app itself** | the field is **absent**  | Unbounded — where the route has an unbounded path at all. Every capability, owner-only and rank check is skipped.                 |
| **A named user**   | `actingUserId: "<uuid>"` | Exactly that user's. Their capabilities, their rank, their visibility, their fencing — the same answer their own token would get. |

<Warning>
  **"The app itself" means the field is *absent*, not falsy.** `actingUserId: ""` and `actingUserId: null` are a caller *attempting* to name someone, and they are a `400`, never a fall-through to the unbounded mode. So `actingUserId: user?.id ?? ""` — the shape a backend reaches for naturally — fails loudly instead of quietly acquiring full authority. That is the point: a request that believed it was binding to a user must never be promoted to the app itself. Only omitting the key entirely (or sending `undefined`, which is indistinguishable from omission) selects that mode. See [Shapes the server rejects](#shapes-the-server-rejects).
</Warning>

A plain user token has only one mode: itself. Sending your **own** user id is a harmless no-op — the resolved actor is the same either way — but naming **anyone else** is a `403 workspace/unauthorized`. The field is never silently ignored for a user token.

Naming an acting user is not a hint or an audit field. It **binds**: if the named user would be refused, so are you. That covers the capability gate, the owner-only gate, the rank guard, [no-escalation](/data-models/workspace-member#no-privilege-escalation), roster/standing [fencing](#what-a-client-app-can-do), and the visibility `404` on a workspace the named user has no relation to.

### The unrestricted path names a user

Backends that need to do something a normal member could not — reset a team, seed an org, repair a bad grant — should act **as the workspace owner**, not as nobody:

```typescript theme={null}
// ✅ Unrestricted, and carried out under a named user id.
await sublay.workspaces.updateWorkspaceMember({
  workspaceId,
  targetUserId,
  rank: 0,
  actingUserId: workspace.ownerId,
});
```

The owner resolves the full capability vocabulary and apex rank, so nothing is out of reach, and the resulting webhooks carry that user id rather than nothing.

<Warning>
  **This is naming, not authentication.** A service key may name *any* UUID, and the server does not verify that it belongs to a live account — it only checks whether the id matches the workspace's `ownerId` (or a membership row). Two consequences:

  * The user id on a webhook tells you what the caller **claimed**, with the same trust level as the key itself. It is not evidence a person acted.
  * `ownerId` is a plain column, not a foreign key — deliberately, so deleting a user cannot cascade away every workspace they own. So acting as the id of a **deleted** owner still resolves full owner authority. If your product deletes accounts, transfer ownership as part of that teardown; do not rely on the id going stale to revoke anything.

  If you need attribution you can actually trust, record it in your own system at the point you decide to make the call.
</Warning>

On roughly half the bundle the actor is **required**, so acting-as-a-user is not merely the good practice — it is the only path, and omitting `actingUserId` is a `400 workspace/missing-user-id` rather than a bypass. Those routes are the ones whose result *belongs to* a specific person: creating a workspace, listing your workspaces or your invites, reading your own authority, accepting or declining an invite, leaving, and the three member-management writes (`updateWorkspaceMember`, `removeWorkspaceMember`, `removeWorkspaceMemberFromSubtree`).

The unbounded path survives on the rest — the guard-only routes (`updateWorkspace`, `updateWorkspaceInheritFlag`, `deleteWorkspace`, `transferWorkspaceOwnership`, the invite outbox reads and `revoke`/`resend`), the three reads, and `createWorkspaceInvite`.

<Note>
  **The [node SDK](/node-sdk/workspaces) types are stricter than the wire on four of those routes.** `updateWorkspace`, `updateWorkspaceInheritFlag`, `deleteWorkspace` and `transferWorkspaceOwnership` accept an omitted actor over REST — that request runs as the app itself — but the node SDK declares `actingUserId` **required** on all four, so TypeScript will not let you omit it. That is a deliberate guardrail on the four most destructive owner-only calls, not a different server rule. Reach the unbounded path on them by calling the REST endpoint directly.
</Note>

### Shapes the server rejects

Eight request shapes are refused outright rather than ignored, all of them `400`s. Seven carry `workspace/invalid-body` or `workspace/invalid-query`, depending on which side of the request the offending field sat on; the eighth is a malformed path parameter, which carries `workspace/invalid-params`.

They come from **two layers**, and knowing which one answered tells you what to fix:

1. **A gate**, mounted ahead of every route on the bundle. It reads the raw request, so it behaves identically whichever endpoint you call and whatever that route declares.
2. **Each route's own body and query schemas.** All 21 routes validate *both* sides, and every schema declares exactly the fields its endpoint accepts. A top-level field it does not declare is refused, not stripped. On the query side one check runs ahead of the schema and reads the raw query string rather than the parsed one — the length limit below — so it too behaves identically on every route.

<AccordionGroup>
  <Accordion title="A body or query `userId` — 400">
    ```json theme={null}
    {
      "error": "`userId` is not the acting user on workspace routes — it addresses the target. Use `actingUserId` to act on behalf of a user.",
      "code": "workspace/invalid-body"
    }
    ```

    On a workspace route `userId` **never** names the caller — it addresses the request *target*. The rejection is unconditional: it fires for user tokens and keys alike, on every route, and even when a correct `actingUserId` is also present, because a request carrying both is malformed regardless. It is checked at the gate, on the raw request, ahead of any route's own schema.

    **One exception:** the invitee `userId` in the **body** of [Create Invite](/api-reference/workspaces/invitations/create-invite), where the field has always meant the target. The carve-out covers that body field and nothing else — a query `?userId=` is refused on Create Invite exactly as it is everywhere else, because no workspace route reads one, so there it can only be the stale actor spelling. The path parameter `:userId` (on the member routes) is untouched — that is the target too.
  </Accordion>

  <Accordion title="An empty or null `actingUserId` — 400">
    ```json theme={null}
    { "error": "Invalid actingUserId.", "code": "workspace/invalid-body" }
    ```

    The actor is read by **presence**, not truthiness. `""`, `null` and a non-UUID string are all a caller *attempting* to name someone, and they fail here rather than falling through to the unbounded mode. On a route with no capability guard the rejection comes from the schema instead and reads `actingUserId: Invalid UUID format` — same status, same code, same outcome.

    This is the trap behind `actingUserId: user?.id ?? ""`. A backend writing that believes it is binding the call to a user; if the empty string read as "named nobody" it would instead receive full owner authority on routes including `DELETE /workspaces/:id`. Only an absent key (or `undefined`, which is indistinguishable from omission) selects the app-itself mode.
  </Accordion>

  <Accordion title="A near-miss spelling of `actingUserId` — 400">
    ```json theme={null}
    {
      "error": "`actingUserID` is not a recognized field — did you mean `actingUserId`? A misspelled acting user names nobody, which would run this request unbound instead of on that user's behalf.",
      "code": "workspace/invalid-body"
    }
    ```

    A key that differs from `actingUserId` only in capitalization — `actingUserID`, `ActingUserId`, `actinguserid` — gets this precise message rather than the generic one below. It fires on **every** request, user tokens included, where a typo cannot escalate anything but still means your stated intent was silently dropped.

    This is message quality, not a second line of defence: any other misspelling (`acting_user_id`, `actingUseId`, `ACTING-USER-ID`) is refused too, one accordion down, as a field the endpoint does not declare.
  </Accordion>

  <Accordion title="Any field the endpoint does not declare — 400">
    ```json theme={null}
    { "error": "Unrecognized key: \"onBehalfOf\"", "code": "workspace/invalid-body" }
    ```

    Every workspaces endpoint declares its fields exactly and refuses a top-level field it does not declare, in the body and in the query string alike, for every caller. Two or more at once are named together — `Unrecognized keys: "onBehalfOf", "impersonate"` — and an offender in the query string carries `workspace/invalid-query`.

    That is a categorical rule, not a list of bad names. `onBehalfOf`, `impersonate`, `acting_user_id`, `ACTING-USER-ID`, `actingUserId ` with a trailing space, `requestId`, `traceId`, `sort` — none of them is a field of any workspaces route, so all of them fail at the wire, whatever they carry. The rule is the same for a service key and for a signed-in user: a request the API cannot fully read is answered rather than half-honored.

    Two consequences worth designing around:

    * **Send only the documented fields.** The SDKs pass your props object to the request body as-is, so `createWorkspace({ ...orgTemplate })` carries every extra key `orgTemplate` holds into the request and fails. Name the fields you mean; put your own data in `metadata`, which is opaque to Sublay and accepts any JSON.
    * **A field this API declares is never judged by its name.** `username` on [Create Invite](/api-reference/workspaces/invitations/create-invite), `newOwnerId` on [Transfer Ownership](/api-reference/workspaces/transfer-ownership), `userId` as an invitee — all real fields, all accepted on their own terms.

    Two query parameters are the exception: `_` and `_t`, the automatic cache-busters some HTTP clients append, are dropped before the request is read. Nothing else is reserved — in particular tracing and correlation identifiers are *not*, because distributed tracing propagates in HTTP **headers** (`traceparent`, `X-B3-*`, `X-Amzn-Trace-Id`), never in the query string.
  </Accordion>

  <Accordion title="A query string with 1,000 or more parameters — 400">
    ```json theme={null}
    {
      "error": "Too many query parameters: 1000 `&`-separated segments, and the limit is 999. The query parser silently discards everything past 1000 of them — including `actingUserId`, which would run this request unbound instead of on that user's behalf. Empty segments and unparseable ones count too.",
      "code": "workspace/invalid-query"
    }
    ```

    A workspaces request whose raw query string holds **1,000 or more `&`-separated segments** is refused before anything else about it is examined. The most any workspaces request may carry is 999; the largest query vocabulary on the bundle is five parameters, so no real call comes near it.

    **This is a rule about the query string's length, not about which names are in it.** The parser's budget is spent per `&`-separated segment, and a segment that parses to nothing spends it just the same — so 1,000 bare ampersands (`?&&&…`), 1,000 copies of `__proto__=1` (a name the parser discards on sight, leaving no key behind), and 1,000 copies of an ordinary *declared* parameter such as `include=` all reach the limit identically and are all refused identically. Which names you used has nothing to do with it, and neither does whether any of them is reserved.

    What makes the limit worth a rule is that the parser truncates **silently**: past the budget, everything beyond it is discarded with no error and no trace, and `actingUserId` goes with it. On this bundle a request naming no acting user is the app itself, so a silently dropped actor is a request that runs unbounded while its caller believes it was scoped to one person. Counting segments on the raw URL is the only rule that can close that — how many segments you sent is not a property of any field name, and after truncation there is nothing left in the parsed request for a schema or an allowlist to inspect.
  </Accordion>

  <Accordion title="A repeated or nested `_` / `_t` — 400">
    ```json theme={null}
    {
      "error": "`_` must be a single value. Repeating it (or nesting it) can push other query parameters past the parser's limit, silently discarding them — including `actingUserId`, which would run this request unbound instead of on that user's behalf.",
      "code": "workspace/invalid-query"
    }
    ```

    The two cache-busters are stripped before the strict schema runs, so no schema ever sees the shape they arrived in — this rule is what stands in for one on those two names. Each must arrive exactly once, as a scalar: `?_=1699000000` passes, `?_=1&_=2` (an array) and `?_[a]=1` (an object) do not. Repeating a *declared* parameter needs no rule of its own: its schema expects a single value, receives an array, and refuses it.

    This is a rule about the **shape** those two names arrive in, and it is not what keeps a long query string from losing `actingUserId` — a query string long enough to be truncated is refused by the length limit above, whatever names it uses, and that check runs first.
  </Accordion>

  <Accordion title="A body no parser read, when the request names nobody — 400">
    ```json theme={null}
    {
      "error": "This request carries a body with content-type \"text/plain;charset=UTF-8\", which no parser reads, so any `actingUserId` inside it was discarded and this request names no acting user. Send the body as application/json.",
      "code": "workspace/invalid-body"
    }
    ```

    Sublay parses `application/json` and nothing else. A body sent as `text/plain`, `application/x-www-form-urlencoded` or `application/vnd.api+json` is read off the wire and thrown away — so an `actingUserId` inside it never reaches the server, and the request names nobody through no fault of its spelling. This is the one shape the schemas cannot catch: with an unparsed content-type the server is handed an empty body, which has no unrecognized key in it.

    **This is the `fetch()` default.** `fetch(url, { method: "DELETE", body: JSON.stringify({ actingUserId }) })` with no `headers` sends `text/plain;charset=UTF-8`. Set `"Content-Type": "application/json"`. Client libraries that set it for you — axios, the Sublay [node SDK](/node-sdk/workspaces), [`@sublay/js`](/js-sdk/workspaces) — never hit this.

    Detected by **media type**, not by "is the body empty": a legitimate `{}` sent as JSON is indistinguishable from a discarded body after the fact, so an empty JSON body and a bodiless request both pass.
  </Accordion>

  <Accordion title="A path parameter that is not a UUID — 400">
    ```json theme={null}
    { "error": "Invalid workspace id: expected a UUID.", "code": "workspace/invalid-params" }
    ```

    Every `:id`, `:workspaceId`, `:userId` and `:inviteId` on the bundle is checked for UUID shape before the route runs, so a malformed one is a plain `400` rather than a `500` echoing driver internals. The message names which parameter — *workspace id*, *user id*, *invitation id*.

    On `DELETE /workspaces/:id/members/me` the `me` segment is a literal rather than a `:userId`, so it is never UUID-checked — the `:id` still is.
  </Accordion>
</AccordionGroup>

<Note>
  **Why this bundle is stricter than the rest of the API.** Elsewhere in Sublay an undeclared field is dropped and the request proceeds. Here it is refused, and the reason is what an unreadable field can *mean* on this bundle.

  A service/master key that names **no** acting user runs unbounded, with owner authority over a whole workspace hierarchy. So absence-of-actor is not a neutral state — it is the signal that grants full authority. A caller who writes `onBehalfOf: "<bob>"`, or `acting_user_id`, or spells the field correctly inside a body no parser read, believes the request is scoped to Bob; under a permissive rule it would instead receive the app's full authority, silently, in production, on routes that cascade-delete a subtree.

  Guessing which stray fields "look like" an actor cannot work: an open input space can always be shown a name nobody enumerated, and every miss lands on the unbounded path. Refusing categorically fails the other way — a field we forgot to declare is a `400` on first use, in development, fixed the same day.
</Note>

<Note>
  **The guarantee covers TOP-LEVEL keys.** State it with that scope rather than as "unknown fields are impossible":

  * `metadata` is caller-owned JSON and is never inspected, so `{"metadata":{"actingUserId":"<bob>"}}` parses, names nobody, and runs as the app. That is correct — `metadata` is your data — but it is not an actor channel.
  * A nested or wrapped actor is **refused**, not ignored — the wrapper itself is an undeclared top-level key: `{ data: { actingUserId } }` and `?ctx[actingUserId]=` both come back `400 Unrecognized key: "data"` / `"ctx"`, and an array-wrapped body is `400 Invalid input: expected object, received array`. (Don't confuse this with the node SDK's `{ data: { actingUserId } }` axios *config* for DELETE bodies — that sends `{ actingUserId }` as the body and works.)

  What makes that safe is not the field rules but the gate itself — no request reaches the unbounded path without clearing it. Spell `actingUserId` at the top level and none of this applies.
</Note>

<Note>
  **The content-type rule is the one asymmetric check — deliberately.** It applies **only** when a service/master key named nobody. Under a user token, or a key that **did** name an actor, a `text/plain` body is merely an empty one, exactly as on every other bundle.

  The reason is what a *dropped* body could mean on each path. Under a token the actor comes from the token no matter what you send, so nothing lost in transit can change who is acting — there is no authority to gain. Under a key naming nobody, a body the server could not read is exactly the shape of an actor it failed to receive: one missing header, and a request the caller believed was bound to one person runs as the app.

  Everything else on this page — the `userId` rejection, the undeclared-field rule, the cache-buster rule — applies uniformly to every caller.
</Note>

<Note>
  **Don't confuse these `400`s with the missing-actor `400`.** Two different failures, two different codes, checked in a fixed order.

  * `workspace/invalid-body` / `workspace/invalid-query` — **the request is malformed.** It carries a `userId`, a field the endpoint does not declare, an unreadable body, or a bad `actingUserId`. Checked **first**, before the route runs.
  * `workspace/missing-user-id` — **the route's own rule.** On the ten routes whose actor is [required](#acting-on-behalf-of-a-user) a key must name someone, and there is no unbounded path to fall back on. Nothing about the request's shape is wrong; it is simply an operation that has to belong to a person.

  On `POST /workspaces` a key with no `actingUserId` and a clean request gets `workspace/missing-user-id` — but the same call carrying an undeclared field, or sent with a `text/plain` body, gets `workspace/invalid-body` instead. Fix what the message names; the missing-actor error appears once the request is otherwise well formed.

  Read the code, not the status: both are `400`, and only the code tells you whether to add an actor or repair the request.
</Note>

<Note>
  **A request that never reaches the gate cannot be unbounded either.** Unbounded authority is *earned* by clearing the gate, not inferred from an absent field. If some future route, router or ordering mistake ever skipped it, the request would fall through to "no actor, no privilege" — a `400` or `403` — rather than silently to app-level authority. The practical guarantee for you: a malformed workspaces request fails loudly, never with more authority than you intended.
</Note>

### Consequence: accepting an invite on someone's behalf

[`acceptWorkspaceInvite`](/api-reference/workspaces/invitations/accept-invite) is bound like everything else, so a backend auto-join flow must satisfy the invitee's own gates:

* the invitation must be **actually addressed to** the named user (by `userId`, or by an email that matches their account) — accepting Alice's invite while naming Bob is a `404 workspace/invite-not-found`;
* the named user's **email must be verified** — otherwise `403 workspace/email-not-verified`.

The same two gates apply to [`declineWorkspaceInvite`](/api-reference/workspaces/invitations/decline-invite). There is no key bypass for either: ownership and membership have exactly three doors (create, accept an invite, receive a transfer) and all three enforce verification identically.

### Consequence: a tier cannot grow itself

Rank is strict — you may only act on, and invite at, a rank **strictly below** your own (smaller number = more senior). So a rank-5 manager can mint rank 6, 7, 8… but **not another rank 5**. Minting a peer requires someone *above* that tier:

| To create…                           | Act as…                                           |
| ------------------------------------ | ------------------------------------------------- |
| a rank-6 member, as a rank-5 manager | that manager (`actingUserId: manager.id`)         |
| **another rank-5 manager**           | someone ranked 0–4, or the owner                  |
| **a rank-0 member**                  | the **owner** — no ranked member clears the floor |

This is not new behavior, but it is easy to hit for the first time when a backend stops running as an implicit owner. If your "add a manager" button is server-driven, act as the owner for it. The floor applies only to an actor with a **direct member row** on the workspace, so it is skipped for an owner or ancestor owner, and for a cross-node [reach](/data-models/workspace#reach-and-the-wall-door-rule) holder with no direct row.

<Note>
  **"A key naming nobody" skips the floor on [Create Invite](/api-reference/workspaces/invitations/create-invite) — and nowhere else.** Invite is the one rank-assigning route with an unbounded path left, so a key that names no inviter genuinely faces no floor there. [Update Member](/api-reference/workspaces/members/update-member) has **no** unbounded path: its actor is required, so a key naming nobody is a `400 workspace/missing-user-id` rather than an exemption. On that route a key is always somebody, and faces exactly that somebody's floors.
</Note>

## Choosing a rank

Almost every rule the ladder enforces is **relative** — act only on someone strictly below you, assign only strictly below yourself (minting rank 0 is the one absolute exception, below) — so rank can be named in either coordinate, on [Create Invite](/api-reference/workspaces/invitations/create-invite) and [Update Member](/api-reference/workspaces/members/update-member) alike:

```tsx theme={null}
const createWorkspaceInvite = useCreateWorkspaceInvite();

// Relative — "one rung below me". Usually what you mean.
await createWorkspaceInvite({ workspaceId, email, relativeRank: 1 });

// Absolute — a specific position on the ladder.
await createWorkspaceInvite({ workspaceId, email, rank: 10 });
```

The same two fields exist on the `@sublay/js` and `@sublay/node` equivalents — this is a server-side rule, not a hook convenience.

The two are **mutually exclusive**: sending both is a `400`. Storage stays absolute — a relative offset is resolved to a number at write time and the member row holds that number.

Reads return **both**. The roster and member-standing reads each carry `rank` (absolute) alongside `relativeRank` (that member's position as an offset from *you*, where `-3` means "three rungs above you"). So there is no "write 2, read 5" asymmetry to reconcile — you can read back in the same coordinate you wrote in. The authority read carries `rank` only: its subject is *you*, so an offset from yourself could only ever be `0`.

<Info>
  **`relativeRank: 1` is the happy path, and the invite default.** Omit *both* rank fields on an invite and the server applies `relativeRank: 1` — one rung below the inviter. That is well defined for every actor (an inviter with no member row here anchors at apex, so their default lands on rank 0) and, by construction, it can never fail the rank floor. There is no equivalent default on [Update Member](/api-reference/workspaces/members/update-member): omitting both there means **rank unchanged**, so editing someone's capabilities never quietly moves them on the ladder.
</Info>

### The anchor is your member row, not your job title

An offset is measured from **your own rank on this workspace if you hold a member row here**, and from **apex** (one step above rank 0) if you do not.

Owners, ancestor owners, reach holders and keys acting as themselves normally have no row on the node in question, so they normally anchor at apex — but that is a coincidence of the common case, not the rule. An ancestor owner who *also* sits in this node's roster measures from that row: Alice owns `root` and is rank 3 on `child`, so on `child` her `relativeRank: 1` resolves to rank **4**, and she reads `child`'s rank-0 member back as `-3`. See [rank semantics](/data-models/workspace-member#the-anchor-your-member-row-not-what-kind-of-actor-you-are).

One consequence worth knowing: because an in-ladder anchor is `>= 0` and a write offset is `>= 1`, **a direct member can never mint rank 0 through the relative form** — the arithmetic simply cannot reach it. The absolute form does not need a special case either. Naming `rank: 0` outright is refused by the ordinary **assign rule**, which requires a strictly larger number than your own: an actor with a member row here is at rank `>= 0`, and nothing is strictly below `0`. They get `403 workspace/insufficient-rank` — *"You may only set ranks strictly below your own."* on [Update Member](/api-reference/workspaces/members/update-member), or *"You may only invite at a rank strictly below your own."* on [Create Invite](/api-reference/workspaces/invitations/create-invite).

There is **no separate "only the owner may assign rank 0" check** — owners are the only minters of rank 0 because they skip the rank block entirely, not because a guard names them. So rank 0 is reachable by the owner, and by any actor with **no member row on this workspace** — an ancestor owner or a [reach](/data-models/workspace#reach-and-the-wall-door-rule) holder — who skips or clears the same floor and, from `relativeRank: 1`, anchors at apex and lands on 0. On [Create Invite](/api-reference/workspaces/invitations/create-invite) only, a **key naming nobody** joins that list; on [Update Member](/api-reference/workspaces/members/update-member) it cannot, because the actor is required there (see the note [above](#consequence-a-tier-cannot-grow-itself)).

<Warning>
  **A relative offset is a snapshot, not a live link.** It is resolved once, at write time, and frozen as an absolute number. Invite at `relativeRank: 1` while you are rank 1 and they land on rank 2 — get promoted to rank 0 later and they are still 2, now two rungs below you rather than one. Nothing re-derives.

  (`relativeRank` on a **read** is the opposite: recomputed per request against whoever is asking, so the same member shows a different `relativeRank` to different callers. Only `rank` is caller-independent.)
</Warning>

<Warning>
  **Omitting the rank field is the easiest way in the whole API to mint rank 0.** "One rung below me" is measured from your anchor, and an inviter with **no member row on this workspace** anchors at apex — so for an **owner**, an **ancestor owner**, a **reach holder** with no direct row, or a **service/master key acting as itself**, the default lands on **rank 0**, the most senior rung there is. Everything else in this bundle gates that rung carefully; the default reaches it by leaving a field off.

  It is semantically correct — one below apex *is* the top rung — and it is not changing. But it inverts the usual instinct that omitting a field is the conservative choice. The case to watch is a **backend invite flow**: a server route that invites people with a service key and no rank field creates a workspace of rank-0 members, each able to manage all the others and none manageable by anyone but the owner. A service-key flow that wants new members at the **bottom** of the ladder has to name a coordinate — an absolute `rank`, or a `relativeRank` anchored on an `actingUserId` who actually sits in the ladder.

  **The milder version applies to in-ladder inviters.** A lead at rank 0 who invites six people with no rank field gets six rank-1 members — and equals cannot act on equals, so none of those six can manage each other. Only the lead can manage any of them. That is often exactly right for a flat team. But if your product has tiers, say so on the invite instead of discovering the flat layer later.
</Warning>

### When you want absolute instead

`rank` is the escape hatch, and it is the right call whenever the number means something in your product rather than something about the caller. It buys more freedom and costs more care: naming a rank you are not entitled to grant is a `403 workspace/insufficient-rank`, and `rank: 0` is simply the extreme case of that — no one holding a row on this workspace can name it. A relative offset clears the **rank floor** by construction — but that is the floor specifically, not a blanket exemption from the rank checks.

One pattern some apps like — **not** the prescribed approach, just one that works — is a set of named tier constants with gaps left for later:

```tsx theme={null}
const TIER = { ADMIN: 0, MANAGER: 10, STAFF: 20 } as const;

await createWorkspaceInvite({ workspaceId, email, rank: TIER.MANAGER });
```

Apps built this way will naturally prefer absolute input — they already know the number they want, and computing `TIER.MANAGER - myRank` just to send it relatively would be a detour. That is precisely why absolute stays. Apps whose hierarchy is a real chain of command, where "under me" is the actual intent, are better served by `relativeRank`. Neither is deprecated.

## Quick start

```tsx theme={null}
import {
  useCreateWorkspace,
  useCreateWorkspaceInvite,
  useFetchMyWorkspaceInvites,
  useAcceptWorkspaceInvite,
} from "@sublay/react-js";

function CreateTeam() {
  const createWorkspace = useCreateWorkspace();

  async function onCreate() {
    const workspace = await createWorkspace({ name: "Acme Inc" });
    console.log("owner:", workspace.ownerId);
  }

  return <button onClick={onCreate}>Create workspace</button>;
}
```

## Hooks

### Workspace lifecycle & ownership

| Hook                                                                                   | Purpose                                   | Authorization                                                        |
| -------------------------------------------------------------------------------------- | ----------------------------------------- | -------------------------------------------------------------------- |
| [`useCreateWorkspace`](/hooks/workspaces/use-create-workspace)                         | Create a root or child workspace          | Verified email (root) / `create-sub-workspace` on the parent (child) |
| [`useFetchWorkspace`](/hooks/workspaces/use-fetch-workspace)                           | Read a single workspace                   | Visibility                                                           |
| [`useFetchManyWorkspaces`](/hooks/workspaces/use-fetch-many-workspaces)                | Leaf fetcher for the caller's workspaces  | Self-service                                                         |
| [`useFetchManyWorkspacesWrapper`](/hooks/workspaces/use-fetch-many-workspaces-wrapper) | Paginated list with load-more             | Self-service                                                         |
| [`useUpdateWorkspace`](/hooks/workspaces/use-update-workspace)                         | Edit name / metadata                      | `edit-workspace` (or owner)                                          |
| [`useUpdateWorkspaceInheritFlag`](/hooks/workspaces/use-update-workspace-inherit-flag) | Flip `inheritsFromParent`                 | Owner-only                                                           |
| [`useDeleteWorkspace`](/hooks/workspaces/use-delete-workspace)                         | Delete a workspace (cascades the subtree) | Owner-only                                                           |
| [`useTransferWorkspaceOwnership`](/hooks/workspaces/use-transfer-workspace-ownership)  | Hand the workspace to a new owner         | Owner-only                                                           |

### Membership

| Hook                                                                                                | Purpose                            | Authorization                                               |
| --------------------------------------------------------------------------------------------------- | ---------------------------------- | ----------------------------------------------------------- |
| [`useFetchWorkspaceMembers`](/hooks/workspaces/use-fetch-workspace-members)                         | The unified roster read            | Visibility                                                  |
| [`useFetchWorkspaceMemberStanding`](/hooks/workspaces/use-fetch-workspace-member-standing)          | One user's resolved standing       | Visibility                                                  |
| [`useUpdateWorkspaceMember`](/hooks/workspaces/use-update-workspace-member)                         | Edit a member's access / profile   | `edit-member-access` or `edit-member-profile`, rank-bounded |
| [`useRemoveWorkspaceMember`](/hooks/workspaces/use-remove-workspace-member)                         | Remove a member from this node     | `remove-member`, rank-bounded                               |
| [`useRemoveWorkspaceMemberFromSubtree`](/hooks/workspaces/use-remove-workspace-member-from-subtree) | Offboard a user across the subtree | `remove-member`, rank-bounded per node                      |
| [`useLeaveWorkspace`](/hooks/workspaces/use-leave-workspace)                                        | Leave a workspace yourself         | Self-service                                                |

### Invitations

| Hook                                                                             | Purpose                                      | Authorization                             |
| -------------------------------------------------------------------------------- | -------------------------------------------- | ----------------------------------------- |
| [`useCreateWorkspaceInvite`](/hooks/workspaces/use-create-workspace-invite)      | Create an invitation                         | `invite` (or owner), rank + no-escalation |
| [`useFetchWorkspaceInvites`](/hooks/workspaces/use-fetch-workspace-invites)      | **Outbox** — invites *this workspace issued* | `invite` (or owner)                       |
| [`useRevokeWorkspaceInvite`](/hooks/workspaces/use-revoke-workspace-invite)      | Revoke a pending invitation                  | `invite` (or owner)                       |
| [`useResendWorkspaceInvite`](/hooks/workspaces/use-resend-workspace-invite)      | Refresh + resend a pending invitation        | `invite` (or owner)                       |
| [`useFetchMyWorkspaceInvites`](/hooks/workspaces/use-fetch-my-workspace-invites) | **Inbox** — invites *addressed to me*        | Self-service                              |
| [`useAcceptWorkspaceInvite`](/hooks/workspaces/use-accept-workspace-invite)      | Accept an invitation                         | Self-service + verified email             |
| [`useDeclineWorkspaceInvite`](/hooks/workspaces/use-decline-workspace-invite)    | Decline an invitation                        | Self-service + verified email             |

<Warning>
  [`useFetchWorkspaceInvites`](/hooks/workspaces/use-fetch-workspace-invites) and [`useFetchMyWorkspaceInvites`](/hooks/workspaces/use-fetch-my-workspace-invites) are the two most confusable hooks in this bundle. The first is the **outbox** of one workspace (`GET /workspaces/:id/invites`) — who *this team* has invited and not yet heard back from; it powers the "Pending invitations" section of a members panel. The second is the signed-in user's **inbox** (`GET /me/workspace-invites`) across every workspace — it powers a "You've been invited" list.
</Warning>

### Authority

| Hook                                                                            | Purpose                             | Authorization |
| ------------------------------------------------------------------------------- | ----------------------------------- | ------------- |
| [`useFetchWorkspaceAuthority`](/hooks/workspaces/use-fetch-workspace-authority) | Resolve the current user's standing | Self-service  |

<Tip>
  Drive your UI off [`useFetchWorkspaceAuthority`](/hooks/workspaces/use-fetch-workspace-authority) rather than guessing: it returns `{ reasons, capabilities, permissions, rank }`, so showing the "Remove member" button is `authority.capabilities.includes("remove-member")`. `reasons` are structured `{ type, viaWorkspaceId? }` entries — the same shape a roster entry carries — so you can also show *which* ancestor grants an inherited standing. And because **`view` is implied by every other capability**, `capabilities.includes("view")` doubles as "does this user have any standing here at all".
</Tip>


# Webhooks & lifecycle
Source: https://docs.sublay.io/v7/sdk/workspaces/webhooks

The workspace webhook event catalog, the member.* vs invite.* streams, and uninstall behavior

The Workspaces bundle emits webhooks across the invitation lifecycle, on workspace deletion, and on any roster change — so you can keep your own seat/roster mirror and workspace-tagged data in sync. Events use the existing [webhook mechanism](/sdk/app-notifications/webhook-integration): HMAC-SHA256 signed, subscription-gated by the events you enable in the dashboard, fire-and-forget (no retry).

## Event catalog

There are exactly **7** events:

| Event                       | Fires when                                                                                          |
| --------------------------- | --------------------------------------------------------------------------------------------------- |
| `workspace.invite.created`  | An invitation is created.                                                                           |
| `workspace.invite.accepted` | An invitation is accepted.                                                                          |
| `workspace.invite.declined` | An invitation is declined.                                                                          |
| `workspace.invite.revoked`  | An invitation is revoked.                                                                           |
| `workspace.deleted`         | A workspace is deleted (one per workspace actually deleted, including each node in a cascade).      |
| `workspace.member.added`    | A membership **row** is created.                                                                    |
| `workspace.member.removed`  | A membership **row** is removed by a *targeted* action — **not** by a workspace delete (see below). |

<Note>
  **There is no `workspace.invite.expired` event.** Expiry is lazy — a stale invite simply won't accept; there is no background sweep and thus no moment to fire it. Capability-change events are deliberately deferred, and **resend** emits no event (the status stays `pending` — no lifecycle transition).
</Note>

## `member.*` vs `invite.*` — two intentionally distinct streams

`invite.*` tracks the **invitation lifecycle**; `member.*` tracks **roster sync** — any membership row appearing or disappearing. **They are NOT redundant, and both are kept.**

* **On accept, BOTH fire:** `workspace.invite.accepted` (lifecycle) **and** `workspace.member.added` (roster). Dedupe on the ids in the payload if you consume both.
* **`member.*` also covers non-invite roster changes** that have **no** invite event:
  * `member.removed` fires on exactly five paths: a **leave**, a **remove**, a **remove-from-subtree** sweep, **user-deletion cleanup**, and when a user *becomes owner* and their existing member row is dropped (owner/member rows are disjoint).
  * `member.added` fires on the **transfer-demote** case (a previous owner demoted into a fresh member row).

So if you dropped `member.*` in favor of `invite.*`, you would lose every targeted removal transition (leaves, removals, offboarding) — which is why `member.*` is the stream to mirror your live seat/roster set.

## Deleting a workspace does NOT emit per-member events

<Warning>
  **`DELETE /workspaces/:id` emits `workspace.deleted` once per node in the cascade, and nothing per membership row.** There is no `workspace.member.removed` for the memberships it tears down — not for the deleted workspace, and not for any descendant.

  Treat **`workspace.deleted` as removing that workspace's entire roster**: on receiving it, drop every seat you hold for that workspace id wholesale. Because the cascade fires one `workspace.deleted` per node, doing this for each event you receive clears the whole subtree.
</Warning>

This is deliberate. A workspace delete tears down *every* membership in the subtree at once, so a 500-member tree would fan out 500+ POSTs in a single burst against a delivery layer with **no retry and no batching** — and every one of them would be redundant with the `workspace.deleted` that accompanies it. The five paths that *do* fire `member.removed` are all bounded, targeted removals where the row is the only thing that changed and no other event would tell you about it.

Note the asymmetry with **user-deletion cleanup**: deleting a *user* does still fire `member.removed` per row, because there is no `workspace.deleted` to stand in for it — the workspaces survive, only that user's seats disappear.

<Note>
  The **idempotent already-member accept** is a no-op: it marks the invite `accepted` (so `invite.accepted` still fires) but creates no membership row, so **no** `member.added` fires.
</Note>

## Uninstalling the bundle

The Workspaces bundle is purely additive — it touches no other bundle's tables, so uninstall has **empty cross-bundle actions**. Uninstalling drops the three workspace tables (invitations → members → workspaces) and the data in them.

<Warning>
  **Uninstall fires NO per-workspace webhook.** Unlike deleting workspaces one at a time (which fires `workspace.deleted` per workspace), tearing the whole bundle out does not emit a `workspace.deleted` for each workspace. Your own data tagged with workspace ids is **your responsibility** — Sublay never touches it and does not notify you per-workspace on uninstall. Back up or reconcile before uninstalling.
</Warning>

## Related

* [Webhook integration](/sdk/app-notifications/webhook-integration)
* [Delete Workspace API](/api-reference/workspaces/delete-workspace)
* [Workspace Invitation data model](/data-models/workspace-invitation)


# Semantic Search & AI
Source: https://docs.sublay.io/v7/semantic-search-ai

Automatic content embedding and semantic search across entities, comments, messages, users, and spaces — plus an AI-powered ask endpoint.

When semantic search is enabled for your project, Sublay automatically generates vector embeddings for content as it is created or updated. Those embeddings power two capabilities:

1. **Semantic search** — find content, users, and spaces by meaning, not just keywords
2. **AI ask** — a retrieval-augmented endpoint that synthesizes a streamed answer from your content in response to a natural-language question

<Note>
  Semantic search and AI features require a paid plan. Projects on the free tier cannot use embedding-based endpoints.

  The search and ask endpoints also **require an authenticated user** — call them with a user access token. Requests without a valid token are rejected (`401` when missing, `403` when expired — refresh and retry). The SDK hooks handle this for you.
</Note>

***

## What Gets Embedded

Sublay embeds the following content types automatically, with no configuration required beyond enabling the feature:

| Content Type      | What is embedded                                    |
| ----------------- | --------------------------------------------------- |
| **Entities**      | Title, body, and other text fields                  |
| **Comments**      | Comment text content                                |
| **Chat messages** | Message text content                                |
| **Users**         | Profile text assembled from name, username, and bio |
| **Spaces**        | Space name, description, and related metadata       |

Embeddings are generated asynchronously after content is created or updated.

***

## Semantic Search

There are three search endpoints, each scoped to a different content domain:

### Search Content

Searches across entities, comments, and chat messages. You can filter by source type and optionally scope results to a specific space or conversation.

* **Parameters:** `query`, `sourceTypes` (array of `"entity" | "comment" | "message"`), `spaceId` (optional), `conversationId` (optional), `limit`
* **Returns:** Array of results, each with `sourceType`, `similarity` score (0–1), and the full hydrated `record` (entity, comment, or message object)

### Search Users

Searches user profiles by semantic similarity to the query. Useful for finding users by description, interests, or bio content.

* **Parameters:** `query`, `limit`
* **Returns:** Array of results, each with `similarity` score and the full `record` (user object)

### Search Spaces

Searches spaces by semantic similarity.

* **Parameters:** `query`, `limit`
* **Returns:** Array of results, each with `similarity` score and the full `record` (space object)

Results across all three endpoints include a `similarity` field (cosine similarity, 0–1) alongside the hydrated record, so you can display or filter by relevance score.

***

## AI Ask

The ask endpoint takes a natural-language question, retrieves the most relevant content chunks from your project, and streams a synthesized answer using an LLM — grounded entirely in your content.

### How It Works

<Steps>
  <Step title="Query embedding">
    The question is embedded into a vector using the same model used for content.
  </Step>

  <Step title="Retrieval">
    The most semantically similar content is retrieved from your project's embeddings. Results can be scoped to a specific space or conversation.
  </Step>

  <Step title="Generation">
    The retrieved content is used as context for the LLM, which synthesizes an answer grounded in your data. If the context does not contain enough information to answer, the model says so.
  </Step>

  <Step title="Streaming response">
    The answer is streamed back via Server-Sent Events (SSE). After the answer completes, a `sources` event delivers the hydrated source records that were used as context.
  </Step>
</Steps>

### Response Format (SSE)

The ask endpoint responds with `Content-Type: text/event-stream`. Events are delivered in this order:

| Event     | Data                     | Description                                         |
| --------- | ------------------------ | --------------------------------------------------- |
| `token`   | `{ "content": "..." }`   | One token of the generated answer                   |
| `sources` | Array of content results | The hydrated source records used as context         |
| `done`    | `{}`                     | Stream complete                                     |
| `error`   | `{ "error": "..." }`     | Only sent if an error occurs after streaming starts |

```ts theme={null}
const response = await fetch("/v7/:projectId/search/ask", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${accessToken}`,
  },
  body: JSON.stringify({
    query: "What are the community rules about self-promotion?",
    sourceTypes: ["entity", "comment"],
    spaceId: "optional-space-id",
    limit: 10,
  }),
});

const reader = response.body!.getReader();
const decoder = new TextDecoder();

for await (const chunk of readLines(reader, decoder)) {
  if (chunk.startsWith("event: token")) {
    // append token to UI
  } else if (chunk.startsWith("event: sources")) {
    // display source citations
  } else if (chunk.startsWith("event: done")) {
    // finalize
  }
}
```

### Parameters

| Parameter        | Type       | Required | Description                                                   |
| ---------------- | ---------- | -------- | ------------------------------------------------------------- |
| `query`          | `string`   | Yes      | The natural-language question                                 |
| `sourceTypes`    | `string[]` | Yes      | Content types to search: `"entity"`, `"comment"`, `"message"` |
| `spaceId`        | `string`   | No       | Scope retrieval to a specific space                           |
| `conversationId` | `string`   | No       | Scope retrieval to a specific conversation                    |
| `limit`          | `number`   | No       | Max number of source records to return                        |

***

## SDK Integration

The SDK provides hooks for all three search endpoints and the ask endpoint:

* `useSearchContent` — search entities, comments, and messages
* `useSearchUsers` — search user profiles
* `useSearchSpaces` — search spaces
* `useAskContent` — ask a question and receive a streamed answer

See [SDK Reference → Search & AI](/sdk/search/overview) and the [Hooks Reference → Search](/hooks/search/use-search-content) for detailed usage.


# Webhooks
Source: https://docs.sublay.io/v7/webhooks

How Sublay calls your server — event notifications, validation hooks, and signature verification.

Sublay can call your server when things happen in your project. **Project webhooks** deliver broadcast and validation events for the project as a whole, configured once in the project dashboard. They use HTTP POST with HMAC-SHA256 signatures.

***

## Configuration

Webhooks are configured per project in the dashboard. You need to set:

* **Webhook URL** — the endpoint on your server that Sublay will call
* **Webhook secret** — a shared secret used to sign outgoing requests and verify incoming responses
* **Subscribed events** — the specific event types you want to receive (you only get called for events you opt into)

***

## Event Types

### Broadcast Events (Non-blocking)

These fire after an operation completes. Your server is notified but the original operation is not affected by your response.

| Event                      | Fires when                                 |
| -------------------------- | ------------------------------------------ |
| `user.created.complete`    | A new user has been created                |
| `user.updated.complete`    | A user's profile has been updated          |
| `entity.created.complete`  | A new entity has been created              |
| `entity.updated.complete`  | An entity has been updated                 |
| `comment.created.complete` | A new comment has been created             |
| `comment.updated.complete` | A comment has been updated                 |
| `space.created.complete`   | A new space has been created               |
| `space.updated.complete`   | A space has been updated                   |
| `message.created.complete` | A new chat message has been sent           |
| `notification.created`     | An app notification was created for a user |

The `notification.created` event is the primary mechanism for bridging Sublay's in-app notification system to push notifications, email, or any other delivery channel your app uses.

### Validation Events (Blocking)

These fire before an operation is committed. Sublay waits for your response. If you respond with `{ "valid": true }`, the operation proceeds. Any other response (or no response) causes the operation to be rejected.

| Event             | Fires when                            |
| ----------------- | ------------------------------------- |
| `user.created`    | A new user is about to be created     |
| `user.updated`    | A user profile is about to be updated |
| `entity.created`  | A new entity is about to be created   |
| `entity.updated`  | An entity is about to be updated      |
| `comment.created` | A new comment is about to be created  |
| `comment.updated` | A comment is about to be updated      |
| `space.created`   | A new space is about to be created    |
| `space.updated`   | A space is about to be updated        |
| `message.created` | A chat message is about to be sent    |

<Note>
  If no webhook is configured for your project, or if an event type is not in your subscribed list, all validation webhooks pass automatically — your server does not need to be present for your project to function.
</Note>

<Warning>
  Validation webhooks are synchronous. A slow or unavailable webhook endpoint will block the operation and cause it to fail. Ensure your webhook handler is fast and reliable.
</Warning>

***

## Payload Format

All webhook deliveries use the same envelope:

```json theme={null}
{
  "type": "notification.created",
  "projectId": "your-project-id",
  "stage": "complete",
  "data": { ... }
}
```

| Field       | Description                                                         |
| ----------- | ------------------------------------------------------------------- |
| `type`      | The event type string (see tables above)                            |
| `projectId` | Your Sublay project ID                                              |
| `stage`     | Lifecycle stage of the event                                        |
| `data`      | The event payload — the created/updated object or notification data |

***

## Signature Verification

Every webhook request includes two headers that allow you to verify the request came from Sublay and has not been tampered with.

| Header        | Value                                                             |
| ------------- | ----------------------------------------------------------------- |
| `X-Signature` | HMAC-SHA256 hex digest of `{timestamp}.{JSON.stringify(payload)}` |
| `X-Timestamp` | Unix timestamp in milliseconds                                    |

To verify on your server:

<Steps>
  <Step title="Read the headers">
    Extract `X-Signature` and `X-Timestamp` from the incoming request.
  </Step>

  <Step title="Recompute the expected signature">
    Compute: `HMAC-SHA256(webhookSecret, "{timestamp}.{JSON.stringify(body)}")` as a hex string, where `timestamp` is the value from `X-Timestamp` and `body` is the raw JSON body.
  </Step>

  <Step title="Compare using a constant-time comparison">
    Compare the expected signature to the received `X-Signature`. Use a constant-time comparison function to prevent timing attacks.
  </Step>

  <Step title="Reject if the signatures do not match">
    Return a non-2xx response. Do not process the request.
  </Step>
</Steps>

```ts theme={null}
import crypto from "crypto";

function verifyWebhookSignature(
  body: unknown,
  receivedSignature: string,
  timestamp: string,
  secret: string
): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${JSON.stringify(body)}`)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(receivedSignature, "hex")
  );
}
```

***

## Responding to Validation Events

For validation webhooks, your server must respond with a signed JSON body indicating whether the operation should proceed.

**To allow the operation:**

```json theme={null}
{ "valid": true }
```

**To reject the operation:**

```json theme={null}
{ "valid": false, "message": "Reason for rejection" }
```

Your response must include an `X-Response-Signature` header:

```
X-Response-Signature: HMAC-SHA256(webhookSecret, JSON.stringify(responseBody))
```

```ts theme={null}
function signWebhookResponse(body: unknown, secret: string): string {
  return crypto
    .createHmac("sha256", secret)
    .update(JSON.stringify(body))
    .digest("hex");
}

// In your handler:
const responseBody = { valid: true };
res.setHeader("X-Response-Signature", signWebhookResponse(responseBody, webhookSecret));
res.json(responseBody);
```

<Warning>
  If the response signature is missing or invalid, Sublay treats the validation as failed and rejects the operation — even if the body contained `{ "valid": true }`.
</Warning>

***

## Common Use Cases

### Push Notification Bridge

Subscribe to `notification.created`. When your webhook receives it, forward the notification to your push provider (FCM, APNs, Expo, OneSignal, etc.) for the target user.

The `data` field contains the notification parameters including the recipient user ID, notification type, and any associated entity or comment.

### Content Moderation Gate

Subscribe to `comment.created` or `entity.created` (validation events). In your handler, check the content against a blocklist or moderation API. Return `{ "valid": false }` to reject content that fails your rules before it is ever stored.

### Audit Logging

Subscribe to broadcast complete events (`user.created.complete`, `entity.created.complete`, etc.) to maintain an external audit log or pipe activity into an analytics system or data warehouse.


# Use comment section
Source: https://docs.sublay.io/v7/hooks/comments/use-comment-section

Access comment section state and actions from CommentSectionProvider

## Overview

`useCommentSection` reads from the nearest `CommentSectionProvider` and returns the full comment section state and actions. It does not fetch data itself — all data loading is managed by the provider.

<Note>
  `useCommentSection` must be used inside a `CommentSectionProvider`. See [Comment Section](/sdk/comments/comment-section) for setup and the full return value reference.
</Note>

## Usage Example

```tsx theme={null}
import { useCommentSection } from "@sublay/react-js";

function CommentList() {
  const { comments, newComments, loading, hasMore, loadMore } = useCommentSection();

  return (
    <>
      {[...newComments, ...comments].map((comment) => (
        <div key={comment.id}>{comment.content}</div>
      ))}
      {hasMore && <button onClick={loadMore}>Load more</button>}
    </>
  );
}
```

See [Comment Section](/sdk/comments/comment-section) for the complete return value reference.


# Create comment
Source: https://docs.sublay.io/v7/hooks/comments/use-create-comment

Create a new comment or reply on an entity

## Overview

`useCreateComment` returns a function that creates a new comment. Use it directly for low-level comment creation. Inside a `CommentSectionProvider`, prefer `createComment` from `useCommentSection` — it adds optimistic UI and manages the comment tree automatically.

<Note>Requires an authenticated user.</Note>

## Usage Example

```tsx theme={null}
import { useCreateComment } from "@sublay/react-js";

function PostComment({ entityId }: { entityId: string }) {
  const createComment = useCreateComment();

  const handleSubmit = async (text: string) => {
    const comment = await createComment({
      entityId,
      content: text,
    });
    console.log("Created:", comment.id);
  };

  return <button onClick={() => handleSubmit("Hello!")}>Comment</button>;
}
```

## Parameters

<ParamField type="string">
  The entity to comment on.
</ParamField>

<ParamField type="string">
  Text content of the comment. Required if `gif` is not provided.
</ParamField>

<ParamField type="GifData">
  GIF attachment. Required if `content` is not provided.
</ParamField>

<ParamField type="string">
  ID of the parent comment for replies.
</ParamField>

<ParamField type="string">
  Your own ID to associate with this comment.
</ParamField>

<ParamField type="string">
  ID of a comment being referenced/quoted in this comment.
</ParamField>

<ParamField type="Mention[]">
  Users or spaces mentioned in the comment content.
</ParamField>

<ParamField type="Record<string, any>[]">
  Arbitrary attachment metadata.
</ParamField>

<ParamField type="Record<string, any>">
  Arbitrary project-specific data.
</ParamField>

## Returns

<ResponseField name="Comment" type="Comment">
  The newly created comment. See [Comment data model](/data-models/comment).
</ResponseField>


# Delete comment
Source: https://docs.sublay.io/v7/hooks/comments/use-delete-comment

Delete a comment

## Overview

`useDeleteComment` returns a function that deletes a comment. When used inside a `CommentSectionProvider`, prefer `deleteComment` from `useCommentSection` — it handles the Reddit-style soft-delete UI automatically.

## Usage Example

```tsx theme={null}
import { useDeleteComment } from "@sublay/react-js";

function DeleteButton({ commentId }: { commentId: string }) {
  const deleteComment = useDeleteComment();

  return (
    <button onClick={() => deleteComment({ commentId })}>Delete</button>
  );
}
```

## Parameters

<ParamField type="string">
  The ID of the comment to delete.
</ParamField>

## Returns

`Promise<void>` — resolves when the comment is deleted.


# Use entity comments
Source: https://docs.sublay.io/v7/hooks/comments/use-entity-comments

Manage a paginated, sorted comment tree for an entity

## Overview

`useEntityComments` is a lower-level hook that fetches and manages a paginated comment tree for a given entity ID. It is used internally by `CommentSectionProvider`. Use it directly when you need comment tree management without the full provider.

<Note>
  For most use cases, use `CommentSectionProvider` + `useCommentSection` instead. See [Comment Section](/sdk/comments/comment-section).
</Note>

## Usage Example

```tsx theme={null}
import { useEntityComments } from "@sublay/react-js";

function CommentTree({ entityId }: { entityId: string }) {
  const { comments, loading, hasMore, loadMore } = useEntityComments({ entityId });

  return (
    <>
      {comments.map((c) => <div key={c.id}>{c.content}</div>)}
      {hasMore && <button onClick={loadMore}>Load more</button>}
    </>
  );
}
```

## Props

<ParamField type="string | null | undefined">
  The entity ID to fetch comments for.
</ParamField>

<ParamField type="number">
  Comments per page. Default: `10`.
</ParamField>

<ParamField type="string">
  Initial sort: `"createdAt"`, `"top"`, or `"controversial"`. Default: `"createdAt"`. `"new"`/`"old"` are deprecated aliases for `"createdAt"` (removed in v8).
</ParamField>

<ParamField type="&#x22;asc&#x22; | &#x22;desc&#x22;">
  Initial sort direction for `sortBy: "createdAt"`. Default: `"desc"` (newest first).
</ParamField>

<ParamField type="string | string[]">
  Populate related data. Accepted values: `"user"`, `"entity"`, `"space"`, `"parent"`, `"grants"`. On a comment feed, `"parent"` is accepted but not resolved — `parentComment` is populated only by the two single-comment reads.
</ParamField>

## Return Values

<ResponseField name="entityCommentsTree" type="EntityCommentsTree">
  Flat map of all comments and their replies, keyed by comment ID.
</ResponseField>

<ResponseField name="comments" type="Comment[]">
  Paginated root-level comments (not newly added ones).
</ResponseField>

<ResponseField name="newComments" type="Comment[]">
  Newly added root comments from this session, sorted newest-first.
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` during fetches.
</ResponseField>

<ResponseField name="hasMore" type="boolean">
  `true` when more pages are available.
</ResponseField>

<ResponseField name="sortBy" type="CommentsSortByOptions | null">
  Current sort order.
</ResponseField>

<ResponseField name="setSortBy" type="(newSortBy: CommentsSortByOptions) => void">
  Changes sort order and resets to page 1.
</ResponseField>

<ResponseField name="sortDir" type="&#x22;asc&#x22; | &#x22;desc&#x22;">
  Current sort direction for `sortBy: "createdAt"`.
</ResponseField>

<ResponseField name="setSortDir" type="(newSortDir: &#x22;asc&#x22; | &#x22;desc&#x22;) => void">
  Changes sort direction and resets to page 1.
</ResponseField>

<ResponseField name="loadMore" type="() => void">
  Loads the next page.
</ResponseField>

<ResponseField name="addCommentsToTree" type="(comments?: Comment[], newlyAdded?: boolean) => void">
  Inserts comments into the tree. Pass `newlyAdded: true` for freshly submitted comments.
</ResponseField>

<ResponseField name="removeCommentFromTree" type="({ commentId }) => void">
  Removes a comment from the tree.
</ResponseField>

<ResponseField name="markCommentAsDeleted" type="({ commentId }) => void">
  Marks a comment as deleted (Reddit-style placeholder) without removing it from the tree.
</ResponseField>


# Fetch comment
Source: https://docs.sublay.io/v7/hooks/comments/use-fetch-comment

Fetch a single comment by its ID

## Overview

`useFetchComment` returns a function that fetches a single comment by ID. The response wraps the comment in a `{ comment }` object to allow future expansion of the response shape.

<Note>
  If the comment author is block-edged with the signed-in caller, in either
  direction, this returns `404` with `comment/not-found` — identical to a
  comment that does not exist. An embedded `parentComment` is nulled under the
  same rule. Requires the `moderation` bundle.
</Note>

## Usage Example

```tsx theme={null}
import { useFetchComment } from "@sublay/react-js";

function DeepLinkComment({ commentId }: { commentId: string }) {
  const fetchComment = useFetchComment();

  const load = async () => {
    const { comment } = await fetchComment({
      commentId,
      include: ["user", "parent"],
    });
    console.log(comment);
  };

  return <button onClick={load}>Load Comment</button>;
}
```

## Parameters

<ParamField type="string">
  The ID of the comment to fetch.
</ParamField>

<ParamField type="string | string[]">
  Populate related data. Accepted values: `"user"`, `"entity"`, `"space"`, `"parent"`, `"grants"`.
</ParamField>

<SpaceReputationParams />

## Returns

<ResponseField name="comment" type="Comment">
  The fetched comment. When `"parent"` is included, `comment.parentComment` is populated. When `spaceReputation` is requested, the embedded author carries an added `spaceReputation` number. See [Comment data model](/data-models/comment) and [Reputation](/data-models/reputation).
</ResponseField>


# Fetch comment by foreign ID
Source: https://docs.sublay.io/v7/hooks/comments/use-fetch-comment-by-foreign-id

Fetch a single comment by its foreign ID

## Overview

`useFetchCommentByForeignId` returns a function that fetches a comment using the foreign ID from your own system. Useful when you've stored your own identifier on a comment and need to retrieve it later.

<Note>
  If the comment author is block-edged with the signed-in caller, in either
  direction, this returns `404` with `comment/not-found` — identical to a
  comment that does not exist. An embedded `parentComment` is nulled under the
  same rule. Requires the `moderation` bundle.
</Note>

## Usage Example

```tsx theme={null}
import { useFetchCommentByForeignId } from "@sublay/react-js";

function MyComment({ myCommentId }: { myCommentId: string }) {
  const fetchComment = useFetchCommentByForeignId();

  const load = async () => {
    const { comment } = await fetchComment({ foreignId: myCommentId });
    console.log(comment);
  };

  return <button onClick={load}>Load</button>;
}
```

## Parameters

<ParamField type="string">
  The foreign ID to look up.
</ParamField>

<ParamField type="string | string[]">
  Populate related data. Accepted values: `"user"`, `"entity"`, `"space"`, `"parent"`, `"grants"`.
</ParamField>

## Returns

<ResponseField name="comment" type="Comment">
  The fetched comment. See [Comment data model](/data-models/comment).
</ResponseField>


# Fetch many comments
Source: https://docs.sublay.io/v7/hooks/comments/use-fetch-many-comments

Fetch a paginated list of comments with filters

## Overview

`useFetchManyComments` returns a function that fetches a paginated list of comments. This is the underlying fetch function used by `useEntityComments` and `useReplies`. Use it directly when you need a custom comment list outside of those hooks.

## Usage Example

```tsx theme={null}
import { useFetchManyComments } from "@sublay/react-js";
import { useState, useEffect } from "react";

function UserComments({ userId }: { userId: string }) {
  const fetchComments = useFetchManyComments();
  const [comments, setComments] = useState([]);

  useEffect(() => {
    fetchComments({ userId, page: 1, limit: 10 }).then((res) =>
      setComments(res.data)
    );
  }, [userId]);

  return (
    <ul>
      {comments.map((c) => <li key={c.id}>{c.content}</li>)}
    </ul>
  );
}
```

## Parameters

<ParamField type="number">
  Page number (1-indexed). Must be greater than 0.
</ParamField>

<ParamField type="string">
  Filter to comments on a specific entity.
</ParamField>

<ParamField type="string">
  Filter to comments by a specific user.
</ParamField>

<ParamField type="string">
  Filter to replies of a specific parent comment.
</ParamField>

<ParamField type="string">
  Sort order: `"createdAt"` or `"top"`. `"new"`/`"old"` are deprecated aliases for `"createdAt"` (removed in v8). A `sortDir` (`"asc"`/`"desc"`) controls `"createdAt"` direction.
</ParamField>

<ParamField type="number">
  Results per page. Must be greater than 0.
</ParamField>

<ParamField type="string">
  Filter to comments within a specific source.
</ParamField>

<ParamField type="string | string[]">
  Populate related data. Accepted values: `"user"`, `"entity"`, `"space"`, `"parent"`, `"grants"`. On a comment feed, `"parent"` is accepted but not resolved — `parentComment` is populated only by the two single-comment reads.
</ParamField>

<SpaceReputationParams />

## Returns

<ResponseField name="data" type="Comment[]">
  Comments for the current page. When `spaceReputation` is requested, each embedded author carries an added `spaceReputation` number. See [Reputation](/data-models/reputation).
</ResponseField>

<ResponseField name="pagination.hasMore" type="boolean">
  Whether there are more pages to load.
</ResponseField>


# Use comments
Source: https://docs.sublay.io/v7/hooks/comments/use-fetch-many-comments-wrapper

Stateful, paginated comment list with sorting

## Overview

`useFetchManyCommentsWrapper` is a stateful wrapper around [`useFetchManyComments`](/hooks/comments/use-fetch-many-comments) that manages pagination, sort state, and the comment list for you. Use it when you need a custom paginated comment list outside of `CommentSectionProvider` — for example, a user profile page showing all comments a user has made, or a custom thread viewer.

Changing `sortBy` resets the list and re-fetches from page 1. At least one of `entityId`, `userId`, or `parentId` must be provided — the hook will not fetch otherwise.

## Usage Example

```tsx theme={null}
import { useFetchManyCommentsWrapper } from "@sublay/react-js";

function UserComments({ userId }: { userId: string }) {
  const {
    comments,
    loading,
    hasMore,
    sortBy,
    setSortBy,
    loadMore,
  } = useFetchManyCommentsWrapper({
    userId,
    limit: 10,
    defaultSortBy: "createdAt",
    include: ["entity"],
  });

  return (
    <div>
      <select value={sortBy ?? ""} onChange={(e) => setSortBy(e.target.value as any)}>
        <option value="createdAt">Newest</option>
        <option value="top">Top</option>
        <option value="controversial">Controversial</option>
      </select>
      <ul>
        {comments.map((comment) => (
          <li key={comment.id}>{comment.content}</li>
        ))}
      </ul>
      {hasMore && (
        <button onClick={loadMore} disabled={loading}>
          Load more
        </button>
      )}
    </div>
  );
}
```

## Parameters

<ParamField type="string | null">
  Filter to comments on a specific entity.
</ParamField>

<ParamField type="string | null">
  Filter to comments by a specific user.
</ParamField>

<ParamField type="string | null">
  Filter to replies of a specific parent comment.
</ParamField>

<ParamField type="string | null">
  Filter to comments within a specific source.
</ParamField>

<ParamField type="number">
  Number of comments per page. Default: `10`.
</ParamField>

<ParamField type="&#x22;createdAt&#x22; | &#x22;top&#x22; | &#x22;controversial&#x22;">
  Initial sort order. Default: `"createdAt"`. `"new"`/`"old"` are deprecated aliases for `"createdAt"` (removed in v8).
</ParamField>

<ParamField type="&#x22;asc&#x22; | &#x22;desc&#x22;">
  Initial sort direction for `sortBy: "createdAt"`. Default: `"desc"` (newest first).
</ParamField>

<ParamField type="CommentIncludeParam">
  Populate related data. Accepted values: `"user"`, `"entity"`, `"space"`, `"parent"`, `"grants"`. On a comment feed, `"parent"` is accepted but not resolved — `parentComment` is populated only by the two single-comment reads.
</ParamField>

## Returns

<ResponseField name="comments" type="Comment[]">
  The current list of fetched comments. Appended to on each `loadMore` call.
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` while fetching the initial page or loading more.
</ResponseField>

<ResponseField name="hasMore" type="boolean">
  `true` if additional pages are available.
</ResponseField>

<ResponseField name="sortBy" type="CommentsSortByOptions | null">
  Current sort order.
</ResponseField>

<ResponseField name="setSortBy" type="(sortBy: CommentsSortByOptions) => void">
  Change the sort order. Resets the comment list and re-fetches from page 1.
</ResponseField>

<ResponseField name="sortDir" type="&#x22;asc&#x22; | &#x22;desc&#x22;">
  Current sort direction for `sortBy: "createdAt"`.
</ResponseField>

<ResponseField name="setSortDir" type="(sortDir: &#x22;asc&#x22; | &#x22;desc&#x22;) => void">
  Change the sort direction. Resets the comment list and re-fetches from page 1.
</ResponseField>

<ResponseField name="loadMore" type="() => void">
  Load the next page of comments. Appends to the existing list.
</ResponseField>


# Use replies
Source: https://docs.sublay.io/v7/hooks/comments/use-replies

Fetch and paginate replies for a specific comment

## Overview

`useReplies` loads replies for a specific comment from the `entityCommentsTree` managed by the nearest `CommentSectionProvider`. It fetches a page of replies when the `page` state increases above `0`.

<Note>
  Must be used inside a `CommentSectionProvider`. Replies are merged into the shared `entityCommentsTree`.
</Note>

## Usage Example

```tsx theme={null}
import { useReplies } from "@sublay/react-js";

function CommentItem({ commentId }: { commentId: string }) {
  const { replies, newReplies, loading, setPage } = useReplies({
    commentId,
    sortBy: "createdAt",
  });

  return (
    <div>
      <button onClick={() => setPage((p) => p + 1)}>Load replies</button>
      {[...newReplies, ...replies].map((r) => (
        <div key={r.id}>{r.content}</div>
      ))}
    </div>
  );
}
```

## Props

<ParamField type="string">
  The ID of the comment to load replies for.
</ParamField>

<ParamField type="CommentsSortByOptions">
  Sort order for replies: `"createdAt"` or `"top"`. `"new"`/`"old"` are deprecated aliases for `"createdAt"` (removed in v8).
</ParamField>

<ParamField type="&#x22;asc&#x22; | &#x22;desc&#x22;">
  Sort direction for `sortBy: "createdAt"`. Default: `"desc"` (newest first).
</ParamField>

## Return Values

<ResponseField name="replies" type="(Comment & { new: boolean })[]">
  Paginated replies (not newly submitted in this session).
</ResponseField>

<ResponseField name="newReplies" type="(Comment & { new: boolean })[]">
  Replies submitted in this session, sorted newest-first.
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` while replies are being fetched.
</ResponseField>

<ResponseField name="page" type="number">
  Current page number. Starts at `0` (no replies loaded). Increment to load replies.
</ResponseField>

<ResponseField name="setPage" type="Dispatch<SetStateAction<number>>">
  Increment to trigger loading the next page of replies.
</ResponseField>


# Update comment
Source: https://docs.sublay.io/v7/hooks/comments/use-update-comment

Update a comment's text content or metadata

## Overview

`useUpdateComment` returns a function that updates an existing comment. At least one of `content` or `metadata` must be provided.

## Usage Example

```tsx theme={null}
import { useUpdateComment } from "@sublay/react-js";

function EditComment({ commentId }: { commentId: string }) {
  const updateComment = useUpdateComment();

  const save = async (newContent: string) => {
    const updated = await updateComment({ commentId, content: newContent });
    console.log("Updated:", updated.id);
  };

  return <button onClick={() => save("Edited content")}>Save</button>;
}
```

## Parameters

<ParamField type="string">
  The ID of the comment to update.
</ParamField>

<ParamField type="string">
  New text content. Must be at least 1 character.
</ParamField>

<ParamField type="Record<string, any>">
  Replacement metadata object.
</ParamField>

## Returns

<ResponseField name="Comment" type="Comment">
  The updated comment. See [Comment data model](/data-models/comment).
</ResponseField>


# Delete entity
Source: https://docs.sublay.io/v7/hooks/entities/use-delete-entity

Delete an entity

<Note>
  **Requires the `entities` bundle.** A project without the entities bundle returns `403 database/tables-not-available`. See [Bundles](/bundles).
</Note>

## Overview

`useDeleteEntity` returns a function that deletes an entity. If called from inside an `EntityProvider`, the provider's entity state is set to `undefined` after deletion.

## Usage Example

```tsx theme={null}
import { useDeleteEntity } from "@sublay/react-js";

function DeleteButton({ entityId }: { entityId: string }) {
  const deleteEntity = useDeleteEntity();

  const handleDelete = async () => {
    await deleteEntity({ entityId });
    console.log("Deleted");
  };

  return <button onClick={handleDelete}>Delete</button>;
}
```

## Parameters

<ParamField type="string">
  The ID of the entity to delete.
</ParamField>

## Returns

`Promise<void>` — resolves when the entity is deleted.


# Fetch drafts
Source: https://docs.sublay.io/v7/hooks/entities/use-fetch-drafts

Fetch the authenticated user's draft entities

<Note>
  **Requires the `entities` bundle.** A project without the entities bundle returns `403 database/tables-not-available`. See [Bundles](/bundles).
</Note>

## Overview

`useFetchDrafts` returns a function that retrieves the authenticated user's unpublished draft entities in a paginated response.

<Note>Requires an authenticated user. Only the user's own drafts are returned.</Note>

## Usage Example

```tsx theme={null}
import { useFetchDrafts } from "@sublay/react-js";
import { useEffect, useState } from "react";

function DraftsList() {
  const fetchDrafts = useFetchDrafts();
  const [drafts, setDrafts] = useState([]);

  useEffect(() => {
    fetchDrafts({ page: 1, limit: 10 }).then((res) => setDrafts(res.data));
  }, []);

  return (
    <ul>
      {drafts.map((d) => (
        <li key={d.id}>{d.title || "Untitled"}</li>
      ))}
    </ul>
  );
}
```

## Parameters

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page.
</ParamField>

<ParamField type="string">
  Filter drafts by source ID.
</ParamField>

<ParamField type="string">
  Filter drafts by space.
</ParamField>

<ParamField type="string | string[]">
  Populate related fields. Accepted values: `"user"`, `"space"`, `"files"`, `"grants"`. `"topComment"` and `"saved"` are not resolved for drafts.
</ParamField>

## Returns

<ResponseField name="data" type="Entity[]">
  Array of draft entities for the current page.
</ResponseField>

<ResponseField name="pagination.page" type="number">
  Current page number.
</ResponseField>

<ResponseField name="pagination.pageSize" type="number">
  Number of results per page.
</ResponseField>

<ResponseField name="pagination.totalPages" type="number">
  Total number of pages.
</ResponseField>

<ResponseField name="pagination.totalItems" type="number">
  Total count of the user's drafts.
</ResponseField>

<ResponseField name="pagination.hasMore" type="boolean">
  `true` if there are additional pages available.
</ResponseField>


# Check if entity is saved
Source: https://docs.sublay.io/v7/hooks/entities/use-is-entity-saved

Check whether an entity is saved in any of the user's collections

<Note>
  **Requires the `entities` bundle.** A project without the entities bundle returns `403 database/tables-not-available`. See [Bundles](/bundles).
</Note>

## Overview

`useIsEntitySaved` provides a function to check whether a specific entity is saved in any collection owned by the current user. The function returns the full result — including the list of collections the entity is saved in — leaving state management to the caller.

<Note>Requires an authenticated user. Throws if called without a logged-in user, an entity ID, or a project ID.</Note>

## Usage Example

```tsx theme={null}
import { useState } from "react";
import { useIsEntitySaved } from "@sublay/react-js";

function SaveStatus({ entityId }) {
  const { checkIfEntityIsSaved } = useIsEntitySaved();
  const [savedStatus, setSavedStatus] = useState(null);

  useEffect(() => {
    checkIfEntityIsSaved({ entityId }).then(setSavedStatus);
  }, [entityId]);

  if (savedStatus === null) return <p>Checking...</p>;
  return <p>{savedStatus.saved ? "Saved" : "Not saved"}</p>;
}
```

## Returns

<ResponseField name="checkIfEntityIsSaved" type="({ entityId }: { entityId: string }) => Promise<{ saved: boolean; collections: Array<{ id: string; name: string }> }>">
  Calls the API to determine whether the entity is saved in any of the user's collections. Returns the full result including the list of collections the entity belongs to.
</ResponseField>

<Note>
  To also check membership in a specific collection, use `isEntitySaved` from `useCollections` — it accepts an optional `collectionId` and returns `inSpecificCollection` in addition to the full data.
</Note>


# Publish draft
Source: https://docs.sublay.io/v7/hooks/entities/use-publish-draft

Publish a draft entity, making it publicly visible

<Note>
  **Requires the `entities` bundle.** A project without the entities bundle returns `403 database/tables-not-available`. See [Bundles](/bundles).
</Note>

## Overview

`usePublishDraft` returns a function that publishes a draft entity. After publishing, `entity.isDraft` becomes `false` and the entity is visible to other users.

## Usage Example

```tsx theme={null}
import { usePublishDraft } from "@sublay/react-js";

function PublishButton({ entityId }: { entityId: string }) {
  const publishDraft = usePublishDraft();

  const handlePublish = async () => {
    const entity = await publishDraft({ entityId });
    console.log("Published, isDraft:", entity.isDraft); // false
  };

  return <button onClick={handlePublish}>Publish</button>;
}
```

## Parameters

<ParamField type="string">
  The ID of the draft entity to publish.
</ParamField>

## Returns

<ResponseField name="Entity" type="Entity">
  The published entity with `isDraft: false`. See [Entity data model](/data-models/entity).
</ResponseField>


# Update entity
Source: https://docs.sublay.io/v7/hooks/entities/use-update-entity

Update an existing entity's content fields

<Note>
  **Requires the `entities` bundle.** A project without the entities bundle returns `403 database/tables-not-available`. See [Bundles](/bundles).
</Note>

## Overview

`useUpdateEntity` returns a function that updates an entity's content fields. After a successful update, the entity state inside the nearest `EntityProvider` is automatically synced with the new data.

## Usage Example

```tsx theme={null}
import { useUpdateEntity } from "@sublay/react-js";

function EditPost({ entityId }: { entityId: string }) {
  const updateEntity = useUpdateEntity();

  const handleSave = async (newContent: string) => {
    const updated = await updateEntity({
      entityId,
      update: { content: newContent },
    });
    console.log("Updated:", updated.id);
  };

  return <button onClick={() => handleSave("Revised content")}>Save</button>;
}
```

## Parameters

<ParamField type="string">
  The ID of the entity to update.
</ParamField>

<ParamField type="string | null">
  New title. Pass `null` to clear.
</ParamField>

<ParamField type="string | null">
  New content body. Pass `null` to clear.
</ParamField>

<ParamField type="Record<string, any>[]">
  Replacement attachments array.
</ParamField>

<ParamField type="string[]">
  Replacement keywords array.
</ParamField>

<ParamField type="{ latitude: number; longitude: number }">
  New geographic location.
</ParamField>

<ParamField type="Record<string, any>">
  Replacement metadata object.
</ParamField>

<ParamField type="Mention[]">
  Updated mentions array.
</ParamField>

<ParamField type="boolean">
  Updated NSFW own-flag. Subject to the same owner / service / master authorization as the rest of the update. To flag another user's entity, a space moderator uses [useSetSpaceEntityNsfw](/hooks/spaces/use-set-space-entity-nsfw) instead. See [Entity NSFW flagging](/data-models/entity#nsfw-flagging).
</ParamField>

## Returns

<ResponseField name="Entity" type="Entity">
  The updated entity. See [Entity data model](/data-models/entity).
</ResponseField>


# Use entity list
Source: https://docs.sublay.io/v7/hooks/entity-lists/use-entity-list

Manage a paginated entity feed with filtering, sorting, and infinite scroll

## Overview

`useEntityList` is the primary hook for building entity feeds. Each call receives a unique `listId` that namespaces its Redux state, so multiple independent lists can coexist on the same page.

See [Fetching Entities](/sdk/entity-lists/fetch-entities) for a full guide on using this hook.

## Usage Example

```tsx theme={null}
import { useEntityList } from "@sublay/react-js";
import { useEffect } from "react";

function Feed() {
  const {
    entities,
    loading,
    hasMore,
    fetchEntities,
    loadMore,
  } = useEntityList({ listId: "main-feed" });

  useEffect(() => {
    fetchEntities({}, { sortBy: "hot" }, { limit: 20, include: ["user"] });
  }, []);

  return (
    <>
      {entities.map((e) => <div key={e.id}>{e.title}</div>)}
      {hasMore && <button onClick={loadMore}>Load more</button>}
    </>
  );
}
```

## Props

<ParamField type="string">
  Unique identifier for this list. Used to namespace Redux state. Must be stable across renders.
</ParamField>

<ParamField type="(foreignId: string) => Promise<Record<string, any> | null>">
  Optional. A function called for each entity with a `foreignId`. Its result is merged into the entity under an `infusion` key. See [Infusing Data](/sdk/entity-lists/infuse-data).
</ParamField>

## Reputation

The `config` object passed to `fetchEntities` accepts an optional `spaceReputation` object that opts each row's embedded author into an added `spaceReputation` number. See [Reputation](/data-models/reputation).

<ParamField type="object">
  Opt-in. Adds a `spaceReputation` number to each row's embedded author. **This object is the primary form** — it replaces the deprecated flat config props below. This is a context surface, so `spaceId` accepts `"context"`.

  <Expandable title="spaceReputation">
    <ParamField name="spaceId" type="string | &#x22;none&#x22; | &#x22;context&#x22;">
      Which bucket to read: a space **`<uuid>`** (that space's bucket), **`"none"`** (the project-general bucket), or **`"context"`** (server-derived per row from the request context — useful for mixed-space feeds). The empty string and the legacy `general` / `null` aliases are rejected (400). Missing buckets read as `0`.
    </ParamField>

    <ParamField name="includeDescendants" type="boolean">
      Only honored when `spaceId` is an explicit space `<uuid>`. When `true`, `spaceReputation` is the subtree sum (the named space plus all of its descendants). Ignored for `"none"`; not allowed with `"context"`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  **Deprecated** — use `config.spaceReputation.spaceId`. The flat form; still accepted (the object wins if both are passed). Accepts a space `<uuid>`, `"none"`, or `"context"`.
</ParamField>

<ParamField type="boolean">
  **Deprecated** — use `config.spaceReputation.includeDescendants`. Only honored alongside an explicit `config.spaceReputationId` `<uuid>`.
</ParamField>

## Return Values

<ResponseField name="entities" type="Entity[]">
  The current list of loaded entities.
</ResponseField>

<ResponseField name="infusedEntities" type="(Entity & { infusion: Record<string, any> })[]">
  Entities merged with data from `infuseData`. Empty array if `infuseData` was not provided.
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` while a fetch or load-more is in progress.
</ResponseField>

<ResponseField name="hasMore" type="boolean">
  `true` when there are more pages to load.
</ResponseField>

<ResponseField name="fetchEntities" type="(filters, sort?, config?, options?) => void">
  Loads the first page with the given filters, sort, and config. Debounced by default (800ms). See [Fetching Entities](/sdk/entity-lists/fetch-entities) for the full parameter reference.
</ResponseField>

<ResponseField name="loadMore" type="() => void">
  Appends the next page of results. Must be called after `fetchEntities` has been invoked at least once.
</ResponseField>

<ResponseField name="createEntity" type="(props: EntityListCreateEntityProps) => Promise<Entity | undefined>">
  Creates a new entity and inserts it into the list. Accepts the same fields as `useCreateEntity`, plus `insertPosition: "first" | "last"`.
</ResponseField>

<ResponseField name="deleteEntity" type="(props: { entityId: string }) => Promise<void>">
  Deletes an entity and removes it from the local list state.
</ResponseField>

<ResponseField name="sortBy" type="&#x22;createdAt&#x22; | &#x22;hot&#x22; | &#x22;top&#x22; | &#x22;controversial&#x22; | &#x22;metadata.field&#x22; | null">
  Current sort algorithm.
</ResponseField>

<ResponseField name="sortByReaction" type="&#x22;upvote&#x22; | &#x22;downvote&#x22; | &#x22;like&#x22; | &#x22;love&#x22; | &#x22;wow&#x22; | &#x22;sad&#x22; | &#x22;angry&#x22; | &#x22;funny&#x22; | null">
  Current reaction sort type (used when `sortBy` is `"top"`).
</ResponseField>

<ResponseField name="sortDir" type="&#x22;asc&#x22; | &#x22;desc&#x22; | null">
  Current sort direction.
</ResponseField>

<ResponseField name="sortType" type="&#x22;auto&#x22; | &#x22;numeric&#x22; | &#x22;text&#x22; | &#x22;boolean&#x22; | &#x22;timestamp&#x22; | null">
  Current sort type hint for metadata sorts.
</ResponseField>

<ResponseField name="timeFrame" type="&#x22;day&#x22; | &#x22;week&#x22; | &#x22;month&#x22; | &#x22;year&#x22; | null">
  Active time frame filter.
</ResponseField>

<ResponseField name="sourceId" type="string | null">
  Active source ID filter (from config).
</ResponseField>

<ResponseField name="userId" type="string | null">
  Active user ID filter.
</ResponseField>

<ResponseField name="followedOnly" type="boolean">
  Whether the followed-only filter is active.
</ResponseField>

<ResponseField name="keywordsFilters" type="KeywordsFilters | null">
  Active keywords filter.
</ResponseField>

<ResponseField name="titleFilters" type="TitleFilters | null">
  Active title filter.
</ResponseField>

<ResponseField name="contentFilters" type="ContentFilters | null">
  Active content filter.
</ResponseField>

<ResponseField name="attachmentsFilters" type="AttachmentsFilters | null">
  Active attachments filter.
</ResponseField>

<ResponseField name="locationFilters" type="LocationFilters | null">
  Active location filter.
</ResponseField>

<ResponseField name="metadataFilters" type="MetadataFilters | null">
  Active metadata filter.
</ResponseField>


# Use entity list actions
Source: https://docs.sublay.io/v7/hooks/entity-lists/use-entity-list-actions

Low-level actions for fetching, creating, and deleting entities in a list

## Overview

`useEntityListActions` provides the low-level Redux-backed actions that power `useEntityList`. In most cases you should use `useEntityList` directly. Use this hook when you need to trigger fetch, create, or delete operations from a component that is separate from the one consuming the list state.

## Usage Example

```tsx theme={null}
import { useEntityListActions } from "@sublay/react-js";

function RefreshButton() {
  const { fetchEntities } = useEntityListActions();

  const handleRefresh = async () => {
    await fetchEntities("my-feed", {
      page: 1,
      sortBy: "hot",
      limit: 20,
    });
  };

  return <button onClick={handleRefresh}>Refresh</button>;
}
```

## Return Values

<ResponseField name="fetchEntities" type="(listId: string, options: FetchEntitiesOptions) => Promise<Entity[] | null>">
  Fetches a page of entities and dispatches the result into the Redux list state.

  <Expandable title="FetchEntitiesOptions">
    <ResponseField name="page" type="number">
      Page number (1-indexed).
    </ResponseField>

    <ResponseField name="sortBy" type="&#x22;createdAt&#x22; | &#x22;hot&#x22; | &#x22;top&#x22; | &#x22;controversial&#x22; | &#x22;metadata.field&#x22;">
      Sort algorithm. See [Fetching Entities](/sdk/entity-lists/fetch-entities) for options.
    </ResponseField>

    <ResponseField name="limit" type="number">
      Results per page.
    </ResponseField>

    <ResponseField name="sortByReaction" type="&#x22;upvote&#x22; | &#x22;downvote&#x22; | &#x22;like&#x22; | &#x22;love&#x22; | &#x22;wow&#x22; | &#x22;sad&#x22; | &#x22;angry&#x22; | &#x22;funny&#x22;">
      Used when `sortBy` is `"top"`.
    </ResponseField>

    <ResponseField name="sortDir" type="&#x22;asc&#x22; | &#x22;desc&#x22;">Sort direction.</ResponseField>

    <ResponseField name="sortType" type="&#x22;auto&#x22; | &#x22;numeric&#x22; | &#x22;text&#x22; | &#x22;boolean&#x22; | &#x22;timestamp&#x22;">
      Type hint for metadata sorts.
    </ResponseField>

    <ResponseField name="sourceId" type="string">Filter by source ID.</ResponseField>
    <ResponseField name="spaceId" type="string">Filter by space ID.</ResponseField>
    <ResponseField name="userId" type="string">Filter by user ID.</ResponseField>
    <ResponseField name="followedOnly" type="boolean">Only show entities from followed users.</ResponseField>
    <ResponseField name="timeFrame" type="&#x22;day&#x22; | &#x22;week&#x22; | &#x22;month&#x22; | &#x22;year&#x22;">Time window filter.</ResponseField>
    <ResponseField name="include" type="string | (&#x22;space&#x22; | &#x22;user&#x22; | &#x22;topComment&#x22; | &#x22;saved&#x22; | &#x22;files&#x22; | &#x22;grants&#x22;)[]">Populate related data.</ResponseField>
    <ResponseField name="keywordsFilters" type="KeywordsFilters">Filter by keywords.</ResponseField>
    <ResponseField name="titleFilters" type="TitleFilters">Filter by title content.</ResponseField>
    <ResponseField name="contentFilters" type="ContentFilters">Filter by body content.</ResponseField>
    <ResponseField name="attachmentsFilters" type="AttachmentsFilters">Filter by attachments.</ResponseField>
    <ResponseField name="locationFilters" type="LocationFilters">Filter by geographic proximity.</ResponseField>
    <ResponseField name="metadataFilters" type="MetadataFilters">Filter by metadata fields.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="createEntity" type="(listId: string, options: CreateEntityOptions) => Promise<Entity | undefined>">
  Creates an entity and inserts it into the specified list.
</ResponseField>

<ResponseField name="deleteEntity" type="(listId: string, options: { entityId: string }) => Promise<void>">
  Deletes an entity and removes it from the specified list.
</ResponseField>


# Use infused data
Source: https://docs.sublay.io/v7/hooks/entity-lists/use-infused-data

Merge an array of Sublay entities with data fetched from your own backend

## Overview

`useInfusedData` takes an array of entities and an optional `infuseData` function, and returns an array of those entities merged with external data under an `infusion` key. Results are cached by `foreignId` per hook instance.

This hook is used internally by `useEntityList` when you pass `infuseData`. Use it directly only if you need to infuse a custom entity array that isn't managed by `useEntityList`.

See [Infusing Data](/sdk/entity-lists/infuse-data) for a full guide.

## Props

<ParamField type="Entity[]">
  The entities to infuse.
</ParamField>

<ParamField type="(foreignId: string) => Promise<Record<string, any> | null>">
  Called once per unique `foreignId`. Return `null` if the external record is not found.
</ParamField>

## Returns

`(Entity & { infusion: Record<string, any> })[]`

Each item in the returned array is the original entity with an added `infusion` property containing the data returned by `infuseData`. Entities without a `foreignId` (or where `infuseData` returns `null`) have `infusion: {}`.


# useAddHost
Source: https://docs.sublay.io/v7/hooks/events/use-add-host

Grant a user host privileges on an event (host-only)

## Overview

`useAddHost` returns a callable that adds a user to an event's `hostIds`. **Host-only** — the logged-in user must already be a host. The operation is idempotent.

## Usage Example

```tsx theme={null}
import { useAddHost } from "@sublay/react-js";

function AddCoHost({ eventId }: { eventId: string }) {
  const addHost = useAddHost();
  return (
    <button onClick={() => addHost({ eventId, userId: "usr_cohost" })}>
      Add co-host
    </button>
  );
}
```

## Parameters

<ParamField type="string">The event ID.</ParamField>
<ParamField type="string">The user to grant host on the event.</ParamField>

## Returns

Returns a `Promise<Event>` — the [Event](/data-models/event) with the new `hostIds`.

## See Also

* [Add Host API](/api-reference/events/add-host)
* [useRemoveHost](/hooks/events/use-remove-host)


# useAddInvite
Source: https://docs.sublay.io/v7/hooks/events/use-add-invite

Invite a user to an event (host-only)

## Overview

`useAddInvite` returns a callable that invites a user to an event. **Host-only.** Idempotent against the unique `(eventId, userId)` constraint. For an `invite`-visibility event, the invited user can now see and RSVP to it; when the `notifications` bundle is enabled, the invitee receives an `event-invite` notification.

## Usage Example

```tsx theme={null}
import { useAddInvite } from "@sublay/react-js";

function InviteButton({ eventId }: { eventId: string }) {
  const addInvite = useAddInvite();
  return (
    <button onClick={() => addInvite({ eventId, userId: "usr_guest" })}>
      Invite
    </button>
  );
}
```

## Parameters

<ParamField type="string">The event ID.</ParamField>
<ParamField type="string">The user to invite (userId only — never a foreign ID).</ParamField>

## Returns

Returns a `Promise<Event>` — the updated [Event](/data-models/event).

## See Also

* [Add Invite API](/api-reference/events/add-invite)
* [useRemoveInvite](/hooks/events/use-remove-invite)


# useCancelEvent
Source: https://docs.sublay.io/v7/hooks/events/use-cancel-event

Cancel an event without deleting it (host-only)

## Overview

`useCancelEvent` returns a callable that cancels an event by setting its `status` to `"cancelled"`. **Host-only.** The event stays fetchable but rejects new RSVPs. When the `notifications` bundle is enabled, all `going`/`maybe` attendees receive an `event-cancelled` notification.

## Usage Example

```tsx theme={null}
import { useCancelEvent } from "@sublay/react-js";

function CancelButton({ eventId }: { eventId: string }) {
  const cancelEvent = useCancelEvent();
  return <button onClick={() => cancelEvent({ eventId })}>Cancel event</button>;
}
```

## Parameters

<ParamField type="string">The event to cancel.</ParamField>

## Returns

Returns a `Promise<Event>` — the [Event](/data-models/event) with `status: "cancelled"`.

## See Also

* [Cancel Event API](/api-reference/events/cancel-event)


# useCreateEvent
Source: https://docs.sublay.io/v7/hooks/events/use-create-event

Create an event, optionally with an inline cover image and gallery

## Overview

`useCreateEvent` returns a callable that creates an event. The logged-in user becomes the creator and is auto-added to `hostIds`. Pass `cover` and/or `gallery` to upload images inline — the hook sends `multipart/form-data` automatically (requires the `files-images` bundle).

## Usage Example

```tsx theme={null}
import { useCreateEvent } from "@sublay/react-js";

function CreateEvent() {
  const createEvent = useCreateEvent();

  const handleCreate = async () => {
    const event = await createEvent({
      title: "Launch Party",
      type: "physical",
      startTime: "2026-09-01T18:00:00.000Z",
      endTime: "2026-09-01T22:00:00.000Z",
      venueName: "The Loft",
      address: "123 Main St, New York, NY",
      capacity: 100,
      visibility: "public",
    });
    console.log("Created:", event.id);
  };
}
```

## Parameters

<ParamField type="string">Event title. 1–300 characters.</ParamField>
<ParamField type="string">ISO datetime when the event starts.</ParamField>

<ParamField type="&#x22;online&#x22; | &#x22;physical&#x22; | &#x22;hybrid&#x22;">
  `online` requires `url`; `physical` requires `address` or `location`; `hybrid` requires both.
</ParamField>

<ParamField type="string">Optional description.</ParamField>
<ParamField type="string">Optional ISO end datetime.</ParamField>
<ParamField type="string">Optional IANA timezone.</ParamField>
<ParamField type="string">Join/stream URL.</ParamField>
<ParamField type="string">Venue name.</ParamField>
<ParamField type="string">Street address.</ParamField>
<ParamField type="{ latitude: number; longitude: number }">Coordinates for proximity search.</ParamField>
<ParamField type="string">Scope to a space. Required when `visibility` is `"members"`.</ParamField>
<ParamField type="&#x22;public&#x22; | &#x22;members&#x22; | &#x22;invite&#x22;">Defaults to `"public"`.</ParamField>
<ParamField type="number">Max `going` RSVPs. Omit for unlimited.</ParamField>
<ParamField type="boolean">Allow `"maybe"` RSVPs. Defaults to `true`.</ParamField>
<ParamField type="boolean">Expose the named guest list. Defaults to `true`.</ParamField>
<ParamField type="string[]">Additional host user IDs (the logged-in user is auto-added).</ParamField>
<ParamField type="Record<string, any>">Arbitrary key-value data. Up to 1 MB.</ParamField>

<ParamField type="{ file: File | RNFile; options?: UploadImageOptions }">
  Single cover image to upload. Sends multipart. Requires the `files-images` bundle.
</ParamField>

<ParamField type="{ files: (File | RNFile)[]; options?: UploadImageOptions }">
  Gallery images to upload (up to 10). Sends multipart. Requires the `files-images` bundle.
</ParamField>

## Returns

Returns a `Promise<Event>` — the created [Event](/data-models/event) with inline `rsvpCounts`.

## See Also

* [Events Overview](/sdk/events/overview)
* [Create Event API](/api-reference/events/create-event)


# useDeleteEvent
Source: https://docs.sublay.io/v7/hooks/events/use-delete-event

Delete an event and clean up its RSVPs and invites (host-only)

## Overview

`useDeleteEvent` returns a callable that deletes an event. **Host-only.** The event's RSVPs and invites are cleaned up; whether the event is soft- or hard-deleted (and whether its files are preserved) follows the project's `eventDeletion` settings.

## Usage Example

```tsx theme={null}
import { useDeleteEvent } from "@sublay/react-js";

function DeleteButton({ eventId }: { eventId: string }) {
  const deleteEvent = useDeleteEvent();
  return <button onClick={() => deleteEvent({ eventId })}>Delete</button>;
}
```

## Parameters

<ParamField type="string">The event to delete.</ParamField>

## Returns

Returns a `Promise<void>`.

## See Also

* [Delete Event API](/api-reference/events/delete-event)


# useEvent & useEventData
Source: https://docs.sublay.io/v7/hooks/events/use-event

Access a single event from context, or manage one directly

## Overview

`useEvent` reads the event loaded by [`EventProvider`](/sdk/events/provider-and-hook) from context, returning the event plus bound actions (`updateEvent`, `deleteEvent`, `cancelEvent`, `setRsvp`, `withdrawRsvp`). `useEventData` is the underlying hook the provider uses — call it directly when you want the same managed state without the provider/context.

## useEvent

Call inside a descendant of `EventProvider`.

```tsx theme={null}
import { useEvent } from "@sublay/react-js";

function EventDetail() {
  const { event, setRsvp, withdrawRsvp, cancelEvent } = useEvent();

  if (event === undefined) return <p>Loading…</p>;
  if (!event) return <p>Not found.</p>;

  return (
    <div>
      <h1>{event.title}</h1>
      <button onClick={() => setRsvp("going")}>Going</button>
    </div>
  );
}
```

`useEvent` returns a `Partial<UseEventDataValues>` (empty object outside a provider).

## useEventData

Manage an event without the provider. Pass either a pre-fetched `event` or an `eventId` to fetch.

```tsx theme={null}
import { useEventData } from "@sublay/react-js";

function EventCard({ eventId }: { eventId: string }) {
  const { event, setRsvp } = useEventData({ eventId, include: "userRsvp" });
  // ...
}
```

### Parameters

<ParamField type="Event">A pre-fetched event. Use this or `eventId`.</ParamField>
<ParamField type="string">An event ID to fetch. Use this or `event`.</ParamField>
<ParamField type="string | string[]">Associations to expand when fetching by `eventId`.</ParamField>

## Returns (both hooks)

<ResponseField name="event" type="Event | null | undefined">The event. `undefined` while loading, `null` if not found.</ResponseField>
<ResponseField name="setEvent" type="React.Dispatch">Set the event state directly (optimistic updates).</ResponseField>
<ResponseField name="updateEvent" type="(props: { update }) => Promise<Event | undefined>">Update mutable fields (host-only).</ResponseField>
<ResponseField name="deleteEvent" type="() => Promise<void>">Delete the event (host-only).</ResponseField>
<ResponseField name="cancelEvent" type="() => Promise<Event | undefined>">Cancel the event (host-only).</ResponseField>
<ResponseField name="setRsvp" type="(status: RsvpStatus) => Promise<Event | undefined>">Set/change the caller's RSVP.</ResponseField>
<ResponseField name="withdrawRsvp" type="() => Promise<Event | undefined>">Withdraw the caller's RSVP.</ResponseField>

## See Also

* [EventProvider & useEvent guide](/sdk/events/provider-and-hook)
* [Event data model](/data-models/event)


# useFetchEvent
Source: https://docs.sublay.io/v7/hooks/events/use-fetch-event

Fetch a single event by ID

## Overview

`useFetchEvent` returns a callable that fetches one event by ID. Visibility is enforced server-side: if the event doesn't exist or the logged-in user can't see it, the request returns `404`. Pass `include` to expand associations and populate `userRsvp`.

## Usage Example

```tsx theme={null}
import { useFetchEvent } from "@sublay/react-js";

function useLoadEvent(eventId: string) {
  const fetchEvent = useFetchEvent();
  return () => fetchEvent({ eventId, include: ["user", "files", "userRsvp"] });
}
```

## Parameters

<ParamField type="string">The event ID.</ParamField>

<ParamField type="string | string[]">
  Associations to expand: `"user"`, `"space"`, `"files"`, `"userRsvp"`.
</ParamField>

## Returns

Returns a `Promise<Event>` — the [Event](/data-models/event).

## See Also

* [Fetch Event API](/api-reference/events/fetch-event)
* [EventProvider & useEvent](/sdk/events/provider-and-hook)


# useFetchEventRsvps
Source: https://docs.sublay.io/v7/hooks/events/use-fetch-event-rsvps

Fetch the named guest list (who RSVP'd) for an event

## Overview

`useFetchEventRsvps` returns a callable that fetches the paginated named RSVP (guest) list. Each item is an [EventRsvp](/data-models/event-rsvp) with the `user` populated. The named list is visible to hosts always, and to any viewer when the event's `guestListVisible` is `true` (otherwise `403`). Aggregate counts are always available on the event's `rsvpCounts`.

## Usage Example

```tsx theme={null}
import { useFetchEventRsvps } from "@sublay/react-js";

function useGuestList(eventId: string) {
  const fetchEventRsvps = useFetchEventRsvps();
  return () => fetchEventRsvps({ eventId, status: "going,maybe", page: 1, limit: 20 });
}
```

## Parameters

<ParamField type="string">The event ID.</ParamField>
<ParamField type="string">Comma-separated statuses to filter by, e.g. `"going,maybe"`. Omit for all.</ParamField>
<ParamField type="number">Page number (1-indexed). Defaults to `1`.</ParamField>
<ParamField type="number">Results per page. Capped at `100`.</ParamField>

## Returns

Returns a `Promise<PaginatedResponse<EventRsvp>>` — `{ data, pagination }`.

## See Also

* [Fetch Event RSVPs API](/api-reference/events/fetch-event-rsvps)
* [useFetchInvitees](/hooks/events/use-fetch-invitees)


# useFetchInvitees
Source: https://docs.sublay.io/v7/hooks/events/use-fetch-invitees

Fetch an event's invited users (host-only)

## Overview

`useFetchInvitees` returns a callable that fetches the paginated invitee (guest) list for an event. **Host-only** — non-hosts receive `403`. Each item is an [EventInvite](/data-models/event-invite) with the invited `user` populated.

## Usage Example

```tsx theme={null}
import { useFetchInvitees } from "@sublay/react-js";

function useInvitees(eventId: string) {
  const fetchInvitees = useFetchInvitees();
  return () => fetchInvitees({ eventId, page: 1, limit: 20 });
}
```

## Parameters

<ParamField type="string">The event ID.</ParamField>
<ParamField type="number">Page number (1-indexed). Defaults to `1`.</ParamField>
<ParamField type="number">Results per page. Capped at `100`.</ParamField>

## Returns

Returns a `Promise<PaginatedResponse<EventInvite>>` — `{ data, pagination }`.

## See Also

* [Fetch Invitees API](/api-reference/events/fetch-invitees)
* [useFetchEventRsvps](/hooks/events/use-fetch-event-rsvps)


# useFetchManyEvents
Source: https://docs.sublay.io/v7/hooks/events/use-fetch-many-events

Low-level one-shot query for a page of events

## Overview

`useFetchManyEvents` returns a callable that fetches a single page of events with all filters, sorting, geo, and free-text search. Visibility is enforced server-side. This is the low-level query — for a stateful list with sort state and load-more, use [`useFetchManyEventsWrapper`](/hooks/events/use-fetch-many-events-wrapper).

## Usage Example

```tsx theme={null}
import { useFetchManyEvents } from "@sublay/react-js";

function useUpcoming() {
  const fetchManyEvents = useFetchManyEvents();
  return () =>
    fetchManyEvents({
      timeWindow: "upcoming",
      sortBy: "startTime",
      type: "physical",
      page: 1,
      limit: 20,
      include: ["userRsvp"],
    });
}
```

## Parameters

<ParamField type="number">Page number (1-indexed). Defaults to `1`.</ParamField>
<ParamField type="number">Results per page. Capped at `100`.</ParamField>
<ParamField type="&#x22;startTime&#x22; | &#x22;going&#x22;">Sort field. Defaults to `"startTime"`.</ParamField>
<ParamField type="&#x22;asc&#x22; | &#x22;desc&#x22;">Sort direction. Defaults to `"asc"`.</ParamField>
<ParamField type="&#x22;upcoming&#x22; | &#x22;ongoing&#x22; | &#x22;past&#x22;">Derived time window.</ParamField>
<ParamField type="string">ISO datetime lower bound on `startTime`.</ParamField>
<ParamField type="string">ISO datetime upper bound on `startTime`.</ParamField>
<ParamField type="string">Restrict to one space.</ParamField>
<ParamField type="string">Only events this user hosts.</ParamField>
<ParamField type="&#x22;online&#x22; | &#x22;physical&#x22; | &#x22;hybrid&#x22;">Filter by type.</ParamField>
<ParamField type="&#x22;active&#x22; | &#x22;cancelled&#x22;">Defaults to `"active"`.</ParamField>
<ParamField type="RsvpStatus | RsvpStatus[]">Statuses the logged-in user RSVP'd with, e.g. `["going","maybe"]`.</ParamField>
<ParamField type="{ latitude; longitude; radius }">Proximity filter (radius in meters).</ParamField>
<ParamField type="{ hasTitle?; includes?; doesNotInclude? }">Free-text filter on `title`.</ParamField>
<ParamField type="{ hasDescription?; includes?; doesNotInclude? }">Free-text filter on `description`.</ParamField>
<ParamField type="string | string[]">Associations to expand.</ParamField>

## Returns

Returns a `Promise<PaginatedResponse<Event>>` — `{ data, pagination }`.

## See Also

* [useFetchManyEventsWrapper](/hooks/events/use-fetch-many-events-wrapper)
* [Fetch Many Events API](/api-reference/events/fetch-many-events)


# useFetchManyEventsWrapper
Source: https://docs.sublay.io/v7/hooks/events/use-fetch-many-events-wrapper

Stateful, paginated events list with sorting and load-more

## Overview

`useFetchManyEventsWrapper` wraps [`useFetchManyEvents`](/hooks/events/use-fetch-many-events) into a ready-to-render list: it holds the accumulated `events`, tracks `loading`/`hasMore`, manages sort state, and exposes `loadMore` and `refresh`. It mirrors `useFetchManyEntitiesWrapper`. Visibility is enforced server-side, so the list only contains events the current user may see.

Changing any filter prop (or calling `refresh`) resets the list to page 1.

## Usage Example

```tsx theme={null}
import { useFetchManyEventsWrapper } from "@sublay/react-js";

function EventsList() {
  const { events, loading, hasMore, loadMore, sortBy, setSortBy, refresh } =
    useFetchManyEventsWrapper({
      timeWindow: "upcoming",
      limit: 20,
      include: "userRsvp",
    });

  return (
    <>
      <button onClick={() => setSortBy("going")}>Sort by popularity</button>
      {events.map((e) => (
        <article key={e.id}>
          <h3>{e.title}</h3>
          <span>{e.rsvpCounts.going} going</span>
        </article>
      ))}
      {hasMore && <button disabled={loading} onClick={loadMore}>Load more</button>}
    </>
  );
}
```

## Parameters

<ParamField type="number">Page size. Defaults to `10`.</ParamField>
<ParamField type="string | null">Restrict to one space.</ParamField>
<ParamField type="string | null">Only events this user hosts.</ParamField>
<ParamField type="&#x22;online&#x22; | &#x22;physical&#x22; | &#x22;hybrid&#x22; | null">Filter by type.</ParamField>
<ParamField type="&#x22;active&#x22; | &#x22;cancelled&#x22; | null">Filter by status.</ParamField>
<ParamField type="&#x22;upcoming&#x22; | &#x22;ongoing&#x22; | &#x22;past&#x22; | null">Derived time window.</ParamField>
<ParamField type="string | null">ISO datetime lower bound.</ParamField>
<ParamField type="string | null">ISO datetime upper bound.</ParamField>
<ParamField type="RsvpStatus | RsvpStatus[] | null">Statuses the logged-in user RSVP'd with.</ParamField>
<ParamField type="object | null">Proximity filter.</ParamField>
<ParamField type="object | null">Free-text filter on `title`.</ParamField>
<ParamField type="object | null">Free-text filter on `description`.</ParamField>
<ParamField type="string | string[]">Associations to expand.</ParamField>
<ParamField type="&#x22;startTime&#x22; | &#x22;going&#x22;">Initial sort field. Defaults to `"startTime"`.</ParamField>
<ParamField type="&#x22;asc&#x22; | &#x22;desc&#x22;">Initial sort direction. Defaults to `"asc"`.</ParamField>

## Returns

<ResponseField name="events" type="Event[]">The accumulated events.</ResponseField>
<ResponseField name="loading" type="boolean">`true` while fetching.</ResponseField>
<ResponseField name="hasMore" type="boolean">Whether more pages remain.</ResponseField>
<ResponseField name="sortBy" type="&#x22;startTime&#x22; | &#x22;going&#x22;">Current sort field.</ResponseField>
<ResponseField name="sortDir" type="&#x22;asc&#x22; | &#x22;desc&#x22;">Current sort direction.</ResponseField>
<ResponseField name="setSortBy" type="(s) => void">Change the sort field (resets to page 1).</ResponseField>
<ResponseField name="setSortDir" type="(d) => void">Change the sort direction (resets to page 1).</ResponseField>
<ResponseField name="loadMore" type="() => void">Advance to the next page.</ResponseField>
<ResponseField name="refresh" type="() => void">Re-run the query from page 1.</ResponseField>

## See Also

* [Events Overview](/sdk/events/overview)
* [Fetch Many Events API](/api-reference/events/fetch-many-events)


# useRemoveHost
Source: https://docs.sublay.io/v7/hooks/events/use-remove-host

Revoke a user's host privileges on an event (host-only)

## Overview

`useRemoveHost` returns a callable that removes a user from an event's `hostIds`. **Host-only.** Rejected with `event/last-host` (409) if the removal would leave the event with no hosts.

## Usage Example

```tsx theme={null}
import { useRemoveHost } from "@sublay/react-js";

function RemoveCoHost({ eventId }: { eventId: string }) {
  const removeHost = useRemoveHost();
  return (
    <button onClick={() => removeHost({ eventId, userId: "usr_cohost" })}>
      Remove co-host
    </button>
  );
}
```

## Parameters

<ParamField type="string">The event ID.</ParamField>
<ParamField type="string">The host to remove.</ParamField>

## Returns

Returns a `Promise<Event>` — the [Event](/data-models/event) with the new `hostIds`.

## See Also

* [Remove Host API](/api-reference/events/remove-host)
* [useAddHost](/hooks/events/use-add-host)


# useRemoveInvite
Source: https://docs.sublay.io/v7/hooks/events/use-remove-invite

Revoke a user's invite to an event (host-only)

## Overview

`useRemoveInvite` returns a callable that removes a user's invite. **Host-only.** Removing the invite revokes access to an `invite`-only event and also deletes that user's RSVP (decrementing the count). Removing a non-invited user is an idempotent no-op.

## Usage Example

```tsx theme={null}
import { useRemoveInvite } from "@sublay/react-js";

function UninviteButton({ eventId }: { eventId: string }) {
  const removeInvite = useRemoveInvite();
  return (
    <button onClick={() => removeInvite({ eventId, userId: "usr_guest" })}>
      Remove invite
    </button>
  );
}
```

## Parameters

<ParamField type="string">The event ID.</ParamField>
<ParamField type="string">The invitee to remove.</ParamField>

## Returns

Returns a `Promise<Event>` — the updated [Event](/data-models/event) with refreshed `rsvpCounts`.

## See Also

* [Remove Invite API](/api-reference/events/remove-invite)
* [useAddInvite](/hooks/events/use-add-invite)


# useSetRsvp
Source: https://docs.sublay.io/v7/hooks/events/use-set-rsvp

Set or change the logged-in user's RSVP to an event

## Overview

`useSetRsvp` returns a callable that sets or changes the logged-in user's RSVP. The event's `rsvpCounts` update atomically. A transition into `going` is capacity-checked. RSVPs close at `startTime`, are rejected on cancelled events, and `"maybe"` is rejected when `allowMaybe` is `false`.

## Usage Example

```tsx theme={null}
import { useSetRsvp } from "@sublay/react-js";

function GoingButton({ eventId }: { eventId: string }) {
  const setRsvp = useSetRsvp();
  return <button onClick={() => setRsvp({ eventId, status: "going" })}>Going</button>;
}
```

## Parameters

<ParamField type="string">The event ID.</ParamField>
<ParamField type="&#x22;going&#x22; | &#x22;maybe&#x22; | &#x22;not_going&#x22;">The RSVP response.</ParamField>

## Returns

Returns a `Promise<Event>` — the [Event](/data-models/event) with refreshed `rsvpCounts` and `userRsvp`.

## See Also

* [Set RSVP API](/api-reference/events/set-rsvp)
* [useWithdrawRsvp](/hooks/events/use-withdraw-rsvp)


# useUpdateEvent
Source: https://docs.sublay.io/v7/hooks/events/use-update-event

Edit an event's fields and curate its cover and gallery images (host-only)

## Overview

`useUpdateEvent` returns a callable that edits an event. **Host-only.** The mutable fields go under `update`; `hostIds`, `status`, and `spaceId` are not editable here. Pass `cover` to **replace** the cover, `gallery` to **append** images, and `update.removeImageIds` to remove existing event images — any image operation sends `multipart/form-data` and requires the `files-images` bundle.

## Usage Example

```tsx theme={null}
import { useUpdateEvent } from "@sublay/react-js";

function EditEvent({ eventId }: { eventId: string }) {
  const updateEvent = useUpdateEvent();

  const handleSave = async (newCover: File) => {
    const event = await updateEvent({
      eventId,
      update: { capacity: 150, description: "Now with more space!" },
      cover: { file: newCover, options: { mode: "original-aspect", sizes: { full: 1600 } } },
    });
    console.log("Updated:", event.id);
  };
}
```

## Parameters

<ParamField type="string">The event to update.</ParamField>

<ParamField type="object">
  The mutable fields to change. All optional:
  `title`, `description`, `startTime`, `endTime`, `timezone`, `type`, `url`,
  `venueName`, `address`, `location` (`{ latitude, longitude }`), `visibility`,
  `capacity`, `allowMaybe`, `guestListVisible`, `metadata`, and `removeImageIds`
  (`string[]` — File IDs of existing event images to remove).
</ParamField>

<ParamField type="{ file: File | RNFile; options?: UploadImageOptions }">
  New cover image — replaces the existing cover. Sends multipart.
</ParamField>

<ParamField type="{ files: (File | RNFile)[]; options?: UploadImageOptions }">
  Gallery images to append. Sends multipart.
</ParamField>

## Returns

Returns a `Promise<Event>` — the updated [Event](/data-models/event).

## See Also

* [Update Event API](/api-reference/events/update-event)
* [EventProvider & useEvent](/sdk/events/provider-and-hook)


# useWithdrawRsvp
Source: https://docs.sublay.io/v7/hooks/events/use-withdraw-rsvp

Remove the logged-in user's RSVP from an event

## Overview

`useWithdrawRsvp` returns a callable that removes the logged-in user's RSVP. The RSVP row is deleted and the matching count decremented. It is idempotent — withdrawing with no RSVP succeeds and changes nothing.

## Usage Example

```tsx theme={null}
import { useWithdrawRsvp } from "@sublay/react-js";

function WithdrawButton({ eventId }: { eventId: string }) {
  const withdrawRsvp = useWithdrawRsvp();
  return <button onClick={() => withdrawRsvp({ eventId })}>Withdraw RSVP</button>;
}
```

## Parameters

<ParamField type="string">The event ID.</ParamField>

## Returns

Returns a `Promise<Event>` — the [Event](/data-models/event) with refreshed `rsvpCounts`.

## See Also

* [Withdraw RSVP API](/api-reference/events/withdraw-rsvp)
* [useSetRsvp](/hooks/events/use-set-rsvp)


# Add reaction
Source: https://docs.sublay.io/v7/hooks/reactions/use-add-reaction

Add a reaction to an entity or comment

## Overview

`useAddReaction` is a low-level hook that adds a reaction to an entity or comment. For most use cases, use [`useReactionToggle`](/hooks/reactions/use-reaction-toggle) instead — it handles toggling, optimistic updates, and state management automatically.

<Note>Requires an authenticated user.</Note>

## Usage Example

```tsx theme={null}
import { useAddReaction } from "@sublay/react-js";

function UpvoteButton({ entityId }: { entityId: string }) {
  const addReaction = useAddReaction();

  const handleUpvote = async () => {
    await addReaction({
      targetType: "entity",
      targetId: entityId,
      reactionType: "upvote",
    });
  };

  return <button onClick={handleUpvote}>Upvote</button>;
}
```

## Parameters

<ParamField type="&#x22;entity&#x22; | &#x22;comment&#x22;">
  The type of the reaction target.
</ParamField>

<ParamField type="string">
  The ID of the entity or comment.
</ParamField>

<ParamField type="ReactionType">
  The reaction to add: `"upvote"`, `"downvote"`, `"like"`, `"love"`, `"wow"`, `"sad"`, `"angry"`, or `"funny"`.
</ParamField>

## Returns

<ResponseField name="Entity | Comment" type="Entity | Comment">
  The updated entity or comment with new `reactionCounts` and `userReaction`.
</ResponseField>


# Fetch comment reactions
Source: https://docs.sublay.io/v7/hooks/reactions/use-fetch-comment-reactions

Fetch a paginated list of users who reacted to a comment

## Overview

`useFetchCommentReactions` returns a function that fetches individual reaction records for a comment. Use this to show "who reacted" lists, optionally filtered by a specific reaction type.

<Note>
  Authentication is optional — the endpoint works without a token. When the
  caller is signed in, reactions from users with a block between them and the
  caller, in either direction, are excluded from both the results and the
  count. Block filtering requires the `moderation` bundle.
</Note>

## Usage Example

```tsx theme={null}
import { useFetchCommentReactions } from "@sublay/react-js";
import { useState } from "react";

function CommentLikers({ commentId }: { commentId: string }) {
  const fetchReactions = useFetchCommentReactions();
  const [reactions, setReactions] = useState([]);

  const load = async () => {
    const res = await fetchReactions({ commentId, page: 1, reactionType: "like" });
    setReactions(res.data);
  };

  return <button onClick={load}>See who liked</button>;
}
```

## Parameters

<ParamField type="string">
  The comment to fetch reactions for.
</ParamField>

<ParamField type="number">
  Page number (1-indexed).
</ParamField>

<ParamField type="number">
  Results per page. Default: `20`.
</ParamField>

<ParamField type="ReactionType">
  Filter to a specific reaction type.
</ParamField>

<ParamField type="&#x22;asc&#x22; | &#x22;desc&#x22;">
  Sort direction by creation date. Default: `"desc"`.
</ParamField>

<SpaceReputationParams />

## Returns

<ResponseField name="data" type="Reaction[]">
  Array of reaction records. Each includes `id`, `userId`, `reactionType`, `targetId`, `targetType`, `createdAt`. The `user` field is populated when user data is available; when `spaceReputation` is requested it carries an added `spaceReputation` number. See [Reputation](/data-models/reputation).
</ResponseField>

<ResponseField name="pagination" type="PaginationMetadata">
  Pagination metadata for the result set.

  * `page` — current page number
  * `pageSize` — number of results returned
  * `totalItems` — total number of reactions matching the query
  * `totalPages` — total number of pages
  * `hasMore` — whether additional pages are available
</ResponseField>


# Use comment reactions
Source: https://docs.sublay.io/v7/hooks/reactions/use-fetch-comment-reactions-wrapper

Stateful, paginated list of reactions on a comment

## Overview

`useFetchCommentReactionsWrapper` is a stateful wrapper around [`useFetchCommentReactions`](/hooks/reactions/use-fetch-comment-reactions) that manages pagination and reaction list state for you. Use it to build "who reacted" UIs for comments — for example, a popover showing users who liked a specific comment.

By default the hook does not fetch on mount. Set `autoFetch: true` to start fetching immediately, or call `refetch()` manually when you're ready (e.g., when a popover opens).

## Usage Example

```tsx theme={null}
import { useFetchCommentReactionsWrapper } from "@sublay/react-js";

function CommentReactions({ commentId }: { commentId: string }) {
  const { reactions, loading, hasMore, loadMore, refetch } =
    useFetchCommentReactionsWrapper({
      commentId,
      reactionType: "like",
      limit: 20,
      autoFetch: true,
    });

  return (
    <div>
      <ul>
        {reactions.map((r) => (
          <li key={r.id}>{r.user?.username}</li>
        ))}
      </ul>
      {hasMore && (
        <button onClick={loadMore} disabled={loading}>
          Load more
        </button>
      )}
    </div>
  );
}
```

## Parameters

<ParamField type="string">
  The comment to fetch reactions for.
</ParamField>

<ParamField type="number">
  Number of reactions per page. Default: `20`.
</ParamField>

<ParamField type="ReactionType">
  Filter to a specific reaction type. When omitted, all reaction types are returned.
</ParamField>

<ParamField type="&#x22;asc&#x22; | &#x22;desc&#x22;">
  Sort direction by creation date. Default: `"desc"`.
</ParamField>

<ParamField type="boolean">
  If `true`, fetch automatically on mount. Default: `false`.
</ParamField>

## Returns

<ResponseField name="reactions" type="Reaction[]">
  The current list of fetched reactions. Appended to on each `loadMore` call.
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` while fetching the initial page or loading more.
</ResponseField>

<ResponseField name="hasMore" type="boolean">
  `true` if additional pages are available.
</ResponseField>

<ResponseField name="loadMore" type="() => void">
  Load the next page of reactions. Appends to the existing list.
</ResponseField>

<ResponseField name="refetch" type="() => void">
  Reset and re-fetch from page 1.
</ResponseField>


# Fetch entity reactions
Source: https://docs.sublay.io/v7/hooks/reactions/use-fetch-entity-reactions

Fetch a paginated list of users who reacted to an entity

## Overview

`useFetchEntityReactions` returns a function that fetches individual reaction records for an entity. Use this to show "who reacted" lists, optionally filtered by a specific reaction type.

<Note>
  Authentication is optional — the endpoint works without a token. When the
  caller is signed in, reactions from users with a block between them and the
  caller, in either direction, are excluded from both the results and the
  count. Block filtering requires the `moderation` bundle.
</Note>

## Usage Example

```tsx theme={null}
import { useFetchEntityReactions } from "@sublay/react-js";
import { useState, useEffect } from "react";

function WhoUpvoted({ entityId }: { entityId: string }) {
  const fetchReactions = useFetchEntityReactions();
  const [reactions, setReactions] = useState([]);

  useEffect(() => {
    fetchReactions({ entityId, page: 1, reactionType: "upvote" }).then(
      (res) => setReactions(res.data)
    );
  }, [entityId]);

  return (
    <ul>
      {reactions.map((r) => <li key={r.id}>{r.user?.username}</li>)}
    </ul>
  );
}
```

## Parameters

<ParamField type="string">
  The entity to fetch reactions for.
</ParamField>

<ParamField type="number">
  Page number (1-indexed).
</ParamField>

<ParamField type="number">
  Results per page. Default: `20`.
</ParamField>

<ParamField type="ReactionType">
  Filter to a specific reaction type.
</ParamField>

<ParamField type="&#x22;asc&#x22; | &#x22;desc&#x22;">
  Sort direction by creation date. Default: `"desc"`.
</ParamField>

<SpaceReputationParams />

## Returns

<ResponseField name="data" type="Reaction[]">
  Array of reaction records. Each includes `id`, `userId`, `reactionType`, `targetId`, `targetType`, `createdAt`. The `user` field is populated when user data is available; when `spaceReputation` is requested it carries an added `spaceReputation` number. See [Reputation](/data-models/reputation).
</ResponseField>

<ResponseField name="pagination" type="PaginationMetadata">
  Pagination metadata for the result set.

  * `page` — current page number
  * `pageSize` — number of results returned
  * `totalItems` — total number of reactions matching the query
  * `totalPages` — total number of pages
  * `hasMore` — whether additional pages are available
</ResponseField>


# Use entity reactions
Source: https://docs.sublay.io/v7/hooks/reactions/use-fetch-entity-reactions-wrapper

Stateful, paginated list of reactions on an entity

## Overview

`useFetchEntityReactionsWrapper` is a stateful wrapper around [`useFetchEntityReactions`](/hooks/reactions/use-fetch-entity-reactions) that manages pagination and reaction list state for you. Use it to build "who reacted" UIs — for example, a modal showing all users who upvoted a post, with infinite scroll.

By default the hook does not fetch on mount. Set `autoFetch: true` to start fetching immediately, or call `refetch()` manually when you're ready (e.g., when a modal opens).

## Usage Example

```tsx theme={null}
import { useFetchEntityReactionsWrapper } from "@sublay/react-js";

function WhoReacted({ entityId }: { entityId: string }) {
  const { reactions, loading, hasMore, loadMore, refetch } =
    useFetchEntityReactionsWrapper({
      entityId,
      reactionType: "upvote",
      limit: 20,
      autoFetch: true,
    });

  return (
    <div>
      <ul>
        {reactions.map((r) => (
          <li key={r.id}>{r.user?.username}</li>
        ))}
      </ul>
      {hasMore && (
        <button onClick={loadMore} disabled={loading}>
          Load more
        </button>
      )}
    </div>
  );
}
```

## Parameters

<ParamField type="string">
  The entity to fetch reactions for.
</ParamField>

<ParamField type="number">
  Number of reactions per page. Default: `20`.
</ParamField>

<ParamField type="ReactionType">
  Filter to a specific reaction type. When omitted, all reaction types are returned.
</ParamField>

<ParamField type="&#x22;asc&#x22; | &#x22;desc&#x22;">
  Sort direction by creation date. Default: `"desc"`.
</ParamField>

<ParamField type="boolean">
  If `true`, fetch automatically on mount. Default: `false`.
</ParamField>

## Returns

<ResponseField name="reactions" type="Reaction[]">
  The current list of fetched reactions. Appended to on each `loadMore` call.
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` while fetching the initial page or loading more.
</ResponseField>

<ResponseField name="hasMore" type="boolean">
  `true` if additional pages are available.
</ResponseField>

<ResponseField name="loadMore" type="() => void">
  Load the next page of reactions. Appends to the existing list.
</ResponseField>

<ResponseField name="refetch" type="() => void">
  Reset and re-fetch from page 1.
</ResponseField>


# Toggle reaction
Source: https://docs.sublay.io/v7/hooks/reactions/use-reaction-toggle

Manage reaction state with optimistic updates and toggle behavior

## Overview

`useReactionToggle` is the recommended hook for reaction UIs. It manages the current reaction and reaction counts locally with optimistic updates, handles toggling (selecting the same reaction removes it), and reverts on error.

It works for both entities and comments via the `targetType` prop.

## Usage Example

```tsx theme={null}
import { useReactionToggle } from "@sublay/react-js";

function ReactionBar({ entity }) {
  const { currentReaction, reactionCounts, toggleReaction, loading } = useReactionToggle({
    targetType: "entity",
    targetId: entity.id,
    initialReaction: entity.userReaction,
    initialReactionCounts: entity.reactionCounts,
  });

  const reactions = ["upvote", "like", "love", "wow", "funny"] as const;

  return (
    <div>
      {reactions.map((type) => (
        <button
          key={type}
          onClick={() => toggleReaction({ reactionType: type })}
          disabled={loading}
          style={{ fontWeight: currentReaction === type ? "bold" : "normal" }}
        >
          {type} ({reactionCounts[type] ?? 0})
        </button>
      ))}
    </div>
  );
}
```

## Props

<ParamField type="&#x22;entity&#x22; | &#x22;comment&#x22;">
  Whether the reaction target is an entity or a comment.
</ParamField>

<ParamField type="string | undefined">
  The ID of the entity or comment.
</ParamField>

<ParamField type="ReactionType | null">
  The authenticated user's current reaction, if any. Sourced from `entity.userReaction` or `comment.userReaction`.
</ParamField>

<ParamField type="ReactionCounts | null">
  The current reaction counts object. Sourced from `entity.reactionCounts` or `comment.reactionCounts`.
</ParamField>

## Return Values

<ResponseField name="currentReaction" type="ReactionType | null">
  The authenticated user's current reaction. Updates optimistically on `toggleReaction`.
</ResponseField>

<ResponseField name="reactionCounts" type="Partial<ReactionCounts>">
  The current reaction counts. Updated optimistically and corrected from server response.
</ResponseField>

<ResponseField name="toggleReaction" type="(props: { reactionType: ReactionType }) => Promise<Entity | Comment | null>">
  Toggles the given reaction. If the user already has this reaction, it is removed. If a different reaction is active, it is replaced. Returns the updated entity or comment from the server, or `null` on error.
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` while a toggle request is in flight. Prevents concurrent reactions.
</ResponseField>


# Remove reaction
Source: https://docs.sublay.io/v7/hooks/reactions/use-remove-reaction

Remove the authenticated user's reaction from an entity or comment

## Overview

`useRemoveReaction` is a low-level hook that removes the authenticated user's current reaction. For most use cases, use [`useReactionToggle`](/hooks/reactions/use-reaction-toggle) instead.

<Note>Requires an authenticated user.</Note>

## Usage Example

```tsx theme={null}
import { useRemoveReaction } from "@sublay/react-js";

function RemoveReactionButton({ entityId }: { entityId: string }) {
  const removeReaction = useRemoveReaction();

  const handle = async () => {
    await removeReaction({ targetType: "entity", targetId: entityId });
  };

  return <button onClick={handle}>Remove Reaction</button>;
}
```

## Parameters

<ParamField type="&#x22;entity&#x22; | &#x22;comment&#x22;">
  The type of the reaction target.
</ParamField>

<ParamField type="string">
  The ID of the entity or comment.
</ParamField>

## Returns

<ResponseField name="Entity | Comment" type="Entity | Comment">
  The updated entity or comment with the reaction removed (`userReaction: null` and decremented counts).
</ResponseField>


# useCreateReputationGrant
Source: https://docs.sublay.io/v7/hooks/reputation/use-create-reputation-grant

Transfer reputation from the logged-in user to another user

## Overview

`useCreateReputationGrant` returns a callable that transfers reputation from the logged-in user to another user. The amount leaves the sender's bucket and lands in the recipient's bucket **for the same space** — nothing is created, and reputation never crosses between the project-general bucket and a space bucket.

There is no actor argument: the sender is always the user the token belongs to. Naming a different sender requires a service key, which the React SDK never holds — see [`@sublay/node`](/v7/node-sdk/reputation).

Requires the `reputation` bundle.

## Usage Example

```tsx theme={null}
import { useCreateReputationGrant } from "@sublay/react-js";

function RewardAnswer({ answer }) {
  const createReputationGrant = useCreateReputationGrant();

  const handleReward = async () => {
    const grant = await createReputationGrant({
      recipientId: answer.userId,
      amount: 50,
      spaceId: answer.spaceId,
      note: "Best answer",
      targetType: "comment",
      targetId: answer.id,
    });
    console.log("Granted:", grant.id);
  };

  return <button onClick={handleReward}>Reward 50</button>;
}
```

## Parameters

<ParamField type="string">
  The user receiving the reputation. Cannot be the logged-in user.
</ParamField>

<ParamField type="number">
  Whole number from `1` to `2147483647` (the signed 32-bit maximum, which is also the width of a reputation balance). A transfer can never be zero, negative, or fractional, and it can never exceed what the sender holds in the source bucket.
</ParamField>

<ParamField type="string | null">
  The bucket both legs move in. Omitted or `null` = the project-general bucket. The space is validated before anything moves: an ID naming no space rejects with `404 reputation-grant/space-not-found`, and naming one at all on a project without the `spaces` bundle rejects with `403 database/tables-not-available`.
</ParamField>

<ParamField type="string | null">
  Free-text note. Trimmed, up to 2000 characters.
</ParamField>

<ParamField type="Record<string, any>">
  Arbitrary key-value data. Up to 1 MB. Omit when unused.
</ParamField>

<ParamField type="&#x22;entity&#x22; | &#x22;comment&#x22; | &#x22;chat-message&#x22;">
  What the grant is for. Must be supplied together with `targetId`. The target is an annotation — it never determines which bucket is used, and it need not be authored by the recipient.
</ParamField>

<ParamField type="string">
  The rewarded record's ID. Must be supplied together with `targetType`, and must exist.
</ParamField>

## Returns

Returns a `Promise<ReputationGrant>` — the created [ReputationGrant](/data-models/reputation-grant), with `sourceType: "user"`.

## Failure Modes

The hook validates locally before the round trip and throws for a missing `projectId`, a missing `recipientId` or `amount`, or a half-filled target (`targetType` without `targetId`, or vice versa).

Server rejections surface as the axios error, most usefully:

| Status | Code                                       | Meaning                                                                                                                                                                               |
| ------ | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `reputation-grant/invalid-body`            | The body failed schema validation. `error` is the field path followed by the message, e.g. `"amount: Too small: expected number to be >=1"`.                                          |
| `400`  | `reputation-grant/self-grant`              | The recipient is the logged-in user.                                                                                                                                                  |
| `403`  | `reputation-grant/user-grants-disabled`    | The project has `settings.reputationGrants.allowUserInitiated` set to `false` (**Settings → SDK** in the dashboard). Route the grant through your backend with a service key instead. |
| `403`  | `database/tables-not-available`            | The project lacks a table the grant needs — `spaces` for a `spaceId`, or the target's bundle for a `targetType`. `missingTables` names them.                                          |
| `403`  | `user/suspended`                           | A suspended user cannot send grants (they can still receive them).                                                                                                                    |
| `404`  | `reputation-grant/user-not-found`          | The recipient doesn't exist — or one of the two parties has blocked the other. The two answers are identical on purpose.                                                              |
| `404`  | `reputation-grant/space-not-found`         | The `spaceId` names no space in this project. Checked before any balance is touched.                                                                                                  |
| `404`  | `reputation-grant/target-not-found`        | The target doesn't exist, or it is a chat message in a conversation the sender isn't an active member of. The two answers are identical on purpose.                                   |
| `409`  | `reputation-grant/insufficient-reputation` | The chosen bucket is short. Nothing moved.                                                                                                                                            |
| `409`  | `reputation-grant/conflict`                | Concurrent write. Retryable.                                                                                                                                                          |

<Warning>
  **Grant creation is not idempotent.** A retried request creates a second grant and moves the points a second time. Disable your button while the promise is in flight.
</Warning>

## See Also

* [Reputation Grants Overview](/sdk/reputation/overview)
* [Create Reputation Grant API](/api-reference/reputation-grants/create-reputation-grant)
* [ReputationGrant data model](/data-models/reputation-grant)


# Use space list
Source: https://docs.sublay.io/v7/hooks/space-lists/use-space-list

Paginated, filterable list of spaces backed by Redux state

## Overview

`useSpaceList` provides a stateful, paginated list of spaces with support for filtering, sorting, search, and creation. Each list is identified by a `listId` and maintains independent Redux state, allowing multiple lists on the same page.

For full integration guidance, see [Space Lists](/sdk/spaces/space-lists).

## Usage Example

```tsx theme={null}
import { useSpaceList } from "@sublay/react-js";
import { useEffect } from "react";

function SpaceDirectory() {
  const { spaces, loading, hasMore, fetchSpaces, loadMore } = useSpaceList({ listId: "directory" });

  useEffect(() => {
    fetchSpaces({ sortBy: "newest" });
  }, []);

  return (
    <div>
      {spaces.map((space) => <div key={space.id}>{space.name}</div>)}
      {hasMore && <button onClick={loadMore} disabled={loading}>Load more</button>}
    </div>
  );
}
```

## Parameters

<ParamField type="string">
  Unique identifier for this list's Redux state slice. Use distinct IDs for independent lists.
</ParamField>

## Returns

<ResponseField name="spaces" type="Space[]">
  Currently loaded spaces.
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` while fetching.
</ResponseField>

<ResponseField name="hasMore" type="boolean">
  `true` if more pages are available.
</ResponseField>

<ResponseField name="fetchSpaces" type="function">
  Trigger a new fetch. Resets to page 1. Accepts filter and config parameters.

  ```ts theme={null}
  fetchSpaces(
    filters: {
      sortBy?: "newest" | "members" | "alphabetical";
      searchSlug?: string | null;
      searchName?: string | null;
      searchDescription?: string | null;
      searchAny?: string | null;
      memberOf?: boolean;
      parentSpaceId?: string | null;
    },
    config?: { limit?: number },
    options?: { fetchImmediately?: boolean; resetUnspecified?: boolean; clearImmediately?: boolean }
  ) => void
  ```
</ResponseField>

<ResponseField name="loadMore" type="() => void">
  Fetch the next page and append results.
</ResponseField>

<ResponseField name="createSpace" type="function">
  Create a new space and insert it into the list.

  ```ts theme={null}
  createSpace(props: {
    name: string;
    slug?: string | null;
    description?: string | null;
    readingPermission?: "anyone" | "members";
    postingPermission?: "anyone" | "members" | "admins";
    visibility?: "public" | "unlisted" | "private";
    requireJoinApproval?: boolean;
    metadata?: Record<string, any>;
    parentSpaceId?: string | null;
    insertPosition?: "first" | "last";
  }) => Promise<Space | undefined>
  ```

  <Note>
    Space avatars and banners are uploaded as files, not URLs, so they can't be
    set through this hook. Use [useCreateSpace](/hooks/spaces/use-create-space)
    or [useUpdateSpace](/hooks/spaces/use-update-space), which send the image as
    `multipart/form-data`.
  </Note>
</ResponseField>

<ResponseField name="deleteSpace" type="function">
  Delete a space and remove it from the list.

  ```ts theme={null}
  deleteSpace(props: { spaceId: string }) => Promise<void>
  ```
</ResponseField>

<ResponseField name="sortBy" type="string | null">
  Current sort setting from Redux state.
</ResponseField>

<ResponseField name="searchSlug" type="string | null">
  Current slug search query from Redux state.
</ResponseField>

<ResponseField name="searchName" type="string | null">
  Current name search query from Redux state.
</ResponseField>

<ResponseField name="searchDescription" type="string | null">
  Current description search query from Redux state.
</ResponseField>

<ResponseField name="searchAny" type="string | null">
  Current general search query from Redux state.
</ResponseField>

<ResponseField name="memberOf" type="boolean">
  Current membership filter from Redux state.
</ResponseField>

<ResponseField name="parentSpaceId" type="string | null">
  Current parent space filter from Redux state.
</ResponseField>


# Use space list actions
Source: https://docs.sublay.io/v7/hooks/space-lists/use-space-list-actions

Low-level actions for fetching, creating, and deleting spaces in a list

## Overview

`useSpaceListActions` provides the low-level fetch, create, and delete operations used internally by `useSpaceList`. In most cases you should use [`useSpaceList`](/hooks/space-lists/use-space-list) directly, which wraps these actions with Redux state management.

Use this hook only when you need direct control over fetching without the Redux list state layer.

## Usage Example

```tsx theme={null}
import { useSpaceListActions } from "@sublay/react-js";

function CustomSpaceLoader({ listId }: { listId: string }) {
  const actions = useSpaceListActions();

  const loadSpaces = async () => {
    await actions.fetchSpaces(listId, {
      page: 1,
      sortBy: "newest",
      limit: 20,
    });
  };
}
```

## Methods

<ResponseField name="fetchSpaces" type="(listId: string, params: FetchParams) => Promise<Space[] | null>">
  Fetch spaces for the given list. Updates Redux state with the results.
</ResponseField>

<ResponseField name="createSpace" type="(listId: string, props: CreateSpaceProps) => Promise<Space | undefined>">
  Create a space and insert it into the given list's state.
</ResponseField>

<ResponseField name="deleteSpace" type="(listId: string, props: { spaceId: string }) => Promise<void>">
  Delete a space and remove it from the given list's state.
</ResponseField>

<Tip>Prefer `useSpaceList` for most use cases — it handles pagination state, debouncing, and load-more automatically.</Tip>


# Create rule
Source: https://docs.sublay.io/v7/hooks/spaces/rules/use-create-rule

Create a new community rule for a space

## Overview

`useCreateRule` returns a callable function for creating a new community rule. Only space admins can create rules.

## Usage Example

```tsx theme={null}
import { useCreateRule } from "@sublay/react-js";

function AddRuleForm({ spaceId }: { spaceId: string }) {
  const createRule = useCreateRule();

  const handleSubmit = async (title: string, description: string) => {
    const rule = await createRule({ spaceId, title, description });
    console.log("Created rule:", rule.id);
  };
}
```

## Parameters

<ParamField type="string">
  UUID of the space.
</ParamField>

<ParamField type="string">
  Short rule title.
</ParamField>

<ParamField type="string">
  Optional detailed description for the rule.
</ParamField>

## Returns

The created Rule object with all fields including the assigned `order` position.


# Delete rule
Source: https://docs.sublay.io/v7/hooks/spaces/rules/use-delete-rule

Delete a community rule from a space

## Overview

`useDeleteRule` returns a callable function for permanently deleting a rule. Only space admins can delete rules.

## Usage Example

```tsx theme={null}
import { useDeleteRule } from "@sublay/react-js";

function DeleteRuleButton({ spaceId, ruleId }: { spaceId: string; ruleId: string }) {
  const deleteRule = useDeleteRule();

  return (
    <button onClick={() => deleteRule({ spaceId, ruleId })}>
      Delete Rule
    </button>
  );
}
```

## Parameters

<ParamField type="string">
  UUID of the space.
</ParamField>

<ParamField type="string">
  UUID of the rule to delete.
</ParamField>

## Returns

<ResponseField name="message" type="string">
  Confirmation message.
</ResponseField>

<ResponseField name="deletedRule" type="object">
  The `id` and `title` of the deleted rule.
</ResponseField>


# Fetch many rules
Source: https://docs.sublay.io/v7/hooks/spaces/rules/use-fetch-many-rules

Fetch all rules for a space

## Overview

`useFetchManyRules` returns a callable function that fetches all community rules for a space. Rules are publicly readable — no authentication is required.

## Usage Example

```tsx theme={null}
import { useFetchManyRules } from "@sublay/react-js";
import { useEffect, useState } from "react";

function RulesList({ spaceId }: { spaceId: string }) {
  const fetchRules = useFetchManyRules();
  const [rules, setRules] = useState([]);

  useEffect(() => {
    fetchRules({ spaceId }).then(({ data }) => setRules(data));
  }, [spaceId]);

  return (
    <ol>
      {rules.map((rule) => (
        <li key={rule.id}><strong>{rule.title}</strong> — {rule.description}</li>
      ))}
    </ol>
  );
}
```

## Parameters

<ParamField type="string">
  UUID of the space whose rules to fetch.
</ParamField>

## Returns

<ResponseField name="data" type="Rule[]">
  Array of rule objects ordered by their `order` field.
</ResponseField>

<ResponseField name="count" type="number">
  Total number of rules.
</ResponseField>

For the Rule data shape, see [Rules guide](/sdk/spaces/rules).


# Fetch rule
Source: https://docs.sublay.io/v7/hooks/spaces/rules/use-fetch-rule

Fetch a single rule by its ID

## Overview

`useFetchRule` returns a callable function that fetches a single community rule by ID. Rules are publicly readable — no authentication is required.

## Usage Example

```tsx theme={null}
import { useFetchRule } from "@sublay/react-js";

function RuleDetail({ spaceId, ruleId }: { spaceId: string; ruleId: string }) {
  const fetchRule = useFetchRule();

  const loadRule = async () => {
    const rule = await fetchRule({ spaceId, ruleId });
    console.log(rule.title, rule.description);
  };
}
```

## Parameters

<ParamField type="string">
  UUID of the space.
</ParamField>

<ParamField type="string">
  UUID of the rule to fetch.
</ParamField>

## Returns

A single Rule object with `id`, `projectId`, `spaceId`, `title`, `description`, `order`, `lastApprovedBy`, `createdAt`, and `updatedAt`.


# Reorder rules
Source: https://docs.sublay.io/v7/hooks/spaces/rules/use-reorder-rules

Reorder the community rules for a space

## Overview

`useReorderRules` returns a callable function for reordering a space's rules by providing a new ordered array of rule IDs. Only space admins can reorder rules.

## Usage Example

```tsx theme={null}
import { useReorderRules } from "@sublay/react-js";

function RulesDragList({ spaceId, rules }: { spaceId: string; rules: Rule[] }) {
  const reorderRules = useReorderRules();

  const handleDragEnd = async (newOrder: Rule[]) => {
    await reorderRules({
      spaceId,
      ruleIds: newOrder.map((r) => r.id),
    });
  };
}
```

## Parameters

<ParamField type="string">
  UUID of the space.
</ParamField>

<ParamField type="string[]">
  Ordered array of all rule UUIDs in the desired display order.
</ParamField>

## Returns

<ResponseField name="Rule[]" type="Rule[]">
  The full list of rules in their new order. Rules are subsequently returned in this order by `useFetchManyRules`.
</ResponseField>


# Update rule
Source: https://docs.sublay.io/v7/hooks/spaces/rules/use-update-rule

Update an existing community rule

## Overview

`useUpdateRule` returns a callable function for updating a rule's title or description. Only space admins can update rules.

## Usage Example

```tsx theme={null}
import { useUpdateRule } from "@sublay/react-js";

function EditRuleForm({ spaceId, ruleId }: { spaceId: string; ruleId: string }) {
  const updateRule = useUpdateRule();

  const handleSave = async (title: string, description: string) => {
    const updated = await updateRule({ spaceId, ruleId, update: { title, description } });
    console.log("Updated:", updated.title);
  };
}
```

## Parameters

<ParamField type="string">
  UUID of the space.
</ParamField>

<ParamField type="string">
  UUID of the rule to update.
</ParamField>

<ParamField type="object">
  Object containing the fields to update. All fields are optional.

  <Expandable title="update fields">
    <ParamField type="string">
      Updated title.
    </ParamField>

    <ParamField type="string | null">
      Updated description. Pass `null` to clear.
    </ParamField>
  </Expandable>
</ParamField>

## Returns

The updated Rule object.


# Approve member
Source: https://docs.sublay.io/v7/hooks/spaces/use-approve-member

Approve a pending membership request

## Overview

`useApproveMember` returns a callable function for approving a pending join request. Sets the membership status from `"pending"` to `"active"`. Requires the caller to be a moderator or admin.

## Usage Example

```tsx theme={null}
import { useApproveMember } from "@sublay/react-js";

function PendingMemberRow({ spaceId, memberId }: { spaceId: string; memberId: string }) {
  const approve = useApproveMember();

  return (
    <button onClick={() => approve({ spaceId, memberId })}>
      Approve
    </button>
  );
}
```

## Parameters

<ParamField type="string">
  UUID of the space.
</ParamField>

<ParamField type="string">
  UUID of the membership record to approve.
</ParamField>

## Returns

<ResponseField name="message" type="string">
  Confirmation message.
</ResponseField>

<ResponseField name="membership" type="object">
  Updated membership with `id`, `status: "active"`, and `joinedAt`.
</ResponseField>


# Ban member
Source: https://docs.sublay.io/v7/hooks/spaces/use-ban-member

Ban a member from a space

## Overview

`useBanMember` returns a callable function for banning a member from a space by setting their status to `"banned"`. Requires the caller to be a moderator or admin. Moderators can only ban regular members — banning an admin requires being the space creator, and the last remaining admin cannot be banned.

A ban is a standing bar: the member stays out until someone calls [`useUnbanMember`](/hooks/spaces/use-unban-member). It also cascades to the space's child spaces and removes the member from the space chat.

## Usage Example

```tsx theme={null}
import { useBanMember } from "@sublay/react-js";

function MemberActions({ spaceId, memberId }: { spaceId: string; memberId: string }) {
  const banMember = useBanMember();

  return (
    <button onClick={() => banMember({ spaceId, memberId })}>
      Ban Member
    </button>
  );
}
```

## Parameters

<ParamField type="string">
  UUID of the space.
</ParamField>

<ParamField type="string">
  UUID of the membership record to ban.
</ParamField>

## Returns

<ResponseField name="message" type="string">
  Confirmation message.
</ResponseField>

<ResponseField name="membership" type="SpaceMember">
  The updated membership record, with `status` set to `"banned"`.
</ResponseField>

See also: [`useUnbanMember`](/hooks/spaces/use-unban-member) to reverse a ban, and [`useLeaveSpace`](/hooks/spaces/use-leave-space) for a member leaving voluntarily.


# Check my membership
Source: https://docs.sublay.io/v7/hooks/spaces/use-check-my-membership

Check the current user's membership status in a space

## Overview

`useCheckMyMembership` returns a callable function that checks the authenticated user's membership in a specific space without loading the full space object.

## Usage Example

```tsx theme={null}
import { useCheckMyMembership } from "@sublay/react-js";

function MembershipBadge({ spaceId }: { spaceId: string }) {
  const checkMembership = useCheckMyMembership();

  const handleCheck = async () => {
    const result = await checkMembership({ spaceId });
    console.log(result.isMember, result.role, result.status);
  };
}
```

## Parameters

<ParamField type="string">
  UUID of the space to check membership for.
</ParamField>

## Returns

<ResponseField name="isMember" type="boolean">
  Whether the user has an active membership.
</ResponseField>

<ResponseField name="role" type="&#x22;admin&#x22; | &#x22;moderator&#x22; | &#x22;member&#x22; | null">
  The user's role. `null` if not a member.
</ResponseField>

<ResponseField name="status" type="&#x22;pending&#x22; | &#x22;active&#x22; | &#x22;banned&#x22; | &#x22;rejected&#x22; | null">
  The user's membership status. `null` if no membership record exists.
</ResponseField>

<ResponseField name="joinedAt" type="Date | null">
  When the membership was created. `null` if not a member.
</ResponseField>

<ResponseField name="permissions" type="object">
  Resolved permissions: `canPost`, `canModerate`, `canRead`, `isAdmin`, `isModerator`.
</ResponseField>


# Check slug availability
Source: https://docs.sublay.io/v7/hooks/spaces/use-check-slug-availability

Check whether a space slug is available for use

## Overview

`useCheckSlugAvailability` returns a callable function that verifies whether a slug is available in the current project. Useful for live validation in a space creation or settings form.

## Usage Example

```tsx theme={null}
import { useCheckSlugAvailability } from "@sublay/react-js";
import { useState } from "react";

function SlugInput() {
  const checkSlug = useCheckSlugAvailability();
  const [available, setAvailable] = useState<boolean | null>(null);

  const handleBlur = async (slug: string) => {
    const result = await checkSlug({ slug });
    setAvailable(result.available);
  };

  return (
    <div>
      <input onBlur={(e) => handleBlur(e.target.value)} />
      {available === false && <p>Slug is already taken.</p>}
      {available === true && <p>Slug is available!</p>}
    </div>
  );
}
```

## Parameters

<ParamField type="string">
  The slug to check. Must match the slug pattern: letters, numbers, hyphens, and underscores (Unicode supported).
</ParamField>

## Returns

<ResponseField name="available" type="boolean">
  `true` if the slug is not currently in use within the project.
</ResponseField>


# Create space
Source: https://docs.sublay.io/v7/hooks/spaces/use-create-space

Create a new space with optional avatar and banner images

## Overview

`useCreateSpace` returns a callable function for creating a new space. The request can include avatar and banner image uploads. The creator is automatically added as an admin.

## Usage Example

```tsx theme={null}
import { useCreateSpace } from "@sublay/react-js";

function CreateSpaceForm() {
  const createSpace = useCreateSpace();

  const handleSubmit = async () => {
    const space = await createSpace({
      name: "Design Community",
      slug: "design-community",
      description: "A place for designers to share work and ideas.",
      readingPermission: "anyone",
      postingPermission: "members",
      requireJoinApproval: false,
    });
    console.log("Created:", space.id);
  };
}
```

## Parameters

<ParamField type="string">
  Display name for the space. 3–100 characters.
</ParamField>

<ParamField type="string">
  Optional URL slug. Must be unique per project. Supports letters, numbers, hyphens, and underscores (Unicode allowed).
</ParamField>

<ParamField type="string">
  Optional description. Up to 1,000 characters.
</ParamField>

<ParamField type="{ file: File | Blob; options: UploadImageOptions }">
  Optional avatar image to upload. The `options` object controls format, quality, dimensions, and variants.
</ParamField>

<ParamField type="{ file: File | Blob; options: UploadImageOptions }">
  Optional banner image to upload.
</ParamField>

<ParamField type="&#x22;anyone&#x22; | &#x22;members&#x22;">
  Who can read content. Defaults to `"anyone"`.
</ParamField>

<ParamField type="&#x22;anyone&#x22; | &#x22;members&#x22; | &#x22;admins&#x22;">
  Who can post entities. Defaults to `"members"`.
</ParamField>

<ParamField type="&#x22;public&#x22; | &#x22;unlisted&#x22; | &#x22;private&#x22;">
  Whether the space is listed and discoverable. Defaults to `"public"`. Independent of `readingPermission` (which governs content). `"unlisted"` hides the space from discovery and search but keeps it reachable by direct link; `"private"` currently behaves like `"unlisted"`. See [Space visibility](/data-models/space#visibility).
</ParamField>

<ParamField type="boolean">
  The space's own NSFW flag. Defaults to `false`. If the space is created under an NSFW parent, its effective NSFW status is `true` regardless of this value (a live rollup — see [Space NSFW flagging](/data-models/space#nsfw-flagging)). Sublay labels and filters NSFW content; it does not blur or age-gate it.
</ParamField>

<ParamField type="boolean">
  Whether new members must be approved. Defaults to `true`.
</ParamField>

<ParamField type="Record<string, any>">
  Optional custom metadata. Up to 1 MB.
</ParamField>

<ParamField type="string">
  Optional UUID of a parent space. The creator must be an admin of the parent space.
</ParamField>

## Returns

Returns the created [Space](/data-models/space) object.

<Note>When creating a child space, all admins and moderators of the parent space are automatically added to the new child space with their same roles.</Note>


# Decline member
Source: https://docs.sublay.io/v7/hooks/spaces/use-decline-member

Decline a pending membership request

## Overview

`useDeclineMember` returns a callable function for declining a pending join request. Sets the membership status to `"rejected"`. Requires the caller to be a moderator or admin.

## Usage Example

```tsx theme={null}
import { useDeclineMember } from "@sublay/react-js";

function PendingMemberRow({ spaceId, memberId }: { spaceId: string; memberId: string }) {
  const decline = useDeclineMember();

  return (
    <button onClick={() => decline({ spaceId, memberId })}>
      Decline
    </button>
  );
}
```

## Parameters

<ParamField type="string">
  UUID of the space.
</ParamField>

<ParamField type="string">
  UUID of the membership record to decline.
</ParamField>

## Returns

<ResponseField name="message" type="string">
  Confirmation message.
</ResponseField>

<ResponseField name="membership" type="object">
  Updated membership with `id` and `status: "rejected"`.
</ResponseField>


# Delete space
Source: https://docs.sublay.io/v7/hooks/spaces/use-delete-space

Delete a space and all its associated data

## Overview

`useDeleteSpace` returns a callable function for deleting a space. Only space admins can delete a space. Deletion cascades to all entities, members, child spaces, rules, and reports associated with the space.

<Warning>Deleting a space is permanent. All entities, comments, members, child spaces, and rules belonging to the space are also deleted.</Warning>

## Usage Example

```tsx theme={null}
import { useDeleteSpace } from "@sublay/react-js";

function DeleteSpaceButton({ spaceId }: { spaceId: string }) {
  const deleteSpace = useDeleteSpace();

  const handleDelete = async () => {
    if (!confirm("Are you sure? This cannot be undone.")) return;
    await deleteSpace({ spaceId });
  };

  return <button onClick={handleDelete}>Delete Space</button>;
}
```

## Parameters

<ParamField type="string">
  UUID of the space to delete.
</ParamField>

## Returns

<ResponseField name="message" type="string">
  Confirmation message.
</ResponseField>

<ResponseField name="deletedSpace" type="object">
  The `id` and `name` of the deleted space.
</ResponseField>

<ResponseField name="counts" type="object">
  Counts of deleted resources: `entities`, `members`, `childSpaces`.
</ResponseField>


# Fetch many spaces
Source: https://docs.sublay.io/v7/hooks/spaces/use-fetch-many-spaces

Fetch a paginated list of spaces with filtering and sorting

## Overview

`useFetchManySpaces` returns a callable function for fetching multiple spaces. It supports searching by name, slug, description, or a combined query; filtering by membership or parent space; and sorting.

For paginated, stateful lists with load-more support, use [`useSpaceList`](/hooks/space-lists/use-space-list) instead.

<Note>
  This is a discovery surface: only `public` spaces are listed. `unlisted` and `private` spaces are excluded for non-members (they stay reachable by direct link/slug). The `memberOf=true` filter is the exception — it returns the caller's own spaces regardless of visibility. See [Space visibility](/data-models/space#visibility).
</Note>

## Usage Example

```tsx theme={null}
import { useFetchManySpaces } from "@sublay/react-js";

function SpaceSearch() {
  const fetchSpaces = useFetchManySpaces();

  const handleSearch = async (query: string) => {
    const result = await fetchSpaces({ searchAny: query, sortBy: "newest" });
    console.log(result.data, result.pagination);
  };
}
```

## Parameters

<ParamField type="number">
  Page number to fetch. Defaults to `1`.
</ParamField>

<ParamField type="number">
  Number of results per page.
</ParamField>

<ParamField type="string">
  Sort order: `"newest"`, `"members"` (most members first), or `"alphabetical"`. Defaults to `"members"`.
</ParamField>

<ParamField type="string | null">
  Filter spaces whose slug contains this value.
</ParamField>

<ParamField type="string | null">
  Filter spaces whose name contains this value.
</ParamField>

<ParamField type="string | null">
  Filter spaces whose description contains this value.
</ParamField>

<ParamField type="string | null">
  Search across name, slug, and description simultaneously.
</ParamField>

<ParamField type="boolean">
  When `true`, returns only spaces where the current user is an active member.
</ParamField>

<ParamField type="string | null">
  Filter to child spaces of a specific parent. Pass `null` for root-level spaces only.
</ParamField>

<ParamField type="&#x22;include-all&#x22; | &#x22;exclude&#x22; | &#x22;only&#x22;">
  Filter by each space's `nsfwEffective` (own flag OR any ancestor). `"include-all"` (default) adds no predicate; `"exclude"` drops effective-NSFW spaces; `"only"` returns only them. Because the filter keys off effective status, `"only"` may return an NSFW child whose safe parent is omitted — results are not guaranteed to form a contiguous tree. See [Space NSFW flagging](/data-models/space#nsfw-flagging).
</ParamField>

<ParamField type="&#x22;files&#x22; | string[]">
  Optional. Pass `"files"` to include avatar file objects in each result.
</ParamField>

## Returns

<ResponseField name="data" type="Space[]">
  Array of [Space](/data-models/space) objects.
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination metadata including `page`, `limit`, `total`, and `hasMore`.
</ResponseField>


# Fetch mutual spaces
Source: https://docs.sublay.io/v7/hooks/spaces/use-fetch-mutual-spaces

Fetch spaces shared between the current user and another user

## Overview

`useFetchMutualSpaces` returns a callable function that fetches the spaces both the authenticated user and another user are active members of — their spaces in common. The response is a paginated list of [Space](/data-models/space) objects.

## Usage Example

```tsx theme={null}
import { useFetchMutualSpaces } from "@sublay/react-js";

function MutualSpaces({ otherUserId }: { otherUserId: string }) {
  const fetchMutualSpaces = useFetchMutualSpaces();

  const loadMutual = async () => {
    const result = await fetchMutualSpaces({ userId: otherUserId, page: 1, limit: 20 });
    // result.data: Space[]
    result.data.forEach((space) => {
      console.log(space.name, space.membersCount);
    });
  };
}
```

## Parameters

<ParamField type="string">
  The other user's ID. Mutual spaces are computed between this user and the authenticated user.
</ParamField>

<ParamField type="number">
  Page number. Defaults to `1`.
</ParamField>

<ParamField type="number">
  Number of results per page. Max `100`.
</ParamField>

<ParamField type="string | string[]">
  Optional includes. Pass `"files"` to populate avatar and banner file objects on each space.
</ParamField>

## Returns

<ResponseField name="data" type="Space[]">
  The spaces both users share ([Space](/data-models/space)). Computed fields such as `membersCount` and `isMember` reflect the authenticated user.
</ResponseField>

<ResponseField name="pagination" type="object">
  Standard pagination metadata.
</ResponseField>


# Fetch space
Source: https://docs.sublay.io/v7/hooks/spaces/use-fetch-space

Fetch a single space by its UUID

## Overview

`useFetchSpace` returns a callable function that fetches a single space by its UUID. The response includes full space details, hierarchy info, and the current user's membership permissions.

## Usage Example

```tsx theme={null}
import { useFetchSpace } from "@sublay/react-js";
import { useEffect, useState } from "react";

function SpacePage({ spaceId }: { spaceId: string }) {
  const fetchSpace = useFetchSpace();
  const [space, setSpace] = useState(null);

  useEffect(() => {
    fetchSpace({ spaceId }).then(setSpace);
  }, [spaceId]);

  return space ? <h1>{space.name}</h1> : <p>Loading...</p>;
}
```

## Parameters

The hook returns a function. That function accepts:

<ParamField type="string">
  UUID of the space to fetch.
</ParamField>

<ParamField type="&#x22;files&#x22; | string[]">
  Optional. Pass `"files"` to include avatar and banner file objects in the response.
</ParamField>

## Returns

Returns a [SpaceDetailed](/data-models/space) object, which includes `memberPermissions`, `parentSpace`, and `childSpaces` in addition to all base space fields.

For most use cases, prefer [`SpaceProvider`](/sdk/spaces/provider-and-hook) over calling this hook directly.


# Fetch space breadcrumb
Source: https://docs.sublay.io/v7/hooks/spaces/use-fetch-space-breadcrumb

Fetch the ancestor chain of a space for breadcrumb navigation

## Overview

`useFetchSpaceBreadcrumb` returns a callable function that fetches the ordered list of ancestor spaces from root to the direct parent of the given space. Useful for breadcrumb navigation in hierarchical space structures.

## Usage Example

```tsx theme={null}
import { useFetchSpaceBreadcrumb } from "@sublay/react-js";

function Breadcrumbs({ spaceId }: { spaceId: string }) {
  const fetchBreadcrumb = useFetchSpaceBreadcrumb();

  const loadBreadcrumb = async () => {
    const result = await fetchBreadcrumb({ spaceId });
    // result.breadcrumb: SpacePreview[]  (root → ... → parent)
  };
}
```

## Parameters

<ParamField type="string">
  UUID of the space to fetch the breadcrumb for.
</ParamField>

## Returns

<ResponseField name="breadcrumb" type="SpacePreview[]">
  Ordered array of [SpacePreview](/data-models/space) objects from the root space to the direct parent. Empty for root-level spaces.
</ResponseField>

<Tip>The `useSpace` hook automatically fetches and exposes the `breadcrumb` field — you only need this hook when fetching breadcrumbs outside of a `SpaceProvider`.</Tip>


# Fetch space by short ID
Source: https://docs.sublay.io/v7/hooks/spaces/use-fetch-space-by-short-id

Fetch a single space by its short identifier

## Overview

`useFetchSpaceByShortId` returns a callable function that fetches a space using its `shortId`. The `shortId` is a compact, URL-safe identifier generated automatically when a space is created.

## Usage Example

```tsx theme={null}
import { useFetchSpaceByShortId } from "@sublay/react-js";

function SpacePage({ shortId }: { shortId: string }) {
  const fetchSpace = useFetchSpaceByShortId();

  const handleFetch = async () => {
    const space = await fetchSpace({ shortId });
    console.log(space.name);
  };
}
```

## Parameters

<ParamField type="string">
  The short identifier of the space.
</ParamField>

<ParamField type="&#x22;files&#x22; | string[]">
  Optional. Pass `"files"` to include avatar and banner file objects.
</ParamField>

## Returns

Returns a [SpaceDetailed](/data-models/space) object.

For most use cases, prefer [`SpaceProvider shortId`](/sdk/spaces/provider-and-hook) prop over calling this hook directly.


# Fetch space by slug
Source: https://docs.sublay.io/v7/hooks/spaces/use-fetch-space-by-slug

Fetch a single space by its URL slug

## Overview

`useFetchSpaceBySlug` returns a callable function that fetches a space using its `slug`. Slugs are optional, unique per project, and must match the pattern `^[\p{L}\p{N}]+(?:[-_][\p{L}\p{N}]+)*$` (letters, numbers, hyphens, underscores, supports Unicode).

## Usage Example

```tsx theme={null}
import { useFetchSpaceBySlug } from "@sublay/react-js";

function SpacePage({ slug }: { slug: string }) {
  const fetchSpace = useFetchSpaceBySlug();

  const handleFetch = async () => {
    const space = await fetchSpace({ slug });
    console.log(space.name);
  };
}
```

## Parameters

<ParamField type="string">
  The URL slug of the space.
</ParamField>

<ParamField type="&#x22;files&#x22; | string[]">
  Optional. Pass `"files"` to include avatar and banner file objects.
</ParamField>

## Returns

Returns a [SpaceDetailed](/data-models/space) object.

For most use cases, prefer [`SpaceProvider slug`](/sdk/spaces/provider-and-hook) prop over calling this hook directly.


# Fetch space children
Source: https://docs.sublay.io/v7/hooks/spaces/use-fetch-space-children

Fetch direct child spaces of a parent space

## Overview

`useFetchSpaceChildren` returns a callable function that fetches the immediate child spaces of a given space. Results are paginated.

<Note>
  Authentication is optional. When the caller is signed in, each child carries
  an `isMember` flag. Only children with `visibility: "public"` are listed for
  every caller — signing in does not surface unlisted or private children.
</Note>

## Usage Example

```tsx theme={null}
import { useFetchSpaceChildren } from "@sublay/react-js";

function ChildSpaceList({ spaceId }: { spaceId: string }) {
  const fetchChildren = useFetchSpaceChildren();

  const loadChildren = async () => {
    const result = await fetchChildren({ spaceId, page: 1, limit: 20 });
    // result.data: Space[]
  };
}
```

## Parameters

<ParamField type="string">
  UUID of the parent space.
</ParamField>

<ParamField type="number">
  Page number. Defaults to `1`.
</ParamField>

<ParamField type="number">
  Number of results per page.
</ParamField>

## Returns

<ResponseField name="data" type="Space[]">
  Array of [Space](/data-models/space) objects representing the child spaces.
</ResponseField>

<ResponseField name="pagination" type="object">
  Standard pagination metadata.
</ResponseField>

<Tip>The `useSpace` hook also includes a `childSpaces` field with up to 10 previews of children, useful for navigation breadcrumbs without a separate fetch.</Tip>


# Fetch space members
Source: https://docs.sublay.io/v7/hooks/spaces/use-fetch-space-members

Fetch a paginated list of members in a space

## Overview

`useFetchSpaceMembers` returns a callable function that fetches the member list for a space. Each result includes embedded public user data. Results are paginated and can be filtered by role or status.

## Usage Example

```tsx theme={null}
import { useFetchSpaceMembers } from "@sublay/react-js";

function MemberList({ spaceId }: { spaceId: string }) {
  const fetchMembers = useFetchSpaceMembers();

  const loadMembers = async () => {
    const result = await fetchMembers({ spaceId, page: 1, limit: 20 });
    result.data.forEach(({ user, role, status }) => {
      console.log(user.displayName, role, status);
    });
  };
}
```

## Parameters

<ParamField type="string">
  UUID of the space.
</ParamField>

<ParamField type="number">
  Page number. Defaults to `1`.
</ParamField>

<ParamField type="number">
  Number of members per page.
</ParamField>

<ParamField type="string">
  Filter by membership status: `"pending"`, `"active"`, `"banned"`, or `"rejected"`.
</ParamField>

<ParamField type="string">
  Filter by role: `"admin"`, `"moderator"`, or `"member"`.
</ParamField>

<SpaceReputationParams />

## Returns

<ResponseField name="data" type="SpaceMemberWithUser[]">
  Array of [SpaceMemberWithUser](/data-models/space-member) objects including embedded user details. When `spaceReputation` is requested, each embedded user carries an added `spaceReputation` number. See [Reputation](/data-models/reputation).
</ResponseField>

<ResponseField name="pagination" type="object">
  Standard pagination metadata.
</ResponseField>


# Fetch space team
Source: https://docs.sublay.io/v7/hooks/spaces/use-fetch-space-team

Fetch all admins and moderators of a space

## Overview

`useFetchSpaceTeam` returns a callable function that fetches all admins and moderators of a space in a single non-paginated response. This is useful for displaying the space's leadership team.

## Usage Example

```tsx theme={null}
import { useFetchSpaceTeam } from "@sublay/react-js";

function SpaceTeam({ spaceId }: { spaceId: string }) {
  const fetchTeam = useFetchSpaceTeam();

  const loadTeam = async () => {
    const { data } = await fetchTeam({ spaceId });
    data.forEach(({ user, role }) => {
      console.log(user.displayName, role);
    });
  };
}
```

## Parameters

<ParamField type="string">
  UUID of the space.
</ParamField>

<SpaceReputationParams />

## Returns

<ResponseField name="data" type="SpaceMemberWithUser[]">
  All admins and moderators with active status, including embedded user details. When `spaceReputation` is requested, each embedded user carries an added `spaceReputation` number. See [SpaceMember](/data-models/space-member) and [Reputation](/data-models/reputation).
</ResponseField>


# Fetch user spaces
Source: https://docs.sublay.io/v7/hooks/spaces/use-fetch-user-spaces

Fetch spaces where the current user is a member

## Overview

`useFetchUserSpaces` returns a callable function that fetches all spaces where the authenticated user has an active membership. The response includes membership metadata alongside each space.

## Usage Example

```tsx theme={null}
import { useFetchUserSpaces } from "@sublay/react-js";

function MySpaces() {
  const fetchUserSpaces = useFetchUserSpaces();

  const loadSpaces = async () => {
    const result = await fetchUserSpaces({ page: 1, limit: 20 });
    // result.data: UserSpaceItem[]
    result.data.forEach(({ space, membership }) => {
      console.log(space.name, membership.role, membership.status);
    });
  };
}
```

## Parameters

<ParamField type="string">
  Membership status to list: `"active"` (default), `"pending"`, or `"banned"`. Use `"pending"` to show join requests still awaiting approval.
</ParamField>

<ParamField type="number">
  Page number. Defaults to `1`.
</ParamField>

<ParamField type="number">
  Number of results per page.
</ParamField>

## Returns

<ResponseField name="data" type="UserSpaceItem[]">
  Each item contains a `space` ([Space](/data-models/space)) and a `membership` object with `membershipId`, `role`, `status`, and `joinedAt`.
</ResponseField>

<ResponseField name="pagination" type="object">
  Standard pagination metadata.
</ResponseField>


# Join space
Source: https://docs.sublay.io/v7/hooks/spaces/use-join-space

Join a space or submit a join request

## Overview

`useJoinSpace` returns a callable function for joining a space. If the space has `requireJoinApproval: true`, the membership is created with `status: "pending"` until approved by a moderator or admin. Otherwise, it is immediately `active`.

<Note>When using `SpaceProvider`, call `joinSpace` from `useSpace` — it handles optimistic state updates automatically.</Note>

## Usage Example

```tsx theme={null}
import { useJoinSpace } from "@sublay/react-js";

function JoinButton({ spaceId }: { spaceId: string }) {
  const joinSpace = useJoinSpace();

  const handleJoin = async () => {
    const result = await joinSpace({ spaceId });
    console.log(result.membership.status); // "pending" or "active"
  };

  return <button onClick={handleJoin}>Join</button>;
}
```

## Parameters

<ParamField type="string">
  UUID of the space to join.
</ParamField>

## Returns

<ResponseField name="message" type="string">
  Confirmation message.
</ResponseField>

<ResponseField name="membership" type="object">
  The created membership record with `id`, `spaceId`, `userId`, `role` (`"member"`), `status`, and `joinedAt`.
</ResponseField>


# Leave space
Source: https://docs.sublay.io/v7/hooks/spaces/use-leave-space

Leave a space

## Overview

`useLeaveSpace` returns a callable function for leaving a space. The user's membership record is removed.

<Note>When using `SpaceProvider`, call `leaveSpace` from `useSpace` — it handles optimistic state updates automatically.</Note>

## Usage Example

```tsx theme={null}
import { useLeaveSpace } from "@sublay/react-js";

function LeaveButton({ spaceId }: { spaceId: string }) {
  const leaveSpace = useLeaveSpace();

  const handleLeave = async () => {
    await leaveSpace({ spaceId });
  };

  return <button onClick={handleLeave}>Leave</button>;
}
```

## Parameters

<ParamField type="string">
  UUID of the space to leave.
</ParamField>

## Returns

<ResponseField name="message" type="string">
  Confirmation message.
</ResponseField>


# Moderate space comment
Source: https://docs.sublay.io/v7/hooks/spaces/use-moderate-space-comment

Approve or remove a comment within a space

## Overview

`useModerateSpaceComment` returns a callable function for taking moderation action on a comment in a space. Requires the caller to be a moderator or admin.

## Usage Example

```tsx theme={null}
import { useModerateSpaceComment } from "@sublay/react-js";

function CommentModerationActions({ spaceId, commentId }: { spaceId: string; commentId: string }) {
  const moderate = useModerateSpaceComment();

  return (
    <div>
      <button onClick={() => moderate({ spaceId, commentId, action: "approve" })}>
        Approve
      </button>
      <button onClick={() => moderate({ spaceId, commentId, action: "remove" })}>
        Remove
      </button>
    </div>
  );
}
```

## Parameters

<ParamField type="string">
  UUID of the space containing the comment.
</ParamField>

<ParamField type="string">
  UUID of the comment to moderate.
</ParamField>

<ParamField type="&#x22;approve&#x22; | &#x22;remove&#x22;">
  The moderation action to take.
</ParamField>

## Returns

A confirmation response from the server.

For integration guidance, see [Moderation](/sdk/spaces/moderation).


# Moderate space entity
Source: https://docs.sublay.io/v7/hooks/spaces/use-moderate-space-entity

Approve or remove an entity within a space

## Overview

`useModerateSpaceEntity` returns a callable function for taking moderation action on an entity in a space. Requires the caller to be a moderator or admin.

## Usage Example

```tsx theme={null}
import { useModerateSpaceEntity } from "@sublay/react-js";

function EntityModerationActions({ spaceId, entityId }: { spaceId: string; entityId: string }) {
  const moderate = useModerateSpaceEntity();

  return (
    <div>
      <button onClick={() => moderate({ spaceId, entityId, action: "approve" })}>
        Approve
      </button>
      <button onClick={() => moderate({ spaceId, entityId, action: "remove" })}>
        Remove
      </button>
    </div>
  );
}
```

## Parameters

<ParamField type="string">
  UUID of the space containing the entity.
</ParamField>

<ParamField type="string">
  UUID of the entity to moderate.
</ParamField>

<ParamField type="&#x22;approve&#x22; | &#x22;remove&#x22;">
  The moderation action to take.
</ParamField>

## Returns

A confirmation response from the server.

For integration guidance, see [Moderation](/sdk/spaces/moderation).


# Set space entity NSFW
Source: https://docs.sublay.io/v7/hooks/spaces/use-set-space-entity-nsfw

Flag or unflag an entity's NSFW status as a space moderator

## Overview

`useSetSpaceEntityNsfw` returns a callable function that sets the `nsfw` own-flag on an entity within a space — including **other users'** entities. It is the moderator counterpart to the owner-only `nsfw` field on [useUpdateEntity](/hooks/entities/use-update-entity). The caller must be an admin or moderator of the space; other callers receive a `403`.

This writes the entity's own `nsfw` flag only. Its effective NSFW status (`nsfwEffective`) is still computed live from that flag OR the space chain. NSFW is a separate axis from moderation (`approve`/`remove`) — flagging **labels** content, it does not hide it. See [Entity NSFW flagging](/data-models/entity#nsfw-flagging).

## Usage Example

```tsx theme={null}
import { useSetSpaceEntityNsfw } from "@sublay/react-js";

function EntityNsfwToggle({ spaceId, entityId }: { spaceId: string; entityId: string }) {
  const setSpaceEntityNsfw = useSetSpaceEntityNsfw();

  return (
    <div>
      <button onClick={() => setSpaceEntityNsfw({ spaceId, entityId, nsfw: true })}>
        Mark NSFW
      </button>
      <button onClick={() => setSpaceEntityNsfw({ spaceId, entityId, nsfw: false })}>
        Clear NSFW
      </button>
    </div>
  );
}
```

## Parameters

<ParamField type="string">
  UUID of the space containing the entity.
</ParamField>

<ParamField type="string">
  UUID of the entity to flag or unflag.
</ParamField>

<ParamField type="boolean">
  The NSFW own-flag to set on the entity.
</ParamField>

## Returns

<ResponseField name="message" type="string">
  Confirmation message.
</ResponseField>

<ResponseField name="nsfw" type="boolean">
  The NSFW flag that was applied.
</ResponseField>

Calls `PATCH /v7/:projectId/spaces/:spaceId/entities/:entityId/nsfw` with body `{ nsfw }`, behind `requireUserAuth` + `requireSpaceModerator`.

## See Also

* [Moderate space entity](/hooks/spaces/use-moderate-space-entity)
* [Update entity](/hooks/entities/use-update-entity)
* [Entity data model](/data-models/entity#nsfw-flagging)


# Use space
Source: https://docs.sublay.io/v7/hooks/spaces/use-space

Access space data, permissions, and operations from SpaceProvider context

## Overview

`useSpace` returns the current space state and all operations from the nearest `SpaceProvider`. It is the primary way to interact with a space in your component tree.

<Note>This hook must be used inside a `SpaceProvider`.</Note>

## Usage Example

```tsx theme={null}
import { useSpace } from "@sublay/react-js";

function SpaceHeader() {
  const {
    space,
    isMember,
    isAdmin,
    canPost,
    isPending,
    joinSpace,
    leaveSpace,
    loading,
  } = useSpace();

  if (loading) return <p>Loading...</p>;
  if (!space) return <p>Space not found.</p>;

  return (
    <div>
      <h1>{space.name}</h1>
      {!isMember && !isPending && (
        <button onClick={joinSpace}>Join</button>
      )}
      {isPending && <p>Awaiting approval...</p>}
      {isMember && <button onClick={leaveSpace}>Leave</button>}
    </div>
  );
}
```

## Returns

<ResponseField name="space" type="SpaceDetailed | null | undefined">
  The loaded space. `undefined` while loading, `null` if not found.
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` while fetching the space.
</ResponseField>

<ResponseField name="error" type="string | null">
  Error message if the fetch failed.
</ResponseField>

<ResponseField name="isMember" type="boolean">
  `true` if the current user has an active membership.
</ResponseField>

<ResponseField name="isAdmin" type="boolean">
  `true` if the current user is a space admin.
</ResponseField>

<ResponseField name="isModerator" type="boolean">
  `true` if the current user is a space moderator.
</ResponseField>

<ResponseField name="canPost" type="boolean">
  `true` if the current user can post entities in this space.
</ResponseField>

<ResponseField name="canModerate" type="boolean">
  `true` if the current user can perform moderation actions.
</ResponseField>

<ResponseField name="membershipStatus" type="&#x22;pending&#x22; | &#x22;active&#x22; | &#x22;banned&#x22; | null">
  Raw membership status. `null` if not a member.
</ResponseField>

<ResponseField name="isPending" type="boolean">
  `true` if the user's join request is awaiting approval.
</ResponseField>

<ResponseField name="isBanned" type="boolean">
  `true` if the user is banned from this space.
</ResponseField>

<ResponseField name="breadcrumb" type="SpacePreview[]">
  Ancestor spaces from root to direct parent. Empty for root spaces.
</ResponseField>

<ResponseField name="parentSpace" type="SpacePreview | null">
  Preview of the parent space. `null` for root spaces.
</ResponseField>

<ResponseField name="childSpaces" type="SpacePreview[]">
  Previews of direct child spaces (up to 10).
</ResponseField>

<ResponseField name="joinSpace" type="() => Promise<void>">
  Join the space. Creates a `pending` membership when approval is required.
</ResponseField>

<ResponseField name="leaveSpace" type="() => Promise<void>">
  Leave the space.
</ResponseField>

<ResponseField name="updateSpace" type="(props: { update }) => Promise<SpaceDetailed | undefined>">
  Update space settings (admin only).
</ResponseField>

<ResponseField name="deleteSpace" type="() => Promise<void>">
  Delete the space (admin only).
</ResponseField>

<ResponseField name="setSpace" type="React.Dispatch">
  Directly update the space state for optimistic UI updates.
</ResponseField>

For integration guidance, see [SpaceProvider & useSpace](/sdk/spaces/provider-and-hook).


# Use space mentions
Source: https://docs.sublay.io/v7/hooks/spaces/use-space-mentions

Get space mention suggestions for autocomplete in text editors

## Overview

`useSpaceMentions` provides autocomplete suggestion logic for `#space-slug` style mentions in text inputs. It tracks cursor position, detects mention triggers, and fetches matching spaces using debounced search.

<Note>Spaces must have a `slug` set to be mentionable. This hook uses the `#` trigger by default.</Note>

## Usage Example

```tsx theme={null}
import { useSpaceMentions } from "@sublay/react-js";

function PostEditor() {
  const [content, setContent] = useState("");
  const [cursorPosition, setCursorPosition] = useState(0);
  const inputRef = useRef<HTMLInputElement>(null);

  const {
    isSpaceMentionActive,
    loading,
    spaceMentionSuggestions,
    handleSpaceMentionClick,
    mentions,
  } = useSpaceMentions({
    content,
    setContent,
    cursorPosition,
    isSelectionActive: false,
    focus: () => inputRef.current?.focus(),
  });

  return (
    <div>
      <input
        ref={inputRef}
        value={content}
        onChange={(e) => {
          setContent(e.target.value);
          setCursorPosition(e.target.selectionStart ?? 0);
        }}
      />
      {isSpaceMentionActive && !loading && (
        <ul>
          {spaceMentionSuggestions.map((space) => (
            <li key={space.id} onClick={() => handleSpaceMentionClick(space)}>
              #{space.slug}
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}
```

## Parameters

<ParamField type="string">
  The current text content of the editor.
</ParamField>

<ParamField type="(value: string) => void">
  Setter to update the content when a mention is selected.
</ParamField>

<ParamField type="() => void">
  Function to re-focus the editor after a mention is selected.
</ParamField>

<ParamField type="number">
  Current cursor position in the text.
</ParamField>

<ParamField type="boolean">
  Whether text is currently selected. Disables mention detection during selection.
</ParamField>

<ParamField type="string">
  Character that triggers mention detection. Defaults to `"#"`.
</ParamField>

<ParamField type="number">
  Minimum characters after the trigger before search fires. Defaults to `3`.
</ParamField>

<ParamField type="number">
  Milliseconds to wait after the last keystroke before fetching. Defaults to `1000`.
</ParamField>

## Returns

<ResponseField name="isSpaceMentionActive" type="boolean">
  Whether the mention autocomplete is currently active.
</ResponseField>

<ResponseField name="loading" type="boolean">
  Whether suggestions are being fetched.
</ResponseField>

<ResponseField name="spaceMentionSuggestions" type="Space[]">
  Matching spaces to display as suggestions.
</ResponseField>

<ResponseField name="handleSpaceMentionClick" type="(space: Space) => void">
  Call this when a suggestion is selected. Replaces the trigger text with the space slug.
</ResponseField>

<ResponseField name="mentions" type="Mention[]">
  Accumulated list of all selected mentions (id, slug, type: "space").
</ResponseField>

<ResponseField name="addSpaceMention" type="(space: Space) => void">
  Manually add a space to the mentions list.
</ResponseField>

<ResponseField name="resetSpaceMentions" type="() => void">
  Clear all mention state.
</ResponseField>


# Use space permissions
Source: https://docs.sublay.io/v7/hooks/spaces/use-space-permissions

Compute resolved permissions for a user in a space

## Overview

`useSpacePermissions` is a utility hook that computes derived permission flags from a user's raw membership permissions and the space's permission settings. It is used internally by `useSpaceData` and exposed for cases where you need to compute permissions outside of a `SpaceProvider`.

<Tip>In most cases, you should use `useSpace` instead — it exposes `isMember`, `isAdmin`, `canPost`, etc. directly. Use `useSpacePermissions` only when working outside a SpaceProvider context.</Tip>

## Usage Example

```tsx theme={null}
import { useSpacePermissions } from "@sublay/core";

const permissions = useSpacePermissions({
  memberPermissions: space.memberPermissions,
  postingPermission: space.postingPermission,
  readingPermission: space.readingPermission,
});

console.log(permissions.canPost, permissions.isAdmin);
```

## Parameters

<ParamField type="SpaceMemberPermissions | null | undefined">
  The raw membership permissions object from the space. `null` or `undefined` if the user is not a member.
</ParamField>

<ParamField type="&#x22;anyone&#x22; | &#x22;members&#x22; | &#x22;admins&#x22;">
  The space's posting permission setting.
</ParamField>

<ParamField type="&#x22;anyone&#x22; | &#x22;members&#x22;">
  The space's reading permission setting. Defaults to `"anyone"`.
</ParamField>

## Returns

<ResponseField name="isMember" type="boolean">
  Whether the user is an active member.
</ResponseField>

<ResponseField name="isAdmin" type="boolean">
  Whether the user is an admin.
</ResponseField>

<ResponseField name="isModerator" type="boolean">
  Whether the user is a moderator.
</ResponseField>

<ResponseField name="canPost" type="boolean">
  Whether the user can post, given the space's posting permission and their membership status.
</ResponseField>

<ResponseField name="canModerate" type="boolean">
  Whether the user can moderate content.
</ResponseField>

<ResponseField name="canRead" type="boolean">
  Whether the user can read content, given the space's reading permission.
</ResponseField>

<ResponseField name="isPending" type="boolean">
  Whether the user has a pending membership.
</ResponseField>

<ResponseField name="isBanned" type="boolean">
  Whether the user is banned.
</ResponseField>


# Unban member
Source: https://docs.sublay.io/v7/hooks/spaces/use-unban-member

Unban a previously banned member from a space

## Overview

`useUnbanMember` returns a callable function for unbanning a member. Sets their membership status from `"banned"` back to `"active"`. Requires the caller to be a moderator or admin.

## Usage Example

```tsx theme={null}
import { useUnbanMember } from "@sublay/react-js";

function BannedMemberRow({ spaceId, memberId }: { spaceId: string; memberId: string }) {
  const unban = useUnbanMember();

  return (
    <button onClick={() => unban({ spaceId, memberId })}>
      Unban
    </button>
  );
}
```

## Parameters

<ParamField type="string">
  UUID of the space.
</ParamField>

<ParamField type="string">
  UUID of the membership record to unban.
</ParamField>

## Returns

<ResponseField name="message" type="string">
  Confirmation message.
</ResponseField>


# Update member role
Source: https://docs.sublay.io/v7/hooks/spaces/use-update-member-role

Update a member's role within a space

## Overview

`useUpdateMemberRole` returns a callable function for changing a space member's role. Only admins can update roles.

## Usage Example

```tsx theme={null}
import { useUpdateMemberRole } from "@sublay/react-js";

function RoleSelector({ spaceId, memberId }: { spaceId: string; memberId: string }) {
  const updateRole = useUpdateMemberRole();

  return (
    <select onChange={(e) => updateRole({ spaceId, memberId, role: e.target.value as any })}>
      <option value="member">Member</option>
      <option value="moderator">Moderator</option>
      <option value="admin">Admin</option>
    </select>
  );
}
```

## Parameters

<ParamField type="string">
  UUID of the space.
</ParamField>

<ParamField type="string">
  UUID of the membership record to update.
</ParamField>

<ParamField type="&#x22;admin&#x22; | &#x22;moderator&#x22; | &#x22;member&#x22;">
  The new role to assign.
</ParamField>

## Returns

<ResponseField name="message" type="string">
  Confirmation message.
</ResponseField>

<ResponseField name="membership" type="object">
  Updated membership with `id`, `role`, `status`, `joinedAt`, and `userId`.
</ResponseField>


# Update space
Source: https://docs.sublay.io/v7/hooks/spaces/use-update-space

Update a space's settings, name, description, or images

## Overview

`useUpdateSpace` returns a callable function for updating a space. Only space admins can update a space. Supports updating avatar and banner images.

<Note>When using `SpaceProvider`, prefer calling `updateSpace` from `useSpace` — it handles state updates automatically.</Note>

## Usage Example

```tsx theme={null}
import { useUpdateSpace } from "@sublay/react-js";

function SpaceSettings({ spaceId }: { spaceId: string }) {
  const updateSpace = useUpdateSpace();

  const handleSave = async (name: string, description: string) => {
    const updated = await updateSpace({
      spaceId,
      update: { name, description },
    });
    console.log("Updated:", updated.name);
  };
}
```

## Parameters

<ParamField type="string">
  UUID of the space to update.
</ParamField>

<ParamField type="object">
  Fields to update. All fields are optional.

  <Expandable title="update fields">
    <ParamField type="string">
      New display name (3–100 characters).
    </ParamField>

    <ParamField type="string | null">
      New URL slug. Pass `null` to remove.
    </ParamField>

    <ParamField type="string | null">
      New description. Pass `null` to remove.
    </ParamField>

    <ParamField type="&#x22;anyone&#x22; | &#x22;members&#x22;">
      Updated reading permission.
    </ParamField>

    <ParamField type="&#x22;anyone&#x22; | &#x22;members&#x22; | &#x22;admins&#x22;">
      Updated posting permission.
    </ParamField>

    <ParamField type="&#x22;public&#x22; | &#x22;unlisted&#x22; | &#x22;private&#x22;">
      Updated visibility (listing/discoverability). Independent of `readingPermission`. See [Space visibility](/data-models/space#visibility).
    </ParamField>

    <ParamField type="boolean">
      Updated NSFW own-flag. Toggling it recomputes this space's effective NSFW and cascades it top-down to every descendant space (and, live, to their entities) in the same transaction. See [Space NSFW flagging](/data-models/space#nsfw-flagging).
    </ParamField>

    <ParamField type="boolean">
      Updated join approval requirement.
    </ParamField>

    <ParamField type="Record<string, any>">
      Updated metadata.
    </ParamField>

    <ParamField type="{ file: File | Blob; options: UploadImageOptions }">
      New avatar image to upload.
    </ParamField>

    <ParamField type="{ file: File | Blob; options: UploadImageOptions }">
      New banner image to upload.
    </ParamField>
  </Expandable>
</ParamField>

## Returns

Returns the updated [SpaceDetailed](/data-models/space) object.


# Accept workspace invite
Source: https://docs.sublay.io/v7/hooks/workspaces/use-accept-workspace-invite

Accept a workspace invitation — identity-matched + verified-email

## Overview

`useAcceptWorkspaceInvite` returns a callable that accepts an [invitation](/data-models/workspace-invitation). The `inviteId` is non-secret. Idempotent when already a member/owner.

**Authorization:** self-service. The invite must be addressed to the signed-in user (identity-matched), and a **verified email is required**.

## Usage Example

```tsx theme={null}
import { useAcceptWorkspaceInvite } from "@sublay/react-js";

function AcceptButton({ inviteId }: { inviteId: string }) {
  const acceptWorkspaceInvite = useAcceptWorkspaceInvite();

  const handleAccept = async () => {
    const { workspaceId } = await acceptWorkspaceInvite({ inviteId });
    console.log("Joined workspace:", workspaceId);
  };

  return <button onClick={handleAccept}>Accept</button>;
}
```

## Parameters

<ParamField type="string">
  The (non-secret) invitation UUID.
</ParamField>

## Returns

`{ success: boolean; workspaceId: string }`.

<Note>
  An unverified accept fails with `workspace/email-not-verified` — prompt the user to verify their email, then retry.
</Note>

## Error codes

| Code                           | Status | Meaning                                                                                    |
| ------------------------------ | ------ | ------------------------------------------------------------------------------------------ |
| `workspace/email-not-verified` | 403    | The accepting user's email is not verified.                                                |
| `workspace/invite-not-found`   | 404    | No such invitation, or it is not addressed to you.                                         |
| `workspace/invite-expired`     | 409    | The invitation lapsed — ask for a [resend](/hooks/workspaces/use-resend-workspace-invite). |
| `workspace/invite-terminal`    | 409    | Already accepted / declined / revoked.                                                     |

## Related

* [`useFetchMyWorkspaceInvites`](/hooks/workspaces/use-fetch-my-workspace-invites) — list the invites addressed to you
* [Accept Invite API](/api-reference/workspaces/invitations/accept-invite)


# Create workspace
Source: https://docs.sublay.io/v7/hooks/workspaces/use-create-workspace

Create a root or child workspace; the caller becomes the owner

## Overview

`useCreateWorkspace` returns a callable that creates a [workspace](/data-models/workspace). The signed-in caller becomes the owner. Omit `parentWorkspaceId` for a root workspace (requires a **verified email**); pass it for a child (requires the `create-sub-workspace` capability on the parent).

<Note>
  The verified-email gate on root creation is **absolute** — there is no server-side escape hatch. A service or master key acting as a named user via the [node SDK](/node-sdk/workspaces) is held to the same rule, exactly as accepting an invite and receiving an ownership transfer are. Prompt the user through email verification before showing a "Create workspace" flow.
</Note>

## Usage Example

```tsx theme={null}
import { useCreateWorkspace } from "@sublay/react-js";

function CreateTeam() {
  const createWorkspace = useCreateWorkspace();

  const handleCreate = async () => {
    const workspace = await createWorkspace({ name: "Acme Inc" });
    console.log("Created:", workspace.id, "owner:", workspace.ownerId);
  };
}
```

## Parameters

<ParamField type="string">
  Display name. 1–100 characters.
</ParamField>

<ParamField type="Record<string, any>">
  Optional opaque developer data.
</ParamField>

<ParamField type="string | null">
  Optional parent for child creation. Absent/`null` → root.
</ParamField>

## Returns

Returns the created [Workspace](/data-models/workspace) object.

## Error codes

| Code                           | Status | Meaning                                                            |
| ------------------------------ | ------ | ------------------------------------------------------------------ |
| `workspace/email-not-verified` | 403    | Root creation, and the caller's email is not verified.             |
| `workspace/unauthorized`       | 403    | Child creation, and you lack `create-sub-workspace` on the parent. |
| `workspace/not-found`          | 404    | The `parentWorkspaceId` does not exist in this project.            |
| `workspace/max-depth-exceeded` | 400    | The child would sit deeper than the 10-level nesting cap.          |

## Related

* [Create Workspace API](/api-reference/workspaces/create-workspace)


# Create workspace invite
Source: https://docs.sublay.io/v7/hooks/workspaces/use-create-workspace-invite

Create a workspace invitation by email, userId, or username

## Overview

`useCreateWorkspaceInvite` returns a callable that creates an [invitation](/data-models/workspace-invitation). Address the invitee by **exactly one** of `email`, `userId`, or `username` (here `userId`/`username` is the invite **target**, not the actor — the inviter is the signed-in user).

**Authorization:** capability-gated + rank-bounded. Requires the `invite` capability (or ownership). The invited `capabilities`/`permissions` are subject to [no-escalation](/data-models/workspace-member#no-privilege-escalation), and if the inviter holds a direct member row the invited rank must be strictly larger (less senior) than their own.

**Rank comes in either coordinate.** Pass `relativeRank` (an offset from the inviter — `1` = one rung below me) or `rank` (absolute), never both. Pass **neither** and the server applies `relativeRank: 1`, which is well defined for every inviter and can never fail the rank floor. See [choosing a rank](/sdk/workspaces/overview#choosing-a-rank).

<Warning>
  **Your project must have `workspaces.inviteAcceptUrl` set before this hook can succeed.** The invitation email deep-links to that URL, and it has **no default** — so a freshly added `workspaces` bundle has none and every call fails with `409 workspace/missing-invite-accept-url` until you configure it. This holds **even when the invitee already has an account**. See [Project settings](/sdk/workspaces/overview#project-settings).
</Warning>

## Usage Example

```tsx theme={null}
import { useCreateWorkspaceInvite } from "@sublay/react-js";

function InviteForm({ workspaceId }: { workspaceId: string }) {
  const createWorkspaceInvite = useCreateWorkspaceInvite();

  const handleInvite = async (email: string) => {
    const invite = await createWorkspaceInvite({
      workspaceId,
      email,
      capabilities: ["view"],
      permissions: ["deploy"],
      // One rung below me — the happy path. Omitting both rank fields
      // entirely means exactly this.
      relativeRank: 1,
    });
    console.log("Invited:", invite.id);
  };
}
```

## Parameters

<ParamField type="string">The workspace UUID.</ParamField>
<ParamField type="string">Invitee email. One of `email`/`userId`/`username`. Trimmed + lowercased server-side, and matched **case-insensitively** against existing accounts — so an account stored as `Jane@Example.com` still gets its `userId` bound when invited as `jane@example.com`.</ParamField>
<ParamField type="string">Invitee user id (existing users only) — the invite **target**.</ParamField>
<ParamField type="string">Invitee username (existing users only).</ParamField>
<ParamField type="WorkspaceCapability[]">Capabilities to apply on accept. Subject to no-escalation.</ParamField>
<ParamField type="string[]">Opaque permissions to apply on accept.</ParamField>
<ParamField type="number">Initial **absolute** rank. For a direct-member inviter it must be strictly larger (less senior) than their own; a reach-holder inviter (no direct row) may set any rank. **No longer required** — mutually exclusive with `relativeRank`, and omitting both applies the default below.</ParamField>
<ParamField type="number">Initial rank as an **offset from the inviter**: `1` = one rung below me. Must be `>= 1`. Anchored on the inviter's own rank if they hold a member row on this workspace, apex (one step above rank 0) otherwise. A **snapshot** — resolved to an absolute number at invite time and frozen; it does not track the inviter's later rank changes.</ParamField>
<ParamField type="string | null">Optional cosmetic title.</ParamField>

## Returns

Returns the created [WorkspaceInvitation](/data-models/workspace-invitation) object.

## Error codes

| Code                                  | Status | Meaning                                                                                                                                                                                                                                                                                                        |
| ------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `workspace/already-member`            | 409    | The target is already a member — edit their grant instead.                                                                                                                                                                                                                                                     |
| `workspace/no-escalation`             | 403    | You tried to grant a capability/permission you do not hold.                                                                                                                                                                                                                                                    |
| `workspace/insufficient-rank`         | 403    | The invited rank is not strictly below your own. Checked on the resolved absolute value, so `relativeRank` clears it by construction.                                                                                                                                                                          |
| `workspace/unauthorized`              | 403    | You lack the `invite` capability.                                                                                                                                                                                                                                                                              |
| `workspace/missing-invite-accept-url` | 409    | The **project** has no [`workspaces.inviteAcceptUrl`](/sdk/workspaces/overview#project-settings) configured, so the invite email would have nowhere to link. Nothing is persisted. A misconfiguration to fix in project settings, not something the end user can act on — surface it to yourself, not to them. |

<Warning>
  **Omitting the rank field is the easiest way to mint rank 0.** The default is "one rung below me", and a signed-in user with **no member row on this workspace** — the workspace's `owner`, an ancestor owner, or a reach holder — anchors at apex, so their default lands on **rank 0**, the most senior rung. That is correct (one below apex *is* the top rung), but it is the opposite of what "I left the field off" usually implies. If a caller with no row here should be inviting people to the *bottom* of the ladder, name a coordinate instead.

  **For an in-ladder inviter it collapses into a flat layer.** A rank-0 lead inviting six people with no rank field gets six rank-1 members — and equals cannot act on equals, so none of them can manage each other; only the lead can. Fine for a flat team, worth deciding deliberately if your product has tiers.
</Warning>

## Related

* [`useFetchWorkspaceInvites`](/hooks/workspaces/use-fetch-workspace-invites) — the invites this workspace has issued
* [`useRevokeWorkspaceInvite`](/hooks/workspaces/use-revoke-workspace-invite) · [`useResendWorkspaceInvite`](/hooks/workspaces/use-resend-workspace-invite)
* [Project settings](/sdk/workspaces/overview#project-settings) — the required `workspaces.inviteAcceptUrl`
* [Create Invite API](/api-reference/workspaces/invitations/create-invite)


# Decline workspace invite
Source: https://docs.sublay.io/v7/hooks/workspaces/use-decline-workspace-invite

Decline a workspace invitation — identity-matched and verification-gated

## Overview

`useDeclineWorkspaceInvite` returns a callable that declines an [invitation](/data-models/workspace-invitation).

**Authorization:** self-service. The invite must be addressed to the signed-in user (identity-matched), and a **verified email is required** — the same gate as [accept](/hooks/workspaces/use-accept-workspace-invite). Otherwise a squatter who signed up with someone else's address could burn that person's invite by declining it.

## Usage Example

```tsx theme={null}
import { useDeclineWorkspaceInvite } from "@sublay/react-js";

function DeclineButton({ inviteId }: { inviteId: string }) {
  const declineWorkspaceInvite = useDeclineWorkspaceInvite();

  return (
    <button onClick={() => declineWorkspaceInvite({ inviteId })}>Decline</button>
  );
}
```

## Parameters

<ParamField type="string">
  The invitation UUID.
</ParamField>

## Returns

`{ success: boolean }`.

## Error codes

| Code                           | Status | Meaning                                            |
| ------------------------------ | ------ | -------------------------------------------------- |
| `workspace/email-not-verified` | 403    | The declining user's email is not verified.        |
| `workspace/invite-not-found`   | 404    | No such invitation, or it is not addressed to you. |
| `workspace/invite-terminal`    | 409    | Already accepted / declined / revoked.             |

## Related

* [`useFetchMyWorkspaceInvites`](/hooks/workspaces/use-fetch-my-workspace-invites) — list the invites addressed to you
* [Decline Invite API](/api-reference/workspaces/invitations/decline-invite)


# Delete workspace
Source: https://docs.sublay.io/v7/hooks/workspaces/use-delete-workspace

Owner-only delete that cascades the whole subtree

## Overview

`useDeleteWorkspace` returns a callable that deletes a [workspace](/data-models/workspace). Deletion **cascades the entire subtree** in one transaction, bottom-up: invitations → members → workspaces. Each deleted workspace fires `workspace.deleted` — and **no** `workspace.member.removed` events for the memberships it tears down. Treat `workspace.deleted` as removing that workspace's whole roster; see [Webhooks & lifecycle](/sdk/workspaces/webhooks#deleting-a-workspace-does-not-emit-per-member-events).

**Authorization:** owner-only. The signed-in user must be this workspace's own owner or an ancestor owner. **There is no `delete-workspace` capability.**

<Warning>
  Your own data tagged with a workspace id (docs, issues, etc.) is **not** deleted by Sublay. React to the [`workspace.deleted` webhook](/sdk/workspaces/webhooks) to clean up your own workspace-tagged data.
</Warning>

## Usage Example

```tsx theme={null}
import { useDeleteWorkspace } from "@sublay/react-js";

function DangerZone({ workspaceId }: { workspaceId: string }) {
  const deleteWorkspace = useDeleteWorkspace();

  const handleDelete = async () => {
    const { message } = await deleteWorkspace({ workspaceId });
    console.log(message);
  };

  return <button onClick={handleDelete}>Delete workspace</button>;
}
```

## Parameters

<ParamField type="string">
  The workspace UUID.
</ParamField>

## Returns

`{ message: string }`.

## Error codes

| Code                     | Status | Meaning                                     |
| ------------------------ | ------ | ------------------------------------------- |
| `workspace/unauthorized` | 403    | You are not the owner or an ancestor owner. |
| `workspace/not-found`    | 404    | No such workspace in this project.          |

## Related

* [`useTransferWorkspaceOwnership`](/hooks/workspaces/use-transfer-workspace-ownership) — hand it over instead of deleting
* [Delete Workspace API](/api-reference/workspaces/delete-workspace)


# Fetch many workspaces
Source: https://docs.sublay.io/v7/hooks/workspaces/use-fetch-many-workspaces

Leaf fetcher for the caller's direct-membership + owned workspaces

## Overview

`useFetchManyWorkspaces` returns a callable that fetches one page of the caller's **direct-membership + owned** workspaces. The actor is derived from the bearer token — no `actingUserId` is sent. For a managed paginated list with load-more, prefer [`useFetchManyWorkspacesWrapper`](/hooks/workspaces/use-fetch-many-workspaces-wrapper).

## Usage Example

```tsx theme={null}
import { useFetchManyWorkspaces } from "@sublay/react-js";

function useMyWorkspaces() {
  const fetchManyWorkspaces = useFetchManyWorkspaces();

  return async () => {
    const { data, pagination } = await fetchManyWorkspaces({
      page: 1,
      limit: 20,
      include: ["memberCount"],
    });
    return data;
  };
}
```

## Parameters

The callable takes an optional params object:

<ParamField type="number">Page number.</ParamField>
<ParamField type="number">Page size.</ParamField>
<ParamField type="string | string[]">Include flags. `memberCount` adds each row's **direct** member count, resolved in one grouped query over the returned page rather than one request per workspace; omit it and the field is absent from each row. An array is joined with commas.</ParamField>

## Returns

Returns a `PaginatedResponse<Workspace>` (`{ data, pagination }`).

## Related

* [List Workspaces API](/api-reference/workspaces/fetch-workspaces)


# Fetch many workspaces (wrapper)
Source: https://docs.sublay.io/v7/hooks/workspaces/use-fetch-many-workspaces-wrapper

Paginated workspace list with accumulation and load-more

## Overview

`useFetchManyWorkspacesWrapper` follows the **Wrapper pattern** (mirroring `useFetchManyEntitiesWrapper`). It manages page state, accumulates results, and exposes a `loadMore`. There is **no** Redux slice — this is the house-style list hook for workspaces.

## Usage Example

```tsx theme={null}
import { useFetchManyWorkspacesWrapper } from "@sublay/react-js";

function WorkspaceList() {
  const { workspaces, loading, hasMore, loadMore } =
    useFetchManyWorkspacesWrapper({ limit: 10, include: ["memberCount"] });

  return (
    <div>
      {workspaces.map((w) => (
        <div key={w.id}>{w.name} — {w.memberCount} members</div>
      ))}
      {hasMore && <button disabled={loading} onClick={loadMore}>Load more</button>}
    </div>
  );
}
```

## Parameters

<ParamField type="number">
  Page size. Defaults to `10`.
</ParamField>

<ParamField type="string | string[]">
  Include flags. `memberCount` adds each accumulated workspace's **direct** member count; omit it and the field is absent. An array is joined with commas.
</ParamField>

## Returns

| Field        | Type          | Description                   |
| ------------ | ------------- | ----------------------------- |
| `workspaces` | `Workspace[]` | Accumulated list.             |
| `loading`    | `boolean`     | Whether a fetch is in flight. |
| `hasMore`    | `boolean`     | Whether more pages remain.    |
| `loadMore`   | `() => void`  | Fetch the next page.          |

## Related

* [List Workspaces API](/api-reference/workspaces/fetch-workspaces)


# Fetch my workspace invites
Source: https://docs.sublay.io/v7/hooks/workspaces/use-fetch-my-workspace-invites

The current user's inbox — live pending workspace invitations addressed to them

## Overview

`useFetchMyWorkspaceInvites` returns a callable for the signed-in user's **live** pending invites (`status='pending' AND expiresAt > now`), matched by `userId` from the token, across **every** workspace. This is the read that powers a "You've been invited" screen — and unlike every other workspace-invite read, each item embeds `workspace: { id, name }` and a populated `invitedBy` (instead of a bare id), since the invitee otherwise has no reach on either (a direct workspace read 404s for a non-member).

**Authorization:** self-service. No capability and no workspace scope — the caller is derived from the token. **Surfacing is not verification-gated**: a user sees invites right after signup; the verified check applies when they act on one — [accept](/hooks/workspaces/use-accept-workspace-invite) *and* [decline](/hooks/workspaces/use-decline-workspace-invite).

<Warning>
  **Inbox, not outbox.** `useFetchMyWorkspaceInvites` (`GET /me/workspace-invites`) lists the invites **addressed to the signed-in user**, spanning every workspace, with no capability required.

  [`useFetchWorkspaceInvites`](/hooks/workspaces/use-fetch-workspace-invites) (`GET /workspaces/:id/invites`) lists the invites **one workspace has issued**, and requires the `invite` capability there.

  These are the two most confusable hooks in the bundle. A members/admin panel wants the **other** hook; a personal notifications screen wants this one.
</Warning>

## Usage Example

```tsx theme={null}
import { useFetchMyWorkspaceInvites } from "@sublay/react-js";

function PendingInvites() {
  const fetchMyWorkspaceInvites = useFetchMyWorkspaceInvites();

  const load = async () => {
    const { data } = await fetchMyWorkspaceInvites();
    return data; // MyWorkspaceInvitation[] — invites addressed to me
  };
}
```

## Parameters

None — the user is derived from the token.

## Returns

`{ data: MyWorkspaceInvitation[] }` — each item a `MyWorkspaceInvitation`: a [WorkspaceInvitation](/data-models/workspace-invitation) with `workspace` and `invitedBy` embedded (see the note on that page). Never paginated.

## Related

* [`useFetchWorkspaceInvites`](/hooks/workspaces/use-fetch-workspace-invites) — the **outbox** counterpart
* [`useAcceptWorkspaceInvite`](/hooks/workspaces/use-accept-workspace-invite) · [`useDeclineWorkspaceInvite`](/hooks/workspaces/use-decline-workspace-invite)
* [List My Invites API](/api-reference/workspaces/invitations/list-my-invites)


# Fetch workspace
Source: https://docs.sublay.io/v7/hooks/workspaces/use-fetch-workspace

Read a single workspace, visibility-filtered

## Overview

`useFetchWorkspace` returns a callable that reads one [workspace](/data-models/workspace), filtered by the caller's reach-visibility.

## Usage Example

```tsx theme={null}
import { useFetchWorkspace } from "@sublay/react-js";

function WorkspaceHeader({ workspaceId }: { workspaceId: string }) {
  const fetchWorkspace = useFetchWorkspace();

  const load = async () => {
    const workspace = await fetchWorkspace({ workspaceId, include: "memberCount" });
    console.log(workspace.name, workspace.memberCount);
  };
}
```

## Parameters

<ParamField type="string">
  The workspace UUID.
</ParamField>

<ParamField type="string | string[]">
  Include flags; `memberCount` adds the direct member count. An array is joined with commas.
</ParamField>

## Returns

Returns the [Workspace](/data-models/workspace) object.

## Related

* [Fetch Workspace API](/api-reference/workspaces/fetch-workspace)


# Fetch workspace authority
Source: https://docs.sublay.io/v7/hooks/workspaces/use-fetch-workspace-authority

Resolve the current user's standing on a workspace

## Overview

`useFetchWorkspaceAuthority` returns a callable that resolves the signed-in user's standing on a workspace: `{ reasons, capabilities, permissions, rank }`. Use it to drive UI (show/hide buttons) — a permission check is a one-line `.includes()` on the result. Sublay never consumes your opaque `permissions`.

<Note>
  **Not visibility-gated.** [`GET /workspaces/:id/authority/me`](/api-reference/workspaces/fetch-authority) requires a signed-in user and nothing more. It returns `404` only when the workspace does not exist — a signed-in user with no relation to an existing workspace gets `200` with `reasons: []` and empty `capabilities` / `permissions`, which is exactly the answer a UI gate wants. The trade-off is that the route confirms a workspace *exists* to any signed-in caller.

  Its sibling, [`useFetchWorkspaceMemberStanding`](/hooks/workspaces/use-fetch-workspace-member-standing), *is* visibility-gated and `404`s on a workspace the caller cannot see, so it never leaks existence. Do not assume the two behave alike.
</Note>

## Usage Example

```tsx theme={null}
import { useFetchWorkspaceAuthority } from "@sublay/react-js";

function InviteGate({ workspaceId }: { workspaceId: string }) {
  const fetchWorkspaceAuthority = useFetchWorkspaceAuthority();

  const canInvite = async () => {
    const authority = await fetchWorkspaceAuthority({ workspaceId });
    return authority.capabilities.includes("invite");
  };
}
```

## Parameters

<ParamField type="string">
  The workspace UUID.
</ParamField>

## Returns

`WorkspaceAuthority`:

| Field          | Type                               | Description                                                                                                                                      |
| -------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `reasons`      | `WorkspaceAuthorityReasonDetail[]` | Why the user has standing — structured `{ type, viaWorkspaceId? }` entries (`type` is `"owner"`/`"ancestor-owner"`/`"member"`/`"reach-holder"`). |
| `capabilities` | `string[]`                         | The resolved capability set (direct + reach + ownership).                                                                                        |
| `permissions`  | `string[]`                         | Per-node permissions (may be empty).                                                                                                             |
| `rank`         | `number \| null`                   | Direct-membership rank, or `null`.                                                                                                               |

`WorkspaceAuthorityReasonDetail`:

| Field            | Type                                                        | Description                                                                                                                                             |
| ---------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`           | `"owner" \| "ancestor-owner" \| "member" \| "reach-holder"` | The kind of standing.                                                                                                                                   |
| `viaWorkspaceId` | `string?`                                                   | The ancestor granting it — present on `ancestor-owner` / `reach-holder` only. A user reaching in from several ancestors carries one entry per ancestor. |

<Note>
  **`view` is implied by every other capability.** Any user with standing resolves with `view` in `capabilities`, including a member whose stored `capabilities` array is empty. A user with no relation at all resolves to `reasons: []` and an empty capability set — so `capabilities.includes("view")` is a reliable "does this user have any standing here" check.
</Note>

Unlike the [member-standing read](/hooks/workspaces/use-fetch-workspace-member-standing), this hook is inherently a **self** read, so `capabilities` / `permissions` / `rank` are never fenced here — the fence exists to stop a caller reconstructing *someone else's* rank, and there is nobody else in this payload.

## Related

* [Read Authority API](/api-reference/workspaces/fetch-authority)


# Fetch workspace invites
Source: https://docs.sublay.io/v7/hooks/workspaces/use-fetch-workspace-invites

A workspace's outbox — the live pending invitations it has issued

## Overview

`useFetchWorkspaceInvites` returns a callable that lists the **live** pending invitations **one workspace has issued** (`status = 'pending' AND expiresAt > now` — effectively-expired rows are excluded). This is the read that powers the "Pending invitations" section of a members panel: who this team has invited and not yet heard back from.

**Authorization:** capability-gated. Requires the `invite` capability on the workspace (owners hold it implicitly).

The list is **always returned in full** — it is deliberately unpaginated, so there is no `page`/`limit` and no `*Wrapper` hook.

<Warning>
  **Outbox, not inbox.** `useFetchWorkspaceInvites` (`GET /workspaces/:id/invites`) lists the invites **this workspace sent out** — it is scoped to one workspace and needs the `invite` capability there.

  [`useFetchMyWorkspaceInvites`](/hooks/workspaces/use-fetch-my-workspace-invites) (`GET /me/workspace-invites`) lists the invites **addressed to the signed-in user** — it is scoped to the caller, spans every workspace, and needs no capability.

  These are the two most confusable hooks in the bundle. If you are building an admin/members screen you want **this** hook; if you are building a "You've been invited" screen you want the other one.
</Warning>

## Usage Example

```tsx theme={null}
import { useFetchWorkspaceInvites } from "@sublay/react-js";

function PendingInvitations({ workspaceId }: { workspaceId: string }) {
  const fetchWorkspaceInvites = useFetchWorkspaceInvites();

  const load = async () => {
    const { data } = await fetchWorkspaceInvites({ workspaceId });
    // data: WorkspaceInvitation[] — everyone this workspace has invited
    return data;
  };
}
```

Paired with [`useRevokeWorkspaceInvite`](/hooks/workspaces/use-revoke-workspace-invite) and [`useResendWorkspaceInvite`](/hooks/workspaces/use-resend-workspace-invite), this completes a members panel entirely on the client — no server-side code and no hand-rolled `fetch`.

## Parameters

<ParamField type="string">
  The workspace UUID whose issued invitations to list.
</ParamField>

## Returns

`{ data: WorkspaceInvitation[] }` — each item a [WorkspaceInvitation](/data-models/workspace-invitation) object. Never paginated.

## Error codes

| Code                     | Status | Meaning                                             |
| ------------------------ | ------ | --------------------------------------------------- |
| `workspace/unauthorized` | 403    | You lack the `invite` capability on this workspace. |
| `workspace/not-found`    | 404    | No such workspace in this project.                  |

## Related

* [`useFetchMyWorkspaceInvites`](/hooks/workspaces/use-fetch-my-workspace-invites) — the **inbox** counterpart
* [`useCreateWorkspaceInvite`](/hooks/workspaces/use-create-workspace-invite) · [`useRevokeWorkspaceInvite`](/hooks/workspaces/use-revoke-workspace-invite) · [`useResendWorkspaceInvite`](/hooks/workspaces/use-resend-workspace-invite)
* [List Workspace Invites API](/api-reference/workspaces/invitations/list-invites)


# Fetch workspace member standing
Source: https://docs.sublay.io/v7/hooks/workspaces/use-fetch-workspace-member-standing

One user's full resolved standing on a workspace, addressed by userId

## Overview

`useFetchWorkspaceMemberStanding` returns a callable that reads a single user's full standing on a workspace, addressed by **user id** (not a membership-row id, so it works even for users with no direct row). It returns the same unified shape as one roster row, computed on demand for **any** relation — direct `member`, this workspace's `owner`, an `ancestor-owner`, or a `reach-holder`.

**Authorization:** requires roster visibility on the workspace — **any relation** (owner, ancestor-owner, member, reach-holder), the same gate as [`useFetchWorkspaceMembers`](/hooks/workspaces/use-fetch-workspace-members). The signed-in user is the actor; `targetUserId` names **who is being read**, not who is asking.

<Warning>
  **`capabilities`, `permissions`, `rank` and `relativeRank` are fenced.** They are **omitted from the response** (absent — not `null`) unless the signed-in user holds one of the four people-operating capabilities on this workspace (`invite`, `remove-member`, `edit-member-access`, `edit-member-profile`), is the `owner` / an `ancestor-owner`, or is reading **their own** standing. The gate is scoped to **this** workspace — it is a per-node verdict, and your resolved standing here includes what reaches in from an open inherit chain but not what a **sealed** boundary blocks. The four fields are optional in the SDK type — read them defensively (`standing.capabilities ?? []`). Everything else (`user`, `reasons`, `title`, `metadata`) is visible to any relation. `relativeRank` is fenced *with* `rank`, not beside it: it is `rank` minus your own anchor, a number you already know, so leaking it would leak `rank` exactly.
</Warning>

## Usage Example

```tsx theme={null}
import { useFetchWorkspaceMemberStanding } from "@sublay/react-js";

function MemberDetail({
  workspaceId,
  targetUserId,
}: {
  workspaceId: string;
  targetUserId: string;
}) {
  const fetchWorkspaceMemberStanding = useFetchWorkspaceMemberStanding();

  const load = async () => {
    const standing = await fetchWorkspaceMemberStanding({
      workspaceId,
      targetUserId,
    });
    // { user, reasons, title, metadata } — plus capabilities/permissions/rank/relativeRank
    // when you may see them (see the fencing warning above).
  };
}
```

## Parameters

<ParamField type="string">
  The workspace UUID.
</ParamField>

<ParamField type="string">
  The **target** user whose standing to read — a path param, not an acting user.
</ParamField>

## Returns

`WorkspaceMemberStanding`:

| Field          | Type                               | Description                                                                                                                                                                                                                                                  |
| -------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `user`         | `WorkspaceStandingUser`            | The target user. Normally the full user record, but **only `id` is guaranteed** — see the note below.                                                                                                                                                        |
| `reasons`      | `WorkspaceAuthorityReasonDetail[]` | Why the user has standing — structured `{ type, viaWorkspaceId? }` entries. `viaWorkspaceId` names the granting ancestor and appears on `ancestor-owner` / `reach-holder` only.                                                                              |
| `capabilities` | `string[]?`                        | The **resolved** capability set (direct + reach + ownership). **Fenced** — see the warning above. **`view` is implied by every other capability**, so anyone with standing carries it.                                                                       |
| `permissions`  | `string[]?`                        | **Per-node** permissions (direct membership on this workspace only; may be empty). **Fenced.**                                                                                                                                                               |
| `rank`         | `number \| null` (optional)        | Direct-membership rank, or `null` for owners / ancestor-owners / reach-only holders. **Fenced.**                                                                                                                                                             |
| `relativeRank` | `number \| null` (optional)        | The target's position as an **offset from you**: `2` = two rungs below you, `-3` = three rungs *above* you, `0` = your peer. `null` exactly when `rank` is. Your own anchor is your member row here if you hold one, apex otherwise. **Fenced** with `rank`. |
| `title`        | `string \| null`                   | Cosmetic title.                                                                                                                                                                                                                                              |
| `metadata`     | `Record<string, any>`              | Opaque member metadata.                                                                                                                                                                                                                                      |

<Note>
  **Only `user.id` is guaranteed.** The server returns the full user record when the user row still exists, and falls back to `{ id }` alone when it does not — a deleted user with a lingering membership row is a reachable case. The SDK type reflects this: `id` is required and every other field is optional, so read the rest defensively (`standing.user.username ?? "Deleted user"`).
</Note>

## Error codes

| Code                     | Status | Meaning                                 |
| ------------------------ | ------ | --------------------------------------- |
| `workspace/unauthorized` | 403    | You cannot see this workspace's roster. |
| `workspace/not-found`    | 404    | No such workspace in this project.      |

## Related

* [`useFetchWorkspaceMembers`](/hooks/workspaces/use-fetch-workspace-members) — the whole roster
* [`useFetchWorkspaceAuthority`](/hooks/workspaces/use-fetch-workspace-authority) — the same read, but for yourself
* [Fetch Member Standing API](/api-reference/workspaces/members/fetch-member-standing)


# Fetch workspace members
Source: https://docs.sublay.io/v7/hooks/workspaces/use-fetch-workspace-members

The unified roster read — one entry per distinct user

## Overview

`useFetchWorkspaceMembers` returns a callable for the [unified roster](/api-reference/workspaces/members/list-members): one entry per distinct user, each with a `reasons` array. Always returned in full (never paginated). With `countOnly`, the shape is `WorkspaceRosterCountsResponse` instead.

<Warning>
  **No `page` / `limit` on this roster.** It is never paginated. `FetchWorkspaceMembersProps` carries only `workspaceId`, `include` and `countOnly`, and the hook builds its query string from exactly those three — so a `page` or `limit` hand-written past the types is never even sent. Calling the [REST route](/api-reference/workspaces/members/list-members) directly does not help either: that endpoint declares `include`, `countOnly`, `actingUserId` and `projectId`, and refuses anything else — `?page=2&limit=10` comes back as `{ "error": "Unrecognized keys: \"page\", \"limit\"", "code": "workspace/invalid-query" }`.

  The response is `{ data, total }` — no `pagination` object, because there is no pagination. `total` equals `data.length`.

  For counts, pass `countOnly` — it returns per-reason counts and a distinct-user total without materializing the roster array. For a windowed UI, slice `roster.data` client-side.
</Warning>

## Usage Example

```tsx theme={null}
import { useFetchWorkspaceMembers } from "@sublay/react-js";

function Roster({ workspaceId }: { workspaceId: string }) {
  const fetchWorkspaceMembers = useFetchWorkspaceMembers();

  const load = async () => {
    const roster = await fetchWorkspaceMembers({
      workspaceId,
      include: "ancestorOwners,descendants",
    });
    // roster.data: WorkspaceRosterEntry[]
  };
}
```

## Parameters

<ParamField type="string">
  The workspace UUID.
</ParamField>

<ParamField type="string">
  Comma-separated add-on buckets: `ancestorOwners`, `reachHolders`, `descendants`.
</ParamField>

<ParamField type="boolean">
  Return per-reason counts + a distinct-user total instead of the array.
</ParamField>

## Returns

`WorkspaceRosterResponse` (`{ data, total }`), or `WorkspaceRosterCountsResponse` (`{ counts, total, distinctUsers }`) when `countOnly` is set.

Each `WorkspaceRosterEntry` is `{ user, reasons }`, where a reason is `{ type, ...detail }` — `member` carries `rank` / `relativeRank` / `capabilities` / `permissions` / `title` / `metadata`, `ancestor-owner` and `reach-holder` carry `viaWorkspaceId` (reach-holder also `capabilities`), and `descendant-member` carries `workspaceId` / `rank` / `capabilities` — **never `relativeRank`**, since rank is per-workspace and an offset across two ladders would be meaningless.

<Warning>
  **`rank`, `relativeRank`, `capabilities` and `permissions` are fenced on other users' entries.** They are **omitted** (absent — not `null`) unless the signed-in user holds one of the four people-operating capabilities on this workspace (`invite`, `remove-member`, `edit-member-access`, `edit-member-profile`) or is the `owner` / an `ancestor-owner`. The caller's **own** entry always carries them, so anyone can discover their own access. Who is on the roster (`user`, reason `type`s, `title`, `metadata`, `viaWorkspaceId`) stays visible to any relation — read the four fenced fields defensively (`reason.capabilities ?? []`). `relativeRank` is a member's position as an **offset from you** (`1` = one rung below you, `-3` = three above), and it is fenced *with* `rank` because it is `rank` minus a number you already know.

  **The gate is per node.** With `include=descendants`, each `descendant-member` reason is judged against your resolved standing on *its own* workspace, not on the one you asked about — so operating people on the parent does not unfence a **sealed** child's ranks and capabilities. Seeing a descendant's roster and seeing its members' authority are two different tiers. (`relativeRank` is a separate matter: it is uniformly absent on descendant rows for everyone.)
</Warning>

## Related

* [List Members API](/api-reference/workspaces/members/list-members)


# Leave workspace
Source: https://docs.sublay.io/v7/hooks/workspaces/use-leave-workspace

Self-service departure — remove your own membership on this node

## Overview

`useLeaveWorkspace` returns a callable that removes the **signed-in user's own** direct membership on **this workspace node only**. Descendant memberships are untouched, and leaving a parent while still owning a child is fine — ownership is independent of membership. Fires `workspace.member.removed`.

**Authorization:** self-service. No capability is required; the actor is always the signed-in user, so this hook cannot remove anyone else (use [`useRemoveWorkspaceMember`](/hooks/workspaces/use-remove-workspace-member) for that).

<Note>
  An **owner** has no member row and cannot leave this way — an owner exits by [transferring ownership](/hooks/workspaces/use-transfer-workspace-ownership) or [deleting](/hooks/workspaces/use-delete-workspace) the workspace. If you have no direct member row here (you only reach in from an ancestor), leaving is a no-op / `404`.
</Note>

## Usage Example

```tsx theme={null}
import { useLeaveWorkspace } from "@sublay/react-js";

function LeaveButton({ workspaceId }: { workspaceId: string }) {
  const leaveWorkspace = useLeaveWorkspace();

  return (
    <button onClick={() => leaveWorkspace({ workspaceId })}>
      Leave workspace
    </button>
  );
}
```

## Parameters

<ParamField type="string">
  The workspace UUID.
</ParamField>

## Returns

Resolves to `void` (the endpoint returns `204 No Content`).

## Error codes

| Code                   | Status | Meaning                                                |
| ---------------------- | ------ | ------------------------------------------------------ |
| `workspace/not-found`  | 404    | You have no direct membership on this workspace.       |
| `workspace/sole-owner` | 409    | The sole owner must transfer ownership before leaving. |

## Related

* [`useRemoveWorkspaceMember`](/hooks/workspaces/use-remove-workspace-member) — remove someone else
* [Leave Workspace API](/api-reference/workspaces/members/leave-workspace)


# Remove workspace member
Source: https://docs.sublay.io/v7/hooks/workspaces/use-remove-workspace-member

Remove a member from this workspace node (rank-bounded; sole-owner protected)

## Overview

`useRemoveWorkspaceMember` returns a callable that removes a direct [member](/data-models/workspace-member) from **this workspace node only**. Fires `workspace.member.removed`.

**Authorization:** capability-gated + rank-bounded. Requires the `remove-member` capability, and you may act only on members ranked strictly below you.

<Note>
  Owners have no member row, so removal targets member rows only. **Sole-owner protection:** the owner cannot be removed while sole owner — [transfer ownership](/hooks/workspaces/use-transfer-workspace-ownership) first.
</Note>

## Usage Example

```tsx theme={null}
import { useRemoveWorkspaceMember } from "@sublay/react-js";

function RemoveButton({
  workspaceId,
  targetUserId,
}: {
  workspaceId: string;
  targetUserId: string;
}) {
  const removeWorkspaceMember = useRemoveWorkspaceMember();

  return (
    <button onClick={() => removeWorkspaceMember({ workspaceId, targetUserId })}>
      Remove
    </button>
  );
}
```

## Parameters

<ParamField type="string">
  The workspace UUID.
</ParamField>

<ParamField type="string">
  The **target** member to remove — a path param, not an acting user.
</ParamField>

## Returns

Resolves to `void` (the endpoint returns `204 No Content`).

## Error codes

| Code                          | Status | Meaning                                                |
| ----------------------------- | ------ | ------------------------------------------------------ |
| `workspace/unauthorized`      | 403    | You lack the `remove-member` capability.               |
| `workspace/insufficient-rank` | 403    | You may only remove members ranked strictly below you. |
| `workspace/sole-owner`        | 409    | The sole owner must transfer ownership first.          |

## Related

* [`useRemoveWorkspaceMemberFromSubtree`](/hooks/workspaces/use-remove-workspace-member-from-subtree) — offboard across descendants too
* [`useLeaveWorkspace`](/hooks/workspaces/use-leave-workspace) — the self-service equivalent
* [Remove Member API](/api-reference/workspaces/members/remove-member)


# Remove workspace member from subtree
Source: https://docs.sublay.io/v7/hooks/workspaces/use-remove-workspace-member-from-subtree

Offboarding convenience — remove a user from this workspace and the descendants you can reach

## Overview

`useRemoveWorkspaceMemberFromSubtree` returns a callable that removes a user's **direct** memberships on this workspace and every descendant **you can reach**, in one action. Each deletion fires `workspace.member.removed`.

**Authorization:** capability-gated + rank-bounded, evaluated **per node**. Requires `remove-member`, and the sweep is refused if you are outranked by the target at any node where you both hold a direct member row. An **owner** (or ancestor owner) reaches the whole subtree via the god-path; a **non-owner** only reaches descendants through an unbroken open inherit chain, so a **sealed** sub-workspace (`inheritsFromParent = false`) is left untouched for a non-owner.

<Warning>
  **A non-owner's sweep may be partial — check `skipped` before you call someone offboarded.** If the target still holds a membership in a descendant you cannot reach, it comes back in `skippedCount` / `skipped` instead of being removed. `removedCount` alone does **not** mean the user is gone from the subtree. An owner or ancestor owner always gets `skippedCount: 0`.
</Warning>

<Warning>
  **Owned descendants block, they do not cascade.** Because owners have no member row, this sweep does not cover descendant workspaces the target *owns*. It fails with `409 workspace/owns-descendants` and reports them, rather than silently orphaning ownership. Reassign each via [`useTransferWorkspaceOwnership`](/hooks/workspaces/use-transfer-workspace-ownership) or delete it, then retry.
</Warning>

## Usage Example

```tsx theme={null}
import { useRemoveWorkspaceMemberFromSubtree } from "@sublay/react-js";

function OffboardButton({
  workspaceId,
  targetUserId,
}: {
  workspaceId: string;
  targetUserId: string;
}) {
  const removeWorkspaceMemberFromSubtree =
    useRemoveWorkspaceMemberFromSubtree();

  const offboard = async () => {
    const { removedCount, removed, skippedCount, skipped } =
      await removeWorkspaceMemberFromSubtree({ workspaceId, targetUserId });

    console.log(`Removed from ${removedCount} workspaces`, removed);

    // Do NOT treat the user as offboarded on `removedCount` alone.
    if (skippedCount > 0) {
      const named = skipped.filter((w) => w.id !== null);
      console.warn(
        `Still a member of ${skippedCount} workspace(s) you cannot reach` +
          (named.length
            ? `: ${named.map((w) => w.name).join(", ")}`
            : ` (identities withheld — ask an owner of those branches)`)
      );
    }
  };
}
```

## Parameters

<ParamField type="string">
  The workspace UUID — the subtree root.
</ParamField>

<ParamField type="string">
  The **target** user to offboard — a path param, not an acting user.
</ParamField>

## Returns

| Field          | Type                                                                     | Description                                                                                                                                          |
| -------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `removedCount` | `number`                                                                 | How many membership rows were torn down.                                                                                                             |
| `removed`      | `{ workspaceId: string; userId: string }[]`                              | One entry per removed membership.                                                                                                                    |
| `skippedCount` | `number`                                                                 | How many memberships the target **retained** because your authority did not reach them. `0` for an owner or ancestor owner. Equals `skipped.length`. |
| `skipped`      | `{ id: string \| null; name: string \| null; reason: "out-of-reach" }[]` | One entry per retained membership.                                                                                                                   |

### Reading `skipped`

Each entry names a descendant where the target is **still a member** after this call.

* `id` / `name` are `null` when you have no standing on that workspace. The call tells you a membership survived without disclosing the existence or name of a sealed sub-workspace you have no authority over — the same sealing fence [`useFetchWorkspaceMembers`](/hooks/workspaces/use-fetch-workspace-members) applies to `include=descendants`. Escalate to an owner or ancestor owner of that branch.
* `reason` is currently always `"out-of-reach"`.
* Only descendants where the target **actually still holds a direct membership** are listed — unreachable descendants they were never in are never disclosed.

## Error codes

| Code                          | Status | Meaning                                                                              |
| ----------------------------- | ------ | ------------------------------------------------------------------------------------ |
| `workspace/owns-descendants`  | 409    | The target owns workspaces in this subtree; the response includes `ownedWorkspaces`. |
| `workspace/insufficient-rank` | 403    | You are outranked by the target at some node in the sweep.                           |
| `workspace/unauthorized`      | 403    | You lack the `remove-member` capability.                                             |

## Related

* [`useRemoveWorkspaceMember`](/hooks/workspaces/use-remove-workspace-member) — this node only
* [Remove From Subtree API](/api-reference/workspaces/members/remove-from-subtree)


# Resend workspace invite
Source: https://docs.sublay.io/v7/hooks/workspaces/use-resend-workspace-invite

Refresh a lapsed pending invitation and resend the email

## Overview

`useResendWorkspaceInvite` returns a callable that refreshes a pending [invitation](/data-models/workspace-invitation) — it sets `expiresAt = now + 14 days` and resends the email. It is **valid on any `pending` invite, including one already past `expiresAt`** (resend = refresh a lapsed invite). A **terminal** invite (`accepted`/`declined`/`revoked`) fails with `409`.

**Authorization:** capability-gated. Requires the `invite` capability on the workspace (owners hold it implicitly).

<Note>
  The underlying route is a verb-suffixed **`POST /workspaces/:id/invites/:inviteId/resend`**. Resend emits **no webhook** — the status stays `pending`, so there is no lifecycle transition.
</Note>

<Warning>
  **Your project must have `workspaces.inviteAcceptUrl` set**, exactly as [`useCreateWorkspaceInvite`](/hooks/workspaces/use-create-workspace-invite) requires — resending an email with nowhere to deep-link is equally pointless. Without it the call fails with `409 workspace/missing-invite-accept-url` and `expiresAt` is left untouched. See [Project settings](/sdk/workspaces/overview#project-settings).
</Warning>

## Usage Example

```tsx theme={null}
import { useResendWorkspaceInvite } from "@sublay/react-js";

function ResendButton({
  workspaceId,
  inviteId,
}: {
  workspaceId: string;
  inviteId: string;
}) {
  const resendWorkspaceInvite = useResendWorkspaceInvite();

  const handleResend = async () => {
    const invite = await resendWorkspaceInvite({ workspaceId, inviteId });
    console.log("New expiry:", invite.expiresAt);
  };

  return <button onClick={handleResend}>Resend</button>;
}
```

## Parameters

<ParamField type="string">
  The workspace UUID.
</ParamField>

<ParamField type="string">
  The invitation UUID.
</ParamField>

## Returns

Returns the refreshed [WorkspaceInvitation](/data-models/workspace-invitation) object, with a reset `expiresAt`.

## Error codes

| Code                                  | Status | Meaning                                                                                                                                         |
| ------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `workspace/unauthorized`              | 403    | You lack the `invite` capability on this workspace.                                                                                             |
| `workspace/invite-not-found`          | 404    | No such invitation on this workspace.                                                                                                           |
| `workspace/invite-terminal`           | 409    | The invitation is accepted / declined / revoked — create a new one instead.                                                                     |
| `workspace/missing-invite-accept-url` | 409    | The **project** has no [`workspaces.inviteAcceptUrl`](/sdk/workspaces/overview#project-settings) configured. The invitation row is not touched. |

## Related

* [`useFetchWorkspaceInvites`](/hooks/workspaces/use-fetch-workspace-invites) — list what there is to resend
* [`useRevokeWorkspaceInvite`](/hooks/workspaces/use-revoke-workspace-invite)
* [Project settings](/sdk/workspaces/overview#project-settings) — the required `workspaces.inviteAcceptUrl`
* [Resend Invite API](/api-reference/workspaces/invitations/resend-invite)


# Revoke workspace invite
Source: https://docs.sublay.io/v7/hooks/workspaces/use-revoke-workspace-invite

Revoke a pending workspace invitation

## Overview

`useRevokeWorkspaceInvite` returns a callable that marks a pending [invitation](/data-models/workspace-invitation) `revoked`. Fires `workspace.invite.revoked`.

**Authorization:** capability-gated. Requires the `invite` capability on the workspace (owners hold it implicitly) — the same gate as creating and listing invites.

<Note>
  The underlying route is a verb-suffixed **`POST /workspaces/:id/invites/:inviteId/revoke`**, not a `DELETE`. The hook handles this for you; it is worth knowing if you are comparing against the [API reference](/api-reference/workspaces/invitations/revoke-invite).
</Note>

## Usage Example

```tsx theme={null}
import {
  useFetchWorkspaceInvites,
  useRevokeWorkspaceInvite,
} from "@sublay/react-js";

function InviteRow({
  workspaceId,
  inviteId,
}: {
  workspaceId: string;
  inviteId: string;
}) {
  const revokeWorkspaceInvite = useRevokeWorkspaceInvite();
  const fetchWorkspaceInvites = useFetchWorkspaceInvites();

  const handleRevoke = async () => {
    await revokeWorkspaceInvite({ workspaceId, inviteId });
    await fetchWorkspaceInvites({ workspaceId }); // refresh the outbox
  };

  return <button onClick={handleRevoke}>Revoke</button>;
}
```

## Parameters

<ParamField type="string">
  The workspace UUID.
</ParamField>

<ParamField type="string">
  The invitation UUID.
</ParamField>

## Returns

`{ success: boolean }`.

## Error codes

| Code                         | Status | Meaning                                             |
| ---------------------------- | ------ | --------------------------------------------------- |
| `workspace/unauthorized`     | 403    | You lack the `invite` capability on this workspace. |
| `workspace/invite-not-found` | 404    | No such invitation on this workspace.               |

## Related

* [`useFetchWorkspaceInvites`](/hooks/workspaces/use-fetch-workspace-invites) — list what there is to revoke
* [`useResendWorkspaceInvite`](/hooks/workspaces/use-resend-workspace-invite)
* [Revoke Invite API](/api-reference/workspaces/invitations/revoke-invite)


# Transfer workspace ownership
Source: https://docs.sublay.io/v7/hooks/workspaces/use-transfer-workspace-ownership

Owner-only ownership transfer, keeping ownerId and member rows disjoint

## Overview

`useTransferWorkspaceOwnership` returns a callable that reassigns a [workspace](/data-models/workspace)'s `ownerId`.

**Authorization:** owner-only. The signed-in user must be this workspace's own owner **or any ancestor owner** — never a capability or reach. (Ancestor-owner transfer is what makes offboarding resolvable: a manager can reassign a departing member's owned sub-workspace without that member's cooperation.)

* The new owner must be a **verified** user in the tenant — they need not already be a member.
* The new owner's existing member row (if any) is removed, keeping `ownerId` and member rows disjoint.
* The previous owner is **demoted** into a fresh member row or **removed**. It defaults to `remove` whenever the field is omitted — on a voluntary self-transfer as much as on an ancestor-owner reassign; pass `"demote"` to keep them on the roster. On demote, rank defaults to **one rung below you** — `0` when you are apex (the usual case), or one below your own row if you are an ancestor owner who also sits in this workspace's ladder.

## Usage Example

```tsx theme={null}
import { useTransferWorkspaceOwnership } from "@sublay/react-js";

function TransferOwnership({ workspaceId }: { workspaceId: string }) {
  const transferWorkspaceOwnership = useTransferWorkspaceOwnership();

  const handleTransfer = async (newOwnerId: string) => {
    const workspace = await transferWorkspaceOwnership({
      workspaceId,
      newOwnerId,
      previousOwnerDisposition: "demote",
      previousOwnerRank: 0,
      previousOwnerCapabilities: ["view"],
    });
    console.log("New owner:", workspace.ownerId);
  };
}
```

## Parameters

<ParamField type="string">
  The workspace UUID.
</ParamField>

<ParamField type="string">
  The new owner — any **verified** user in the tenant. This is the transfer **target**, not an acting user.
</ParamField>

<ParamField type="&#x22;demote&#x22; | &#x22;remove&#x22;">
  What happens to the outgoing owner. Defaults to `remove` when omitted, on every path.
</ParamField>

<ParamField type="number">
  On demote, the ex-owner's rank. **Absolute only** — no relative form. Defaults to **one rung below your own anchor**: `0` when you are apex (an owner or ancestor owner with no member row here), or `yourRank + 1` when you do hold a row here, so the default never seats the outgoing owner above you. An explicit value is honored verbatim.
</ParamField>

<ParamField type="WorkspaceCapability[]">
  On demote, the ex-owner's capabilities.
</ParamField>

## Returns

Returns the updated [Workspace](/data-models/workspace) object with the new `ownerId`.

## Error codes

| Code                           | Status | Meaning                                     |
| ------------------------------ | ------ | ------------------------------------------- |
| `workspace/unauthorized`       | 403    | You are not the owner or an ancestor owner. |
| `workspace/email-not-verified` | 403    | The new owner has no verified email.        |
| `workspace/invalid-target`     | 404    | The target user does not exist.             |

## Related

* [Transfer Ownership API](/api-reference/workspaces/transfer-ownership)


# Update workspace
Source: https://docs.sublay.io/v7/hooks/workspaces/use-update-workspace

Edit a workspace's name and metadata from the client

## Overview

`useUpdateWorkspace` returns a callable that edits a [workspace](/data-models/workspace)'s own `name` and/or `metadata`. The actor is the signed-in user.

**Authorization:** capability-gated. Requires the `edit-workspace` capability (owners hold it implicitly).

<Note>
  This does **not** flip `inheritsFromParent` — that is a separate owner-only action, [`useUpdateWorkspaceInheritFlag`](/hooks/workspaces/use-update-workspace-inherit-flag).
</Note>

## Usage Example

```tsx theme={null}
import { useUpdateWorkspace } from "@sublay/react-js";

function RenameWorkspace({ workspaceId }: { workspaceId: string }) {
  const updateWorkspace = useUpdateWorkspace();

  const handleRename = async (name: string) => {
    const workspace = await updateWorkspace({ workspaceId, name });
    console.log("Renamed to:", workspace.name);
  };
}
```

## Parameters

<ParamField type="string">
  The workspace UUID.
</ParamField>

<ParamField type="string">
  New display name. 1–100 characters.
</ParamField>

<ParamField type="Record<string, any>">
  New opaque developer metadata.
</ParamField>

## Returns

Returns the updated [Workspace](/data-models/workspace) object.

## Error codes

| Code                     | Status | Meaning                                   |
| ------------------------ | ------ | ----------------------------------------- |
| `workspace/unauthorized` | 403    | You lack the `edit-workspace` capability. |
| `workspace/not-found`    | 404    | No such workspace in this project.        |

## Related

* [`useFetchWorkspaceAuthority`](/hooks/workspaces/use-fetch-workspace-authority) — check `edit-workspace` before showing the form
* [Update Workspace API](/api-reference/workspaces/update-workspace)


# Update workspace inherit flag
Source: https://docs.sublay.io/v7/hooks/workspaces/use-update-workspace-inherit-flag

Owner-only flip of the reach/inherit flag

## Overview

`useUpdateWorkspaceInheritFlag` returns a callable that flips a workspace's `inheritsFromParent` flag — the switch controlling whether authority held on an ancestor reaches into this node. See [Reach & the wall/door rule](/data-models/workspace#reach-and-the-wall-door-rule).

**Authorization:** owner-only, in both directions. The signed-in user must be this workspace's own owner or an ancestor owner. **No capability grants this.** It is additionally blocked when the project sets [`workspaces.inheritEnforced`](/sdk/workspaces/overview#project-settings).

## Usage Example

```tsx theme={null}
import { useUpdateWorkspaceInheritFlag } from "@sublay/react-js";

function InheritToggle({ workspaceId }: { workspaceId: string }) {
  const updateWorkspaceInheritFlag = useUpdateWorkspaceInheritFlag();

  const seal = async () => {
    // false = sealed (a wall); true = open (a door)
    await updateWorkspaceInheritFlag({
      workspaceId,
      inheritsFromParent: false,
    });
  };
}
```

## Parameters

<ParamField type="string">
  The workspace UUID.
</ParamField>

<ParamField type="boolean">
  The new flag value — `true` = open/door, `false` = sealed/wall.
</ParamField>

## Returns

Returns the updated [Workspace](/data-models/workspace) object.

## Error codes

| Code                         | Status | Meaning                                                               |
| ---------------------------- | ------ | --------------------------------------------------------------------- |
| `workspace/unauthorized`     | 403    | You are not the owner or an ancestor owner.                           |
| `workspace/inherit-enforced` | 403    | The project enforces its inherit default; the flag cannot be changed. |

## Related

* [`useUpdateWorkspace`](/hooks/workspaces/use-update-workspace) — for name/metadata
* [Flip Inherit Flag API](/api-reference/workspaces/update-inherit-flag)


# Update workspace member
Source: https://docs.sublay.io/v7/hooks/workspaces/use-update-workspace-member

Edit a member's access or profile fields, with two capability tiers

## Overview

`useUpdateWorkspaceMember` returns a callable that edits a direct [member](/data-models/workspace-member) of a workspace.

**Authorization:** capability-gated + rank-bounded, in **two tiers by field sensitivity**:

* **Powerful fields** (`capabilities`, `permissions`, and rank — as either `rank` or `relativeRank`) require **`edit-member-access`**, plus the [rank rule](/data-models/workspace-member#rank-semantics) and the [no-escalation](/data-models/workspace-member#no-privilege-escalation) guard.
* **Cosmetic fields** (`title`, `metadata`) require only **`edit-member-profile`**. A member editing **their own `title`** needs no capability at all.

**Grant vs strip asymmetry:** you may only *add* a capability/permission you hold on the target node (resolved set, including via reach); *stripping* is governed by rank alone.

**Rank moves in either coordinate** — `rank` (absolute) or `relativeRank` (an offset from you), never both. Omitting **both** means **rank unchanged**: unlike the invite hook there is no value default here, so editing someone's capabilities never quietly moves them on the ladder. See [choosing a rank](/sdk/workspaces/overview#choosing-a-rank).

## Usage Example

```tsx theme={null}
import { useUpdateWorkspaceMember } from "@sublay/react-js";

function MemberRow({
  workspaceId,
  targetUserId,
}: {
  workspaceId: string;
  targetUserId: string;
}) {
  const updateWorkspaceMember = useUpdateWorkspaceMember();

  const promote = async () => {
    const member = await updateWorkspaceMember({
      workspaceId,
      targetUserId,
      capabilities: ["view", "invite"],
      // Absolute. Use `relativeRank: 1` instead for "one rung below me",
      // or omit both to change capabilities without touching the ladder.
      rank: 3,
    });
    console.log("Updated:", member.id);
  };
}
```

## Parameters

<ParamField type="string">
  The workspace UUID.
</ParamField>

<ParamField type="string">
  The **target** member's user id — a path param, not an acting user.
</ParamField>

<ParamField type="WorkspaceCapability[]">
  New capability set (powerful — `edit-member-access`).
</ParamField>

<ParamField type="string[]">
  New opaque permission set (powerful — `edit-member-access`).
</ParamField>

<ParamField type="number">
  New **absolute** rank, `0` – `2147483647` (powerful — `edit-member-access` + rank rules). Mutually exclusive with `relativeRank`; omitting both leaves rank unchanged.
</ParamField>

<ParamField type="number">
  New rank as an **offset from you**: `1` = one rung below me. Must be `1` – `2147483647`. Anchored on your own rank if you hold a member row on this workspace, apex otherwise. Resolved to an absolute number at write time and frozen — a **snapshot**, not a link to your rank. The resolved value is bounded too, so an offset that overflows once anchored is a `400`. No default: omitting both rank fields leaves rank unchanged.
</ParamField>

<ParamField type="string | null">
  New cosmetic title (`edit-member-profile`, or self for your own title).
</ParamField>

<ParamField type="Record<string, any>">
  New cosmetic metadata (`edit-member-profile`).
</ParamField>

## Returns

Returns the updated [WorkspaceMember](/data-models/workspace-member) object.

## Error codes

| Code                          | Status | Meaning                                                                                                                                                                                                                                                                |
| ----------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `workspace/unauthorized`      | 403    | You lack the capability tier for a field you touched.                                                                                                                                                                                                                  |
| `workspace/insufficient-rank` | 403    | Two rules share this code: you may only **manage** members ranked strictly below you, and you may only **set** ranks strictly below your own. The second is also what refuses `rank: 0` to anyone holding a row on this workspace — there is no separate rank-0 guard. |
| `workspace/no-escalation`     | 403    | You tried to grant a capability/permission you do not hold.                                                                                                                                                                                                            |

## Related

* [`useRemoveWorkspaceMember`](/hooks/workspaces/use-remove-workspace-member)
* [Update Member API](/api-reference/workspaces/members/update-member)


# Change Password
Source: https://docs.sublay.io/v7/api-reference/auth/change-password

POST /v7/:projectId/auth/change-password
Change the authenticated user's password

Changes the password for the currently authenticated user. The user must provide their current password for verification. Requires a valid access token in the `Authorization` header.

<Note>
  This endpoint is only available to users who signed up with email and password.
  OAuth-only users who have no password will receive a `400` error.
</Note>

## What a password change ends

A password change is what someone reaches for when they think their account has been taken, so it
ends sessions rather than only rotating a secret. In one transaction, the server:

* writes the new password;
* deletes **every push binding** this user holds, on every device, so notification content stops
  routing to a device an intruder may hold — except the device named by the optional `pushDevice`
  field below. Projects without the `push` bundle skip this step and are otherwise unaffected;
* destroys **every refresh-token family** for this user except the caller's own.

Either all three land or none does.

<Note>
  **The caller's own session survives, and nothing has to be sent for that.** The access token this
  route is authenticated by carries the id of the session it was minted from, so the server can tell
  which of the user's sessions is asking. The user stays signed in where they are standing; every
  other device must sign in again with the new password.

  A **service or master key** is not a session, so a call made with one has nothing to spare and
  ends every session for the user.
</Note>

<Warning>
  **Name your device or it stops notifying.** Nothing re-binds a device to push from its live
  session — repair happens on a cold start, an account switch or a token rotation, which on a
  resident mobile app can be days away. So a client that does not send `pushDevice` keeps its
  session but loses its notifications until one of those happens.
</Warning>

Existing **access** tokens are not revoked by this: an access token minted before the change keeps
working until it expires, up to 30 minutes. It is the refresh families that go, so no other device
can mint a new one.

## Body Parameters

<ParamField type="string">
  The user's current password.
</ParamField>

<ParamField type="string">
  The new password. Must be different from the current password.
</ParamField>

<ParamField type="object">
  The physical device making the call, so **its** push binding survives while every other device
  this user is bound to loses theirs.

  The same shape [Register Device](/api-reference/push-notifications/register-device) and
  [Sign Out](/api-reference/auth/sign-out) take: `{ platform: "ios" | "android", token }` for
  native, `{ platform: "web", subscription }` for Web Push. It only ever spares a binding belonging
  to this user, so it cannot keep another account's binding alive on a shared device.

  Omit it and every binding for the user is deleted, this device's included.
</ParamField>

<ParamField type="string">
  The acting user. **Service/master keys only** — an end-user token infers it from the access token
  and may not name a different user.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  `true` on success.
</ResponseField>

<ResponseField name="message" type="string">
  Confirmation message: `"Password updated successfully."`
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="User Not Found — 403">
    ```json theme={null}
    {
      "error": "User not found.",
      "code": "auth/no-user-found"
    }
    ```
  </Accordion>

  <Accordion title="Not Password Authenticated — 400">
    ```json theme={null}
    {
      "error": "User is not authenticated with email and password.",
      "code": "auth/not-password-authenticated"
    }
    ```
  </Accordion>

  <Accordion title="Wrong Password — 401">
    ```json theme={null}
    {
      "error": "Incorrect password.",
      "code": "auth/wrong-password"
    }
    ```
  </Accordion>

  <Accordion title="Invalid Body — 400">
    ```json theme={null}
    { "error": "...", "code": "auth/invalid-body" }
    ```

    Returned when a required field is missing, when `newPassword` fails the password
    rules, when `newPassword` equals `password`, or when `pushDevice` is malformed —
    for example `platform: "ios"` with no `token`.
  </Accordion>

  <Accordion title="Missing User ID — 400">
    ```json theme={null}
    { "error": "Missing user ID", "code": "auth/missing-user-id" }
    ```

    Returned when a service/master key calls this route without naming a `userId`.
  </Accordion>

  <Accordion title="Acting As Another User — 403">
    ```json theme={null}
    { "error": "Unauthorized", "code": "auth/unauthorized" }
    ```

    Returned when an end-user token names a `userId` other than its own.
  </Accordion>

  <Accordion title="Server Error — 500">
    ```json theme={null}
    {
      "error": "Internal server error.",
      "code": "auth/server-error"
    }
    ```

    Nothing was committed — the password, the sessions and the push bindings are all
    as they were.
  </Accordion>
</AccordionGroup>

**Rate limit:** 5 requests per 5 minutes per IP. Exceeding it returns `429` with the plain-text message `Too many attempts to change password, please wait 5 minutes` and no `code`.

## See Also

* [`useAuth` hook](/hooks/auth/use-auth) — `changePassword`
* [Built-in Auth guide](/sdk/authentication/built-in)


# Confirm Account Deletion
Source: https://docs.sublay.io/v7/api-reference/auth/confirm-account-deletion

POST /v7/:projectId/auth/confirm-account-deletion
Verify the emailed code and permanently delete the authenticated user's account

Completes the self-service account-deletion flow. Verifies the one-time code sent by the [Request Account Deletion](/api-reference/auth/request-account-deletion) endpoint and, on a match, **permanently deletes** the authenticated user's account.

Requires a valid user access token. The cascade is identical to the service-key [Delete User](/api-reference/users/delete-user) endpoint: reactions, files, follows, connections, collections, reports, mentions, notifications, and embeddings are removed, while the user's entities and comments are preserved as hollow shells (their `userId`, content, and attachments cleared) to keep threads intact.

<Warning>
  Deletion is **immediate and irreversible**. There is no grace period and no
  recovery once this endpoint returns `204`.
</Warning>

## Body Parameters

<ParamField type="string">
  The one-time confirmation code from the deletion email. Must match the most recently issued code exactly.
</ParamField>

## Response

Returns `204 No Content` on success. The user and their session tokens no longer exist after this call.

## Error Codes

| Code                           | Status | Description                                                                |
| ------------------------------ | ------ | -------------------------------------------------------------------------- |
| `auth/invalid-or-expired-code` | 400    | The code does not match, was never issued, or has expired (10-minute TTL). |
| `user/not-found`               | 404    | The authenticated user no longer exists.                                   |
| `user/delete-failed`           | 404    | The user could not be deleted (not found or already deleted).              |

<Note>
  The confirmation code is single-use — it is consumed once deletion succeeds,
  so it cannot be replayed. If deletion fails with a server error, the code is
  left in place so you can retry until it expires (10-minute TTL).
</Note>

## See Also

* [`useConfirmAccountDeletion` hook](/hooks/auth/use-confirm-account-deletion)
* [Request Account Deletion endpoint](/api-reference/auth/request-account-deletion)
* [Delete User (service key) endpoint](/api-reference/users/delete-user)


# Request Access Token
Source: https://docs.sublay.io/v7/api-reference/auth/request-access-token

POST /v7/:projectId/auth/request-new-access-token
Obtain a new access token using a refresh token

Exchanges a valid refresh token for a new access token and a new refresh token. This endpoint implements **refresh token rotation**: every successful call revokes the current refresh token and issues a replacement. Reusing a revoked refresh token is detected as a potential replay attack and results in the entire token family being invalidated.

## Body Parameters

<ParamField type="string">
  The refresh token JWT. If omitted or `null`, the server returns `200` with
  `{ user: null, accessToken: null }` — indicating no active session. The
  `success` and `refreshToken` fields are absent in this case.
</ParamField>

## Response

When a valid refresh token is provided, the response is:

<ResponseField name="success" type="boolean">
  `true` when a valid refresh token was provided and a new session was issued.
  This field is absent when no refresh token was submitted.
</ResponseField>

<ResponseField name="accessToken" type="string | null">
  New short-lived JWT access token. Expires in 30 minutes. `null` if no refresh
  token was provided.
</ResponseField>

<ResponseField name="refreshToken" type="string">
  New long-lived JWT refresh token (rotated). Expires in 30 days. This field is
  absent when no refresh token was provided.
</ResponseField>

<ResponseField name="user" type="object | null">
  The authenticated user's full profile, or `null` if no refresh token was
  provided.

  <Expandable title="properties">
    <ResponseField name="id" type="string">Unique user ID (UUID).</ResponseField>
    <ResponseField name="foreignId" type="string | null">External user ID, if set.</ResponseField>
    <ResponseField name="role" type="string">User role.</ResponseField>
    <ResponseField name="email" type="string | null">Email address.</ResponseField>
    <ResponseField name="name" type="string | null">Display name.</ResponseField>
    <ResponseField name="username" type="string | null">Username.</ResponseField>
    <ResponseField name="avatar" type="string | null">Avatar URL.</ResponseField>
    <ResponseField name="bio" type="string | null">Bio text.</ResponseField>
    <ResponseField name="metadata" type="object | null">Public custom data.</ResponseField>
    <ResponseField name="reputation" type="number | null">Reputation score.</ResponseField>
    <ResponseField name="isVerified" type="boolean | null">Whether the user is verified.</ResponseField>
    <ResponseField name="isActive" type="boolean | null">Whether the account is active.</ResponseField>
    <ResponseField name="lastActive" type="string | null">ISO timestamp of last activity.</ResponseField>
    <ResponseField name="suspensions" type="array">Active suspensions on the account.</ResponseField>
    <ResponseField name="avatarFile" type="object | null">Processed avatar file with variants.</ResponseField>
    <ResponseField name="bannerFile" type="object | null">Processed banner file with variants.</ResponseField>
    <ResponseField name="authMethods" type="string[]">List of auth methods.</ResponseField>
    <ResponseField name="createdAt" type="string">ISO timestamp of account creation.</ResponseField>
  </Expandable>
</ResponseField>

## Token Rotation and Reuse Detection

Each call to this endpoint revokes the submitted refresh token and issues a new one. If the same refresh token is submitted again after being revoked:

* **Within 30 seconds of revocation** (grace period): The server returns the successor token to handle concurrent requests gracefully.
* **After 30 seconds**: The entire token family is destroyed and the user must sign in again on every device that shared it.

Reuse detection ends **sessions only**. Push bindings are left in place, so notifications keep arriving on the user's devices and resume normally once each signs back in. Re-presenting a spent refresh token is a signal, not a proof — an app killed mid-refresh, a staggered multi-tab restore or a response lost in transit all look identical to it, which is what the 30-second grace window exists for — and none of those should silence every handset a user owns. The two events that *do* clear push bindings are ones the user deliberately takes: [Reset Password](/api-reference/auth/reset-password) and [Change Password](/api-reference/auth/change-password).

## Error Responses

<AccordionGroup>
  <Accordion title="Project Mismatch — 403">
    ```json theme={null}
    {
      "error": "Refresh token does not match this project.",
      "code": "auth/refresh-token-project-mismatch"
    }
    ```
  </Accordion>

  <Accordion title="Token Not Recognized — 403">
    ```json theme={null}
    {
      "error": "Refresh token not recognized.",
      "code": "auth/refresh-token-mismatch"
    }
    ```
  </Accordion>

  <Accordion title="Token Reuse Detected — 401">
    ```json theme={null}
    {
      "error": "Token reuse detected. All sessions in this family have been revoked.",
      "code": "auth/token-reuse-detected"
    }
    ```
  </Accordion>

  <Accordion title="Token Expired or Malformed — 403">
    ```json theme={null}
    {
      "error": "Refresh token is expired or malformed.",
      "code": "auth/refresh-token-malformed"
    }
    ```
  </Accordion>

  <Accordion title="User Not Found — 403">
    ```json theme={null}
    {
      "error": "User not found.",
      "code": "auth/no-user-found"
    }
    ```
  </Accordion>
</AccordionGroup>

## See Also

* [`useAuth` hook](/hooks/auth/use-auth) — `requestNewAccessToken`
* [Authentication overview](/sdk/authentication/overview)


# Request Account Deletion
Source: https://docs.sublay.io/v7/api-reference/auth/request-account-deletion

POST /v7/:projectId/auth/request-account-deletion
Email the authenticated user a one-time code to confirm self-service account deletion

Starts the self-service account-deletion flow for the authenticated user. The server generates a one-time, 6-digit confirmation code, emails it to the user's registered address, and stores it for **10 minutes**. The user completes deletion by passing that code to the [Confirm Account Deletion](/api-reference/auth/confirm-account-deletion) endpoint.

Requires a valid user access token. This step does **not** delete anything — it only sends the code.

<Warning>
  This flow only works for accounts with an email on file. Accounts without one
  (e.g. anonymous or foreign-id users) cannot self-serve deletion — delete them
  server-side with a service key via the [node SDK](/node-sdk/users).
</Warning>

## Body Parameters

This endpoint takes no body parameters.

## Response

<ResponseField name="success" type="boolean">
  `true` when the request is processed without a server error. The response is intentionally generic.
</ResponseField>

## Error Codes

| Code                    | Status | Description                                                                                                                         |
| ----------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `auth/no-email-on-file` | 400    | The authenticated account has no email address, so a confirmation code cannot be delivered. Use a service key to delete it instead. |
| `auth/no-user-found`    | 403    | The access token is valid but no matching user record exists (e.g. the account was already deleted).                                |

<Note>
  Each call generates a fresh code and overwrites any pending one for that user.
  The code expires after 10 minutes.
</Note>

## See Also

* [`useRequestAccountDeletion` hook](/hooks/auth/use-request-account-deletion)
* [Confirm Account Deletion endpoint](/api-reference/auth/confirm-account-deletion)
* [Delete User (service key) endpoint](/api-reference/users/delete-user)


# Request Password Reset
Source: https://docs.sublay.io/v7/api-reference/auth/request-password-reset

POST /v7/:projectId/auth/request-password-reset
Send a password reset email to a user

Sends a password reset email to the specified address if an account with that email exists and has a password set. The reset link in the email expires after 1 hour.

The response is always a generic success message regardless of whether the email is registered. This prevents user enumeration.

## Body Parameters

<ParamField type="string">
  The email address to send the reset link to.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Always `true` when the request is processed without a server error.
</ResponseField>

<ResponseField name="message" type="string">
  Generic confirmation message: `"If an account with that email exists, a password reset link has been sent."`
</ResponseField>

<Note>
  The password reset token is stored as a SHA-256 hash in the database.
  Only one reset token is active per user at a time — requesting a new one
  overwrites the previous token.
</Note>

## See Also

* [`useRequestPasswordReset` hook](/hooks/auth/use-request-password-reset)
* [Reset Password endpoint](/api-reference/auth/reset-password)
* [Built-in Auth guide](/sdk/authentication/built-in)


# Reset Password
Source: https://docs.sublay.io/v7/api-reference/auth/reset-password

POST /v7/:projectId/auth/reset-password
Reset a user's password using a token from the reset email

Sets a new password for a user by validating a reset token received via email.

On success, in one transaction, the server writes the new password, invalidates **every refresh token** for that user — including the session that asked for the reset — and deletes **every push binding** that user holds on every device, so notification content stops routing to a device someone else may hold. Either all three land or none does. Projects without the `push` bundle skip the binding step and are otherwise unaffected. The user's own devices re-bind on their own the next time each is opened.

Access tokens are not revoked by this: one minted before the reset keeps working until it expires, up to 30 minutes. It is the refresh families that go, so no device can mint a new one.

## Body Parameters

<ParamField type="string">
  The raw reset token from the password reset email link. The server hashes
  this token internally before comparing it to the stored hash.
</ParamField>

<ParamField type="string">
  The new password to set.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  `true` on success.
</ResponseField>

<ResponseField name="message" type="string">
  Confirmation message: `"Password has been reset successfully."`
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="Invalid or Expired Token — 400">
    ```json theme={null}
    {
      "error": "Invalid or expired password reset token.",
      "code": "auth/invalid-reset-token"
    }
    ```

    Returned when the token does not match any user record or the token has
    expired (1 hour TTL).
  </Accordion>

  <Accordion title="Server Error — 500">
    ```json theme={null}
    {
      "error": "Internal server error.",
      "code": "auth/server-error"
    }
    ```

    Nothing was committed — the password, the sessions and the push bindings are
    all as they were, and the reset token is still usable.
  </Accordion>
</AccordionGroup>

<Warning>
  Every session for the user is revoked and every push binding they hold is
  removed, on every device. The user signs in again everywhere, and each device
  re-binds for push on its own once it is next opened.
</Warning>

**Rate limit:** 5 requests per 15 minutes per IP. Exceeding it returns `429` with the plain-text message `Too many password reset attempts, please wait 15 minutes` and no `code`.

## See Also

* [Request Password Reset endpoint](/api-reference/auth/request-password-reset)
* [`useRequestPasswordReset` hook](/hooks/auth/use-request-password-reset)
* [Built-in Auth guide](/sdk/authentication/built-in)


# Send Verification Email
Source: https://docs.sublay.io/v7/api-reference/auth/send-verification-email

POST /v7/:projectId/auth/send-verification-email
Send an email verification token or link to the authenticated user

Sends a verification email to the authenticated user's registered email address. The token or link expires after **5 minutes**.

Requires a valid user access token. Returns immediately with `{ success: true }` if the user is already verified.

## Body Parameters

All parameters are optional.

<ParamField type="&#x22;code&#x22; | &#x22;link&#x22;">
  Delivery mode.

  * `"code"` — The email contains a short token the user types into your app. Call the [Verify Email](/api-reference/auth/verify-email) endpoint to complete verification.
  * `"link"` — The email contains a clickable button. When clicked, the server verifies the token and redirects the user (or renders a hosted confirmation page).
</ParamField>

<ParamField type="&#x22;hex&#x22; | &#x22;numeric&#x22; | &#x22;alpha&#x22; | &#x22;alphanumeric&#x22;">
  Character set used to generate the token.

  | Value            | Example     | Notes                                              |
  | ---------------- | ----------- | -------------------------------------------------- |
  | `"hex"`          | `a3f9c2...` | 64-character hex string. `tokenLength` is ignored. |
  | `"numeric"`      | `048291`    | Digits only (0–9). Good for OTP-style inputs.      |
  | `"alpha"`        | `GXRTPK`    | Uppercase letters only (A–Z).                      |
  | `"alphanumeric"` | `B4KR9Z`    | Uppercase letters and digits.                      |
</ParamField>

<ParamField type="number">
  Length of the generated token. Must be an integer between `4` and `12`. Ignored when `tokenFormat` is `"hex"`.
</ParamField>

<ParamField type="string">
  A URL to redirect the user to after they click the verification link. Only used when `mode` is `"link"`.

  On success the query parameter `?verified=true` is appended. On failure, `?verified=false&error=invalid-or-expired-token` is appended instead.

  If omitted, the server renders a hosted success/error page.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  `true` when the request is processed without a server error (including when the user is already verified).
</ResponseField>

## Error Codes

| Code                     | Status | Description                                                                                          |
| ------------------------ | ------ | ---------------------------------------------------------------------------------------------------- |
| `auth/not-password-user` | 400    | The authenticated user does not have an email/password account.                                      |
| `auth/no-user-found`     | 403    | The access token is valid but no matching user record exists (e.g. the account was already deleted). |

<Note>
  Each call generates a new token. A previous unused token remains valid in
  Redis until it either expires or the new one is consumed first.
</Note>

## See Also

* [`useSendVerificationEmail` hook](/hooks/auth/use-send-verification-email)
* [Verify Email endpoint](/api-reference/auth/verify-email)
* [Verify Email Link endpoint](/api-reference/auth/verify-email-link)
* [Built-in Auth guide](/sdk/authentication/built-in)


# Set Password
Source: https://docs.sublay.io/v7/api-reference/auth/set-password

POST /v7/:projectId/auth/set-password
Set an initial password for an OAuth-only user

Sets an initial password for the currently authenticated user. This is for accounts that signed up through OAuth (or an external identity) and have **no password yet** — for example, so they can later sign in with email and password, or unlink their last OAuth identity without being locked out. Requires a valid access token in the `Authorization` header.

<Note>
  This endpoint is only for users who do **not** already have a password. If the
  user already has one, use [Change Password](/api-reference/auth/change-password)
  instead, which verifies the current password before changing it.
</Note>

## Headers

<ParamField type="string">
  `Bearer {accessToken}` — a valid access token for the authenticated user.
</ParamField>

## Body Parameters

<ParamField type="string">
  The password to set for the account.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  `true` on success.
</ResponseField>

<ResponseField name="message" type="string">
  Confirmation message: `"Password set successfully."`
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="User Not Found — 403">
    ```json theme={null}
    {
      "error": "User not found.",
      "code": "auth/no-user-found"
    }
    ```
  </Accordion>

  <Accordion title="Already Password Authenticated — 400">
    ```json theme={null}
    {
      "error": "User already has a password. Use change-password instead.",
      "code": "auth/already-password-authenticated"
    }
    ```

    Returned when the user already has a password. Use
    [Change Password](/api-reference/auth/change-password) instead.
  </Accordion>
</AccordionGroup>

## See Also

* [`useAuth` hook](/hooks/auth/use-auth) — `setPassword`
* [Change Password](/api-reference/auth/change-password)
* [Unlink OAuth Identity](/api-reference/oauth/unlink-identity)
* [Built-in Auth guide](/sdk/authentication/built-in)


# Sign In
Source: https://docs.sublay.io/v7/api-reference/auth/sign-in

POST /v7/:projectId/auth/sign-in
Authenticate a user with email and password

Authenticates an existing user by email and password. Returns an access token, refresh token, and the user's profile.

## Body Parameters

<ParamField type="string">
  User's registered email address.
</ParamField>

<ParamField type="string">
  User's password.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  `true` on successful authentication.
</ResponseField>

<ResponseField name="accessToken" type="string">
  Short-lived JWT access token. Expires in 30 minutes.
</ResponseField>

<ResponseField name="refreshToken" type="string">
  Long-lived JWT refresh token. Expires in 30 days. Use it to request a new
  access token when the current one expires.
</ResponseField>

<ResponseField name="user" type="object">
  The authenticated user's profile.

  <Expandable title="properties">
    <ResponseField name="id" type="string">Unique user ID (UUID).</ResponseField>
    <ResponseField name="foreignId" type="string | null">External user ID, if set.</ResponseField>
    <ResponseField name="role" type="string">User role.</ResponseField>
    <ResponseField name="email" type="string | null">Email address.</ResponseField>
    <ResponseField name="name" type="string | null">Display name.</ResponseField>
    <ResponseField name="username" type="string | null">Username.</ResponseField>
    <ResponseField name="avatar" type="string | null">Avatar URL.</ResponseField>
    <ResponseField name="bio" type="string | null">Bio text.</ResponseField>
    <ResponseField name="metadata" type="object | null">Public custom data.</ResponseField>
    <ResponseField name="reputation" type="number | null">Reputation score.</ResponseField>
    <ResponseField name="isVerified" type="boolean | null">Whether the user is verified.</ResponseField>
    <ResponseField name="isActive" type="boolean | null">Whether the account is active.</ResponseField>
    <ResponseField name="lastActive" type="string | null">ISO timestamp of last activity.</ResponseField>
    <ResponseField name="suspensions" type="array">Active suspensions on the account.</ResponseField>
    <ResponseField name="avatarFile" type="object | null">Processed avatar file with variants.</ResponseField>
    <ResponseField name="bannerFile" type="object | null">Processed banner file with variants.</ResponseField>
    <ResponseField name="authMethods" type="string[]">List of auth methods (e.g., `["password", "google"]`).</ResponseField>
    <ResponseField name="createdAt" type="string">ISO timestamp of account creation.</ResponseField>
  </Expandable>
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="User Not Found — 403">
    ```json theme={null}
    {
      "error": "User not found.",
      "code": "auth/no-user-found"
    }
    ```
  </Accordion>

  <Accordion title="Invalid Credentials — 403 or 400">
    ```json theme={null}
    {
      "error": "Invalid credentials.",
      "code": "auth/invalid-credentials"
    }
    ```

    `403` when the user exists but has no password set (e.g. an OAuth-only account).

    The **same code also arrives as `400`** for a malformed request body — a missing or non-string `email` or `password`. Sign-in is the one auth route whose body validation reports `auth/invalid-credentials` rather than `auth/invalid-body`, so this code has two statuses. Branch on the status as well as the code if you need to tell "fix your request" from "these credentials will never work".

    ```json theme={null}
    {
      "error": "...",
      "code": "auth/invalid-credentials"
    }
    ```
  </Accordion>

  <Accordion title="Wrong Password — 401">
    ```json theme={null}
    {
      "error": "Incorrect password.",
      "code": "auth/wrong-password"
    }
    ```
  </Accordion>

  <Accordion title="Server Error — 500">
    ```json theme={null}
    {
      "error": "Internal server error.",
      "code": "auth/server-error"
    }
    ```
  </Accordion>
</AccordionGroup>

**Rate limit:** 25 requests per 5 minutes per IP. Exceeding it returns `429` with the plain-text message `Too many sign in attempts, please wait 5 minutes` and no `code`.

## See Also

* [`useAuth` hook](/hooks/auth/use-auth) — `signInWithEmailAndPassword`
* [Built-in Auth guide](/sdk/authentication/built-in)


# Sign Out
Source: https://docs.sublay.io/v7/api-reference/auth/sign-out

POST /v7/:projectId/auth/sign-out
Sign out the current user, invalidate the refresh token family, and optionally unbind the device's push

Signs out a user by invalidating their refresh token and the entire token family associated with it. All rotated tokens from the same session are revoked, preventing future token refreshes.

A plain sign-out — a body carrying only `refreshToken` — always returns `204 No Content`, even if the refresh token is missing, invalid, or already expired. This keeps sign-out safe to call unconditionally: a user must always be able to end their session locally, whatever state their credential is in.

Supplying the optional `pushDevice` object changes that in one narrowly scoped way. See [Atomic push deregistration](#atomic-push-deregistration) below.

## Body Parameters

<ParamField type="string">
  The refresh token JWT to invalidate. If omitted or `null`, the server returns
  `204` without performing any revocation.
</ParamField>

<ParamField type="object">
  Optional. Identifies the physical device the user is signing out on, so the
  server can unbind that account's push notifications in the same request. Same
  shape as the [Deregister Device](/api-reference/push-notifications/deregister-device)
  body. Ignored on projects without the `push` bundle.

  <Expandable title="pushDevice fields">
    <ParamField type="string">
      The device platform. One of `"ios"`, `"android"`, or `"web"`.
    </ParamField>

    <ParamField type="string">
      The APNs or FCM device token. Required when `platform` is `"ios"` or `"android"`.
    </ParamField>

    <ParamField type="object">
      The Web Push subscription object (`endpoint` plus `keys.p256dh` / `keys.auth`).
      Required when `platform` is `"web"`. Only `endpoint` is used to identify the
      registration.
    </ParamField>
  </Expandable>
</ParamField>

## Atomic push deregistration

A device can be signed into several accounts at once, and each account has its own push binding on it. Signing out of an account without removing its binding would leave that account's notifications arriving on a device nobody is signed into — and once the credential is gone there is nothing left to repair it with.

So when `pushDevice` is present and the project has the `push` bundle, the server deletes that user's push binding for that device **inside the same transaction** as the token-family destroy, attempting the unbind first. Either both happen or neither does.

<Warning>
  **If the unbind fails, nothing is committed and the request returns an error.**
  The session survives, the refresh token still works, and the caller is expected
  to retry. Do not treat a failed sign-out as signed out — tearing down local
  state anyway is exactly what leaves a user receiving notifications from an
  account they can no longer reach.
</Warning>

Details worth knowing:

* **The binding is user-scoped.** The unbind targets only the signing-out user's row for that device. Other accounts bound to the same device are untouched.
* **An expired refresh token still unbinds.** Session destruction requires a live token, but the unbind accepts an authentic-but-expired one (its signature still proves which user it was minted for) up to 90 days past expiry. Beyond that bound the token is refused as an unbind credential and the request falls back to a plain `204`.
* **A destroyed token family still unbinds.** If the session was already ended by a prior sign-out-all, the binding is still removed.
* **Projects without the `push` bundle are unaffected on the success path.** The route itself carries no bundle gate — it is never refused with `database/tables-not-available`. When `pushDevice` is supplied the server looks the bundle up, and on a project that does not have it the `pushDevice` is ignored and the endpoint returns `204` exactly as it does without one.
* **If the bundle lookup itself cannot be resolved, the sign-out still completes and the skipped unbind is reported.** The response is a `200` carrying `pushUnbindSkipped: true` and the code `auth/push-unbind-status-unknown` (see [Response](#response)) instead of a bare `204`, because nobody checked and the binding may still be live. The session is destroyed either way — a user can always sign out. That body is emitted only once the sign-out has actually committed; in the rare case where the lookup could not be resolved *and* the session write then failed, the response is a plain `204` instead, because the claim it makes — signed out, do not retry — would be false.
* **A device identifier matching no binding still returns `204`.** The unbind is scoped to the signing-out user, so a key that matches no row of theirs removes nothing and the sign-out completes. The server records that outcome in its own logs; there is no separate response for it.
* **A malformed or wrong-signature token still returns `204`.** There is no user to scope an unbind to and no session to destroy, so the endpoint keeps its permissive behavior rather than blocking sign-out.

## Response

Returns `204 No Content` on success. No response body.

### Signed out, unbind skipped — 200

One success case answers with a body instead. When `pushDevice` was supplied and the server could not determine whether the project has the `push` bundle, it signs the user out and does **not** attempt an unbind:

```json theme={null}
{
  "pushUnbindSkipped": true,
  "code": "auth/push-unbind-status-unknown",
  "message": "Signed out. Whether this project has push devices could not be determined, so no unbind was attempted and this device may still be bound to that account."
}
```

The session really is destroyed, so this is not an error and must not be retried as one. It is not a `204` either: a `204` says there is nothing left to remove, and here nobody looked — the binding may still be live while the credential that could have removed it is being discarded. Surface it, and remove the binding by registering that account on the device again.

Because that promise is what clients act on, the body rides only on a committed sign-out. If the session write fails on this path the transaction rolls back, the token family survives, and the endpoint answers a plain `204` rather than claiming a sign-out that did not happen.

## Error Responses

The first two `500`s below are reachable only when `pushDevice` is supplied; the generic one is reachable with or without it. Every `500` means **nothing was committed** — the session, and the push binding when there was one at stake, are both still in place, and the request can be retried. Everything after them is decided before the handler runs and can be returned with or without a `pushDevice`.

<AccordionGroup>
  <Accordion title="Push Deregistration Failed — 500">
    ```json theme={null}
    {
      "error": "Failed to deregister the push device. Nothing was signed out; retry.",
      "code": "auth/device-deregistration-failed"
    }
    ```

    The `PushDevices` delete itself failed inside the transaction, so nothing
    was committed and the session was left intact. The binding is still live, so
    keep the account and its credential and retry.
  </Accordion>

  <Accordion title="Sign Out Failed — 500">
    ```json theme={null}
    {
      "error": "Failed to sign out. Nothing was committed; retry.",
      "code": "auth/sign-out-failed"
    }
    ```

    The unbind was not what failed. Either it succeeded and the token-family
    destroy did not, or the transaction never opened at all — in both cases the
    whole transaction, including any unbind, was rolled back.
  </Accordion>

  <Accordion title="Server Error — 500">
    ```json theme={null}
    {
      "error": "Internal server error.",
      "code": "auth/server-error"
    }
    ```

    A generic fault, raised on a path where no unbind was ever attempted and so
    no push binding is at stake. Nothing was committed; retry.
  </Accordion>

  <Accordion title="Invalid Body — 400">
    ```json theme={null}
    { "error": "...", "code": "auth/invalid-body" }
    ```

    Returned when `pushDevice` is malformed — for example `platform: "ios"` with no
    `token`, or `platform: "web"` with no `subscription`.
  </Accordion>

  <Accordion title="Quota Reached — 429">
    ```json theme={null}
    {
      "error": "Quota reached for apiCallsPerMonth. Current: …, Action size: …, Limit: …",
      "code": "project/quota-reached",
      "details": { "current": 0, "actionSize": 0, "limit": 0, "metric": "apiCallsPerMonth" }
    }
    ```

    Returned when the project has spent its monthly API-call allowance and is on
    a plan that hard-blocks at the limit. Distinct from the rate-limit `429`
    below, which is plain text with no `code`.
  </Accordion>

  <Accordion title="Project Pending Deletion — 423">
    ```json theme={null}
    {
      "error": "This project is pending deletion and is not available.",
      "code": "project/pending-deletion"
    }
    ```
  </Accordion>

  <Accordion title="Project Migrating — 503">
    ```json theme={null}
    { "error": "...", "code": "project/migrating" }
    ```

    Returned while the project is mid-migration.
  </Accordion>
</AccordionGroup>

**Rate limit:** 50 requests per 5 minutes per IP. Exceeding it returns `429` with the plain-text message `Too many sign out attempts, please wait 5 minutes` and no `code`.

The budget is sized for a fan-out: signing out of every stored account issues one request per account in parallel, so a five-account sign-out spends five of the fifty. The limiter keys on IP, so several users behind one address share the budget.

<Note>
  **A rejection that never reached this endpoint is not an unbind failure.** The `423`, `503` and
  `429` above — and a `400` — are decided before the handler runs, so no unbind was attempted and no
  push binding is at risk. Exactly two responses mean the server could not complete an unbind it was
  asked for and committed nothing: `auth/device-deregistration-failed` and `auth/sign-out-failed`.
  Those two are the ones a client must keep its credential for; on anything else it should sign out
  locally as usual. A client that blocks account removal on *any* failure makes an account
  unremovable whenever the project is throttled or migrating. `auth/push-unbind-status-unknown` is
  deliberately not one of them: it rides on a `200`, the sign-out has already happened, and blocking
  on it would leave a user unable to leave their account because a cache lookup was briefly
  unavailable.
</Note>

## See Also

* [`useAuth` hook](/hooks/auth/use-auth) — `signOut`
* [`useSignOutAll` hook](/hooks/auth/use-sign-out-all)
* [Deregister Device](/api-reference/push-notifications/deregister-device)
* [Built-in Auth guide](/sdk/authentication/built-in)


# Sign Up
Source: https://docs.sublay.io/v7/api-reference/auth/sign-up

POST /v7/:projectId/auth/sign-up
Create a new user account with email and password

Registers a new user within the specified project. On success, returns an access token, refresh token, and the created user object. The endpoint also accepts optional profile data and image file uploads for the avatar and banner.

<Note>
  This endpoint accepts `multipart/form-data` when uploading avatar or banner
  images. Send `application/json` for text-only registration.
</Note>

## Body Parameters

<ParamField type="string">
  User's email address. Must be a valid email format. Automatically lowercased.
</ParamField>

<ParamField type="string">
  User's password.
</ParamField>

<ParamField type="string">
  Display name.
</ParamField>

<ParamField type="string">
  Unique username within the project. Automatically lowercased. Fails with 409
  if already taken.
</ParamField>

<ParamField type="string">
  URL of the user's avatar image. Ignored if `avatarFile` is also provided.
</ParamField>

<ParamField type="string">
  Short bio text.
</ParamField>

<ParamField type="object">
  Geographic location.

  <Expandable title="properties">
    <ParamField type="number">
      Latitude between -90 and 90.
    </ParamField>

    <ParamField type="number">
      Longitude between -180 and 180.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  ISO 8601 datetime string representing the user's date of birth.
</ParamField>

<ParamField type="object">
  Public custom key-value data attached to the user.
</ParamField>

<ParamField type="object">
  Private custom key-value data. Not returned to other users.
</ParamField>

<ParamField type="file">
  Avatar image file (multipart). Maximum 50 MB. Must be a valid image format.
  Requires `avatarFile.options` to also be present.
</ParamField>

<ParamField type="file">
  Banner image file (multipart). Maximum 50 MB. Must be a valid image format.
  Requires `bannerFile.options` to also be present.
</ParamField>

## Response

On success, returns HTTP `201` with:

<ResponseField name="success" type="boolean">
  `true` on successful registration.
</ResponseField>

<ResponseField name="accessToken" type="string">
  Short-lived JWT access token. Expires in 30 minutes.
</ResponseField>

<ResponseField name="refreshToken" type="string">
  Long-lived JWT refresh token. Expires in 30 days.
</ResponseField>

<ResponseField name="user" type="object">
  The created user's profile.

  <Expandable title="properties">
    <ResponseField name="id" type="string">Unique user ID (UUID).</ResponseField>
    <ResponseField name="foreignId" type="string | null">External user ID, if set.</ResponseField>
    <ResponseField name="role" type="string">User role (e.g., `"visitor"`).</ResponseField>
    <ResponseField name="email" type="string | null">User's email address.</ResponseField>
    <ResponseField name="name" type="string | null">Display name.</ResponseField>
    <ResponseField name="username" type="string | null">Username.</ResponseField>
    <ResponseField name="avatar" type="string | null">Avatar URL.</ResponseField>
    <ResponseField name="bio" type="string | null">Bio text.</ResponseField>
    <ResponseField name="metadata" type="object | null">Public custom data.</ResponseField>
    <ResponseField name="reputation" type="number | null">Reputation score.</ResponseField>
    <ResponseField name="isVerified" type="boolean | null">Whether the user is verified.</ResponseField>
    <ResponseField name="isActive" type="boolean | null">Whether the account is active.</ResponseField>
    <ResponseField name="lastActive" type="string | null">ISO timestamp of last activity.</ResponseField>
    <ResponseField name="suspensions" type="array">Active suspensions on the account.</ResponseField>
    <ResponseField name="avatarFile" type="object | null">Processed avatar file with variants.</ResponseField>
    <ResponseField name="bannerFile" type="object | null">Processed banner file with variants.</ResponseField>
    <ResponseField name="authMethods" type="string[]">List of auth methods (e.g., `["password"]`).</ResponseField>
    <ResponseField name="createdAt" type="string">ISO timestamp of account creation.</ResponseField>
  </Expandable>
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="Email Already In Use — 409">
    ```json theme={null}
    {
      "error": "Email already in use",
      "field": "email",
      "code": "DUPLICATE_EMAIL"
    }
    ```
  </Accordion>

  <Accordion title="Username Already Taken — 409">
    ```json theme={null}
    {
      "error": "Username already taken",
      "field": "username",
      "code": "DUPLICATE_USERNAME"
    }
    ```
  </Accordion>

  <Accordion title="Invalid Body — 400">
    ```json theme={null}
    {
      "error": "...",
      "code": "auth/invalid-body"
    }
    ```
  </Accordion>

  <Accordion title="File Too Large — 413">
    ```json theme={null}
    {
      "error": "Avatar image exceeds 50MB limit.",
      "code": "auth/file-too-large"
    }
    ```

    Also returned with `"Banner image exceeds 50MB limit."` for the banner file.
  </Accordion>

  <Accordion title="Invalid Image — 422">
    ```json theme={null}
    {
      "error": "Avatar file is not a valid image: ...",
      "code": "auth/invalid-image"
    }
    ```

    Returned when the uploaded file cannot be parsed as an image. Also returned for the banner file with `"Banner file is not a valid image: ..."`.
  </Accordion>

  <Accordion title="Missing Image Options — 400">
    ```json theme={null}
    {
      "error": "Image options are required when uploading an avatar. Must include mode property.",
      "code": "auth/missing-image-options"
    }
    ```

    Returned when `avatarFile` or `bannerFile` is uploaded without the corresponding `.options` field.
  </Accordion>

  <Accordion title="Validation Failed — 400">
    ```json theme={null}
    {
      "error": "User validation failed",
      "code": "auth/validation-failed"
    }
    ```
  </Accordion>

  <Accordion title="Duplicate User Field — 409">
    ```json theme={null}
    {
      "error": "A user with this <field> already exists in this project",
      "field": "<field>",
      "code": "DUPLICATE_USER_FIELD"
    }
    ```

    The catch-all uniqueness conflict, raised for any unique column the two
    conflicts above do not name. `field` identifies the column.
  </Accordion>

  <Accordion title="Storage Quota Reached — 429">
    ```json theme={null}
    {
      "error": "Quota reached for storageFileBytes. Current: …, Action size: …, Limit: …",
      "code": "project/quota-reached",
      "details": { "current": 0, "actionSize": 0, "limit": 0, "metric": "storageFileBytes" }
    }
    ```

    Returned when an uploaded avatar or banner would take the project past its
    plan's file-storage limit. No user is created.
  </Accordion>

  <Accordion title="Server Error — 500">
    ```json theme={null}
    {
      "error": "Internal server error",
      "code": "auth/server-error"
    }
    ```
  </Accordion>
</AccordionGroup>

**Rate limit:** 5 requests per 5 minutes per IP. Exceeding it returns `429` with the plain-text message `Too many sign up attempts, please wait 5 minutes` and no `code` — distinct from the quota `429` above, which carries a JSON body.

## See Also

* [`useAuth` hook](/hooks/auth/use-auth) — `signUpWithEmailAndPassword`
* [Built-in Auth guide](/sdk/authentication/built-in)


# Verify Email
Source: https://docs.sublay.io/v7/api-reference/auth/verify-email

POST /v7/:projectId/auth/verify-email
Verify a user's email address using a token from a verification email

Verifies a user's email address using the token sent by the [Send Verification Email](/api-reference/auth/send-verification-email) endpoint (when `mode` is `"code"`). On success, the user's `isVerified` field is set to `true` and the token is invalidated.

This endpoint is unauthenticated — the token itself proves identity.

## Body Parameters

<ParamField type="string">
  The verification token from the email. Must match exactly, including case.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  `true` when the email was successfully verified.
</ResponseField>

## Error Codes

| Code                            | Status | Description                                                                                                           |
| ------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------- |
| `auth/invalid-or-expired-token` | 400    | The token does not exist in Redis — either it was never issued, has expired (5-minute TTL), or has already been used. |

<Note>
  Tokens are single-use. Once consumed, the same token returns a 400 error.
  Tokens expire after 5 minutes regardless of whether they are used.
</Note>

## See Also

* [`useVerifyEmail` hook](/hooks/auth/use-verify-email)
* [Send Verification Email endpoint](/api-reference/auth/send-verification-email)
* [Built-in Auth guide](/sdk/authentication/built-in)


# Verify Email Link
Source: https://docs.sublay.io/v7/api-reference/auth/verify-email-link

GET /v7/:projectId/auth/verify-email-link
Verify a user's email address via a link clicked in an email

Verifies a user's email address when they click the link from a verification email sent with `mode: "link"`. On success, `isVerified` is set to `true` and the token is invalidated.

This endpoint is called automatically by the browser — you do not call it directly from your app. It is the target URL embedded in the verification button in the email.

## Query Parameters

<ParamField type="string">
  The verification token embedded in the link by the server.
</ParamField>

<ParamField type="string">
  The URL to redirect the user to after verification. This is set automatically by the server based on the `redirectUrl` you passed to [Send Verification Email](/api-reference/auth/send-verification-email).

  On success: redirects to `{redirectUrl}?verified=true`
  On failure: redirects to `{redirectUrl}?verified=false&error=invalid-or-expired-token`
</ParamField>

## Behaviour

| Outcome                 | `redirect` present                                                        | `redirect` absent          |
| ----------------------- | ------------------------------------------------------------------------- | -------------------------- |
| Success                 | Redirect to `{redirectUrl}?verified=true`                                 | Render hosted success page |
| Invalid / expired token | Redirect to `{redirectUrl}?verified=false&error=invalid-or-expired-token` | Render hosted error page   |
| Server error            | Redirect to `{redirectUrl}?verified=false&error=server-error`             | Render hosted error page   |

## See Also

* [Send Verification Email endpoint](/api-reference/auth/send-verification-email)
* [`useSendVerificationEmail` hook](/hooks/auth/use-send-verification-email)
* [Built-in Auth guide](/sdk/authentication/built-in)


# Verify External User
Source: https://docs.sublay.io/v7/api-reference/auth/verify-external-user

POST /v7/:projectId/auth/verify-external-user
Verify or create a user from an external auth system JWT

Accepts a JWT signed by your own auth system and returns Sublay tokens. If the user does not exist in the project, they are created. If they do exist, their profile is updated with any changed fields from the JWT payload.

The JWT must be signed with the RSA private key corresponding to the public key configured in your Sublay project settings.

## Body Parameters

<ParamField type="string">
  A JWT signed with your project's RSA private key (RS256 algorithm). The
  payload must include `sub` (external user ID) and `iss` (your Sublay project
  ID). The `userData` claim may contain optional profile fields.
</ParamField>

## JWT Payload Structure

The `userJwt` must contain:

| Claim      | Required | Description                                                 |
| ---------- | -------- | ----------------------------------------------------------- |
| `sub`      | Yes      | External user ID. Stored as `foreignId` on the Sublay user. |
| `iss`      | Yes      | Your Sublay project ID. Must match the request project.     |
| `userData` | No       | Object with optional profile fields (see below).            |

### `userData` fields

| Field            | Type     | Description               |
| ---------------- | -------- | ------------------------- |
| `email`          | `string` | Email address             |
| `name`           | `string` | Display name              |
| `username`       | `string` | Username                  |
| `avatar`         | `string` | Avatar URL                |
| `bio`            | `string` | Bio text                  |
| `location`       | object   | `{ latitude, longitude }` |
| `birthdate`      | `string` | ISO 8601 date             |
| `metadata`       | object   | Public custom data        |
| `secureMetadata` | object   | Private custom data       |

## Response

<ResponseField name="success" type="boolean">
  `true` on success.
</ResponseField>

<ResponseField name="accessToken" type="string">
  Short-lived JWT access token. Expires in 30 minutes.
</ResponseField>

<ResponseField name="refreshToken" type="string">
  Long-lived JWT refresh token. Expires in 30 days.
</ResponseField>

<ResponseField name="user" type="object">
  The verified or created user's profile.

  <Expandable title="properties">
    <ResponseField name="id" type="string">Unique user ID (UUID).</ResponseField>
    <ResponseField name="foreignId" type="string | null">External user ID (the `sub` claim).</ResponseField>
    <ResponseField name="role" type="string">User role.</ResponseField>
    <ResponseField name="email" type="string | null">Email address.</ResponseField>
    <ResponseField name="name" type="string | null">Display name.</ResponseField>
    <ResponseField name="username" type="string | null">Username.</ResponseField>
    <ResponseField name="avatar" type="string | null">Avatar URL.</ResponseField>
    <ResponseField name="bio" type="string | null">Bio text.</ResponseField>
    <ResponseField name="metadata" type="object | null">Public custom data.</ResponseField>
    <ResponseField name="reputation" type="number | null">Reputation score.</ResponseField>
    <ResponseField name="isVerified" type="boolean | null">Whether the user is verified.</ResponseField>
    <ResponseField name="isActive" type="boolean | null">Whether the account is active.</ResponseField>
    <ResponseField name="lastActive" type="string | null">ISO timestamp of last activity.</ResponseField>
    <ResponseField name="suspensions" type="array">Active suspensions on the account.</ResponseField>
    <ResponseField name="avatarFile" type="object | null">Processed avatar file with variants.</ResponseField>
    <ResponseField name="bannerFile" type="object | null">Processed banner file with variants.</ResponseField>
    <ResponseField name="authMethods" type="string[]">List of auth methods (includes `"external"`).</ResponseField>
    <ResponseField name="createdAt" type="string">ISO timestamp of account creation.</ResponseField>
  </Expandable>
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="Missing JWT Keys — 403">
    ```json theme={null}
    {
      "error": "Missing JWT keys",
      "code": "auth/missing-keys"
    }
    ```

    The project does not have a public key configured.
  </Accordion>

  <Accordion title="Invalid Token — 403">
    ```json theme={null}
    {
      "error": "Invalid token",
      "code": "auth/invalid-token"
    }
    ```

    The JWT signature is invalid or the token is expired.
  </Accordion>

  <Accordion title="Project ID Mismatch — 403">
    ```json theme={null}
    {
      "error": "Project ID mismatch",
      "code": "auth/project-mismatch"
    }
    ```

    The `iss` claim in the JWT does not match the request project ID.
  </Accordion>

  <Accordion title="Username Already Taken — 409">
    ```json theme={null}
    {
      "error": "Username already taken",
      "field": "username",
      "code": "DUPLICATE_USERNAME"
    }
    ```
  </Accordion>
</AccordionGroup>

## See Also

* [External Auth guide](/sdk/authentication/external)


# Authentication
Source: https://docs.sublay.io/v7/api-reference/authentication

How to authenticate API requests with Bearer tokens and manage token refresh

Most Sublay API endpoints require an authenticated user. Authentication uses short-lived JWT access tokens passed as `Bearer` tokens in the `Authorization` header.

## Bearer Token

Include the access token on every protected request:

```http theme={null}
GET /v7/:projectId/app-notifications
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

Access tokens expire after **30 minutes**.

## Obtaining Tokens

Tokens are issued by the auth endpoints. Depending on your auth setup:

| Method                       | Endpoint                                                                      |
| ---------------------------- | ----------------------------------------------------------------------------- |
| Email + password sign-up     | [POST `/auth/sign-up`](/api-reference/auth/sign-up)                           |
| Email + password sign-in     | [POST `/auth/sign-in`](/api-reference/auth/sign-in)                           |
| External user (JWT-verified) | [POST `/auth/verify-external-user`](/api-reference/auth/verify-external-user) |
| OAuth (Google, GitHub, etc.) | [POST `/oauth/authorize`](/api-reference/oauth/authorize)                     |

All of these return the same token structure:

```json theme={null}
{
  "accessToken": "eyJ...",
  "refreshToken": "eyJ...",
  "user": { ... }
}
```

## Refreshing Tokens

When an access token expires, use the refresh token to obtain a new access token:

```http theme={null}
POST /v7/:projectId/auth/request-new-access-token
Content-Type: application/json

{
  "refreshToken": "eyJ..."
}
```

The response includes a new `accessToken` and a rotated `refreshToken`. Always store and use the latest refresh token — reusing a revoked one will invalidate the entire session. Each rotated refresh token is valid for another **30 days**, so active users stay signed in indefinitely. Only if a refresh token goes unused for 30 days will it expire and require the user to sign in again.

See [Request New Access Token](/api-reference/auth/request-access-token) for full details.

## SDK Token Management

If you are using the Sublay SDK (`@sublay/react-js`, `@sublay/react-native`, etc.), **you do not need to manage tokens manually**. The SDK stores tokens, attaches them to every request, and automatically refreshes them before they expire.

Token management is only relevant when calling the REST API directly — for example, from a server-side environment using the [Node SDK](/sdk/getting-started) or a custom HTTP client.

## Unauthenticated Requests

Some endpoints are publicly accessible without a token (e.g., fetching public entity data). These endpoints do not require an `Authorization` header.

On endpoints that **require** auth, a missing header and a bad one are answered differently:

| Situation                                | Status | Body                        |
| ---------------------------------------- | ------ | --------------------------- |
| No `Authorization` header                | `401`  | `Unauthorized` (plain text) |
| Header present, token expired or invalid | `403`  | `Forbidden` (plain text)    |

<Warning>
  An **expired token returns `403`, not `401`**. If you are calling the REST API
  directly, this is the case to build your refresh logic around — a client that
  only refreshes on `401` will never refresh, and will start failing once its
  first access token passes its 30-minute TTL.

  Both responses are `text/plain` with no JSON body and no `code` field. Every
  *other* `401`/`403` the API returns comes from a controller and **does** carry
  a `code` (`space/auth-required`, `project/plan-required`, `user/suspended`, …).
  Those describe a decision no token refresh can change, so the presence of a
  `code` is a reliable way to tell "retry after refreshing" apart from "stop and
  surface this to the user".
</Warning>

### Public endpoints ignore an unusable token

Endpoints that treat the viewer as optional do **not** reject a token they cannot
verify — they answer `200` and simply treat the caller as anonymous. A request
carrying an expired token therefore succeeds, but comes back without any
viewer-specific data: the caller's own reactions, saved state, and block
filtering are all absent, with nothing in the response to signal it.

If you are integrating directly, refresh proactively rather than waiting for an
error on these routes. The official SDKs do this for you.


# Getting Started
Source: https://docs.sublay.io/v7/api-reference/getting-started

Base URL, projectId scoping, request format, pagination, and error codes

The Sublay REST API is a project-scoped HTTP API. All endpoints follow the same base structure and share common conventions for authentication, pagination, and error reporting.

## Base URL

All API requests are made to:

```
https://api.sublay.io/v7/:projectId
```

Replace `:projectId` with the UUID of your Sublay project, which you can find in the [Sublay dashboard](https://dash.sublay.io).

So every endpoint takes the form:

```
https://api.sublay.io/v7/:projectId/<endpoint>
```

## Request Format

Most endpoints accept `application/json`. Endpoints that support file uploads accept `multipart/form-data`. The `Content-Type` header should be set accordingly.

```http theme={null}
POST /v7/:projectId/auth/sign-in
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "secret"
}
```

## Authentication

Protected endpoints require a `Bearer` token in the `Authorization` header:

```http theme={null}
GET /v7/:projectId/app-notifications
Authorization: Bearer <accessToken>
```

See [Authentication](/api-reference/authentication) for full details on obtaining and refreshing tokens.

## Pagination

Endpoints that return lists use cursor-free offset pagination. Pass `page` and `limit` as query parameters:

| Parameter | Default | Max    | Description                          |
| --------- | ------- | ------ | ------------------------------------ |
| `page`    | `1`     | —      | Page number (1-indexed)              |
| `limit`   | varies  | varies | Results per page (endpoint-specific) |

Paginated responses always return the same envelope:

```json theme={null}
{
  "data": [...],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalPages": 5,
    "totalItems": 97,
    "hasMore": true
  }
}
```

## Error Format

All error responses follow a consistent structure:

```json theme={null}
{
  "error": "Human-readable error message.",
  "code": "feature/error-slug"
}
```

Some errors include an additional `field` key (e.g., validation errors on a specific input field):

```json theme={null}
{
  "error": "Username already taken",
  "field": "username",
  "code": "DUPLICATE_USERNAME"
}
```

### Common HTTP Status Codes

| Status | Meaning                                                                                 |
| ------ | --------------------------------------------------------------------------------------- |
| `200`  | Success                                                                                 |
| `201`  | Resource created                                                                        |
| `400`  | Bad request — invalid input or missing required fields                                  |
| `401`  | Unauthorized — no `Authorization` header, or a request the endpoint requires a user for |
| `403`  | Forbidden — token expired or invalid, or a valid token without the required permission  |
| `404`  | Not found                                                                               |
| `409`  | Conflict — duplicate resource (e.g., email already in use)                              |
| `429`  | Rate limit exceeded                                                                     |
| `500`  | Internal server error                                                                   |

<Note>
  An **expired token returns `403`, not `401`** — see
  [Authentication](/api-reference/authentication) for why that distinction
  matters when writing your own refresh logic.
</Note>

## Rate Limiting

Each endpoint has its own rate limit, applied per project and per IP. When a limit is exceeded, the API returns `429 Too Many Requests`. Limits are noted per endpoint in this reference.


# Authorize OAuth
Source: https://docs.sublay.io/v7/api-reference/oauth/authorize

POST /v7/:projectId/oauth/authorize
Initiate an OAuth sign-in or sign-up flow

Initiates an OAuth 2.0 authorization flow for unauthenticated users (sign-in or sign-up). Returns a provider authorization URL that the client should redirect to. After the user authenticates with the provider, they are redirected back to the `redirectAfterAuth` URL with tokens in the URL fragment.

<Note>
  The OAuth provider must be configured and enabled in the Sublay dashboard
  before this endpoint can be used. The `redirectAfterAuth` URL must be in
  the provider's allowed redirect URI list.
</Note>

## Body Parameters

<ParamField type="string">
  The OAuth provider to use. Must be one of: `"google"`, `"github"`, `"apple"`,
  `"facebook"`.
</ParamField>

<ParamField type="string">
  The URL to redirect the user to after authentication. Must be a valid URL
  and must be present in the provider's configured allowed redirect URIs.
</ParamField>

## Response

<ResponseField name="authorizationUrl" type="string">
  The provider's authorization URL. Redirect the user's browser to this URL
  to begin the OAuth flow.
</ResponseField>

## Callback

After the user authorizes with the provider, they are redirected to `redirectAfterAuth` with one of:

**On success** — Tokens in the URL fragment:

```
https://yourapp.com/callback#accessToken=...&refreshToken=...
```

**On error** — Error details in query parameters:

```
https://yourapp.com/callback?error=access_denied&error_description=...
```

## Error Responses

<AccordionGroup>
  <Accordion title="Provider Not Configured — 400">
    ```json theme={null}
    {
      "error": "OAuth provider 'google' is not configured or not enabled for this project",
      "code": "oauth/provider-not-configured"
    }
    ```
  </Accordion>

  <Accordion title="Invalid Redirect URI — 400">
    ```json theme={null}
    {
      "error": "redirectAfterAuth is not in the allowed redirect URIs for this project",
      "code": "oauth/invalid-redirect-uri"
    }
    ```
  </Accordion>
</AccordionGroup>

## See Also

* [OAuth integration guide](/sdk/authentication/oauth)
* [Link OAuth Provider](/api-reference/oauth/link)


# Link OAuth Provider
Source: https://docs.sublay.io/v7/api-reference/oauth/link

POST /v7/:projectId/oauth/link
Link a new OAuth provider to the current authenticated user

Initiates an OAuth 2.0 flow to link an additional provider to the currently authenticated user's account. Requires a valid access token. The flow and callback behavior are identical to the [Authorize OAuth](/api-reference/oauth/authorize) endpoint.

The authenticated user's ID is taken from the access token — it cannot be specified in the request body.

## Headers

<ParamField type="string">
  `Bearer {accessToken}` — a valid access token for the user linking the provider.
</ParamField>

## Body Parameters

<ParamField type="string">
  The OAuth provider to link. Must be one of: `"google"`, `"github"`, `"apple"`,
  `"facebook"`.
</ParamField>

<ParamField type="string">
  The URL to redirect the user to after authorization. Must be a valid URL and
  must be in the provider's configured allowed redirect URIs.
</ParamField>

## Response

<ResponseField name="authorizationUrl" type="string">
  The provider's authorization URL. Redirect the user's browser to this URL.
</ResponseField>

## Callback

After the user authorizes with the provider, they are redirected to `redirectAfterAuth` with one of:

**On success** — Tokens in the URL fragment (new tokens are issued for the linked account):

```
https://yourapp.com/callback#accessToken=...&refreshToken=...
```

**On error** — Error details in query parameters:

```
https://yourapp.com/callback?error=...&error_description=...
```

## Error Responses

<AccordionGroup>
  <Accordion title="Provider Not Configured — 400">
    ```json theme={null}
    {
      "error": "OAuth provider 'github' is not configured or not enabled for this project",
      "code": "oauth/provider-not-configured"
    }
    ```
  </Accordion>

  <Accordion title="Invalid Redirect URI — 400">
    ```json theme={null}
    {
      "error": "redirectAfterAuth is not in the allowed redirect URIs for this project",
      "code": "oauth/invalid-redirect-uri"
    }
    ```
  </Accordion>
</AccordionGroup>

## See Also

* [OAuth integration guide](/sdk/authentication/oauth)
* [Authorize OAuth](/api-reference/oauth/authorize)
* [`useOAuthIdentities` hook](/hooks/auth/use-oauth-identities)


# List OAuth Identities
Source: https://docs.sublay.io/v7/api-reference/oauth/list-identities

GET /v7/:projectId/oauth/identities
List all OAuth identities linked to the current user

Returns all OAuth identities linked to the authenticated user's account, ordered by creation date. Use this to display connected accounts on a settings page.

Requires a valid access token.

## Headers

<ParamField type="string">
  `Bearer {accessToken}` — a valid access token for the authenticated user.
</ParamField>

## Response

<ResponseField name="identities" type="OAuthIdentity[]">
  Array of linked identities, ordered oldest first.

  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identity ID (UUID).
    </ResponseField>

    <ResponseField name="provider" type="string">
      OAuth provider name (e.g., `"google"`, `"github"`, `"external"`).
    </ResponseField>

    <ResponseField name="providerAccountId" type="string">
      The user's account ID at the provider.
    </ResponseField>

    <ResponseField name="email" type="string | null">
      Email address returned by the provider.
    </ResponseField>

    <ResponseField name="name" type="string | null">
      Name returned by the provider.
    </ResponseField>

    <ResponseField name="avatar" type="string | null">
      Avatar URL returned by the provider.
    </ResponseField>

    <ResponseField name="isVerified" type="boolean">
      Whether the provider marked the email as verified.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO timestamp of when the identity was linked.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="hasPassword" type="boolean">
  Whether the user has a password set. `false` for OAuth-only accounts. Use this
  to decide whether to prompt the user to
  [set an initial password](/api-reference/auth/set-password) before letting
  them unlink their last identity.
</ResponseField>

## See Also

* [`useOAuthIdentities` hook](/hooks/auth/use-oauth-identities)
* [Unlink Identity](/api-reference/oauth/unlink-identity)
* [OAuth integration guide](/sdk/authentication/oauth)


# Unlink OAuth Identity
Source: https://docs.sublay.io/v7/api-reference/oauth/unlink-identity

DELETE /v7/:projectId/oauth/identities/:identityId
Remove a linked OAuth identity from the current user

Unlinks an OAuth identity from the authenticated user's account. The identity is permanently deleted.

Requires a valid access token. The identity must belong to the authenticated user.

## Headers

<ParamField type="string">
  `Bearer {accessToken}` — a valid access token for the authenticated user.
</ParamField>

## Path Parameters

<ParamField type="string">
  UUID of the identity to unlink. Retrieve identity IDs from the
  [List Identities](/api-reference/oauth/list-identities) endpoint.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  `true` when the identity was successfully unlinked.
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="Identity Not Found — 404">
    ```json theme={null}
    {
      "error": "Identity not found",
      "code": "oauth/identity-not-found"
    }
    ```

    Returned when the identity does not exist or does not belong to the
    authenticated user.
  </Accordion>

  <Accordion title="Last Identity — 400">
    ```json theme={null}
    {
      "error": "Cannot unlink the last identity. Set a password first or link another provider.",
      "code": "oauth/last-identity"
    }
    ```

    Returned when this is the only identity on the account and the user
    has no password set. Unlinking would lock the user out. Have the user
    [set a password](/api-reference/auth/set-password) or link another
    provider first.
  </Accordion>

  <Accordion title="User Not Found — 404">
    ```json theme={null}
    {
      "error": "User not found",
      "code": "oauth/user-not-found"
    }
    ```
  </Accordion>
</AccordionGroup>

## See Also

* [`useOAuthIdentities` hook](/hooks/auth/use-oauth-identities)
* [List Identities](/api-reference/oauth/list-identities)
* [Set Password](/api-reference/auth/set-password)
* [OAuth integration guide](/sdk/authentication/oauth)


# Fetch User
Source: https://docs.sublay.io/v7/api-reference/users/fetch-user

GET /v7/:projectId/users/:userId
Get a user's public profile by ID

Returns a user's public profile by their Sublay user ID. Optionally includes associated file records for the avatar and banner.

<Note>
  If the profile owner has blocked the signed-in caller, this returns `404` — the
  same response as a user who does not exist. The reverse is not true: a user
  *you* have blocked stays visible, so you keep a way to find and unblock them. Requires the `moderation` bundle.
</Note>

## Path Parameters

<ParamField type="string">
  The Sublay user ID (UUID).
</ParamField>

## Query Parameters

<ParamField type="string">
  Comma-separated list of associations to include. Pass `"files"` to include
  the processed `avatarFile` and `bannerFile` objects.
</ParamField>

### Space-scoped reputation

This endpoint has no space in context, so the opt-in `spaceReputation` object accepts a `spaceId` of a space **`<uuid>`** or **`none`** only — `context` is rejected (400). It adds a `spaceReputation` field to each returned user, alongside the always-present `reputation` total. Requires the `reputation` bundle. See the [Reputation data model](/data-models/reputation).

<SpaceReputationParams />

## Response

On success, returns HTTP `200` with the user object:

<ResponseField name="id" type="string">
  Unique user ID (UUID).
</ResponseField>

<ResponseField name="foreignId" type="string | null">
  External identifier linking this user to your system.
</ResponseField>

<ResponseField name="projectId" type="string">
  Project this user belongs to.
</ResponseField>

<ResponseField name="name" type="string | null">
  Display name.
</ResponseField>

<ResponseField name="username" type="string | null">
  Unique username within the project.
</ResponseField>

<ResponseField name="avatar" type="string | null">
  Avatar image URL.
</ResponseField>

<ResponseField name="bio" type="string | null">
  Short bio text.
</ResponseField>

<ResponseField name="metadata" type="object | null">
  Public custom key-value data.
</ResponseField>

<ResponseField name="reputation" type="number">
  The user's overall reputation total (the sum of all their reputation buckets).
  This is a global lookup with no space in context, so it returns the total only —
  see [Reputation](/data-models/reputation) for space-scoped reads.
</ResponseField>

<ResponseField name="avatarFile" type="object | null">
  Processed avatar image with variants. Only present when `include=files` is
  requested.
</ResponseField>

<ResponseField name="bannerFile" type="object | null">
  Processed banner image with variants. Only present when `include=files` is
  requested.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO timestamp of account creation.
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="User Not Found — 404">
    ```json theme={null}
    {
      "error": "User not found",
      "code": "user/not-found"
    }
    ```
  </Accordion>

  <Accordion title="Invalid Params — 400">
    ```json theme={null}
    {
      "error": "...",
      "code": "user/invalid-params"
    }
    ```
  </Accordion>
</AccordionGroup>

## See Also

* [`useFetchUser` hook](/hooks/users/use-fetch-user)
* [User data model](/data-models/user)


# Fetch User by Foreign ID
Source: https://docs.sublay.io/v7/api-reference/users/fetch-user-by-foreign-id

GET /v7/:projectId/users/by-foreign-id
Look up a user by your own system's external user ID

Finds a user within the project by their `foreignId` — the external identifier you provided when creating or syncing the user. Optionally creates the user if not found (requires service or master token).

<Note>
  If the profile owner has blocked the signed-in caller, this returns `404` — the
  same response as a user who does not exist. The reverse is not true: a user
  *you* have blocked stays visible, so you keep a way to find and unblock them. Requires the `moderation` bundle.
</Note>

## Query Parameters

<ParamField type="string">
  The external identifier from your system.
</ParamField>

<ParamField type="string">
  Comma-separated list of associations to include. Pass `"files"` to include
  the processed `avatarFile` and `bannerFile` objects.
</ParamField>

<ParamField type="string">
  Set to `"true"` to create the user if they do not exist. Requires a service
  or master token. Returns `201` on creation, `200` on an existing user.
</ParamField>

<ParamField type="string">
  Display name to set when creating the user (`createIfNotFound` only).
</ParamField>

<ParamField type="string">
  Username to assign when creating the user (`createIfNotFound` only).
</ParamField>

<ParamField type="string">
  Avatar URL to set when creating the user (`createIfNotFound` only).
</ParamField>

<ParamField type="string">
  Bio text to set when creating the user (`createIfNotFound` only).
</ParamField>

<ParamField type="string">
  JSON-encoded public metadata to set when creating the user
  (`createIfNotFound` only).
</ParamField>

<ParamField type="string">
  JSON-encoded private metadata to set when creating the user
  (`createIfNotFound` only).
</ParamField>

### Space-scoped reputation

This endpoint has no space in context, so the opt-in `spaceReputation` object accepts a `spaceId` of a space **`<uuid>`** or **`none`** only — `context` is rejected (400). It adds a `spaceReputation` field to each returned user, alongside the always-present `reputation` total. Requires the `reputation` bundle. See the [Reputation data model](/data-models/reputation).

<SpaceReputationParams />

## Response

Returns HTTP `200` (found) or `201` (created) with the user object:

<ResponseField name="id" type="string">
  Unique user ID (UUID).
</ResponseField>

<ResponseField name="foreignId" type="string | null">
  The foreign ID you provided.
</ResponseField>

<ResponseField name="projectId" type="string">
  Project this user belongs to.
</ResponseField>

<ResponseField name="name" type="string | null">
  Display name.
</ResponseField>

<ResponseField name="username" type="string | null">
  Unique username within the project.
</ResponseField>

<ResponseField name="avatar" type="string | null">
  Avatar image URL.
</ResponseField>

<ResponseField name="bio" type="string | null">
  Short bio text.
</ResponseField>

<ResponseField name="metadata" type="object | null">
  Public custom key-value data.
</ResponseField>

<ResponseField name="reputation" type="number">
  Reputation score.
</ResponseField>

<ResponseField name="avatarFile" type="object | null">
  Processed avatar image with variants. Only present when `include=files` is
  requested.
</ResponseField>

<ResponseField name="bannerFile" type="object | null">
  Processed banner image with variants. Only present when `include=files` is
  requested.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO timestamp of account creation.
</ResponseField>

<Note>
  `createIfNotFound=true` is only permitted with a **service** or **master**
  token. Client tokens receive a 404 if the user does not exist.
</Note>

## Error Responses

<AccordionGroup>
  <Accordion title="User Not Found — 404">
    ```json theme={null}
    {
      "error": "User not found",
      "code": "user/not-found"
    }
    ```
  </Accordion>

  <Accordion title="Invalid Query — 400">
    ```json theme={null}
    {
      "error": "...",
      "code": "user/invalid-query"
    }
    ```
  </Accordion>
</AccordionGroup>

## See Also

* [`useFetchUserByForeignId` hook](/hooks/users/use-fetch-user-by-foreign-id)
* [External auth guide](/sdk/authentication/external)
* [User data model](/data-models/user)


# Use app notifications
Source: https://docs.sublay.io/v7/hooks/app-notifications/use-app-notifications

Fetch notifications, track unread count, and mark as read

## Overview

Redux-powered hook that provides a paginated notification feed for the current authenticated user. Loads notifications and unread count on mount, supports infinite scrolling via `loadMore`, and exposes mark-as-read actions with optimistic updates.

For integration guidance and template configuration, see [App Notifications](/sdk/app-notifications/hook).

## Usage Example

```tsx theme={null}
import { useAppNotifications } from "@sublay/react-js";

function NotificationBell() {
  const { unreadAppNotificationsCount } = useAppNotifications();

  return <span>{unreadAppNotificationsCount} unread</span>;
}

function NotificationList() {
  const {
    appNotifications,
    loading,
    hasMore,
    loadMore,
    markNotificationAsRead,
  } = useAppNotifications({
    limit: 20,
    notificationTemplates: {
      entityComment: { content: "$initiatorName commented on your post" },
      newFollow: { content: "$initiatorName followed you" },
    },
  });

  return (
    <ul>
      {appNotifications.map((n) => (
        <li key={n.id} onClick={() => markNotificationAsRead({ notificationId: n.id })}>
          {n.content ?? n.type}
        </li>
      ))}
      {hasMore && <button onClick={loadMore}>Load more</button>}
    </ul>
  );
}
```

## Parameters

<ParamField type="number">
  Number of notifications to load per page. Defaults to `10`.
</ParamField>

<ParamField type="Partial<NotificationTemplates>">
  Optional display text templates for each notification type. Applied at render time. See [Notification Templates](/sdk/app-notifications/notification-templates).
</ParamField>

## Returns

<ResponseField name="appNotifications" type="UnifiedAppNotification[]">
  Array of notification records, augmented with `title` and `content` if templates are provided.
</ResponseField>

<ResponseField name="unreadAppNotificationsCount" type="number">
  Total number of unread notifications for the current user.
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` while a fetch is in progress.
</ResponseField>

<ResponseField name="hasMore" type="boolean">
  `true` if there are additional pages to load.
</ResponseField>

<ResponseField name="loadMore" type="() => void">
  Triggers loading the next page of notifications and appending them to the list.
</ResponseField>

<ResponseField name="markNotificationAsRead" type="({ notificationId: string }) => Promise<void>">
  Marks a single notification as read with an optimistic local update.
</ResponseField>

<ResponseField name="markAllNotificationsAsRead" type="() => Promise<void>">
  Marks all notifications as read with an optimistic local update.
</ResponseField>

<ResponseField name="resetAppNotifications" type="() => Promise<void>">
  Clears and re-fetches from page 1.
</ResponseField>

<Note>
  This hook requires the current user to be authenticated. It will not load until `user` and `projectId` are available.
</Note>


# Use block manager
Source: https://docs.sublay.io/v7/hooks/blocks/use-block-manager

Manage block state between the current user and another user in a single hook

## Overview

Combines block-status fetching and toggle actions into a single hook. On mount, loads whether the current user blocks `userId`, then provides a `toggleBlock` function to block or unblock in one call. This is the hook to wire to a block/unblock button.

Blocking is part of the trust & safety (moderation) bundle. See [Moderation — Blocking](/sdk/moderation/overview#blocking) for what a block prevents and hides.

## Usage Example

```tsx theme={null}
import { useBlockManager } from "@sublay/react-js";

function BlockButton({ userId }: { userId: string }) {
  const { isBlocked, isLoading, toggleBlock } = useBlockManager({ userId });

  return (
    <button onClick={toggleBlock} disabled={isLoading || isBlocked === null}>
      {isBlocked ? "Unblock" : "Block"}
    </button>
  );
}
```

## Parameters

<ParamField type="string">
  The ID of the target user.
</ParamField>

## Returns

<ResponseField name="isBlocked" type="boolean | null">
  `true` if the current user blocks the target, `false` if not, `null` while the initial status is loading.
</ResponseField>

<ResponseField name="isLoading" type="boolean">
  `true` while the initial status check is in progress.
</ResponseField>

<ResponseField name="toggleBlock" type="() => Promise<void>">
  Blocks the target user if not currently blocked; unblocks if currently blocked. No-ops while loading or if `userId` is the current user's own ID.
</ResponseField>

## Related

* [useBlockUser](/hooks/blocks/use-block-user)
* [useUnblockUser](/hooks/blocks/use-unblock-user)
* [useFetchBlockStatus](/hooks/blocks/use-fetch-block-status)
* [useFetchBlockedUsers](/hooks/blocks/use-fetch-blocked-users)


# Use block user
Source: https://docs.sublay.io/v7/hooks/blocks/use-block-user

Block another user

## Overview

Returns a function that blocks a user by their ID. On a new block, the server retroactively removes any existing follows and connections between the two users (both directions). Blocking is idempotent — re-blocking an already-blocked user succeeds.

<Note>
  Requires the `moderation` bundle. See [Moderation — Blocking](/sdk/moderation/overview#blocking).
</Note>

## Usage Example

```tsx theme={null}
import { useBlockUser } from "@sublay/react-js";

function BlockAction({ userId }: { userId: string }) {
  const blockUser = useBlockUser();

  return <button onClick={() => blockUser({ userId })}>Block</button>;
}
```

## Parameters

The hook returns a function. That function accepts:

<ParamField type="string">
  The ID of the user to block (the target).
</ParamField>

## Returns

The returned function resolves to `void` on success.

## Related

* [useUnblockUser](/hooks/blocks/use-unblock-user)
* [useBlockManager](/hooks/blocks/use-block-manager) — combines block/unblock with status loading


# Fetch block status
Source: https://docs.sublay.io/v7/hooks/blocks/use-fetch-block-status

Check whether the current user blocks a specific user

## Overview

Returns a function that checks whether the current authenticated user blocks a given `userId`. The result reports the current user's **outbound** state only — whether *I* block this user. It never reveals whether the other user has blocked the current user (the inbound direction is deliberately hidden for non-disclosure).

## Usage Example

```tsx theme={null}
import { useFetchBlockStatus } from "@sublay/react-js";

function ProfilePage({ userId }: { userId: string }) {
  const fetchBlockStatus = useFetchBlockStatus();

  useEffect(() => {
    fetchBlockStatus({ userId }).then((status) => {
      console.log(status.blocked, status.blockId);
    });
  }, [userId]);
}
```

## Parameters

The hook returns a function. That function accepts:

<ParamField type="string">
  The ID of the user to check. Cannot be the current user's own ID.
</ParamField>

## Returns

<ResponseField name="blocked" type="boolean">
  Whether the current user blocks the target user.
</ResponseField>

<ResponseField name="blockId" type="string | undefined">
  The ID of the block record. Present when `blocked` is `true`.
</ResponseField>

<ResponseField name="createdAt" type="string | undefined">
  ISO timestamp of when the block was created. Present when `blocked` is `true`.
</ResponseField>

## Related

* [useBlockManager](/hooks/blocks/use-block-manager) — loads this status automatically on mount


# Fetch blocked users
Source: https://docs.sublay.io/v7/hooks/blocks/use-fetch-blocked-users

Read the current user's own paginated block list

## Overview

Returns a function that fetches a paginated list of the users the current user has blocked (their **outbound** blocks), each row carrying a public profile summary. This is the private "manage / way back to unblock" surface — it exposes only the current user's own blocks.

## Usage Example

```tsx theme={null}
import { useFetchBlockedUsers } from "@sublay/react-js";

function BlockList() {
  const fetchBlockedUsers = useFetchBlockedUsers();

  useEffect(() => {
    fetchBlockedUsers({ page: 1, limit: 20 }).then(({ data }) => {
      data.forEach((row) => console.log(row.blockedUser?.username));
    });
  }, []);
}
```

## Parameters

The hook returns a function. That function accepts an optional object:

<ParamField type="number">
  Page number for pagination.
</ParamField>

<ParamField type="number">
  Number of results per page. Max `100`.
</ParamField>

## Returns

A `PaginatedResponse<BlockedUser>`, where each `BlockedUser` is:

<ResponseField name="id" type="string">
  ID of the block record.
</ResponseField>

<ResponseField name="blockedUser" type="User | null">
  Public profile of the blocked user.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO timestamp of when the block was created.
</ResponseField>

## Related

* [useBlockManager](/hooks/blocks/use-block-manager)
* [useUnblockUser](/hooks/blocks/use-unblock-user)


# Use unblock user
Source: https://docs.sublay.io/v7/hooks/blocks/use-unblock-user

Remove a block on another user

## Overview

Returns a function that unblocks a user by their ID. Unblocking is idempotent and restores nothing — removed follows and connections stay gone; a previously frozen 1:1 conversation becomes usable again.

<Note>
  Requires the `moderation` bundle. See [Moderation — Blocking](/sdk/moderation/overview#blocking).
</Note>

## Usage Example

```tsx theme={null}
import { useUnblockUser } from "@sublay/react-js";

function UnblockAction({ userId }: { userId: string }) {
  const unblockUser = useUnblockUser();

  return <button onClick={() => unblockUser({ userId })}>Unblock</button>;
}
```

## Parameters

The hook returns a function. That function accepts:

<ParamField type="string">
  The ID of the user to unblock (the target). Cannot be the current user's own ID.
</ParamField>

## Returns

The returned function resolves to `void` on success.

## Related

* [useBlockUser](/hooks/blocks/use-block-user)
* [useBlockManager](/hooks/blocks/use-block-manager) — combines block/unblock with status loading


# Use conversation
Source: https://docs.sublay.io/v7/hooks/chat/conversations/use-conversation

Fetch, update, and delete a single conversation

## Overview

Fetches the full details of a single conversation by ID and provides `update` and `deleteConversation` actions. The conversation is loaded once on mount if it is not already in Redux state, and kept in sync by `conversation:updated` socket events.

<Note>Requires `ChatProvider` in the component tree.</Note>

## Usage Example

```tsx theme={null}
import { useConversation } from "@sublay/react-js";

function ConversationHeader({ conversationId }: { conversationId: string }) {
  const { conversation, loading, update, deleteConversation } = useConversation({
    conversationId,
  });

  if (loading || !conversation) return <div>Loading...</div>;

  return (
    <div>
      <h2>{conversation.name ?? "Direct Message"}</h2>
      <button onClick={() => update({ name: "Renamed Group" })}>Rename</button>
      <button onClick={deleteConversation}>Delete</button>
    </div>
  );
}
```

## Props

<ParamField type="string">
  The ID of the conversation to fetch and manage.
</ParamField>

## Returns

<ResponseField name="conversation" type="Conversation | null">
  The full [Conversation](/data-models/conversation) object, or `null` while loading or if not found.
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` while the initial fetch is in progress.
</ResponseField>

<ResponseField name="update" type="(params: { name?: string; description?: string; avatarFileId?: string | null; postingPermission?: 'members' | 'admins' }) => Promise<Conversation | undefined>">
  Updates the conversation. Dispatches the updated conversation to Redux on success. `conversationId` is already bound from the hook props and should not be passed here.

  | Field               | Type                    | Description                     |
  | ------------------- | ----------------------- | ------------------------------- |
  | `name`              | `string`                | New conversation name           |
  | `description`       | `string`                | New description                 |
  | `avatarFileId`      | `string \| null`        | File ID for the avatar image    |
  | `postingPermission` | `'members' \| 'admins'` | Who can post (space chats only) |
</ResponseField>

<ResponseField name="deleteConversation" type="() => Promise<void>">
  Deletes the conversation. Does not update local Redux state — the caller is responsible for navigating away or removing the conversation from local lists.
</ResponseField>

## Notes

* For integration guidance, see [Chat: Conversations](/sdk/chat/conversations).


# Use conversation members
Source: https://docs.sublay.io/v7/hooks/chat/conversations/use-conversation-members

Fetch and manage the members of a conversation

## Overview

Fetches the member list for a conversation on mount and provides actions to add members, remove members, change roles, and leave the conversation. Also exposes `upsertMember` and `removeMemberLocally` for real-time socket-driven updates.

<Note>Requires `ChatProvider` in the component tree.</Note>

## Usage Example

```tsx theme={null}
import { useConversationMembers } from "@sublay/react-js";

function MemberList({ conversationId }: { conversationId: string }) {
  const {
    members,
    loading,
    addMember,
    removeMember,
    changeRole,
    leave,
  } = useConversationMembers({ conversationId });

  if (loading) return <div>Loading members...</div>;

  return (
    <ul>
      {members.map((m) => (
        <li key={m.userId}>
          {m.user?.name} — {m.role}
          <button onClick={() => removeMember({ userId: m.userId })}>Remove</button>
          <button onClick={() => changeRole({ userId: m.userId, role: "admin" })}>
            Make Admin
          </button>
        </li>
      ))}
      <button onClick={leave}>Leave conversation</button>
    </ul>
  );
}
```

## Props

<ParamField type="string">
  The ID of the conversation whose members to fetch.
</ParamField>

<SpaceReputationParams />

## Returns

<ResponseField name="members" type="ConversationMember[]">
  The current member list. When `spaceReputation` is requested, each embedded user carries an added `spaceReputation` number. See [ConversationMember](/data-models/conversation-member) and [Reputation](/data-models/reputation).
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` while the initial fetch is in progress.
</ResponseField>

<ResponseField name="addMember" type="({ userId: string }) => Promise<void>">
  Adds a user to the conversation. Updates the local member list on success.
</ResponseField>

<ResponseField name="removeMember" type="({ userId: string }) => Promise<void>">
  Removes a user from the conversation. Updates the local member list on success.
</ResponseField>

<ResponseField name="leave" type="() => Promise<void>">
  Removes the current user from the conversation.
</ResponseField>

<ResponseField name="changeRole" type="({ userId: string; role: 'admin' | 'member' }) => Promise<void>">
  Updates a member's role. Updates the local member list on success.
</ResponseField>

<ResponseField name="upsertMember" type="(member: ConversationMember) => void">
  Inserts or replaces a member in the local list by `userId`. Intended for use with real-time socket event handlers.
</ResponseField>

<ResponseField name="removeMemberLocally" type="({ userId: string }) => void">
  Removes a member from the local list by `userId` without making an API call. Intended for use with real-time socket event handlers.
</ResponseField>

## Notes

* The member list is fetched with a limit of 100. For very large conversations, consider lazy-loading or paginating members separately.
* For integration guidance, see [Chat: Conversations](/sdk/chat/conversations).


# Use conversations
Source: https://docs.sublay.io/v7/hooks/chat/conversations/use-conversations

Fetch a paginated list of the current user's conversations

## Overview

Fetches the authenticated user's conversation list with cursor-based pagination. Conversations are sorted by most recent activity. The hook also exposes a `createGroup` function to create new group conversations.

<Note>Requires `ChatProvider` in the component tree.</Note>

## Usage Example

```tsx theme={null}
import { useConversations } from "@sublay/react-js";

function ConversationList() {
  const { conversations, loading, hasMore, loadMore, refresh } =
    useConversations({ types: ["direct", "group"] });

  return (
    <div>
      {conversations.map((convo) => (
        <div key={convo.id}>
          <strong>{convo.name ?? "Direct Message"}</strong>
          {convo.unreadCount > 0 && <span>{convo.unreadCount} unread</span>}
        </div>
      ))}
      {hasMore && (
        <button onClick={loadMore} disabled={loading}>
          Load more
        </button>
      )}
    </div>
  );
}
```

## Props

<ParamField type="('direct' | 'group' | 'space')[]">
  Filter conversations by type. If omitted, all types are returned.
</ParamField>

## Returns

<ResponseField name="conversations" type="ConversationPreview[]">
  The loaded conversations sorted by most recent activity. Each item is a [Conversation](/data-models/conversation) extended with `unreadCount`, a truncated `lastMessage`, and `otherMembers` — up to 5 active members other than the current user (public fields `id`, `name`, `username`, `avatar`), populated for `direct`/`group` conversations so a DM/group row can render the counterparty's name and avatar. Capped at 5 (use `memberCount` for the group total); empty for `space` conversations.
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` while a fetch is in progress.
</ResponseField>

<ResponseField name="hasMore" type="boolean">
  `true` if there are more conversations to load.
</ResponseField>

<ResponseField name="loadMore" type="() => Promise<void>">
  Fetches the next page of conversations and appends them to the list. No-ops if `loading` is `true` or `hasMore` is `false`.
</ResponseField>

<ResponseField name="refresh" type="() => Promise<void>">
  Resets the cursor and re-fetches the conversation list from the beginning.
</ResponseField>

<ResponseField name="createGroup" type="(params: { name?: string; metadata?: Record<string, unknown>; memberIds?: string[] }) => Promise<ConversationPreview>">
  Creates a new group conversation and prepends it to the loaded list. Resolves to the created `ConversationPreview`. Pass `memberIds` to add initial members in the same request — the server creates their member rows in one transaction. The creator is added as admin automatically and is de-duplicated if also present in `memberIds`.
</ResponseField>

## Notes

* The initial fetch runs on mount. Re-runs automatically when the authenticated project changes.
* New messages received via socket update the `lastMessage` and `lastMessageAt` of the relevant conversation in the list automatically — no manual refresh needed.
* For integration guidance, see [Chat: Conversations](/sdk/chat/conversations).


# Create direct conversation
Source: https://docs.sublay.io/v7/hooks/chat/conversations/use-create-direct-conversation

Create or retrieve a 1:1 direct conversation with another user

## Overview

Returns an async function that creates a direct (1:1) conversation with a given user. If a direct conversation between the two users already exists on the server, it is returned rather than creating a duplicate. The conversation is also stored in Redux state.

<Note>Requires `ChatProvider` in the component tree.</Note>

## Usage Example

```tsx theme={null}
import { useCreateDirectConversation } from "@sublay/react-js";

function UserCard({ userId }: { userId: string }) {
  const createDirect = useCreateDirectConversation();

  const handleMessage = async () => {
    const conversation = await createDirect({ userId });
    // Navigate to the conversation, e.g. router.push(`/chat/${conversation.id}`)
  };

  return <button onClick={handleMessage}>Message</button>;
}
```

## Parameters

The hook returns a function. That function accepts:

<ParamField type="string">
  The ID of the user to start a conversation with.
</ParamField>

## Returns

<ResponseField name="Conversation" type="Conversation">
  The created or retrieved direct [Conversation](/data-models/conversation).
</ResponseField>

## Notes

* For integration guidance, see [Chat: Conversations](/sdk/chat/conversations).


# Use delete conversation
Source: https://docs.sublay.io/v7/hooks/chat/conversations/use-delete-conversation

Delete a conversation

## Overview

Returns an async function that deletes a conversation via the API. This is a low-level hook — it makes the DELETE request without touching Redux state. The caller is responsible for navigating away or removing the conversation from any local lists after deletion.

<Note>Requires `ChatProvider` in the component tree.</Note>

## Usage Example

```tsx theme={null}
import { useDeleteConversation } from "@sublay/react-js";

function DeleteButton({ conversationId }: { conversationId: string }) {
  const deleteConversation = useDeleteConversation();

  const handleDelete = async () => {
    await deleteConversation({ conversationId });
    // Navigate away or update local state here
  };

  return <button onClick={handleDelete}>Delete</button>;
}
```

## Parameters

The hook returns a function. That function accepts:

<ParamField type="string">
  The ID of the conversation to delete.
</ParamField>

## Returns

`Promise<void>`

## Notes

* This hook does not update Redux state. After deletion, navigate away or remove the conversation from any local lists manually.
* For integration guidance, see [Chat: Conversations](/sdk/chat/conversations).


# Use fetch conversation
Source: https://docs.sublay.io/v7/hooks/chat/conversations/use-fetch-conversation

Fetch a single conversation by ID

## Overview

Returns an async function that fetches the full details of a single conversation by ID. This is a low-level hook — it makes the API call and returns the result without touching Redux state. Use it when you need to fetch a conversation on demand rather than on mount.

<Note>Requires `ChatProvider` in the component tree.</Note>

## Usage Example

```tsx theme={null}
import { useFetchConversation } from "@sublay/react-js";

function ConversationLoader({ conversationId }: { conversationId: string }) {
  const fetchConversation = useFetchConversation();

  const handleRefresh = async () => {
    const conversation = await fetchConversation({ conversationId });
    console.log(conversation);
  };

  return <button onClick={handleRefresh}>Refresh</button>;
}
```

## Parameters

The hook returns a function. That function accepts:

<ParamField type="string">
  The ID of the conversation to fetch.
</ParamField>

## Returns

<ResponseField name="Conversation" type="Conversation">
  The fetched [Conversation](/data-models/conversation) object.
</ResponseField>

## Notes

* This hook does not update Redux state. If you want the result stored and reactive, dispatch `setConversation` manually or use [`useConversation`](/hooks/chat/conversations/use-conversation) instead.
* For integration guidance, see [Chat: Conversations](/sdk/chat/conversations).


# Fetch space conversation
Source: https://docs.sublay.io/v7/hooks/chat/conversations/use-fetch-space-conversation

Fetch the chat conversation associated with a space

## Overview

Fetches the single `Conversation` that is tied to a Space. Each Space has exactly one conversation of type `"space"`. Use this hook to retrieve the conversation ID before rendering message components.

<Note>Requires `ChatProvider` in the component tree.</Note>

## Usage Example

```tsx theme={null}
import { useFetchSpaceConversation } from "@sublay/react-js";

function SpaceChatPanel({ spaceId }: { spaceId: string }) {
  const { conversation, loading } = useFetchSpaceConversation({ spaceId });

  if (loading) return <div>Loading...</div>;
  if (!conversation) return null;

  return <MessageList conversationId={conversation.id} />;
}
```

## Props

<ParamField type="string">
  The ID of the space whose conversation to fetch.
</ParamField>

## Returns

<ResponseField name="conversation" type="Conversation | null">
  The [Conversation](/data-models/conversation) associated with the space, or `null` while loading.
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` while the fetch is in progress.
</ResponseField>

## Notes

* The conversation is fetched on mount and stored in both local state and Redux.
* For integration guidance, see [Chat: Conversations](/sdk/chat/conversations).


# Use mute conversation
Source: https://docs.sublay.io/v7/hooks/chat/conversations/use-mute-conversation

Set or clear the current user's mute on a conversation

## Overview

`useMuteConversation` returns a function that sets or clears the signed-in user's mute on a conversation. Muting suppresses the `message` push for that conversation only — the message is still delivered and readable. Timed mutes expire on their own; push resumes with no further action.

The client passes a **duration choice**, never a raw timestamp — the server resolves the window and represents "forever" via an explicit signal on the returned member.

<Note>Requires `ChatProvider` in the component tree, an authenticated user, and the `chat` bundle.</Note>

## Usage Example

```tsx theme={null}
import { useMuteConversation } from "@sublay/react-js";

function MuteMenu({ conversationId }: { conversationId: string }) {
  const { muteConversation, muting } = useMuteConversation();

  const mute8h = () => muteConversation({ conversationId, duration: "8h" });
  const muteForever = () => muteConversation({ conversationId, duration: "forever" });
  const unmute = () => muteConversation({ conversationId, duration: null });

  return (
    <>
      <button onClick={mute8h} disabled={muting}>Mute 8h</button>
      <button onClick={muteForever} disabled={muting}>Mute forever</button>
      <button onClick={unmute} disabled={muting}>Unmute</button>
    </>
  );
}
```

## Parameters

The hook returns `{ muteConversation, muting }`. `muteConversation` accepts:

<ParamField type="string">
  The conversation to mute or unmute.
</ParamField>

<ParamField type="&#x22;8h&#x22; | &#x22;24h&#x22; | &#x22;1w&#x22; | &#x22;forever&#x22; | null">
  The mute **duration choice**, or `null` to clear the mute. Never a raw timestamp.
</ParamField>

## Returns

`muteConversation` resolves to the acting user's own (self-serialized) `currentMember`. Read the resulting mute state off it:

<ResponseField name="mutedForever" type="boolean">
  `true` when the conversation is muted indefinitely (`mutedUntil` is then `null`).
</ResponseField>

<ResponseField name="mutedUntil" type="string | null">
  Real ISO timestamp for a timed mute; `null` when not muted or muted forever.
</ResponseField>

<Warning>
  **"Forever" is an explicit boolean, not a magic date.** Check `mutedForever` — do not string-match a far-future `mutedUntil`. The SDK never receives the storage sentinel.
</Warning>

## Notes

* Available on `@sublay/react-js`, `@sublay/react-native`, and `@sublay/expo` (inherited from `@sublay/core`).
* Mute state is personal — it's returned only on the viewer's own member row, never on other members'.
* For per-type push toggles, see [`useNotificationPreferences`](/hooks/push/use-notification-preferences).


# Use update conversation
Source: https://docs.sublay.io/v7/hooks/chat/conversations/use-update-conversation

Update a conversation's details

## Overview

Returns an async function that updates a conversation's details via the API. This is a low-level hook — it makes the PATCH request and returns the updated conversation without touching Redux state. Use it when you need direct control over when and how state is updated.

<Note>Requires `ChatProvider` in the component tree.</Note>

## Usage Example

```tsx theme={null}
import { useUpdateConversation } from "@sublay/react-js";

function RenameButton({ conversationId }: { conversationId: string }) {
  const updateConversation = useUpdateConversation();

  const handleRename = async () => {
    const updated = await updateConversation({
      conversationId,
      name: "New Name",
    });
    console.log(updated);
  };

  return <button onClick={handleRename}>Rename</button>;
}
```

## Parameters

The hook returns a function. That function accepts:

<ParamField type="string">
  The ID of the conversation to update.
</ParamField>

<ParamField type="string">
  New conversation name.
</ParamField>

<ParamField type="string">
  New conversation description.
</ParamField>

<ParamField type="string | null">
  File ID for the avatar image. Pass `null` to remove the current avatar.
</ParamField>

<ParamField type="'members' | 'admins'">
  Who can post messages. Only applicable to space conversations.
</ParamField>

## Returns

<ResponseField name="Conversation" type="Conversation">
  The updated [Conversation](/data-models/conversation) object.
</ResponseField>

## Notes

* This hook does not update Redux state. If you want the result reflected in the UI, dispatch `setConversation` manually or use [`useConversation`](/hooks/chat/conversations/use-conversation) which handles this automatically.
* For integration guidance, see [Chat: Conversations](/sdk/chat/conversations).


# Use chat messages (deprecated)
Source: https://docs.sublay.io/v7/hooks/chat/messages/use-chat-messages

Deprecated alias for useLiveChatMessages

<Warning>
  `useChatMessages` has been renamed to [`useLiveChatMessages`](/hooks/chat/messages/use-live-chat-messages). The old name still works as an alias and forwards to the new hook, but it is deprecated and will be removed in a future major version. Update your imports:

  ```diff theme={null}
  - import { useChatMessages } from "@sublay/react-js";
  + import { useLiveChatMessages } from "@sublay/react-js";
  ```
</Warning>

The behaviour and signature are identical — see [`useLiveChatMessages`](/hooks/chat/messages/use-live-chat-messages) for full documentation.

Looking to fetch a **filtered** or read-only list of messages (e.g. only messages that have replies)? Use [`useFetchManyChatMessages`](/hooks/chat/messages/use-fetch-many-chat-messages) instead.


# Delete message
Source: https://docs.sublay.io/v7/hooks/chat/messages/use-delete-message

Soft-delete a chat message

## Overview

Returns an async function that soft-deletes a message. The message is removed from the local Redux store immediately. On the server, the message's content is cleared and `userDeletedAt` is set — the record is retained for threading consistency.

<Note>Requires `ChatProvider` in the component tree.</Note>

## Usage Example

```tsx theme={null}
import { useDeleteMessage } from "@sublay/react-js";

function MessageActions({
  conversationId,
  messageId,
}: {
  conversationId: string;
  messageId: string;
}) {
  const deleteMsg = useDeleteMessage();

  return (
    <button onClick={() => deleteMsg({ conversationId, messageId })}>
      Delete
    </button>
  );
}
```

## Parameters

The hook returns a function. That function accepts:

<ParamField type="string">
  The ID of the conversation that contains the message.
</ParamField>

<ParamField type="string">
  The ID of the message to delete.
</ParamField>

## Returns

`Promise<void>`

## Notes

* Other participants see the deletion in real-time via the `message:deleted` socket event, which is handled automatically by `ChatProvider`. Their local copy of the message will have `userDeletedAt` set and `content: null`.
* For integration guidance, see [Chat: Messages](/sdk/chat/messages).


# Edit message
Source: https://docs.sublay.io/v7/hooks/chat/messages/use-edit-message

Edit the content of an existing chat message

## Overview

Returns an async function that patches an existing message's content. The updated message is dispatched to Redux on success. The `editedAt` field is set by the server and reflects the time of the most recent edit.

<Note>Requires `ChatProvider` in the component tree.</Note>

## Usage Example

```tsx theme={null}
import { useEditMessage } from "@sublay/react-js";

function EditMessageForm({
  conversationId,
  messageId,
  currentContent,
}: {
  conversationId: string;
  messageId: string;
  currentContent: string;
}) {
  const edit = useEditMessage();
  const [text, setText] = useState(currentContent);

  const handleSave = async () => {
    await edit({ conversationId, messageId, content: text });
  };

  return (
    <div>
      <input value={text} onChange={(e) => setText(e.target.value)} />
      <button onClick={handleSave}>Save</button>
    </div>
  );
}
```

## Parameters

The hook returns a function. That function accepts:

<ParamField type="string">
  The ID of the conversation that contains the message.
</ParamField>

<ParamField type="string">
  The ID of the message to edit.
</ParamField>

<ParamField type="string">
  New text content.
</ParamField>

<ParamField type="GifData | null">
  New or cleared GIF attachment.
</ParamField>

<ParamField type="Mention[]">
  Updated mentions list.
</ParamField>

<ParamField type="Record<string, any>">
  Updated metadata.
</ParamField>

## Returns

<ResponseField name="ChatMessage" type="ChatMessage">
  The updated [ChatMessage](/data-models/chat-message) returned by the server.
</ResponseField>

## Notes

* Other participants see the update in real-time via the `message:updated` socket event, which is handled automatically by `ChatProvider`.
* For integration guidance, see [Chat: Messages](/sdk/chat/messages).


# Fetch many chat messages
Source: https://docs.sublay.io/v7/hooks/chat/messages/use-fetch-many-chat-messages

Stateless fetcher for conversation messages — no Redux, no socket

## Overview

`useFetchManyChatMessages` returns a function that fetches a single page of conversation messages and resolves to the raw response. It stores nothing — no Redux, no socket subscription — so you own the resulting state.

This is the low-level fetcher shared by [`useLiveChatMessages`](/hooks/chat/messages/use-live-chat-messages) (the live store-backed view) and [`useFetchManyChatMessagesWrapper`](/hooks/chat/messages/use-fetch-many-chat-messages-wrapper) (a batteries-included paginated list). Use it directly when you need full control; most apps will prefer the wrapper.

<Note>Because results never enter the live store, this is the right tool for **filtered** or read-only queries (e.g. only messages that have replies) that should not be polluted by live socket traffic. It is a point-in-time query — call it again to refresh.</Note>

## Usage Example

```tsx theme={null}
import { useFetchManyChatMessages } from "@sublay/react-js";
import { useState, useEffect } from "react";

function MessagesWithReplies({ conversationId }: { conversationId: string }) {
  const fetchMessages = useFetchManyChatMessages();
  const [messages, setMessages] = useState([]);

  useEffect(() => {
    fetchMessages({ conversationId, filters: { hasReplies: true } }).then((res) =>
      setMessages(res.messages)
    );
  }, [conversationId]);

  return (
    <ul>
      {messages.map((m) => <li key={m.id}>{m.content}</li>)}
    </ul>
  );
}
```

## Parameters

<ParamField type="string">
  The ID of the conversation to query.
</ParamField>

<ParamField type="string | null">
  Restrict to thread replies of this message.
</ParamField>

<ParamField type="string | null">
  Keyset cursor (ISO timestamp): messages created before this. Mutually exclusive with `after`.
</ParamField>

<ParamField type="string | null">
  Keyset cursor (ISO timestamp): messages created after this. Mutually exclusive with `before`.
</ParamField>

<ParamField type="number">
  Page size (1–100). Defaults to `50`.
</ParamField>

<ParamField type="&#x22;asc&#x22; | &#x22;desc&#x22;">
  Sort by creation time.
</ParamField>

<ParamField type="boolean">
  When `true`, the server populates the `files` field on each message.
</ParamField>

<ParamField type="boolean">
  When `true`, each message carries its [reputation-grant summary](/data-models/reputation-grant#grantsummary) at `message.grants` — `{ total, count, viewerTotal }` over positive grants. Populated by the `reputation` bundle; on a project without it the summary comes back zero-filled rather than missing.
</ParamField>

<SpaceReputationParams />

<ParamField type="MessageFilters">
  Optional filters. `filters.hasReplies` (boolean): when `true`, returns only messages that have thread replies (`threadReplyCount > 0`); when `false`, only messages with none. Filters by thread replies, not quotings.

  <Note>Threads are one level deep, so `hasReplies: true` together with `parentId` always returns an empty list — the response's `notice` field explains why.</Note>
</ParamField>

## Returns

A `Promise` resolving to:

<ResponseField name="messages" type="ChatMessage[]">
  Messages for the requested page. When `spaceReputation` is requested, each embedded sender carries an added `spaceReputation` number. See [ChatMessage](/data-models/chat-message) and [Reputation](/data-models/reputation).
</ResponseField>

<ResponseField name="hasMore" type="boolean">
  Whether more messages exist in the requested direction.
</ResponseField>

<ResponseField name="oldestCreatedAt" type="string | null">
  ISO timestamp of the oldest message in this page; `null` if empty.
</ResponseField>

<ResponseField name="newestCreatedAt" type="string | null">
  ISO timestamp of the newest message in this page; `null` if empty.
</ResponseField>

<ResponseField name="notice" type="string">
  Present only when a filter combination can't return results — e.g. `hasReplies: true` together with `parentId`. Explains why the list is empty.
</ResponseField>


# Fetch many chat messages (wrapper)
Source: https://docs.sublay.io/v7/hooks/chat/messages/use-fetch-many-chat-messages-wrapper

Stateful, paginated message list for read-only / filtered queries

## Overview

`useFetchManyChatMessagesWrapper` is a stateful wrapper around [`useFetchManyChatMessages`](/hooks/chat/messages/use-fetch-many-chat-messages) that manages the message list and cursor pagination for you. It keeps results in local component state — **not** Redux — and never receives socket updates.

Use it for a read-only or **filtered** list of messages that should not be touched by live traffic — for example, a "messages with replies" panel, an admin/moderation view, or any custom message list outside the live conversation stream. For the live canonical conversation view, use [`useLiveChatMessages`](/hooks/chat/messages/use-live-chat-messages) instead.

<Note>This is a point-in-time query: it does not auto-update from socket events. Call `refetch` (e.g. on a refresh button, or on a socket signal of your choosing) to pick up new matches. It does not require `ChatProvider`.</Note>

## Usage Example

```tsx theme={null}
import { useFetchManyChatMessagesWrapper } from "@sublay/react-js";

function MessagesWithReplies({ conversationId }: { conversationId: string }) {
  const { messages, loading, hasMore, loadMore, refetch } =
    useFetchManyChatMessagesWrapper({
      conversationId,
      filters: { hasReplies: true },
    });

  return (
    <div>
      <button onClick={refetch} disabled={loading}>Refresh</button>
      {messages.map((m) => (
        <div key={m.id}>
          {m.content} · {m.threadReplyCount} replies
        </div>
      ))}
      {hasMore && (
        <button onClick={loadMore} disabled={loading}>Load more</button>
      )}
    </div>
  );
}
```

## Props

<ParamField type="string">
  The ID of the conversation to query.
</ParamField>

<ParamField type="string | null">
  Restrict to thread replies of this message.
</ParamField>

<ParamField type="number">
  Page size. Defaults to `50`.
</ParamField>

<ParamField type="&#x22;asc&#x22; | &#x22;desc&#x22;">
  Sort by creation time. Defaults to `"desc"` (newest first), where `loadMore` fetches older messages. With `"asc"`, `loadMore` fetches newer messages.
</ParamField>

<ParamField type="boolean">
  When `true`, the server populates the `files` field on each message.
</ParamField>

<ParamField type="boolean">
  When `true`, each message carries its [reputation-grant summary](/data-models/reputation-grant#grantsummary) at `message.grants` — `{ total, count, viewerTotal }` over positive grants. Populated by the `reputation` bundle; on a project without it the summary comes back zero-filled rather than missing.
</ParamField>

<ParamField type="MessageFilters">
  Optional filters. `filters.hasReplies` (boolean): when `true`, returns only messages that have thread replies (`threadReplyCount > 0`); when `false`, only messages with none. Filters by thread replies, not quotings.

  <Note>Threads are one level deep, so `hasReplies: true` together with `parentId` always yields an empty list. This wrapper exposes only `messages`; use the lower-level [`useFetchManyChatMessages`](/hooks/chat/messages/use-fetch-many-chat-messages) if you want the `notice` explaining why.</Note>
</ParamField>

## Returns

<ResponseField name="messages" type="ChatMessage[]">
  The loaded messages. See [ChatMessage](/data-models/chat-message).
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` while a fetch is in progress.
</ResponseField>

<ResponseField name="hasMore" type="boolean">
  `true` if more messages can be loaded.
</ResponseField>

<ResponseField name="loadMore" type="() => void">
  Loads the next page in the direction of `sort` and appends it. No-ops while loading or when there are no more pages.
</ResponseField>

<ResponseField name="refetch" type="() => void">
  Re-fetches the first page from scratch (e.g. to pick up new matches).
</ResponseField>


# Use live chat messages
Source: https://docs.sublay.io/v7/hooks/chat/messages/use-live-chat-messages

Live, store-backed message stream for a conversation or thread

## Overview

The live, canonical view of a conversation's messages. Results are stored in Redux and kept in sync by `ChatProvider` socket events, so new messages, edits, reactions and reply-count changes appear in real time, and state is shared with `useSendMessage` (optimistic inserts), unread tracking and reconnect catch-up. Can be used for the main message stream or for a specific thread (by passing `parentId`).

<Note>Requires `ChatProvider` in the component tree.</Note>

<Tip>For a read-only or **filtered** query (e.g. "only messages that have replies") that should not be touched by live socket traffic, use [`useFetchManyChatMessages` / `useFetchManyChatMessagesWrapper`](/hooks/chat/messages/use-fetch-many-chat-messages) instead. The live hook intentionally does not take a `filters` prop.</Tip>

## Usage Example

```tsx theme={null}
import { useLiveChatMessages } from "@sublay/react-js";

function MessageList({ conversationId }: { conversationId: string }) {
  const { messages, loading, hasMore, loadOlder } = useLiveChatMessages({
    conversationId,
  });

  return (
    <div>
      {hasMore && (
        <button onClick={loadOlder} disabled={loading}>
          Load older messages
        </button>
      )}
      {messages.map((msg) => (
        <div key={msg.id}>
          <strong>{msg.user?.name ?? "Deleted user"}</strong>: {msg.content}
        </div>
      ))}
    </div>
  );
}
```

## Props

<ParamField type="string">
  The ID of the conversation to load messages for.
</ParamField>

<ParamField type="string | null">
  When provided, loads thread replies for this parent message ID instead of the main stream. Replies are sorted ascending (oldest first); `loadOlder` fetches newer replies.
</ParamField>

<ParamField type="number">
  Number of messages per page. Defaults to `50`.
</ParamField>

<ParamField type="boolean">
  When `true`, the server populates the `files` field on each message. Omitted by default to keep payloads small.
</ParamField>

<ParamField type="boolean">
  When `true`, each message carries its [reputation-grant summary](/data-models/reputation-grant#grantsummary) at `message.grants` — `{ total, count, viewerTotal }` over positive grants. Populated by the `reputation` bundle; on a project without it the summary comes back zero-filled rather than missing.
</ParamField>

## Returns

<ResponseField name="messages" type="ChatMessage[]">
  The loaded messages in ascending order (oldest first). See [ChatMessage](/data-models/chat-message).
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` while a fetch is in progress.
</ResponseField>

<ResponseField name="hasMore" type="boolean">
  `true` if there are more messages to load.
</ResponseField>

<ResponseField name="loadOlder" type="() => Promise<void>">
  For the main stream: fetches messages older than the oldest currently loaded.
  For threads: fetches replies newer than the newest currently loaded.
  No-ops if `loading` is `true` or `hasMore` is `false`.
</ResponseField>

## Notes

* New messages that arrive via the socket (`message:created`) are appended to the store automatically — no manual refetch needed.
* For integration guidance, see [Chat: Messages](/sdk/chat/messages).


# Use message thread
Source: https://docs.sublay.io/v7/hooks/chat/messages/use-message-thread

Load replies and send new replies in a message thread

## Overview

A convenience hook that wraps `useLiveChatMessages` and `useSendMessage` for a specific message thread. Returns the thread's replies and a `sendReply` function that automatically sets `parentMessageId`.

<Note>Requires `ChatProvider` in the component tree.</Note>

## Usage Example

```tsx theme={null}
import { useMessageThread } from "@sublay/react-js";

function ThreadPanel({
  conversationId,
  messageId,
}: {
  conversationId: string;
  messageId: string;
}) {
  const { replies, loading, hasMore, loadMore, sendReply } = useMessageThread({
    conversationId,
    messageId,
  });
  const [text, setText] = useState("");

  const handleReply = async () => {
    if (!text.trim()) return;
    await sendReply({ content: text });
    setText("");
  };

  return (
    <div>
      {replies.map((reply) => (
        <div key={reply.id}>
          <strong>{reply.user?.name}</strong>: {reply.content}
        </div>
      ))}
      {hasMore && <button onClick={loadMore}>Load more</button>}
      <input value={text} onChange={(e) => setText(e.target.value)} />
      <button onClick={handleReply}>Reply</button>
    </div>
  );
}
```

## Props

<ParamField type="string">
  The ID of the conversation that contains the thread.
</ParamField>

<ParamField type="string">
  The ID of the parent message whose thread to load.
</ParamField>

## Returns

<ResponseField name="replies" type="ChatMessage[]">
  Thread replies in ascending order (oldest first). See [ChatMessage](/data-models/chat-message).
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` while a fetch is in progress.
</ResponseField>

<ResponseField name="hasMore" type="boolean">
  `true` if there are more replies to load.
</ResponseField>

<ResponseField name="loadMore" type="() => Promise<void>">
  Fetches more replies (newer than the newest loaded). No-ops if `loading` is `true` or `hasMore` is `false`.
</ResponseField>

<ResponseField name="sendReply" type="(params: Omit<SendMessageParams, 'parentMessageId'>) => Promise<ChatMessage>">
  Sends a reply to this thread. Accepts the same parameters as `useSendMessage` except `parentMessageId` (set automatically). Returns the confirmed [ChatMessage](/data-models/chat-message).
</ResponseField>

## Notes

* For integration guidance, see [Chat: Threads](/sdk/chat/threads).


# Send message
Source: https://docs.sublay.io/v7/hooks/chat/messages/use-send-message

Send a message to a conversation with optimistic updates

## Overview

Returns an async function that sends a message to a conversation. An optimistic entry is inserted into Redux immediately — with a temporary ID — and replaced by the server-confirmed message on success. If the request fails, the optimistic message is flagged with `sendFailed: true`.

<Note>Requires `ChatProvider` in the component tree.</Note>

## Usage Example

```tsx theme={null}
import { useSendMessage } from "@sublay/react-js";

function MessageInput({ conversationId }: { conversationId: string }) {
  const send = useSendMessage({ conversationId });
  const [text, setText] = useState("");

  const handleSend = async () => {
    if (!text.trim()) return;
    await send({ content: text });
    setText("");
  };

  return (
    <div>
      <input value={text} onChange={(e) => setText(e.target.value)} />
      <button onClick={handleSend}>Send</button>
    </div>
  );
}
```

## Props

<ParamField type="string">
  The ID of the conversation to send the message to.
</ParamField>

## Parameters

The hook returns a function. That function accepts:

<ParamField type="string">
  Plain text content of the message.
</ParamField>

<ParamField type="GifData">
  GIF attachment data.
</ParamField>

<ParamField type="Mention[]">
  User mentions to embed in the message.
</ParamField>

<ParamField type="Record<string, any>">
  Arbitrary key-value data attached to the message.
</ParamField>

<ParamField type="string | null">
  ID of the message being quoted. Populates `quotedMessage` on the stored message.
</ParamField>

<ParamField type="string | null">
  ID of the parent message when sending a thread reply.
</ParamField>

<ParamField type="File[]">
  File attachments. When provided, the request is sent as `multipart/form-data`.
</ParamField>

<SpaceReputationParams />

## Returns

<ResponseField name="ChatMessage" type="ChatMessage">
  The server-confirmed [ChatMessage](/data-models/chat-message) object. When `spaceReputation` is requested, its embedded sender carries an added `spaceReputation` number. See [Reputation](/data-models/reputation).
</ResponseField>

## Notes

* At least one of `content`, `gif`, `files`, or non-empty `metadata` should be provided for a meaningful message.
* For integration guidance, see [Chat: Messages](/sdk/chat/messages).


# Toggle reaction
Source: https://docs.sublay.io/v7/hooks/chat/messages/use-toggle-reaction

Add or remove an emoji reaction on a chat message

## Overview

Returns an async function that toggles an emoji reaction on a message. If the current user has not reacted with this emoji, it adds the reaction. If they have, it removes it. The `reactionCounts` and `userReactions` on the message in Redux are updated after the server confirms the toggle.

<Note>Requires `ChatProvider` in the component tree.</Note>

## Usage Example

```tsx theme={null}
import { useToggleReaction } from "@sublay/react-js";

function ReactionPicker({
  conversationId,
  messageId,
  reactionCounts,
  userReactions,
}: {
  conversationId: string;
  messageId: string;
  reactionCounts: Record<string, number>;
  userReactions: string[];
}) {
  const toggle = useToggleReaction();

  return (
    <div>
      {["👍", "❤️", "😂", "😮"].map((emoji) => (
        <button
          key={emoji}
          onClick={() => toggle({ conversationId, messageId, emoji })}
          style={{ fontWeight: userReactions.includes(emoji) ? "bold" : "normal" }}
        >
          {emoji} {reactionCounts[emoji] ?? 0}
        </button>
      ))}
    </div>
  );
}
```

## Parameters

The hook returns a function. That function accepts:

<ParamField type="string">
  The ID of the conversation that contains the message.
</ParamField>

<ParamField type="string">
  The ID of the message to react to.
</ParamField>

<ParamField type="string">
  The emoji to toggle (e.g. `"👍"`, `"❤️"`).
</ParamField>

## Returns

<ResponseField name="reactionCounts" type="Record<string, number>">
  Updated map of emoji to total count for this message.
</ResponseField>

<ResponseField name="userReactions" type="string[]">
  Updated list of emojis the current user has reacted with on this message.
</ResponseField>

## Notes

* Other participants see the reaction update in real-time via the `message:reaction` socket event, handled automatically by `ChatProvider`.
* For integration guidance, see [Chat: Messages](/sdk/chat/messages).


# Use chat socket
Source: https://docs.sublay.io/v7/hooks/chat/use-chat-socket

Access the underlying Socket.io connection state for chat

## Overview

Returns the shared Socket.io socket instance and its connection state from `ChatProvider`. Most applications will only need the `connected` flag for displaying connection status UI. Direct socket access is available for advanced use cases.

<Note>Requires `ChatProvider` in the component tree.</Note>

## Usage Example

```tsx theme={null}
import { useChatSocket } from "@sublay/react-js";

function ConnectionStatus() {
  const { connected } = useChatSocket();

  return (
    <span className={connected ? "text-green-500" : "text-gray-400"}>
      {connected ? "Online" : "Connecting..."}
    </span>
  );
}
```

## Returns

<ResponseField name="socket" type="Socket | null">
  The underlying Socket.io socket instance. `null` when no user is authenticated or before the connection is established. For most use cases, prefer the higher-level chat hooks over accessing the socket directly.
</ResponseField>

<ResponseField name="connected" type="boolean">
  `true` when the socket is connected and ready to receive events.
</ResponseField>

## Notes

* For integration guidance, see [Chat: Real-time](/sdk/chat/real-time).


# Mark conversation as read
Source: https://docs.sublay.io/v7/hooks/chat/use-mark-conversation-as-read

Mark messages in a conversation as read up to a given message

## Overview

Returns an async function that marks a conversation as read up to a specific message. The unread count for the conversation is cleared in Redux immediately (optimistic update). The server is then notified to advance the user's `lastReadAt` timestamp.

<Note>Requires `ChatProvider` in the component tree.</Note>

## Usage Example

```tsx theme={null}
import { useMarkConversationAsRead } from "@sublay/react-js";
import { useEffect } from "react";

function ConversationView({
  conversationId,
  messages,
}: {
  conversationId: string;
  messages: { id: string }[];
}) {
  const mark = useMarkConversationAsRead({ conversationId });

  useEffect(() => {
    const lastMessage = messages[messages.length - 1];
    if (lastMessage) {
      mark({ messageId: lastMessage.id });
    }
  }, [messages]);

  // ...
}
```

## Props

<ParamField type="string">
  The ID of the conversation to mark as read.
</ParamField>

## Parameters

The hook returns a function. That function accepts:

<ParamField type="string">
  The ID of the message to mark as read up to. The server sets `lastReadAt` to this message's `createdAt`.
</ParamField>

## Returns

`Promise<void>`

## Notes

* The failure to mark as read on the server (e.g. network error) is non-critical. The local Redux count is already cleared and reconciles against the server on the next reconnect or `ChatProvider` mount.
* For integration guidance, see [Chat: Real-time](/sdk/chat/real-time).


# Use total unread count
Source: https://docs.sublay.io/v7/hooks/chat/use-total-unread-count

Get the total number of unread messages across all conversations

## Overview

Returns the total count of unread messages across all of the current user's conversations. This value is fetched from the server on `ChatProvider` mount and kept in sync via socket events as new messages arrive.

<Note>Requires `ChatProvider` in the component tree.</Note>

## Usage Example

```tsx theme={null}
import { useTotalUnreadCount } from "@sublay/react-js";

function ChatNavItem() {
  const unread = useTotalUnreadCount();

  return (
    <div className="relative">
      <ChatIcon />
      {unread > 0 && (
        <span className="badge">{unread > 99 ? "99+" : unread}</span>
      )}
    </div>
  );
}
```

## Returns

<ResponseField name="number" type="number">
  Total unread message count. Returns `0` before the first fetch completes.
</ResponseField>

## Notes

* This count is accurate before the conversation list is ever loaded — useful for showing a badge in navigation without requiring the user to visit the chat screen first.
* For integration guidance, see [Chat: Real-time](/sdk/chat/real-time).


# Use typing indicator
Source: https://docs.sublay.io/v7/hooks/chat/use-typing-indicator

Send and receive typing indicator events in a conversation

## Overview

Manages the typing indicator for a conversation. Returns the list of user IDs currently typing (for rendering a "Someone is typing..." indicator) and `startTyping`/`stopTyping` functions that emit the appropriate socket events.

<Note>Requires `ChatProvider` in the component tree.</Note>

## Usage Example

```tsx theme={null}
import { useTypingIndicator } from "@sublay/react-js";

function MessageInput({ conversationId }: { conversationId: string }) {
  const { typingUsers, startTyping, stopTyping } = useTypingIndicator({
    conversationId,
  });
  const [text, setText] = useState("");

  return (
    <div>
      {typingUsers.length > 0 && (
        <p className="text-sm text-gray-500">
          {typingUsers.length === 1
            ? "Someone is typing..."
            : `${typingUsers.length} people are typing...`}
        </p>
      )}
      <input
        value={text}
        onChange={(e) => {
          setText(e.target.value);
          startTyping();
        }}
        onBlur={stopTyping}
      />
    </div>
  );
}
```

## Props

<ParamField type="string">
  The ID of the conversation to track typing state for.
</ParamField>

## Returns

<ResponseField name="typingUsers" type="string[]">
  Array of user IDs currently typing in this conversation. The current user is always excluded.
</ResponseField>

<ResponseField name="startTyping" type="() => void">
  Emits a `typing:start` event to the server. Throttled internally — safe to call on every keystroke. Re-emits the keep-alive every 2 seconds while typing continues.
</ResponseField>

<ResponseField name="stopTyping" type="() => void">
  Emits a `typing:stop` event to the server and cancels the keep-alive interval. Call on message send, input clear, or blur.
</ResponseField>

## Notes

* `startTyping()` is idempotent while already typing — calling it repeatedly does not emit duplicate events; only the keep-alive timer re-emits every 2 seconds.
* On unmount, if the user was typing, `typing:stop` is emitted automatically to prevent a stale indicator on recipients' screens.
* Each typing user is auto-removed from `typingUsers` after 5 seconds of no keep-alive (handled by `ChatProvider`).
* For integration guidance, see [Chat: Real-time](/sdk/chat/real-time).


# Use unread conversation count
Source: https://docs.sublay.io/v7/hooks/chat/use-unread-conversation-count

Get the number of conversations with at least one unread message

## Overview

Returns the number of conversations that have at least one unread message. This value is fetched from the server on `ChatProvider` mount and kept in sync via socket events.

<Note>Requires `ChatProvider` in the component tree.</Note>

## Usage Example

```tsx theme={null}
import { useUnreadConversationCount } from "@sublay/react-js";

function InboxBadge() {
  const count = useUnreadConversationCount();

  return (
    <div>
      Inbox {count > 0 && <span>({count})</span>}
    </div>
  );
}
```

## Returns

<ResponseField name="number" type="number">
  Number of conversations with at least one unread message. Returns `0` before the first fetch completes.
</ResponseField>

## Notes

* When an event touches a conversation not currently loaded in the list (e.g. paginated out), this count reconciles automatically against the server's authoritative unread summary — no remount required. It also reconciles on socket reconnect.
* To get the total number of unread messages (not conversations), use [`useTotalUnreadCount`](/hooks/chat/use-total-unread-count).
* For integration guidance, see [Chat: Real-time](/sdk/chat/real-time).


# Use collection entities
Source: https://docs.sublay.io/v7/hooks/collections/use-collection-entities-wrapper

Fetch and paginate entities saved in a collection

## Overview

`useCollectionEntitiesWrapper` fetches the paginated list of entities saved in a collection. It supports multiple sort modes and infinite-scroll pagination via `loadMore`.

If no `collectionId` is passed, it defaults to the current collection from the Redux collections state (i.e., whatever `useCollections` is currently navigated to).

## Usage Example

```tsx theme={null}
import { useCollectionEntitiesWrapper } from "@sublay/react-js";

function SavedFeed({ collectionId }) {
  const {
    entities,
    loading,
    hasMore,
    sortBy,
    setSortBy,
    loadMore,
    refetch,
  } = useCollectionEntitiesWrapper({
    collectionId,
    defaultSortBy: "added",
    defaultSortDir: "desc",
    limit: 20,
  });

  return (
    <div>
      <select value={sortBy} onChange={(e) => setSortBy(e.target.value as any)}>
        <option value="added">Recently Added</option>
        <option value="new">Newest</option>
        <option value="top">Top Voted</option>
      </select>
      <ul>
        {entities.map((entity) => (
          <li key={entity.id}>{entity.title}</li>
        ))}
      </ul>
      {hasMore && (
        <button onClick={loadMore} disabled={loading}>
          Load more
        </button>
      )}
    </div>
  );
}
```

## Parameters

<ParamField type="string | null">
  The collection to fetch entities from. Defaults to the current collection in Redux state.
</ParamField>

<ParamField type="number">
  Number of entities per page. Default: `20`.
</ParamField>

<ParamField type="&#x22;new&#x22; | &#x22;top&#x22; | &#x22;hot&#x22; | &#x22;added&#x22;">
  Initial sort mode. Default: `"added"` (sorted by when the entity was saved).
</ParamField>

<ParamField type="&#x22;asc&#x22; | &#x22;desc&#x22;">
  Initial sort direction. Default: `"desc"`.
</ParamField>

<ParamField type="EntityIncludeParam">
  Optional associations to include with each entity: `"user"`, `"space"`, `"topComment"`, `"grants"`. (`"saved"` and `"files"` are not resolved on this endpoint.)
</ParamField>

## Returns

<ResponseField name="entities" type="Entity[]">
  The current list of fetched entities. Appended to on each `loadMore` call.
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` while fetching the initial page or loading more.
</ResponseField>

<ResponseField name="hasMore" type="boolean">
  `true` if additional pages are available.
</ResponseField>

<ResponseField name="sortBy" type="&#x22;new&#x22; | &#x22;top&#x22; | &#x22;hot&#x22; | &#x22;added&#x22;">
  Current sort mode.
</ResponseField>

<ResponseField name="sortDir" type="&#x22;asc&#x22; | &#x22;desc&#x22;">
  Current sort direction.
</ResponseField>

<ResponseField name="setSortBy" type="(sortBy: 'new' | 'top' | 'hot' | 'added') => void">
  Change the sort mode. Resets the entity list and re-fetches from page 1.
</ResponseField>

<ResponseField name="setSortDir" type="(sortDir: 'asc' | 'desc') => void">
  Change the sort direction. Resets the entity list and re-fetches from page 1.
</ResponseField>

<ResponseField name="loadMore" type="() => void">
  Load the next page of entities. Appends to the existing list.
</ResponseField>

<ResponseField name="refetch" type="() => void">
  Reset and re-fetch from page 1.
</ResponseField>

## Sort Modes

| Value   | Description                                           |
| ------- | ----------------------------------------------------- |
| `added` | Sorted by when the entity was added to the collection |
| `new`   | Sorted by entity creation date                        |
| `top`   | Sorted by vote count                                  |
| `hot`   | Sorted by hot score (engagement-based)                |


# Use collections
Source: https://docs.sublay.io/v7/hooks/collections/use-collections

Navigate the user's collection hierarchy and manage saved entities

## Overview

`useCollections` is the primary hook for working with a user's collection library. It automatically fetches the root collection on mount, loads sub-collections as you navigate deeper, and exposes actions for creating, updating, deleting, and saving entities.

<Note>Requires an authenticated user. The hook reads user and project context from the nearest `SublayProvider`.</Note>

## Usage Example

```tsx theme={null}
import { useCollections } from "@sublay/react-js";

function CollectionsPanel() {
  const {
    currentCollection,
    subCollections,
    loading,
    openCollection,
    goBack,
    createCollection,
    addToCollection,
  } = useCollections();

  if (loading) return <p>Loading...</p>;
  if (!currentCollection) return null;

  return (
    <div>
      <h2>{currentCollection.name}</h2>
      <ul>
        {subCollections.map((col) => (
          <li key={col.id} onClick={() => openCollection(col)}>
            {col.name}
          </li>
        ))}
      </ul>
      <button onClick={() => createCollection({ collectionName: "New Folder" })}>
        Add folder
      </button>
      {currentCollection.parentId && (
        <button onClick={goBack}>Back</button>
      )}
    </div>
  );
}
```

## Parameters

This hook accepts no required parameters. Pass an empty object or nothing.

## Returns

<ResponseField name="currentCollection" type="Collection | null">
  The collection currently being viewed. Starts as the root collection on mount.
</ResponseField>

<ResponseField name="subCollections" type="Collection[]">
  Direct child collections of `currentCollection`. Loaded automatically when `currentCollection` changes.
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` while fetching the root collection or sub-collections.
</ResponseField>

<ResponseField name="openCollection" type="(collection: Collection) => void">
  Navigate into a sub-collection. Pushes to the internal navigation stack and fetches its children.
</ResponseField>

<ResponseField name="goBack" type="() => void">
  Navigate to the previous collection in the stack.
</ResponseField>

<ResponseField name="goToRoot" type="() => void">
  Jump directly back to the root collection.
</ResponseField>

<ResponseField name="isEntitySaved" type="({ entityId, collectionId }: { entityId: string; collectionId?: string }) => Promise<{ saved: boolean; inSpecificCollection?: boolean; collections: Array<{ id: string; name: string }> }>">
  Check whether an entity is saved in any collection. If `collectionId` is provided, also returns `inSpecificCollection` indicating whether it is in that specific folder.
</ResponseField>

<ResponseField name="createCollection" type="({ collectionName }: CreateCollectionProps) => Promise<void>">
  Create a new sub-collection inside the current collection.
</ResponseField>

<ResponseField name="updateCollection" type="({ collectionId, update }: UpdateCollectionProps) => Promise<void>">
  Rename a collection. `update` accepts `{ name: string }`. The root collection cannot be renamed.
</ResponseField>

<ResponseField name="deleteCollection" type="({ collection }: DeleteCollectionProps) => Promise<void>">
  Delete a collection. The root collection cannot be deleted. Navigation automatically moves to the parent after deletion.
</ResponseField>

<ResponseField name="addToCollection" type="({ entityId }: AddToCollectionProps) => Promise<void>">
  Save an entity into the current collection.
</ResponseField>

<ResponseField name="removeFromCollection" type="({ entityId }: RemoveFromCollectionProps) => Promise<void>">
  Remove an entity from the current collection.
</ResponseField>

For a full integration guide, see [Managing Collections](/sdk/collections/managing-collections).


# Use collections actions
Source: https://docs.sublay.io/v7/hooks/collections/use-collections-actions

Low-level actions for fetching, creating, updating, and deleting collections

## Overview

`useCollectionsActions` exposes every collection action as a standalone callable function. It is used internally by `useCollections` but can also be used directly when you need fine-grained control over collection operations without the navigation state.

<Note>For most use cases, prefer `useCollections` — it combines these actions with navigation state. Use `useCollectionsActions` only when you need to perform actions independently of a navigation context.</Note>

## Usage Example

```tsx theme={null}
import { useCollectionsActions } from "@sublay/react-js";

function QuickSaveButton({ entityId, collectionId, projectId }) {
  const { addToCollection } = useCollectionsActions();

  return (
    <button onClick={() => addToCollection({ projectId, collectionId, entityId })}>
      Save
    </button>
  );
}
```

## Returns

### Navigation

<ResponseField name="openCollection" type="(collection: Collection) => void">
  Push a collection onto the Redux navigation stack.
</ResponseField>

<ResponseField name="goBack" type="() => void">
  Pop the current collection from the navigation stack.
</ResponseField>

<ResponseField name="goToRoot" type="() => void">
  Reset navigation to the root collection.
</ResponseField>

### Data Fetching

<ResponseField name="fetchRootCollection" type="({ projectId }: { projectId: string }) => Promise<void>">
  Fetch and set the user's root collection in Redux state.
</ResponseField>

<ResponseField name="fetchSubCollections" type="({ projectId, collectionId }: { projectId: string; collectionId: string }) => Promise<void>">
  Fetch sub-collections for a given collection and update Redux state.
</ResponseField>

### CRUD Operations

<ResponseField name="createCollection" type="({ projectId, parentCollectionId, collectionName }: ...) => Promise<void>">
  Create a new sub-collection under the specified parent collection. Navigates into the new collection after creation.
</ResponseField>

<ResponseField name="updateCollection" type="({ projectId, collectionId, update }: ...) => Promise<void>">
  Update a collection's `name`.
</ResponseField>

<ResponseField name="deleteCollection" type="({ projectId, collection }: ...) => Promise<void>">
  Delete a collection. Updates Redux state to navigate back to the parent.
</ResponseField>

<ResponseField name="addToCollection" type="({ projectId, collectionId, entityId }: ...) => Promise<void>">
  Add an entity to a collection by creating a junction table entry.
</ResponseField>

<ResponseField name="removeFromCollection" type="({ projectId, collectionId, entityId }: ...) => Promise<void>">
  Remove an entity from a collection.
</ResponseField>

### Utility

<ResponseField name="resetCollections" type="() => void">
  Clear all collections state from Redux (e.g., on sign-out).
</ResponseField>


# Accept connection
Source: https://docs.sublay.io/v7/hooks/connections/use-accept-connection

Accept a pending connection request by connection ID

## Overview

Returns a function that accepts a pending incoming connection request. The current user must be authenticated and must be the recipient of the request.

## Usage Example

```tsx theme={null}
import { useAcceptConnection } from "@sublay/react-js";

function PendingRequest({ connectionId }: { connectionId: string }) {
  const acceptConnection = useAcceptConnection();

  return (
    <button onClick={() => acceptConnection({ connectionId })}>
      Accept
    </button>
  );
}
```

## Parameters

The hook returns a function. That function accepts:

<ParamField type="string">
  The ID of the connection record to accept.
</ParamField>

## Returns

<ResponseField name="id" type="string">
  The connection record ID.
</ResponseField>

<ResponseField name="status" type="string">
  The updated status, e.g. `"connected"`.
</ResponseField>

<ResponseField name="respondedAt" type="string | undefined">
  ISO timestamp when the request was accepted.
</ResponseField>

## Related

* [useDeclineConnection](/hooks/connections/use-decline-connection) — decline instead of accept
* [useFetchReceivedPendingConnections](/hooks/connections/use-fetch-received-pending-connections) — list pending requests to accept


# Use connection manager
Source: https://docs.sublay.io/v7/hooks/connections/use-connection-manager

Manage connection state and actions between two users

## Overview

High-level hook that fetches the connection status between the current user and a target user on mount, then exposes named action functions for every state transition. The appropriate action for each state is enforced — only valid transitions can fire.

For integration guidance and a full example, see [Relationships — useConnectionManager](/sdk/relationships/use-connection-manager).

## Usage Example

```tsx theme={null}
import { useConnectionManager } from "@sublay/react-js";

function ConnectionControls({ userId }: { userId: string }) {
  const { connectionStatus, isLoading, sendConnectionRequest, acceptConnectionRequest } =
    useConnectionManager({ userId });

  if (isLoading) return null;
  if (connectionStatus === "none")
    return <button onClick={() => sendConnectionRequest()}>Connect</button>;
  if (connectionStatus === "pending-received")
    return <button onClick={acceptConnectionRequest}>Accept</button>;
  return null;
}
```

## Parameters

<ParamField type="string">
  The ID of the user whose connection relationship to manage.
</ParamField>

## Returns

<ResponseField name="connectionStatus" type="ConnectionStatus">
  One of: `"none"` | `"pending-sent"` | `"pending-received"` | `"connected"` | `"declined-sent"` | `"declined-received"`.
</ResponseField>

<ResponseField name="connectionId" type="string | null">
  The active connection record ID, or `null` if there is no connection.
</ResponseField>

<ResponseField name="connectionData" type="object">
  Metadata about the current connection state (timestamps, direction). See [useConnectionManager SDK page](/sdk/relationships/use-connection-manager) for full shape.
</ResponseField>

<ResponseField name="isLoading" type="boolean">
  `true` while the initial status is being fetched.
</ResponseField>

<ResponseField name="sendConnectionRequest" type="(message?: string) => Promise<void>">
  Sends a connection request. Only active when status is `"none"` or `"declined-received"`.
</ResponseField>

<ResponseField name="acceptConnectionRequest" type="() => Promise<void>">
  Accepts an incoming request. Only active when status is `"pending-received"`.
</ResponseField>

<ResponseField name="declineConnectionRequest" type="() => Promise<void>">
  Declines an incoming request. Only active when status is `"pending-received"`.
</ResponseField>

<ResponseField name="withdrawConnectionRequest" type="() => Promise<void>">
  Withdraws a sent request. Only active when status is `"pending-sent"`.
</ResponseField>

<ResponseField name="disconnectUser" type="() => Promise<void>">
  Removes an established connection. Only active when status is `"connected"`.
</ResponseField>

<ResponseField name="removeConnectionSmart" type="() => Promise<void>">
  Removes the connection in any state using the user ID (withdraw, disconnect, or decline depending on state).
</ResponseField>

<ResponseField name="refreshConnectionStatus" type="() => Promise<void>">
  Re-fetches connection status from the server.
</ResponseField>


# Decline connection
Source: https://docs.sublay.io/v7/hooks/connections/use-decline-connection

Decline a pending connection request by connection ID

## Overview

Returns a function that declines a pending incoming connection request. After declining, the connection status from the current user's perspective becomes `"declined-received"`. The current user must be authenticated and must be the recipient.

## Usage Example

```tsx theme={null}
import { useDeclineConnection } from "@sublay/react-js";

function PendingRequest({ connectionId }: { connectionId: string }) {
  const declineConnection = useDeclineConnection();

  return (
    <button onClick={() => declineConnection({ connectionId })}>
      Decline
    </button>
  );
}
```

## Parameters

The hook returns a function. That function accepts:

<ParamField type="string">
  The ID of the connection record to decline.
</ParamField>

## Returns

<ResponseField name="id" type="string">
  The connection record ID.
</ResponseField>

<ResponseField name="status" type="string">
  The updated status, e.g. `"declined"`.
</ResponseField>

<ResponseField name="respondedAt" type="string | undefined">
  ISO timestamp when the request was declined.
</ResponseField>

## Related

* [useAcceptConnection](/hooks/connections/use-accept-connection) — accept instead of decline
* [useFetchReceivedPendingConnections](/hooks/connections/use-fetch-received-pending-connections) — list pending requests


# Fetch connection status
Source: https://docs.sublay.io/v7/hooks/connections/use-fetch-connection-status

Check the connection status between the current user and another user

## Overview

Returns a function that fetches the full connection status between the current authenticated user and a target user. Returns a discriminated union based on the current state: `"none"`, `"pending"`, `"connected"`, or `"declined"`.

`useConnectionManager` calls this automatically on mount. Use this hook directly when you need one-off status checks without managing state.

## Usage Example

```tsx theme={null}
import { useFetchConnectionStatus } from "@sublay/react-js";

function ProfilePage({ userId }: { userId: string }) {
  const fetchConnectionStatus = useFetchConnectionStatus();

  useEffect(() => {
    fetchConnectionStatus({ userId }).then((status) => {
      console.log(status.status); // "none" | "pending" | "connected" | "declined"
    });
  }, [userId]);
}
```

## Parameters

The hook returns a function. That function accepts:

<ParamField type="string">
  The ID of the user to check. Cannot be the current user's own ID.
</ParamField>

## Returns

Returns a `ConnectionStatusResponse` — a discriminated union based on `status`:

**When `status === "none"`:**

<ResponseField name="status" type="&#x22;none&#x22;">
  No connection exists.
</ResponseField>

**When `status === "pending"`:**

<ResponseField name="status" type="&#x22;pending&#x22;">
  A connection request is pending.
</ResponseField>

<ResponseField name="type" type="&#x22;sent&#x22; | &#x22;received&#x22;">
  Direction from the current user's perspective.
</ResponseField>

<ResponseField name="connectionId" type="string">
  The connection record ID.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO timestamp when the request was created.
</ResponseField>

**When `status === "connected"`:**

<ResponseField name="status" type="&#x22;connected&#x22;">
  Connection is established.
</ResponseField>

<ResponseField name="connectionId" type="string">
  The connection record ID.
</ResponseField>

<ResponseField name="connectedAt" type="string">
  ISO timestamp when the connection was established.
</ResponseField>

<ResponseField name="requestedAt" type="string">
  ISO timestamp when the request was originally sent.
</ResponseField>

**When `status === "declined"`:**

<ResponseField name="status" type="&#x22;declined&#x22;">
  A connection request was declined.
</ResponseField>

<ResponseField name="type" type="&#x22;sent&#x22; | &#x22;received&#x22;">
  Direction of the original request.
</ResponseField>

<ResponseField name="connectionId" type="string">
  The connection record ID.
</ResponseField>

<ResponseField name="respondedAt" type="string">
  ISO timestamp when the request was declined.
</ResponseField>

## Related

* [useConnectionManager](/hooks/connections/use-connection-manager) — loads this status automatically


# Fetch connections
Source: https://docs.sublay.io/v7/hooks/connections/use-fetch-connections

Fetch the current user's accepted connections with pagination

## Overview

Returns a function that fetches the paginated list of accepted connections for the currently authenticated user. Each entry includes the connected user's profile and timestamps.

For fetching another user's connections, see `useFetchConnectionsByUserId`.

<Note>
  Users with a block between them and you, in either direction, are excluded
  from the results. Requires the `moderation` bundle.
</Note>

## Usage Example

```tsx theme={null}
import { useFetchConnections } from "@sublay/react-js";

function ConnectionsList() {
  const fetchConnections = useFetchConnections();
  const [connections, setConnections] = useState([]);

  useEffect(() => {
    fetchConnections({ page: 1, limit: 20 }).then((res) => {
      setConnections(res.data);
    });
  }, []);

  return (
    <ul>
      {connections.map(({ id, connectedUser }) => (
        <li key={id}>{connectedUser.name}</li>
      ))}
    </ul>
  );
}
```

## Parameters

The hook returns a function. That function accepts:

<ParamField type="number">
  Page number to fetch. Defaults to `1`.
</ParamField>

<ParamField type="number">
  Number of results per page. Defaults to `20`.
</ParamField>

<ParamField type="string">
  Optional search term. Filters the list to connections whose connected user's username or name contains this text (case-insensitive). When omitted, no filtering is applied.
</ParamField>

<ParamField type="string">
  Restricts which field `query` matches against — `username` or `name`. When omitted, `query` matches either field.
</ParamField>

## Returns

Returns a `PaginatedResponse` containing an array of established connections:

<ResponseField name="data" type="EstablishedConnection[]">
  Array of accepted connection entries.

  <Expandable title="EstablishedConnection properties">
    <ResponseField name="id" type="string">
      ID of the connection record.
    </ResponseField>

    <ResponseField name="connectedUser" type="User">
      The other user's profile. See [User data model](/data-models/user).
    </ResponseField>

    <ResponseField name="connectedAt" type="string">
      ISO timestamp when the connection was established.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination metadata including `page`, `pageSize`, `totalPages`, `totalItems`, and `hasMore`.
</ResponseField>

## Related

* [useFetchConnectionsByUserId](/hooks/connections/use-fetch-connections-by-user-id) — fetch another user's connections
* [useFetchConnectionsCount](/hooks/connections/use-fetch-connections-count) — get total connection count


# Fetch connections by user ID
Source: https://docs.sublay.io/v7/hooks/connections/use-fetch-connections-by-user-id

Fetch accepted connections for any user by their ID

## Overview

Returns a function that fetches the paginated list of accepted connections for any user, identified by `userId`. Authentication is optional — the endpoint works without a token. When the caller is signed in, any user with a block between them and the caller, in either direction, is excluded from the results. Block filtering requires the `moderation` bundle.

For fetching your own connections, see `useFetchConnections`.

## Usage Example

```tsx theme={null}
import { useFetchConnectionsByUserId } from "@sublay/react-js";

function UserConnections({ userId }: { userId: string }) {
  const fetchConnectionsByUserId = useFetchConnectionsByUserId();
  const [connections, setConnections] = useState([]);

  useEffect(() => {
    fetchConnectionsByUserId({ userId, page: 1 }).then((res) => {
      setConnections(res.data);
    });
  }, [userId]);

  return (
    <ul>
      {connections.map(({ id, connectedUser }) => (
        <li key={id}>{connectedUser.name}</li>
      ))}
    </ul>
  );
}
```

## Parameters

The hook returns a function. That function accepts:

<ParamField type="string">
  The ID of the user whose connections to fetch.
</ParamField>

<ParamField type="number">
  Page number to fetch. Defaults to `1`.
</ParamField>

<ParamField type="number">
  Number of results per page. Defaults to `20`.
</ParamField>

<ParamField type="string">
  Optional search term. Filters the list to connections whose connected user's username or name contains this text (case-insensitive). When omitted, no filtering is applied.
</ParamField>

<ParamField type="string">
  Restricts which field `query` matches against — `username` or `name`. When omitted, `query` matches either field.
</ParamField>

<SpaceReputationParams />

## Returns

Returns a `PaginatedResponse` containing an array of established connections:

<ResponseField name="data" type="EstablishedConnection[]">
  Array of accepted connection entries.

  <Expandable title="EstablishedConnection properties">
    <ResponseField name="id" type="string">
      ID of the connection record.
    </ResponseField>

    <ResponseField name="connectedUser" type="User">
      The other user's profile. When `spaceReputation` is requested, it carries an added `spaceReputation` number. See [User data model](/data-models/user) and [Reputation](/data-models/reputation).
    </ResponseField>

    <ResponseField name="connectedAt" type="string">
      ISO timestamp when the connection was established.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination metadata including `page`, `pageSize`, `totalPages`, `totalItems`, and `hasMore`.
</ResponseField>

## Related

* [useFetchConnections](/hooks/connections/use-fetch-connections) — fetch the current user's own connections
* [useFetchConnectionsCountByUserId](/hooks/connections/use-fetch-connections-count-by-user-id) — get count for any user


# Fetch connections count
Source: https://docs.sublay.io/v7/hooks/connections/use-fetch-connections-count

Get the total number of accepted connections for the current user

## Overview

Returns a function that fetches the total count of accepted connections for the currently authenticated user.

<Note>
  Users with a block between them and you, in either direction, are excluded
  from the count. Requires the `moderation` bundle.
</Note>

## Usage Example

```tsx theme={null}
import { useFetchConnectionsCount } from "@sublay/react-js";

function ConnectionCount() {
  const fetchConnectionsCount = useFetchConnectionsCount();
  const [count, setCount] = useState<number | null>(null);

  useEffect(() => {
    fetchConnectionsCount().then((res) => setCount(res.count));
  }, []);

  return <span>{count ?? "..."} connections</span>;
}
```

## Parameters

The hook returns a function that takes no parameters.

## Returns

<ResponseField name="count" type="number">
  Total number of accepted connections for the current user.
</ResponseField>

## Related

* [useFetchConnectionsCountByUserId](/hooks/connections/use-fetch-connections-count-by-user-id) — get count for any user
* [useFetchConnections](/hooks/connections/use-fetch-connections) — fetch the full list


# Fetch connections count by user ID
Source: https://docs.sublay.io/v7/hooks/connections/use-fetch-connections-count-by-user-id

Get the connection count for any user by their ID

## Overview

Returns a function that fetches the total number of accepted connections for any user, identified by `userId`. Authentication is optional — the endpoint works without a token. When the caller is signed in, any user with a block between them and the caller, in either direction, is excluded from the count. Block filtering requires the `moderation` bundle.

## Usage Example

```tsx theme={null}
import { useFetchConnectionsCountByUserId } from "@sublay/react-js";

function UserStats({ userId }: { userId: string }) {
  const fetchConnectionsCountByUserId = useFetchConnectionsCountByUserId();
  const [count, setCount] = useState<number | null>(null);

  useEffect(() => {
    fetchConnectionsCountByUserId({ userId }).then((res) => setCount(res.count));
  }, [userId]);

  return <span>{count ?? "..."} connections</span>;
}
```

## Parameters

The hook returns a function. That function accepts:

<ParamField type="string">
  The ID of the user whose connection count to fetch.
</ParamField>

## Returns

<ResponseField name="count" type="number">
  Total number of accepted connections for the specified user.
</ResponseField>

## Related

* [useFetchConnectionsCount](/hooks/connections/use-fetch-connections-count) — get count for the current user
* [useFetchConnectionsByUserId](/hooks/connections/use-fetch-connections-by-user-id) — fetch the full list


# Fetch received pending connections
Source: https://docs.sublay.io/v7/hooks/connections/use-fetch-received-pending-connections

Fetch connection requests received by the current user that are still pending

## Overview

Returns a function that fetches the paginated list of connection requests that other users have sent to the current authenticated user and that have not yet been accepted or declined.

<Note>
  Users with a block between them and you, in either direction, are excluded
  from the results. Requires the `moderation` bundle.
</Note>

## Usage Example

```tsx theme={null}
import { useFetchReceivedPendingConnections } from "@sublay/react-js";
import { useAcceptConnection } from "@sublay/react-js";

function IncomingRequests() {
  const fetchReceivedPendingConnections = useFetchReceivedPendingConnections();
  const acceptConnection = useAcceptConnection();
  const [requests, setRequests] = useState([]);

  useEffect(() => {
    fetchReceivedPendingConnections({ page: 1 }).then((res) => {
      setRequests(res.data);
    });
  }, []);

  return (
    <ul>
      {requests.map(({ id, user }) => (
        <li key={id}>
          {user.name} wants to connect
          <button onClick={() => acceptConnection({ connectionId: id })}>Accept</button>
        </li>
      ))}
    </ul>
  );
}
```

## Parameters

The hook returns a function. That function accepts:

<ParamField type="number">
  Page number to fetch. Defaults to `1`.
</ParamField>

<ParamField type="number">
  Number of results per page. Defaults to `20`.
</ParamField>

## Returns

Returns a `PaginatedResponse` containing pending connection entries:

<ResponseField name="data" type="PendingConnection[]">
  Array of pending connection entries.

  <Expandable title="PendingConnection properties">
    <ResponseField name="id" type="string">
      ID of the connection record.
    </ResponseField>

    <ResponseField name="user" type="User">
      The user who sent the request. See [User data model](/data-models/user).
    </ResponseField>

    <ResponseField name="type" type="&#x22;received&#x22;">
      Always `"received"` for this endpoint.
    </ResponseField>

    <ResponseField name="message" type="string | undefined">
      Optional message included with the request.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO timestamp when the request was created.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination metadata including `page`, `pageSize`, `totalPages`, `totalItems`, and `hasMore`.
</ResponseField>

## Related

* [useFetchSentPendingConnections](/hooks/connections/use-fetch-sent-pending-connections) — outgoing requests
* [useAcceptConnection](/hooks/connections/use-accept-connection) — accept a received request
* [useDeclineConnection](/hooks/connections/use-decline-connection) — decline a received request


# Fetch sent pending connections
Source: https://docs.sublay.io/v7/hooks/connections/use-fetch-sent-pending-connections

Fetch connection requests sent by the current user that are still pending

## Overview

Returns a function that fetches the paginated list of connection requests the current authenticated user has sent that have not yet been accepted or declined.

<Note>
  Users with a block between them and you, in either direction, are excluded
  from the results. Requires the `moderation` bundle.
</Note>

## Usage Example

```tsx theme={null}
import { useFetchSentPendingConnections } from "@sublay/react-js";

function SentRequests() {
  const fetchSentPendingConnections = useFetchSentPendingConnections();
  const [requests, setRequests] = useState([]);

  useEffect(() => {
    fetchSentPendingConnections({ page: 1 }).then((res) => {
      setRequests(res.data);
    });
  }, []);

  return (
    <ul>
      {requests.map(({ id, user }) => (
        <li key={id}>Pending request to {user.name}</li>
      ))}
    </ul>
  );
}
```

## Parameters

The hook returns a function. That function accepts:

<ParamField type="number">
  Page number to fetch. Defaults to `1`.
</ParamField>

<ParamField type="number">
  Number of results per page. Defaults to `20`.
</ParamField>

## Returns

Returns a `PaginatedResponse` containing pending connection entries:

<ResponseField name="data" type="PendingConnection[]">
  Array of pending connection entries.

  <Expandable title="PendingConnection properties">
    <ResponseField name="id" type="string">
      ID of the connection record.
    </ResponseField>

    <ResponseField name="user" type="User">
      The user the request was sent to. See [User data model](/data-models/user).
    </ResponseField>

    <ResponseField name="type" type="&#x22;sent&#x22;">
      Always `"sent"` for this endpoint.
    </ResponseField>

    <ResponseField name="message" type="string | undefined">
      Optional message included with the request.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO timestamp when the request was created.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination metadata including `page`, `pageSize`, `totalPages`, `totalItems`, and `hasMore`.
</ResponseField>

## Related

* [useFetchReceivedPendingConnections](/hooks/connections/use-fetch-received-pending-connections) — incoming requests
* [useRemoveConnection](/hooks/connections/use-remove-connection) — withdraw a sent request


# Remove connection
Source: https://docs.sublay.io/v7/hooks/connections/use-remove-connection

Remove a connection or withdraw a pending request by connection ID

## Overview

Returns a function that deletes a connection record by its `connectionId`. This works for both withdrawing a pending sent request and disconnecting an established connection. The current user must be authenticated.

If you don't have the connection ID, use `useRemoveConnectionByUserId` instead.

## Usage Example

```tsx theme={null}
import { useRemoveConnection } from "@sublay/react-js";

function DisconnectButton({ connectionId }: { connectionId: string }) {
  const removeConnection = useRemoveConnection();

  return (
    <button onClick={() => removeConnection({ connectionId })}>
      Disconnect
    </button>
  );
}
```

## Parameters

The hook returns a function. That function accepts:

<ParamField type="string">
  The ID of the connection record to remove.
</ParamField>

## Returns

<ResponseField name="message" type="string">
  A confirmation message.
</ResponseField>

## Related

* [useRemoveConnectionByUserId](/hooks/connections/use-remove-connection-by-user-id) — remove by user ID instead
* [useFetchConnections](/hooks/connections/use-fetch-connections) — returns `id` on each connection entry


# Remove connection by user ID
Source: https://docs.sublay.io/v7/hooks/connections/use-remove-connection-by-user-id

Remove a connection with a user by their user ID

## Overview

Returns a function that removes a connection with another user by their `userId`, without needing the connection record ID. The server determines the correct action (withdraw, disconnect, or decline) based on the current state. The current user must be authenticated.

<Note>
  This hook is used internally by `useConnectionManager`'s `removeConnectionSmart` function.
</Note>

## Usage Example

```tsx theme={null}
import { useRemoveConnectionByUserId } from "@sublay/react-js";

function RemoveButton({ userId }: { userId: string }) {
  const removeConnectionByUserId = useRemoveConnectionByUserId();

  return (
    <button onClick={() => removeConnectionByUserId({ userId })}>
      Remove Connection
    </button>
  );
}
```

## Parameters

The hook returns a function. That function accepts:

<ParamField type="string">
  The ID of the user to disconnect from. Cannot be the current user's own ID.
</ParamField>

## Returns

<ResponseField name="id" type="string | undefined">
  The connection record ID, if applicable.
</ResponseField>

<ResponseField name="action" type="&#x22;withdraw&#x22; | &#x22;disconnect&#x22; | &#x22;decline&#x22; | undefined">
  The action performed by the server.
</ResponseField>

<ResponseField name="message" type="string | undefined">
  A confirmation message.
</ResponseField>

## Related

* [useRemoveConnection](/hooks/connections/use-remove-connection) — remove by connection ID
* [useConnectionManager](/hooks/connections/use-connection-manager) — wraps this as `removeConnectionSmart`


# Request connection
Source: https://docs.sublay.io/v7/hooks/connections/use-request-connection

Send a connection request to a user

## Overview

Returns a function that sends a connection request to another user. An optional message can be included with the request. The current user must be authenticated.

## Usage Example

```tsx theme={null}
import { useRequestConnection } from "@sublay/react-js";

function ConnectButton({ userId }: { userId: string }) {
  const requestConnection = useRequestConnection();

  const handleConnect = async () => {
    const result = await requestConnection({ userId, message: "Let's connect!" });
    console.log("Request sent:", result.id);
  };

  return <button onClick={handleConnect}>Connect</button>;
}
```

## Parameters

The hook returns a function. That function accepts:

<ParamField type="string">
  The ID of the user to send a connection request to.
</ParamField>

<ParamField type="string">
  An optional message to include with the connection request.
</ParamField>

## Returns

<ResponseField name="id" type="string">
  The ID of the newly created connection record.
</ResponseField>

<ResponseField name="status" type="string">
  The status of the connection, e.g. `"pending"`.
</ResponseField>

<ResponseField name="createdAt" type="string | undefined">
  ISO timestamp when the request was created.
</ResponseField>

## Related

* [useConnectionManager](/hooks/connections/use-connection-manager) — handles this with state tracking
* [useAcceptConnection](/hooks/connections/use-accept-connection) — for the recipient to accept


# Sign testing JWT
Source: https://docs.sublay.io/v7/hooks/crypto/use-sign-testing-jwt

Generate a signed JWT for testing external auth — development only

## Overview

Returns a function that calls the Sublay API to sign a JWT using your project's private key. This is intended **exclusively for development and testing** of external authentication flows — it lets you generate valid user JWTs from the client without setting up a backend.

<Warning>
  **Never use this hook in production.** Calling this function exposes your project's private key in client-side code, which is a critical security vulnerability. In production, JWT signing must happen on your backend server. See the [External Authentication](/sdk/authentication/external) guide.
</Warning>

## Usage Example

```tsx theme={null}
import { useSignTestingJwt } from "@sublay/react-js";
import { useAuth } from "@sublay/react-js";

function DevAuthHelper() {
  const signTestingJwt = useSignTestingJwt();
  const { signInWithToken } = useAuth();

  const signInAsTestUser = async () => {
    const token = await signTestingJwt({
      projectId: "your-project-id",
      privateKey: "your-private-key", // ⚠️ Development only
      userData: {
        id: "external-user-123",
        name: "Test User",
        email: "test@example.com",
      },
    });

    if (token) {
      await signInWithToken(token);
    }
  };

  return <button onClick={signInAsTestUser}>Sign in as test user</button>;
}
```

## Parameters

<ParamField type="string">
  Your Sublay project ID.
</ParamField>

<ParamField type="string">
  Your project's private key, used to sign the JWT. This key is available in your Sublay dashboard. **Never expose this in production code.**
</ParamField>

<ParamField type="object">
  The user data to encode in the JWT payload. Must include `id` (the external user's identifier). Additional fields are passed through as custom claims.

  ```ts theme={null}
  {
    id: string;           // Required: external user identifier
    [key: string]: any;   // Optional: name, email, avatar, etc.
  }
  ```
</ParamField>

## Returns

Returns `Promise<string | undefined>`. On success, resolves to a signed JWT string that can be passed to the external auth sign-in flow.

## Notes

* The function logs a console warning each time it is called as a reminder that it is not for production use.
* Use the returned token with the external authentication flow described in [External Authentication](/sdk/authentication/external).


# Fetch follow status
Source: https://docs.sublay.io/v7/hooks/follows/use-fetch-follow-status

Check whether the current user follows a specific user

## Overview

Returns a function that checks whether the current authenticated user follows a given `userId`. Returns a status object including the follow ID and timestamp if following.

## Usage Example

```tsx theme={null}
import { useFetchFollowStatus } from "@sublay/react-js";

function ProfilePage({ userId }: { userId: string }) {
  const fetchFollowStatus = useFetchFollowStatus();

  useEffect(() => {
    fetchFollowStatus({ userId }).then((status) => {
      console.log(status.isFollowing, status.followId);
    });
  }, [userId]);
}
```

## Parameters

The hook returns a function. That function accepts:

<ParamField type="string">
  The ID of the user to check. Cannot be the current user's own ID.
</ParamField>

## Returns

<ResponseField name="isFollowing" type="boolean">
  Whether the current user is following the target user.
</ResponseField>

<ResponseField name="followId" type="string | undefined">
  The ID of the follow record. Present when `isFollowing` is `true`.
</ResponseField>

<ResponseField name="followedAt" type="string | undefined">
  ISO timestamp of when the follow was created. Present when `isFollowing` is `true`.
</ResponseField>

## Related

* [useFollowManager](/hooks/follows/use-follow-manager) — loads this status automatically on mount


# Fetch followers
Source: https://docs.sublay.io/v7/hooks/follows/use-fetch-followers

Fetch the current user's followers with pagination

## Overview

Returns a function that fetches the paginated list of users who follow the currently authenticated user. Each entry includes the follow record ID, the follower's user profile, and the timestamp.

For fetching another user's followers, see `useFetchFollowersByUserId`.

<Note>
  Users with a block between them and you, in either direction, are excluded
  from the results. Requires the `moderation` bundle.
</Note>

## Usage Example

```tsx theme={null}
import { useFetchFollowers } from "@sublay/react-js";

function FollowersList() {
  const fetchFollowers = useFetchFollowers();
  const [followers, setFollowers] = useState([]);

  useEffect(() => {
    fetchFollowers({ page: 1, limit: 20 }).then((res) => {
      setFollowers(res.data);
    });
  }, []);

  return (
    <ul>
      {followers.map(({ followId, user }) => (
        <li key={followId}>{user.name}</li>
      ))}
    </ul>
  );
}
```

## Parameters

The hook returns a function. That function accepts:

<ParamField type="number">
  Page number to fetch. Defaults to `1`.
</ParamField>

<ParamField type="number">
  Number of results per page. Defaults to `20`.
</ParamField>

<ParamField type="string">
  Optional search term. Filters the list to users whose username or name contains this text (case-insensitive). When omitted, no filtering is applied.
</ParamField>

<ParamField type="string">
  Restricts which field `query` matches against — `username` or `name`. When omitted, `query` matches either field.
</ParamField>

## Returns

Returns a `PaginatedResponse` containing an array of follower entries:

<ResponseField name="data" type="FollowerWithFollowInfo[]">
  Array of follower entries.

  <Expandable title="FollowerWithFollowInfo properties">
    <ResponseField name="followId" type="string">
      ID of the follow record.
    </ResponseField>

    <ResponseField name="user" type="User">
      The follower's user profile. See [User data model](/data-models/user).
    </ResponseField>

    <ResponseField name="followedAt" type="string">
      ISO timestamp of when the follow was created.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination metadata including `currentPage`, `totalPages`, `totalCount`, `hasNextPage`, and `hasPreviousPage`.
</ResponseField>

## Related

* [useFetchFollowersByUserId](/hooks/follows/use-fetch-followers-by-user-id) — fetch another user's followers
* [useFetchFollowersCount](/hooks/follows/use-fetch-followers-count) — get total follower count


# Fetch followers by user ID
Source: https://docs.sublay.io/v7/hooks/follows/use-fetch-followers-by-user-id

Fetch the followers of any user by their ID

## Overview

Returns a function that fetches the paginated list of followers for any user, identified by `userId`. Authentication is optional — the endpoint works without a token. When the caller is signed in, any user with a block between them and the caller, in either direction, is excluded from the results. Block filtering requires the `moderation` bundle.

For fetching your own followers, see `useFetchFollowers`.

## Usage Example

```tsx theme={null}
import { useFetchFollowersByUserId } from "@sublay/react-js";

function UserFollowers({ userId }: { userId: string }) {
  const fetchFollowersByUserId = useFetchFollowersByUserId();
  const [followers, setFollowers] = useState([]);

  useEffect(() => {
    fetchFollowersByUserId({ userId, page: 1 }).then((res) => {
      setFollowers(res.data);
    });
  }, [userId]);

  return (
    <ul>
      {followers.map(({ followId, user }) => (
        <li key={followId}>{user.name}</li>
      ))}
    </ul>
  );
}
```

## Parameters

The hook returns a function. That function accepts:

<ParamField type="string">
  The ID of the user whose followers to fetch.
</ParamField>

<ParamField type="number">
  Page number to fetch. Defaults to `1`.
</ParamField>

<ParamField type="number">
  Number of results per page. Defaults to `20`.
</ParamField>

<ParamField type="string">
  Optional search term. Filters the list to users whose username or name contains this text (case-insensitive). When omitted, no filtering is applied.
</ParamField>

<ParamField type="string">
  Restricts which field `query` matches against — `username` or `name`. When omitted, `query` matches either field.
</ParamField>

<SpaceReputationParams />

## Returns

Returns a `PaginatedResponse` containing an array of follower entries:

<ResponseField name="data" type="FollowerWithFollowInfo[]">
  Array of follower entries.

  <Expandable title="FollowerWithFollowInfo properties">
    <ResponseField name="followId" type="string">
      ID of the follow record.
    </ResponseField>

    <ResponseField name="user" type="User">
      The follower's user profile. When `spaceReputation` is requested, it carries an added `spaceReputation` number. See [User data model](/data-models/user) and [Reputation](/data-models/reputation).
    </ResponseField>

    <ResponseField name="followedAt" type="string">
      ISO timestamp of when the follow was created.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination metadata including `currentPage`, `totalPages`, `totalCount`, `hasNextPage`, and `hasPreviousPage`.
</ResponseField>

## Related

* [useFetchFollowers](/hooks/follows/use-fetch-followers) — fetch the current user's own followers
* [useFetchFollowersCountByUserId](/hooks/follows/use-fetch-followers-count-by-user-id) — get follower count for a user


# Fetch followers count
Source: https://docs.sublay.io/v7/hooks/follows/use-fetch-followers-count

Get the total number of followers for the current user

## Overview

Returns a function that fetches the total follower count of the currently authenticated user.

For getting another user's follower count, see `useFetchFollowersCountByUserId`.

<Note>
  Users with a block between them and you, in either direction, are excluded
  from the count. Requires the `moderation` bundle.
</Note>

## Usage Example

```tsx theme={null}
import { useFetchFollowersCount } from "@sublay/react-js";

function FollowerCount() {
  const fetchFollowersCount = useFetchFollowersCount();
  const [count, setCount] = useState<number | null>(null);

  useEffect(() => {
    fetchFollowersCount().then((res) => setCount(res.count));
  }, []);

  return <span>{count ?? "..."} followers</span>;
}
```

## Parameters

The hook returns a function that takes no parameters.

## Returns

<ResponseField name="count" type="number">
  Total number of users following the current user.
</ResponseField>

## Related

* [useFetchFollowersCountByUserId](/hooks/follows/use-fetch-followers-count-by-user-id) — get count for any user
* [useFetchFollowers](/hooks/follows/use-fetch-followers) — fetch the full list


# Fetch followers count by user ID
Source: https://docs.sublay.io/v7/hooks/follows/use-fetch-followers-count-by-user-id

Get the total follower count for any user by their ID

## Overview

Returns a function that fetches the total follower count of any user, identified by `userId`. Authentication is optional — the endpoint works without a token. When the caller is signed in, any user with a block between them and the caller, in either direction, is excluded from the count. Block filtering requires the `moderation` bundle.

## Usage Example

```tsx theme={null}
import { useFetchFollowersCountByUserId } from "@sublay/react-js";

function UserStats({ userId }: { userId: string }) {
  const fetchFollowersCountByUserId = useFetchFollowersCountByUserId();
  const [count, setCount] = useState<number | null>(null);

  useEffect(() => {
    fetchFollowersCountByUserId({ userId }).then((res) => setCount(res.count));
  }, [userId]);

  return <span>{count ?? "..."} followers</span>;
}
```

## Parameters

The hook returns a function. That function accepts:

<ParamField type="string">
  The ID of the user whose follower count to fetch.
</ParamField>

## Returns

<ResponseField name="count" type="number">
  Total number of followers for the specified user.
</ResponseField>

## Related

* [useFetchFollowersCount](/hooks/follows/use-fetch-followers-count) — get count for the current user
* [useFetchFollowersByUserId](/hooks/follows/use-fetch-followers-by-user-id) — fetch the full list


# Fetch following
Source: https://docs.sublay.io/v7/hooks/follows/use-fetch-following

Fetch the list of users the current user is following

## Overview

Returns a function that fetches the paginated list of users the currently authenticated user follows. Each entry includes the follow record ID, the followed user's profile, and the timestamp.

For fetching another user's following list, see `useFetchFollowingByUserId`.

<Note>
  Users with a block between them and you, in either direction, are excluded
  from the results. Requires the `moderation` bundle.
</Note>

## Usage Example

```tsx theme={null}
import { useFetchFollowing } from "@sublay/react-js";

function FollowingList() {
  const fetchFollowing = useFetchFollowing();
  const [following, setFollowing] = useState([]);

  useEffect(() => {
    fetchFollowing({ page: 1, limit: 20 }).then((res) => {
      setFollowing(res.data);
    });
  }, []);

  return (
    <ul>
      {following.map(({ followId, user }) => (
        <li key={followId}>{user.name}</li>
      ))}
    </ul>
  );
}
```

## Parameters

The hook returns a function. That function accepts:

<ParamField type="number">
  Page number to fetch. Defaults to `1`.
</ParamField>

<ParamField type="number">
  Number of results per page. Defaults to `20`.
</ParamField>

<ParamField type="string">
  Optional search term. Filters the list to users whose username or name contains this text (case-insensitive). When omitted, no filtering is applied.
</ParamField>

<ParamField type="string">
  Restricts which field `query` matches against — `username` or `name`. When omitted, `query` matches either field.
</ParamField>

## Returns

Returns a `PaginatedResponse` containing an array of following entries:

<ResponseField name="data" type="FollowingWithFollowInfo[]">
  Array of following entries.

  <Expandable title="FollowingWithFollowInfo properties">
    <ResponseField name="followId" type="string">
      ID of the follow record.
    </ResponseField>

    <ResponseField name="user" type="User">
      The followed user's profile. See [User data model](/data-models/user).
    </ResponseField>

    <ResponseField name="followedAt" type="string">
      ISO timestamp of when the follow was created.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination metadata including `currentPage`, `totalPages`, `totalCount`, `hasNextPage`, and `hasPreviousPage`.
</ResponseField>

## Related

* [useFetchFollowingByUserId](/hooks/follows/use-fetch-following-by-user-id) — fetch another user's following list
* [useFetchFollowingCount](/hooks/follows/use-fetch-following-count) — get total following count


# Fetch following by user ID
Source: https://docs.sublay.io/v7/hooks/follows/use-fetch-following-by-user-id

Fetch the following list for any user by their ID

## Overview

Returns a function that fetches the paginated list of users that a given user follows, identified by `userId`. Authentication is optional — the endpoint works without a token. When the caller is signed in, any user with a block between them and the caller, in either direction, is excluded from the results. Block filtering requires the `moderation` bundle.

For fetching your own following list, see `useFetchFollowing`.

## Usage Example

```tsx theme={null}
import { useFetchFollowingByUserId } from "@sublay/react-js";

function UserFollowing({ userId }: { userId: string }) {
  const fetchFollowingByUserId = useFetchFollowingByUserId();
  const [following, setFollowing] = useState([]);

  useEffect(() => {
    fetchFollowingByUserId({ userId, page: 1 }).then((res) => {
      setFollowing(res.data);
    });
  }, [userId]);

  return (
    <ul>
      {following.map(({ followId, user }) => (
        <li key={followId}>{user.name}</li>
      ))}
    </ul>
  );
}
```

## Parameters

The hook returns a function. That function accepts:

<ParamField type="string">
  The ID of the user whose following list to fetch.
</ParamField>

<ParamField type="number">
  Page number to fetch. Defaults to `1`.
</ParamField>

<ParamField type="number">
  Number of results per page. Defaults to `20`.
</ParamField>

<ParamField type="string">
  Optional search term. Filters the list to users whose username or name contains this text (case-insensitive). When omitted, no filtering is applied.
</ParamField>

<ParamField type="string">
  Restricts which field `query` matches against — `username` or `name`. When omitted, `query` matches either field.
</ParamField>

<SpaceReputationParams />

## Returns

Returns a `PaginatedResponse` containing an array of following entries:

<ResponseField name="data" type="FollowingWithFollowInfo[]">
  Array of following entries.

  <Expandable title="FollowingWithFollowInfo properties">
    <ResponseField name="followId" type="string">
      ID of the follow record.
    </ResponseField>

    <ResponseField name="user" type="User">
      The followed user's profile. When `spaceReputation` is requested, it carries an added `spaceReputation` number. See [User data model](/data-models/user) and [Reputation](/data-models/reputation).
    </ResponseField>

    <ResponseField name="followedAt" type="string">
      ISO timestamp of when the follow was created.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination metadata including `currentPage`, `totalPages`, `totalCount`, `hasNextPage`, and `hasPreviousPage`.
</ResponseField>

## Related

* [useFetchFollowing](/hooks/follows/use-fetch-following) — fetch the current user's own following list
* [useFetchFollowingCountByUserId](/hooks/follows/use-fetch-following-count-by-user-id) — get following count for a user


# Fetch following count
Source: https://docs.sublay.io/v7/hooks/follows/use-fetch-following-count

Get the total number of users the current user is following

## Overview

Returns a function that fetches the total count of users the currently authenticated user follows.

For getting another user's following count, see `useFetchFollowingCountByUserId`.

<Note>
  Users with a block between them and you, in either direction, are excluded
  from the count. Requires the `moderation` bundle.
</Note>

## Usage Example

```tsx theme={null}
import { useFetchFollowingCount } from "@sublay/react-js";

function FollowingCount() {
  const fetchFollowingCount = useFetchFollowingCount();
  const [count, setCount] = useState<number | null>(null);

  useEffect(() => {
    fetchFollowingCount().then((res) => setCount(res.count));
  }, []);

  return <span>{count ?? "..."} following</span>;
}
```

## Parameters

The hook returns a function that takes no parameters.

## Returns

<ResponseField name="count" type="number">
  Total number of users the current user is following.
</ResponseField>

## Related

* [useFetchFollowingCountByUserId](/hooks/follows/use-fetch-following-count-by-user-id) — get count for any user
* [useFetchFollowing](/hooks/follows/use-fetch-following) — fetch the full list


# Fetch following count by user ID
Source: https://docs.sublay.io/v7/hooks/follows/use-fetch-following-count-by-user-id

Get the following count for any user by their ID

## Overview

Returns a function that fetches the total count of users that a given user follows. Authentication is optional — the endpoint works without a token. When the caller is signed in, any user with a block between them and the caller, in either direction, is excluded from the count. Block filtering requires the `moderation` bundle.

## Usage Example

```tsx theme={null}
import { useFetchFollowingCountByUserId } from "@sublay/react-js";

function UserStats({ userId }: { userId: string }) {
  const fetchFollowingCountByUserId = useFetchFollowingCountByUserId();
  const [count, setCount] = useState<number | null>(null);

  useEffect(() => {
    fetchFollowingCountByUserId({ userId }).then((res) => setCount(res.count));
  }, [userId]);

  return <span>{count ?? "..."} following</span>;
}
```

## Parameters

The hook returns a function. That function accepts:

<ParamField type="string">
  The ID of the user whose following count to fetch.
</ParamField>

## Returns

<ResponseField name="count" type="number">
  Total number of users that the specified user is following.
</ResponseField>

## Related

* [useFetchFollowingCount](/hooks/follows/use-fetch-following-count) — get count for the current user
* [useFetchFollowingByUserId](/hooks/follows/use-fetch-following-by-user-id) — fetch the full list


# Use follow manager
Source: https://docs.sublay.io/v7/hooks/follows/use-follow-manager

Manage follow state between two users in a single hook

## Overview

Combines follow status fetching and toggle actions into a single hook. On mount, loads whether the current user follows `userId`, then provides a `toggleFollow` function to follow or unfollow in one call.

For integration guidance, see [Relationships — useFollowManager](/sdk/relationships/use-follow-manager).

## Usage Example

```tsx theme={null}
import { useFollowManager } from "@sublay/react-js";

function FollowButton({ userId }: { userId: string }) {
  const { isFollowing, isLoading, toggleFollow } = useFollowManager({ userId });

  return (
    <button onClick={toggleFollow} disabled={isLoading || isFollowing === null}>
      {isFollowing ? "Unfollow" : "Follow"}
    </button>
  );
}
```

## Parameters

<ParamField type="string">
  The ID of the target user.
</ParamField>

## Returns

<ResponseField name="isFollowing" type="boolean | null">
  `true` if following, `false` if not, `null` while the initial status is loading.
</ResponseField>

<ResponseField name="isLoading" type="boolean">
  `true` while the initial status check is in progress.
</ResponseField>

<ResponseField name="toggleFollow" type="() => Promise<void>">
  Follows the user if not currently following; unfollows if currently following. No-ops while loading or if `userId` is the current user's own ID.
</ResponseField>


# Follow user
Source: https://docs.sublay.io/v7/hooks/follows/use-follow-user

Follow a user by their ID

## Overview

Returns a function that follows a target user. The current user must be authenticated. Use `useFollowManager` if you need status tracking and toggle behavior; use this hook directly when you need fine-grained control.

## Usage Example

```tsx theme={null}
import { useFollowUser } from "@sublay/react-js";

function FollowButton({ userId }: { userId: string }) {
  const followUser = useFollowUser();

  const handleFollow = async () => {
    await followUser({ userId });
  };

  return <button onClick={handleFollow}>Follow</button>;
}
```

## Parameters

The hook returns a function. That function accepts:

<ParamField type="string">
  The ID of the user to follow.
</ParamField>

## Returns

The function returns `Promise<void>`.

## Related

* [useUnfollowUserByUserId](/hooks/follows/use-unfollow-user-by-user-id) — unfollow by user ID
* [useFetchFollowStatus](/hooks/follows/use-fetch-follow-status) — check follow status before calling


# Unfollow by follow ID
Source: https://docs.sublay.io/v7/hooks/follows/use-unfollow-by-follow-id

Remove a follow relationship using the follow record ID

## Overview

Returns a function that removes a follow by its `followId`. Use this when you have the follow ID available (e.g., from a followers list response). If you only have the user ID, use `useUnfollowUserByUserId` instead.

## Usage Example

```tsx theme={null}
import { useUnfollowByFollowId } from "@sublay/react-js";

function RemoveFollowerButton({ followId }: { followId: string }) {
  const unfollowByFollowId = useUnfollowByFollowId();

  return (
    <button onClick={() => unfollowByFollowId({ followId })}>
      Remove
    </button>
  );
}
```

## Parameters

The hook returns a function. That function accepts:

<ParamField type="string">
  The ID of the follow record to delete.
</ParamField>

## Returns

The function returns `Promise<void>`.

## Related

* [useUnfollowUserByUserId](/hooks/follows/use-unfollow-user-by-user-id) — unfollow by user ID instead
* [useFetchFollowers](/hooks/follows/use-fetch-followers) — returns `followId` in each follower entry


# Unfollow by user ID
Source: https://docs.sublay.io/v7/hooks/follows/use-unfollow-user-by-user-id

Unfollow a user by their user ID

## Overview

Returns a function that unfollows a target user by their user ID. The current user must be authenticated. This is the simpler alternative to `useUnfollowByFollowId` when you don't have the follow record ID.

## Usage Example

```tsx theme={null}
import { useUnfollowUserByUserId } from "@sublay/react-js";

function UnfollowButton({ userId }: { userId: string }) {
  const unfollowUserByUserId = useUnfollowUserByUserId();

  return (
    <button onClick={() => unfollowUserByUserId({ userId })}>
      Unfollow
    </button>
  );
}
```

## Parameters

The hook returns a function. That function accepts:

<ParamField type="string">
  The ID of the user to unfollow. Cannot be the current user's own ID.
</ParamField>

## Returns

The function returns `Promise<void>`.

## Related

* [useFollowUser](/hooks/follows/use-follow-user) — follow a user
* [useUnfollowByFollowId](/hooks/follows/use-unfollow-by-follow-id) — unfollow by follow record ID


# Use project
Source: https://docs.sublay.io/v7/hooks/project/use-project

Access the current project ID and configuration from context

## Overview

`useProject` returns the project context values set by the nearest `SublayProvider`. Use it to read the active `projectId` and the project's configuration (such as enabled integrations) from anywhere inside the provider tree.

## Usage Example

```tsx theme={null}
import { useProject } from "@sublay/react-js";

function IntegrationStatus() {
  const { projectId, project } = useProject();

  if (!project) return <p>Loading project...</p>;

  return (
    <div>
      <p>Project ID: {projectId}</p>
      <p>Integrations: {project.integrations.map((i) => i.name).join(", ")}</p>
    </div>
  );
}
```

## Returns

<ResponseField name="projectId" type="string | undefined">
  The project ID passed to the enclosing `SublayProvider`.
</ResponseField>

<ResponseField name="project" type="object | null | undefined">
  Lean project data fetched from the API, or `null` while loading. Contains:

  * `id` — the project's UUID.
  * `integrations` — array of integrations enabled for this project. Each entry has:
    * `id` — integration ID
    * `projectId` — parent project ID
    * `name` — integration name
    * `data` — integration-specific configuration
    * `createdAt` — creation timestamp
</ResponseField>


# useAccountPushToggle
Source: https://docs.sublay.io/v7/hooks/push/use-account-push-toggle

Turn push notifications on or off for any stored account on this device

## Overview

One physical device can hold several signed-in accounts, and each of them is bound to the device separately. `useAccountPushToggle` is the switch for that binding — **per account, per device** — and it works on accounts the user is not currently signed into.

The stored flag is **durable intent**: it lives in the account map next to that account's credential, in the same platform storage, and it is *merged* into the entry rather than overwriting it — so it survives switches, relaunches, and the refresh-token rotation that rebuilds the entry on every launch and every transition. An account silenced here is still silenced after the app is force-quit and reopened, and stays silenced until something explicitly turns it back on. The server-side binding is disposable state that the SDK reconciles back to match the flag.

The flag has **three** states, not two. `true` and `false` are choices the user made; *absent* means the account has never been asked. Absent reads as enabled when *describing* an account — which is what `isAccountPushEnabled` below returns, and what a switch should render — but it is never treated as consent to create a binding. Nothing is bound for an account that has not explicitly opted in.

<Note>
  Requires the `push` bundle. Reconciling is a no-op until this device has a stored push identifier — there is nothing to bind or unbind. [`usePushRegistration`](/hooks/push/use-push-registration) is what records one, through `register()`, `unregister()`, its rotation subscription, or — on native, when the device already holds notification permission — its mount-time read.
</Note>

## Usage Example

```tsx theme={null}
import { useAccounts, useAccountPushToggle } from "@sublay/react-js";

function PerAccountNotificationSettings() {
  const { accounts } = useAccounts();
  const { setAccountPushEnabled, isAccountPushEnabled, isUpdating, error } =
    useAccountPushToggle();

  return (
    <>
      {accounts.map((account) => (
        <label key={account.id}>
          {account.name ?? account.email}
          <input
            type="checkbox"
            checked={isAccountPushEnabled(account.id)}
            disabled={isUpdating}
            onChange={(e) =>
              setAccountPushEnabled({
                userId: account.id,
                enabled: e.target.checked,
              }).catch(() => {
                /* `error` below carries the reason */
              })
            }
          />
        </label>
      ))}
      {error && <p role="alert">{error}</p>}
    </>
  );
}
```

## Returns

<ResponseField name="setAccountPushEnabled" type="({ userId, enabled }) => Promise<boolean>">
  Applies the binding change server-side first, then writes the flag and persists it.

  `userId` may be **any** account in the stored map, active or not. Silencing a background account unbinds it server-side without switching to it, and without touching the current session.

  Resolves `true` when a binding change actually went out to the server, `false` when it was a no-op — this device has no stored identifier yet, so there was nothing to bind or unbind. Both are successful outcomes; the flag is written as the requested intent either way. Use this to tell "repaired" from "there was nothing to repair" directly, instead of diffing `useAccounts()`'s `needsPushRebind` marker before and after the call.

  Rejects when the binding change fails. It also rejects when `userId` names no stored account — with an [`AccountTransitionError`](/sdk/authentication/multi-account#telling-a-dead-account-from-a-dead-network) carrying `accountNotFound: true` and `credentialRejected: false`, the same typed shape `switchAccount` and `removeAccount` use for a stale id. Nothing was attempted and nothing was marked; refresh your account list rather than prompting a sign-in.
</ResponseField>

<ResponseField name="isAccountPushEnabled" type="(userId: string) => boolean">
  Whether a stored account currently wants push on this device — the value to render as a switch's `checked`. An account that has never expressed a preference reads as **enabled**: absent means "never asked", not "off". Returns `false` for an unknown id.

  It is reported state, not the rule that decides whether a binding exists. An account reading as enabled purely because it never answered has no binding until it explicitly opts in — through this toggle, or through a [`register()`](/hooks/push/use-push-registration) that records a preference for every account that never had one.
</ResponseField>

<ResponseField name="isUpdating" type="boolean">
  `true` while a change is in flight.
</ResponseField>

<ResponseField name="error" type="string | null">
  The reason the last change failed, or `null`.
</ResponseField>

## Failure Semantics

**The flag is written only after the attempt completes without throwing** — whether that means a binding change actually went out and succeeded, or there was nothing to bind because this device has no stored identifier yet (both are successful outcomes; see `setAccountPushEnabled` above). If the call fails, the previous value stands and the promise rejects.

This is deliberate and it is not a UI preference: the SDK must never report an account as push-enabled while nothing is actually bound, or as silenced while a binding survives. What you render on failure — a reverted switch, a retry affordance, an inline error — is entirely yours.

Failing here destroys nothing. The account stays, its credential stays, and the user can retry.

An account whose binding is stale because this device's push token rotated while it was in the background is a different situation, reported separately as `needsPushRebind` on [`useAccounts`](/hooks/auth/use-accounts) and repaired by switching into the account — not by toggling it.

## Turning Off a Background Account

Silencing an account the user is *not* signed into requires acting as that account for one request. The SDK does this by exchanging that account's stored refresh token for a short-lived access token.

That exchange **rotates** — it revokes the token it presents and issues a successor — so the SDK persists the successor before treating the operation as complete. You do not need to do anything about this, but it is why the operation involves a network round trip per background account rather than being instant, and why it is confined to this one deliberate, user-initiated path.

## Not the Same as Notification Preferences

|              | `useAccountPushToggle`                                              | [`useNotificationPreferences`](/hooks/push/use-notification-preferences) |
| ------------ | ------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| Scope        | One account's binding on **this device**                            | The signed-in user's **event types**, everywhere                         |
| Applies to   | Any stored account, active or not                                   | The active account only                                                  |
| When off     | The device is not bound — **nothing** arrives for that account here | The device is still bound; specific event types are suppressed           |
| Stored where | On the device, in the account map                                   | On the server, per user                                                  |

They compose: an account silenced with this hook receives nothing on this device regardless of its event-type preferences, and those preferences are untouched — they apply again the moment it is turned back on.

## See Also

* [usePushRegistration](/hooks/push/use-push-registration)
* [Multi-Account](/sdk/authentication/multi-account)
* [SDK — Push Notifications](/sdk/push-notifications/overview)
* [Notification Preferences & Mute](/notification-preferences)


# Use notification preferences
Source: https://docs.sublay.io/v7/hooks/push/use-notification-preferences

Read and update the current user's disabled push notification types

## Overview

`useNotificationPreferences` reads and updates the signed-in user's push notification preferences — the set of event types they've disabled for push. Use it to build a notification-settings screen with a per-type toggle.

Disabling a type suppresses **push only** — the in-app notification is still written, so the bell/inbox is unaffected. A user with no preferences is all-on (`disabledTypes` is `[]`).

<Note>Requires an authenticated user and the `push` bundle installed on the project.</Note>

<Note>
  **Not the same as [`useAccountPushToggle`](/hooks/push/use-account-push-toggle).** This hook controls **which event types** the signed-in user receives. That one controls **whether an account is bound to this device at all** — and works on any stored account, not just the active one. An account silenced there receives nothing on that device regardless of what is set here, and these preferences are left untouched, applying again as soon as it is turned back on.
</Note>

## Usage Example

```tsx theme={null}
import { useNotificationPreferences, PUSH_EVENT_TYPES } from "@sublay/react-js";

function NotificationSettings() {
  const { disabledTypes, loading, updating, updatePreferences } =
    useNotificationPreferences();

  if (loading || !disabledTypes) return <Spinner />;

  const toggle = (type: (typeof PUSH_EVENT_TYPES)[number]) => {
    const next = disabledTypes.includes(type)
      ? disabledTypes.filter((t) => t !== type)
      : [...disabledTypes, type];
    return updatePreferences(next);
  };

  return (
    <ul>
      {PUSH_EVENT_TYPES.map((type) => (
        <li key={type}>
          <label>
            <input
              type="checkbox"
              // checked = push ENABLED = NOT in disabledTypes
              checked={!disabledTypes.includes(type)}
              disabled={updating}
              onChange={() => toggle(type)}
            />
            {type}
          </label>
        </li>
      ))}
    </ul>
  );
}
```

## Returns

The hook returns an object:

<ResponseField name="disabledTypes" type="PushEventType[] | undefined">
  The event types the user has disabled for push. `undefined` until the read resolves; `[]` when nothing is disabled (all-on).
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` while the initial read is in flight.
</ResponseField>

<ResponseField name="updating" type="boolean">
  `true` while an update is in flight.
</ResponseField>

<ResponseField name="error" type="unknown">
  The read error, if any.
</ResponseField>

<ResponseField name="refetch" type="() => void">
  Re-fetch the preferences.
</ResponseField>

<ResponseField name="updatePreferences" type="(disabledTypes: PushEventType[]) => Promise<void>">
  Replace the disabled-types set (upsert). Pass the **complete** set you want stored, not a delta. Only valid event type names are accepted; unknown names are rejected server-side.
</ResponseField>

## Notes

* Available on `@sublay/react-js`, `@sublay/react-native`, and `@sublay/expo` (inherited from `@sublay/core`).
* The full list of valid type names is exported as `PUSH_EVENT_TYPES`. See the [event palette](/notification-preferences#the-event-palette).
* For per-conversation muting, see [`useMuteConversation`](/hooks/chat/conversations/use-mute-conversation).


# usePushRegistration
Source: https://docs.sublay.io/v7/hooks/push/use-push-registration

Request push permission and register or unregister the current user's device

## Overview

Explicit, developer-triggered hook for registering and unregistering the current user's device for push notifications. Unlike auth-token restoration, requesting OS or browser push permission is a deliberate action and should happen in response to a user gesture (for example, when they opt in to notifications in your settings screen) — not silently on mount.

Calling `register()` once per device is enough. **Mounting the hook is a separate concern from calling it**, because mounting is also what installs the SDK's [device-token rotation](#automatic-token-rotation) handling — the thing that keeps bindings correct without the app re-registering on every launch.

<Warning>
  **Mount it once at your app root, not on the settings screen** — and what
  that buys you differs by platform.

  On **Expo and React Native** the adapter installs a real OS rotation
  listener, and it lives for exactly as long as the hook is mounted. A hook
  mounted only on a notification-settings screen therefore covers only the
  seconds that screen is open; a token that rotates while the user is anywhere
  else in the app is missed, and that account's notifications go quiet until
  something else happens to re-bind it. Root-mounting is what makes the
  guarantee hold on native: *any app that has ever registered gets rotation
  coverage for the whole session*.

  On **web there is no ongoing listener at all.** The browser's
  `pushsubscriptionchange` event fires inside the service worker your app
  registers, which the SDK cannot subscribe to from page context. The web
  adapter instead does a **single comparison at mount**: it reads the
  subscription the browser already holds and re-binds if it differs from the
  stored one. So on the web, a rotation that happens mid-session is not caught
  no matter where the hook is mounted — it is picked up on the next mount
  (in practice, the next page load). Mounting at the root still matters there,
  just for a different reason: it makes that one check happen on every launch
  rather than only when the settings screen is opened.

  **Mounting never prompts the user** — on every platform, nothing on this
  path can raise a permission dialog. It is not, however, free of side effects:
  on the two native platforms mounting also performs one non-prompting read of
  the current device identifier per launch (gated on the device already holding
  notification permission, with a documented once-per-device exception — see
  [Reading the current identifier on mount](#reading-the-current-identifier-on-mount-native)),
  and if that identifier has changed the hook re-binds the active account and
  marks the others for re-binding. Web does none of this; it declares nothing
  here and is covered by the mount-time comparison above.

  Call `register()` from wherever your opt-in UI lives; that part is still a
  deliberate user gesture, and the two do not have to happen in the same
  component: mount the hook at the root and pass its `register` / `unregister`
  down through your own context to the settings screen that triggers them.
</Warning>

The hook accepts a **platform adapter** that abstracts the platform-specific permission and token-retrieval steps. Three adapters are available out of the box:

| Adapter                       | Package                | Platform                          |
| ----------------------------- | ---------------------- | --------------------------------- |
| `expoPushTokenAdapter`        | `@sublay/expo`         | Expo (iOS + Android)              |
| `reactNativePushTokenAdapter` | `@sublay/react-native` | Bare React Native (iOS + Android) |
| `webPushTokenAdapter`         | `@sublay/react-js`     | Browser (Web Push)                |

## Usage Example

The mount belongs at the root; only the `register()` call belongs on the settings screen. The
smallest shape that satisfies both is one root-level hook whose handlers are shared downward:

```tsx theme={null}
// App root — mounted for the whole session, so rotation handling is always installed.
import { createContext, useContext } from "react";
import { usePushRegistration, type UsePushRegistrationValues } from "@sublay/core";
import { expoPushTokenAdapter } from "@sublay/expo";

const PushContext = createContext<UsePushRegistrationValues | null>(null);
export const usePush = () => {
  const push = useContext(PushContext);
  if (!push) throw new Error("usePush() must be called under the App root that mounts usePushRegistration.");
  return push;
};

export function App({ children }) {
  const push = usePushRegistration(expoPushTokenAdapter);
  return <PushContext.Provider value={push}>{children}</PushContext.Provider>;
}

// Settings screen — triggers the deliberate user action, mounts nothing.
function NotificationOptIn() {
  const { register, registering } = usePush();

  return (
    <Button onPress={register} disabled={registering}>
      {registering ? "Enabling…" : "Enable push notifications"}
    </Button>
  );
}
```

The two snippets below call the hook inline for brevity. That is fine for a screen that is always
mounted, and loses rotation coverage otherwise — see the warning above.

```tsx theme={null}
import { usePushRegistration } from "@sublay/core";
import { expoPushTokenAdapter } from "@sublay/expo";

function NotificationOptIn() {
  const { register, unregister, registering } = usePushRegistration(expoPushTokenAdapter);

  return (
    <Button onPress={register} disabled={registering}>
      {registering ? "Enabling…" : "Enable push notifications"}
    </Button>
  );
}
```

```tsx theme={null}
// Web (Next.js / React)
import { usePushRegistration } from "@sublay/core";
import { webPushTokenAdapter } from "@sublay/react-js";

function NotificationSettings() {
  const { register, unregister, registering, unregistering } =
    usePushRegistration(webPushTokenAdapter);

  return (
    <>
      <button onClick={register} disabled={registering}>Enable</button>
      <button onClick={unregister} disabled={unregistering}>Disable</button>
    </>
  );
}
```

## Parameters

<ParamField type="PushTokenAdapter">
  A platform adapter implementing `requestPermission()` and `getDeviceIdentifier()`, and optionally `subscribeToIdentifierChanges()`. Import one of the three built-in adapters or implement your own.
</ParamField>

## Returns

<ResponseField name="register" type="() => Promise<boolean>">
  Requests OS or browser permission, retrieves the device token or subscription, and registers it with the server. Returns `true` on success, `false` if permission was denied or the adapter could not produce an identifier (both are expected outcomes, not errors). Throws when the server call fails. It also records this device's identifier and enables push for the stored accounts — see [What `register()` does beyond the API call](#what-register-does-beyond-the-api-call).
</ResponseField>

<ResponseField name="unregister" type="() => Promise<void>">
  Unbinds the **active** account from this device and records that as a durable preference — see [`unregister()` is a preference, not a logout step](#unregister-is-a-preference-not-a-logout-step). A no-op if the adapter returns no identifier.
</ResponseField>

<ResponseField name="registering" type="boolean">
  `true` while `register()` is in progress.
</ResponseField>

<ResponseField name="unregistering" type="boolean">
  `true` while `unregister()` is in progress.
</ResponseField>

<Note>
  The hook requires an authenticated user — `register()` and `unregister()` throw immediately if no user session is available.
</Note>

### What `register()` does beyond the API call

On success it also:

* **stores this device's identifier durably**, so account-management paths that hold no adapter (removal, sign-out, the per-account toggle) can still unbind push;
* **records push as enabled for the active account**, because "push is on for this account on this device" is a sticky preference rather than a one-shot call;
* **records it for every other stored account that has never expressed a preference.** Permission is a device-level grant, so `register()` speaks for the accounts that were never asked — but never over one the user deliberately silenced, which keeps its `false`. Turn individual accounts back off with [`useAccountPushToggle`](/hooks/push/use-account-push-toggle);
* **marks accounts as needing a re-bind**, so each is bound the next time the user switches into it, using the live session that switch establishes. Two things put an account in that state, and they are different sets:

  * the device identifier this call brought **differs** from the stored one, which makes every opted-in background account's binding stale — all of them are marked;
  * the identifier is unchanged but this call just flipped some accounts from "never asked" to enabled. Those are reported as push-enabled and have no binding, and only the active account was registered here — so exactly the newly flipped ones are marked, and accounts that were already working are left alone.

  A repeat `register()` on the same identifier that flips nothing marks nothing.

Only the **active** account is bound by this call, and the return value reports on that registration. Binding the others here would mean spending each one's stored refresh token on a one-time-use exchange in the background, which permanently locks an account out if it is interrupted — see [When notifications are paused](/sdk/authentication/multi-account#when-notifications-are-paused).

### `unregister()` is a preference, not a logout step

`unregister()` silences the active account on this device **durably**: the flag is stored in the account map and merged into the entry on every rebuild, so it survives switches and relaunches until `register()` or the per-account toggle turns it back on. It does *not* clear the stored device identifier — that is device state shared with every other account on the device, and clearing it would break their deregistration too. It does record the identifier it fetched, so a device with none stored acquires one here.

<Warning>
  **Do not call it in a logout flow.** Signing out (`signOut`, `removeAccount`, `signOutAll`) already deregisters the account atomically server-side, so there is nothing to clean up — and because the flag is durable, an `unregister()` at logout permanently silences that account's next session with no visible cause. Wire it to a user-facing notification switch instead.
</Warning>

## Platform Adapters

### `expoPushTokenAdapter` (`@sublay/expo`)

Uses `expo-notifications` to request permission and retrieve the raw APNs/FCM device token directly (not the Expo relay token — Sublay dispatches to APNs and FCM using the project's own credentials).

```tsx theme={null}
import { expoPushTokenAdapter } from "@sublay/expo";

const { register } = usePushRegistration(expoPushTokenAdapter);
```

Works in Expo managed and bare workflow. Requires `expo-notifications` in your project.

### `reactNativePushTokenAdapter` (`@sublay/react-native`)

Uses `@react-native-firebase/messaging` for both iOS and Android. On iOS, `getAPNSToken()` returns the raw APNs token; on Android, `getToken()` returns the FCM registration token.

```tsx theme={null}
import { reactNativePushTokenAdapter } from "@sublay/react-native";

const { register } = usePushRegistration(reactNativePushTokenAdapter);
```

Requires `@react-native-firebase/messaging` and the native Firebase setup for your platform (GoogleService-Info.plist / google-services.json).

### `webPushTokenAdapter` (`@sublay/react-js`)

Uses the browser's Notification permission API and Push API. Fetches the project's VAPID public key from the server (unauthenticated), then calls `PushManager.subscribe()` to create a Web Push subscription. Requires a service worker registered on your page.

```tsx theme={null}
import { webPushTokenAdapter } from "@sublay/react-js";

const { register } = usePushRegistration(webPushTokenAdapter);
```

Returns `false` (without throwing) in environments where the Notification or Push APIs are unavailable (for example, SSR).

## Custom Adapters

Implement `PushTokenAdapter` from `@sublay/core` to use your own push library:

```typescript theme={null}
import type { PushTokenAdapter, PushDeviceIdentifier } from "@sublay/core";

const myAdapter: PushTokenAdapter = {
  async requestPermission(): Promise<boolean> {
    // ask the OS or browser for permission
    return true;
  },
  async getDeviceIdentifier(context): Promise<PushDeviceIdentifier | null> {
    // return { platform: "ios", token: "..." }
    // return { platform: "android", token: "..." }
    // return { platform: "web", subscription: { endpoint, keys: { p256dh, auth } } }
    return null;
  },

  // OPTIONAL — see "Reading the current identifier on mount" below.
  // Read the CURRENT permission status; never prompt here.
  async hasPermission(): Promise<boolean> {
    return myPushLibrary.permissionStatus() === "granted";
  },

  // OPTIONAL — set only if getDeviceIdentifier() cannot prompt.
  canReadIdentifierWithoutPrompting: true,

  // OPTIONAL — see "Automatic token rotation" below.
  subscribeToIdentifierChanges(context, onChange) {
    const unsubscribe = myPushLibrary.onTokenChange((token) => {
      onChange({ platform: "android", token });
    });
    return unsubscribe;
  },
};
```

`subscribeToIdentifierChanges` is optional. Omit it and rotation simply falls back to the next `register()` — the pre-existing behaviour. Emitting `null`, or an identifier equal to the stored one, is a no-op.

`canReadIdentifierWithoutPrompting` and `hasPermission` are optional and work as a pair — see [Reading the current identifier on mount](#reading-the-current-identifier-on-mount-native). Set the flag only if `getDeviceIdentifier()` reads a value the platform already holds and can never raise a permission prompt; an adapter that omits `hasPermission` is not gated on one.

## Automatic Token Rotation

Device push tokens rotate on reinstall, on an OS-initiated refresh, and after a backup restore, and every binding on the old token dies with it. The hook covers this itself: whenever it is mounted with an adapter that implements `subscribeToIdentifierChanges`, it subscribes to that signal. On a change it unbinds the old identifier for the active account, records the new one, re-binds the **active** account, and **marks** every other push-enabled account as needing a re-bind — repaired on each account's next activation rather than by spending its stored credential in the background. Silenced accounts are left silenced, and an account that never expressed a preference is neither marked nor bound.

The subscription is gated on the adapter alone, so an app whose adapter omits it subscribes to nothing. Nothing on this path prompts the user — receiving a refreshed token asks for no permission — and nothing on it exchanges a stored credential.

**What "subscribing" means is not the same on every platform**, and the difference decides how much a root mount buys you:

| Platform           | What the subscription is                                                                                                                                                                                                                                                                                   | What a root mount buys                                                                                                                                                                                                                                                                    |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Expo, React Native | A real OS rotation event (`addPushTokenListener`, Firebase `onTokenRefresh`), installed on mount and torn down on unmount                                                                                                                                                                                  | **Live coverage for the whole session.** Mounted only on a settings screen, it catches rotations only while that screen is open; a token that rotates anywhere else in the app is missed entirely.                                                                                        |
| Web                | **No listener.** `pushsubscriptionchange` fires inside the service worker the integrator registers, which the SDK cannot subscribe to from page context — so the web adapter emits **once, at mount**, from the subscription the browser already holds, and core compares it against the stored identifier | **One check per mount, not live coverage.** A rotation mid-session is not caught on the web wherever the hook sits; it is picked up on the next mount — in practice the next page load. Root-mounting makes that check happen on every launch instead of only when some screen is opened. |

So the guarantee to state honestly is: **native gets rotation coverage for as long as the hook is mounted; web gets a single reconciliation each time it mounts.** Root-mounting is the right advice on both, for the two different reasons above.

### Reading the current identifier on mount (native)

Both native subscriptions are rotation-only, so a device whose token never rotates would never emit one — and every path that *unbinds* push is gated on having a stored identifier. To cover that, the built-in native adapters declare `canReadIdentifierWithoutPrompting`, and the hook reads the current identifier once on mount and feeds it through the same path a rotation takes. An identifier equal to the stored one changes nothing, which is the common case.

Two conditions gate it, and both matter:

* **The adapter must declare that reading cannot prompt.** `expoPushTokenAdapter` and `reactNativePushTokenAdapter` do; `webPushTokenAdapter` must not, because its `getDeviceIdentifier()` calls `pushManager.subscribe()`, which can raise a permission prompt with no user gesture behind it. Web covers the same ground through its mount-emitting subscription instead.
* **The device must already hold OS notification permission**, read through the adapter's `hasPermission()` — which reads the current status and never asks. A device token exists on both native platforms whether or not the user was ever asked (that is how silent push works), so "reading cannot prompt" is not on its own a reason to store one. `register()` cannot create a binding without a permission grant, so a device with no grant has no binding to discover *from this release*. An adapter that does not implement `hasPermission()` is not gated.

This does not require a permission *prompt* and never raises one; it reads a grant that already exists. A device whose permission is granted but which never registered for Sublay push simply stores an identifier that matches no binding — sign-out then asks for an unbind that removes nothing.

#### The permission gate is bypassed once per device

A grant proves nothing about the past. Turning notifications off in system settings does not invalidate an APNs or FCM token and does not remove a binding: the provider still accepts the notification and the OS simply does not display it, and the server prunes a token only on an uninstall or dead-token signal from the provider. So a device that registered on an SDK release which stored no identifier, and has since revoked permission, holds a live binding that the gate makes unreachable — no identifier means sign-out, account removal and the per-account toggle all no-op, and re-enabling notifications later delivers that account's notifications to a device nobody is signed into.

To close that, the **first** identifier read on a device ignores `hasPermission()`. The SDK records that it has run and persists the record with the account map, so it happens once per install and every later read is gated normally. Two further conditions narrow it: the device must already have **at least one stored account** (an unbind is scoped to a refresh token's subject, so with none stored there is nothing an identifier could ever unbind) and must have **no identifier stored yet**. A device whose account storage was empty the first time this SDK ran is marked as ineligible outright — it cannot be carrying a binding from an older release. A read that fails does not consume the one turn.

The cost is stated rather than hidden: a device that has accounts, never registered for push, and holds no permission does get an identifier stored by that single read, and its sign-outs then ask for an unbind that matches nothing.

The three built-in adapters are deliberately asymmetric, because the platforms are:

| Adapter                       | Behaviour                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `expoPushTokenAdapter`        | Real OS event (`addPushTokenListener`), emitting exactly the shape the adapter registers. **Rotation-only:** it fires when the OS hands over a new token, never merely because something subscribed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `reactNativePushTokenAdapter` | Firebase `onTokenRefresh`, also rotation-only. The event carries an **FCM** token while the adapter registers **APNs** on iOS, so the handler ignores the emitted value and re-derives through `getDeviceIdentifier()`. Consequence: iOS APNs rotation is not reported by this event at all. It is caught by the [mount-time read](#reading-the-current-identifier-on-mount-native) on the next launch instead — this adapter declares `canReadIdentifierWithoutPrompting` — or sooner by a `register()` or `unregister()`. A failed re-derivation is reported through the SDK's error handler rather than passed off as "no change".                                                                                                                                                                                                           |
| `webPushTokenAdapter`         | **No in-page event exists** — `pushsubscriptionchange` fires inside the service worker *you* register, which the SDK cannot subscribe to. Web is covered by comparison instead: on mount it reads the browser's existing subscription and emits it if it differs from the stored one, which is how a web device with no stored identifier acquires one without calling `register()` again. It calls `getSubscription()` only, never `subscribe()`, so it cannot prompt on page load; it probes for a registration before awaiting `serviceWorker.ready`, which never settles when no service worker is registered; and a failure is reported through the SDK's error handler rather than swallowed. Native reaches the same place differently — see [Reading the current identifier on mount](#reading-the-current-identifier-on-mount-native). |

## Relationship to Other Hooks

| Hook                                                                     | Scope                                                                                                           |
| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| `usePushRegistration`                                                    | Permission + this device's identifier + the **active** account's binding, plus the re-bind markers for the rest |
| [`useAccountPushToggle`](/hooks/push/use-account-push-toggle)            | Any **stored** account's binding on this device, without switching to it                                        |
| [`useNotificationPreferences`](/hooks/push/use-notification-preferences) | Which **event types** the signed-in user receives — not whether the device is bound at all                      |

## See Also

* [useAccountPushToggle](/hooks/push/use-account-push-toggle)
* [Push Notifications overview](/push-notifications)
* [Register Device endpoint](/api-reference/push-notifications/register-device)
* [Node SDK — push.send](/node-sdk/push-notifications)


# Create report
Source: https://docs.sublay.io/v7/hooks/reports/use-create-report

Submit a report against an entity, comment, or chat message

## Overview

Returns a function to submit a content report on behalf of the authenticated user. Pass `type: "comment"`, `type: "entity"`, or `type: "message"` when calling the hook — the returned function is pre-configured for that target type.

If the same target already has an **open** report, the user's report is appended to it (reports are deduplicated per user, so reporting the same target twice has no additional effect).

Once a moderator resolves a report — dismissed or actioned — it is closed. A later report of that same target opens a **fresh** report rather than reopening the closed one, so previously-dismissed content can be re-reported and returns to the moderation queue.

<Note>Requires an authenticated user.</Note>

## Usage Example

```tsx theme={null}
import { useCreateReport } from "@sublay/react-js";

function ReportEntityButton({ entityId }: { entityId: string }) {
  const createEntityReport = useCreateReport({ type: "entity" });

  const handleReport = async () => {
    await createEntityReport({
      targetId: entityId,
      reason: "spam",
    });
    alert("Report submitted.");
  };

  return <button onClick={handleReport}>Report</button>;
}
```

## Parameters

<ParamField type="&#x22;comment&#x22; | &#x22;entity&#x22; | &#x22;message&#x22;">
  The target type this hook instance will report against. Determines the shape of the returned function.
</ParamField>

## Returned Function

The hook returns `createCommentReport`, `createEntityReport`, or `createMessageReport` depending on the `type` argument. All three accept the same parameters:

<ParamField type="string">
  The ID of the comment, entity, or chat message being reported. For messages
  this is the message id — the conversation is resolved server-side, so no
  `conversationId` is needed.
</ParamField>

<ParamField type="ReportReasonKey">
  The reason for the report. Must be one of the following keys:

  | Key                    | Label                                   |
  | ---------------------- | --------------------------------------- |
  | `spam`                 | It's spam                               |
  | `inappropriateContent` | Contains inappropriate content          |
  | `harassment`           | It's harassment or bullying             |
  | `misinformation`       | Spreads false information               |
  | `hateSpeech`           | Contains hate speech or symbols         |
  | `violence`             | Promotes violence or dangerous behavior |
  | `illegalActivity`      | Promotes illegal activity               |
  | `selfHarm`             | Promotes self-harm or suicide           |
  | `other`                | Other                                   |

  These are enforced by the API: any other value is rejected with
  `report/invalid-body`. Use `other` plus `details` for anything the taxonomy
  doesn't cover.
</ParamField>

<ParamField type="string">
  Optional free-text elaboration on the reason.
</ParamField>

## Returns

The returned function returns `Promise<void>`. It resolves when the report is accepted (whether created or appended to an existing one).

## Notes

* If the target has an open report this user already filed, the server returns `200` with code `report/already-reported` without error. The hook function resolves normally in this case. After that report is resolved, the same user may report the target again.
* You cannot report your own content — the API rejects it with `report/self-report`.
* Reporting a message requires membership of its conversation; a non-member gets `chat/not-a-member`.
* Where a message report lands depends on the conversation: reports on **space** conversations reach space moderators via [`useFetchModeratedReports`](/hooks/reports/use-fetch-moderated-reports); reports on **DMs and group chats** have no space, so they are project-level and appear only in the Sublay dashboard.
* Reports are scoped to the space the content belongs to, enabling space moderators to action them. See [`useFetchModeratedReports`](/hooks/reports/use-fetch-moderated-reports).


# Fetch moderated reports
Source: https://docs.sublay.io/v7/hooks/reports/use-fetch-moderated-reports

Fetch content reports for spaces the current user moderates

## Overview

Returns a function to fetch content reports (entities and comments) from spaces where the current user has an `admin` or `moderator` role.

If `spaceId` is provided, returns reports for that specific space (the user must moderate it). If omitted, returns reports aggregated from **all** spaces the user moderates.

<Note>Requires an authenticated user with `admin` or `moderator` role in at least one space.</Note>

## Usage Example

```tsx theme={null}
import { useFetchModeratedReports } from "@sublay/react-js";
import { useEffect, useState } from "react";

function ModerationQueue({ spaceId }: { spaceId: string }) {
  const fetchModeratedReports = useFetchModeratedReports();
  const [reports, setReports] = useState([]);

  useEffect(() => {
    fetchModeratedReports({ spaceId, status: "pending", page: 1, limit: 20 })
      .then(res => setReports(res.data));
  }, [spaceId]);

  return (
    <ul>
      {reports.map(r => (
        <li key={r.id}>{r.targetType}: {r.reporterCount} reports</li>
      ))}
    </ul>
  );
}
```

## Parameters

<ParamField type="string">
  Filter reports to a specific space. If omitted, returns reports from all spaces the user moderates.
</ParamField>

<ParamField type="&#x22;comment&#x22; | &#x22;entity&#x22;">
  Filter by target type.
</ParamField>

<ParamField type="&#x22;pending&#x22; | &#x22;on-hold&#x22; | &#x22;escalated&#x22; | &#x22;dismissed&#x22; | &#x22;actioned&#x22;">
  Filter by report status.
</ParamField>

<ParamField type="&#x22;new&#x22; | &#x22;old&#x22;">
  Sort order. Defaults to `"new"` (newest first).
</ParamField>

<ParamField type="number">
  Page number for pagination. Defaults to `1`.
</ParamField>

<ParamField type="number">
  Items per page. Defaults to `20`.
</ParamField>

## Returns

Returns `Promise<PaginatedResponse<Report>>`:

```ts theme={null}
{
  data: Report[];
  pagination: {
    page: number;
    pageSize: number;
    totalPages: number;
    totalItems: number;
    hasMore: boolean;
  };
}
```

### Report object

<ResponseField name="id" type="string">UUID of the report record.</ResponseField>
<ResponseField name="projectId" type="string">Project the report belongs to.</ResponseField>
<ResponseField name="spaceId" type="string | null">Space the reported content belongs to.</ResponseField>
<ResponseField name="targetId" type="string">ID of the reported entity or comment.</ResponseField>
<ResponseField name="targetType" type="&#x22;comment&#x22; | &#x22;entity&#x22;">Type of the reported content.</ResponseField>
<ResponseField name="reporterCount" type="number">Total number of users who have reported this target.</ResponseField>
<ResponseField name="userReports" type="array">Individual user report entries. Each includes `id`, `userId`, `reason`, `details`, and `createdAt`.</ResponseField>
<ResponseField name="status" type="string">Current moderation status: `pending`, `on-hold`, `escalated`, `dismissed`, or `actioned`.</ResponseField>
<ResponseField name="actionTaken" type="string | null">Free-text description of action taken, if any.</ResponseField>
<ResponseField name="target" type="Entity | Comment | null">The reported content record (includes the author user object). Populated even if the content was soft-deleted.</ResponseField>
<ResponseField name="space" type="Space | null">The space the reported content belongs to.</ResponseField>
<ResponseField name="createdAt" type="Date">When the first report for this target was submitted.</ResponseField>
<ResponseField name="updatedAt" type="Date">When the report record was last updated.</ResponseField>
<ResponseField name="deletedAt" type="Date | null">Soft-delete timestamp. `null` if the report has not been deleted.</ResponseField>


# Handle space chat report
Source: https://docs.sublay.io/v7/hooks/reports/use-handle-space-chat-report

Action a chat message report as a space moderator

## Overview

Returns a function that allows a space moderator to take action on a chat message report. Available actions are: remove the message, ban the message's author from the space, or dismiss the report.

<Note>Requires the authenticated user to have `admin` or `moderator` role in the target space.</Note>

<Info>
  `ban-user` here is **space-scoped** — it sets the target's space membership to
  banned. Project-wide suspension is a separate, dashboard-only action; a space
  moderator cannot suspend a user across the whole project.
</Info>

## Usage Example

```tsx theme={null}
import { useHandleSpaceChatReport } from "@sublay/react-js";

function ChatReportActions({ report }) {
  const handleSpaceChatReport = useHandleSpaceChatReport();

  const removeMessage = async () => {
    await handleSpaceChatReport({
      spaceId: report.spaceId,
      reportId: report.id,
      messageId: report.targetId,
      actions: ["remove-message"],
      summary: "Removed message for harassment",
    });
  };

  const dismiss = async () => {
    await handleSpaceChatReport({
      spaceId: report.spaceId,
      reportId: report.id,
      actions: ["dismiss"],
      summary: "No violation found",
    });
  };

  return (
    <div>
      <button onClick={removeMessage}>Remove Message</button>
      <button onClick={dismiss}>Dismiss</button>
    </div>
  );
}
```

## Parameters

<ParamField type="string">
  The ID of the space the report belongs to.
</ParamField>

<ParamField type="string">
  The ID of the report to action.
</ParamField>

<ParamField type="string">
  The ID of the reported message. Required when `remove-message` is included in `actions`.
</ParamField>

<ParamField type="Array<'remove-message' | 'ban-user' | 'dismiss'>">
  One or more actions to take:

  * `remove-message` — Removes the message.
  * `ban-user` — Bans the message's author from the space (requires `userId`).
  * `dismiss` — Marks the report as dismissed.
</ParamField>

<ParamField type="string">
  A moderator note describing the action taken.
</ParamField>

<ParamField type="string">
  The ID of the user to ban — the ban **target**, not the moderator. Required when `ban-user` is included in `actions`.
</ParamField>

<ParamField type="string">
  The reason for banning, if applicable.
</ParamField>

<ParamField type="string">
  The moderator the action is attributed to. Service and master keys only.
</ParamField>

## Returns

Returns `Promise<{ message: string; code: string }>`.

## Notes

* This is the chat equivalent of [`useHandleSpaceEntityReport`](/hooks/reports/use-handle-space-entity-report) and [`useHandleSpaceCommentReport`](/hooks/reports/use-handle-space-comment-report).
* Message reports are created with [`useCreateReport`](/hooks/reports/use-create-report) using `type: "message"`.
* To fetch pending reports, use [`useFetchModeratedReports`](/hooks/reports/use-fetch-moderated-reports).


# Handle space comment report
Source: https://docs.sublay.io/v7/hooks/reports/use-handle-space-comment-report

Action a comment report as a space moderator

## Overview

Returns a function that allows a space moderator to take action on a comment report. Available actions are: remove the comment, ban the comment's author from the space, or dismiss the report.

<Note>Requires the authenticated user to have `admin` or `moderator` role in the target space.</Note>

## Usage Example

```tsx theme={null}
import { useHandleSpaceCommentReport } from "@sublay/react-js";

function CommentReportActions({ report }) {
  const handleSpaceCommentReport = useHandleSpaceCommentReport();

  const removeComment = async () => {
    await handleSpaceCommentReport({
      spaceId: report.spaceId,
      reportId: report.id,
      commentId: report.targetId,
      actions: ["remove-comment"],
      summary: "Removed comment for harassment",
    });
  };

  const dismiss = async () => {
    await handleSpaceCommentReport({
      spaceId: report.spaceId,
      reportId: report.id,
      commentId: report.targetId,
      actions: ["dismiss"],
      summary: "No violation found",
    });
  };

  return (
    <div>
      <button onClick={removeComment}>Remove Comment</button>
      <button onClick={dismiss}>Dismiss</button>
    </div>
  );
}
```

## Parameters

<ParamField type="string">
  The ID of the space the report belongs to.
</ParamField>

<ParamField type="string">
  The ID of the report to action.
</ParamField>

<ParamField type="string">
  The ID of the reported comment.
</ParamField>

<ParamField type="Array<'remove-comment' | 'ban-user' | 'dismiss'>">
  One or more actions to take:

  * `remove-comment` — Removes the comment.
  * `ban-user` — Bans the comment's author from the space (requires `userId`).
  * `dismiss` — Marks the report as dismissed.
</ParamField>

<ParamField type="string">
  A moderator note describing the action taken.
</ParamField>

<ParamField type="string">
  The ID of the user to ban. Required when `ban-user` is included in `actions`.
</ParamField>

<ParamField type="string">
  The reason for banning, if applicable.
</ParamField>

## Returns

Returns `Promise<{ message: string; code: string }>`.

## Notes

* This is the comment equivalent of [`useHandleSpaceEntityReport`](/hooks/reports/use-handle-space-entity-report).
* To fetch pending reports, use [`useFetchModeratedReports`](/hooks/reports/use-fetch-moderated-reports).


# Handle space entity report
Source: https://docs.sublay.io/v7/hooks/reports/use-handle-space-entity-report

Action an entity report as a space moderator

## Overview

Returns a function that allows a space moderator to take action on an entity report. Available actions are: remove the entity from the space, ban the reporting target's author, or dismiss the report.

Multiple actions can be combined in a single call (e.g., remove the entity and ban the user simultaneously).

<Note>Requires the authenticated user to have `admin` or `moderator` role in the target space.</Note>

## Usage Example

```tsx theme={null}
import { useHandleSpaceEntityReport } from "@sublay/react-js";

function EntityReportActions({ report }) {
  const handleSpaceEntityReport = useHandleSpaceEntityReport();

  const removeAndBan = async () => {
    await handleSpaceEntityReport({
      spaceId: report.spaceId,
      reportId: report.id,
      entityId: report.targetId,
      actions: ["remove-entity", "ban-user"],
      summary: "Removed spam content and banned user from space",
      userId: report.target?.userId,
    });
  };

  const dismiss = async () => {
    await handleSpaceEntityReport({
      spaceId: report.spaceId,
      reportId: report.id,
      entityId: report.targetId,
      actions: ["dismiss"],
      summary: "Content reviewed — no violation found",
    });
  };

  return (
    <div>
      <button onClick={removeAndBan}>Remove & Ban</button>
      <button onClick={dismiss}>Dismiss</button>
    </div>
  );
}
```

## Parameters

<ParamField type="string">
  The ID of the space the report belongs to.
</ParamField>

<ParamField type="string">
  The ID of the report to action.
</ParamField>

<ParamField type="string">
  The ID of the reported entity.
</ParamField>

<ParamField type="Array<'remove-entity' | 'ban-user' | 'dismiss'>">
  One or more actions to take. Multiple actions are applied together.

  * `remove-entity` — Removes the entity from the space.
  * `ban-user` — Bans the entity's author from the space (requires `userId`).
  * `dismiss` — Marks the report as dismissed without taking action on the content.
</ParamField>

<ParamField type="string">
  A moderator note describing the action taken. Stored on the report record.
</ParamField>

<ParamField type="string">
  The ID of the user to ban. Required when `ban-user` is included in `actions`.
</ParamField>

<ParamField type="string">
  The reason for banning, if applicable.
</ParamField>

## Returns

Returns `Promise<{ message: string; code: string }>`.

## Notes

* This hook actions reports at the **space level** (space moderation). For platform-level entity moderation, see [`useModerateSpaceEntity`](/hooks/spaces/use-moderate-space-entity).
* To fetch the list of pending reports, use [`useFetchModeratedReports`](/hooks/reports/use-fetch-moderated-reports).


# useFetchManyReputationGrants
Source: https://docs.sublay.io/v7/hooks/reputation/use-fetch-many-reputation-grants

One-shot query for a page of reputation grants

## Overview

`useFetchManyReputationGrants` returns a callable that fetches one page of reputation grants. It is the low-level fetcher — for a ready-to-render list with accumulated state, `loadMore`, and `refresh`, use [`useFetchManyReputationGrantsWrapper`](/hooks/reputation/use-fetch-many-reputation-grants-wrapper).

Exactly one filter shape per call — by recipient, by sender, or by target. The shapes are mutually exclusive and are not AND-ed.

Only **positive** grants are ever returned. Negative grants are your app's private moderation deductions and are unreadable from every SDK surface.

Grants pointing at a **chat message** are private to their conversation — see [Chat-message targets](#chat-message-targets) below.

Requires the `reputation` bundle.

## Usage Example

```tsx theme={null}
import { useFetchManyReputationGrants } from "@sublay/react-js";

function useRecentRewards(userId: string) {
  const fetchManyReputationGrants = useFetchManyReputationGrants();

  return async () => {
    const { data, pagination } = await fetchManyReputationGrants({
      recipientId: userId,
      include: ["user"],
      limit: 25,
    });

    console.log(data.length, "of", pagination.totalItems);
    return data;
  };
}
```

## Parameters

<ParamField type="string">What this user received.</ParamField>
<ParamField type="string">What this user sent.</ParamField>

<ParamField type="&#x22;entity&#x22; | &#x22;comment&#x22; | &#x22;chat-message&#x22;">
  Who rewarded this item. Supplied together with `targetId`.
</ParamField>

<ParamField type="string">The rewarded record's ID. Supplied together with `targetType`.</ParamField>
<ParamField type="number">Page number (1-indexed). Defaults to `1`.</ParamField>
<ParamField type="number">Page size. Defaults to `20`; the maximum is `100`. A larger value is rejected by the server with `400 reputation-grant/invalid-query` rather than clamped.</ParamField>

<ParamField type="string | string[]">
  Associations to expand. Only `"user"` is supported — it hydrates **both** the sender and the recipient on every row.
</ParamField>

<ParamField type="object">
  Opt-in per-user space reputation on the hydrated users. This is a context surface, so `spaceReputation: { spaceId: "context" }` scores each user against *that grant's own* space. See [Reputation](/data-models/reputation#reading-space-scoped-reputation).
</ParamField>

## Returns

Returns a `Promise` resolving to the paginated envelope:

<ResponseField name="data" type="ReputationGrant[]">The page of [grants](/data-models/reputation-grant), newest first.</ResponseField>
<ResponseField name="pagination" type="{ page, pageSize, totalPages, totalItems, hasMore }">Page metadata.</ResponseField>

<ResponseField name="summary" type="GrantSummary | undefined">
  `{ total, count, viewerTotal }` for the target — returned **only** on the target filter shape, so a standalone "who rewarded this" view doesn't have to fetch the parent item to know the totals.
</ResponseField>

## Chat-message targets

A grant on a chat message is as private as the message, so it surfaces differently depending on the shape you query:

* `targetType: "chat-message"` returns rows only when the logged-in user is a **member** of that message's conversation — the same test the message read itself applies, so a user who has left the conversation still counts. Anyone else — a user who was never a member, or any user on a project without the `chat` bundle — gets a successful, empty result: `data` is `[]`, `pagination.totalItems` is `0`, and `summary` is `{ total: 0, count: 0, viewerTotal: 0 }`. It never throws, because an error would confirm the message exists.
* `recipientId` and `senderId` run the same test per row. A chat-message-targeted grant stays in the feed of someone who can see the message and drops out for someone who cannot — out of `data` and `pagination.totalItems` together, so a filtered page and a filtered total never disagree. A user's own "reputation I received" feed therefore includes the grants made on messages in their own conversations.
* Either shape hides the grants on a message moderation has removed, a member of the conversation included.

For the running totals on a message, ask the message read itself with `includeGrants: true` rather than paging this list.

## Failure Modes

The hook mirrors the server's filter rules locally, so a malformed query throws before the round trip rather than returning a `400`: it throws when there is no `projectId`, when no filter is supplied, when two shapes are combined, and when only one half of `targetType` / `targetId` is present.

## See Also

* [useFetchManyReputationGrantsWrapper](/hooks/reputation/use-fetch-many-reputation-grants-wrapper)
* [Reputation Grants Overview](/sdk/reputation/overview)
* [Fetch Many Reputation Grants API](/api-reference/reputation-grants/fetch-many-reputation-grants)


# useFetchManyReputationGrantsWrapper
Source: https://docs.sublay.io/v7/hooks/reputation/use-fetch-many-reputation-grants-wrapper

Stateful, paginated reputation-grants list with load-more and refresh

## Overview

`useFetchManyReputationGrantsWrapper` wraps [`useFetchManyReputationGrants`](/hooks/reputation/use-fetch-many-reputation-grants) into a ready-to-render list: it holds the accumulated `grants`, tracks `loading` / `hasMore`, keeps the target `summary`, and exposes `loadMore` and `refresh`.

Changing any filter prop (or calling `refresh`) resets the list to page 1.

The server requires exactly one filter shape. With none supplied — or with two — the hook stays **idle** rather than issuing a request it knows will fail: `grants` is empty, `summary` is `null`, `loading` is `false`, and `hasMore` is `false`. That makes it safe to mount with a `targetId` that hasn't resolved yet.

Requires the `reputation` bundle.

## Usage Example

```tsx theme={null}
import { useFetchManyReputationGrantsWrapper } from "@sublay/react-js";

function WhoRewardedThis({ commentId }: { commentId: string }) {
  const { grants, summary, loading, hasMore, loadMore, refresh } =
    useFetchManyReputationGrantsWrapper({
      targetType: "comment",
      targetId: commentId,
      include: ["user"],
      limit: 20,
    });

  return (
    <>
      <h4>
        {summary?.total ?? 0} points from {summary?.count ?? 0} people
      </h4>
      {grants.map((g) => (
        <div key={g.id}>
          {g.sender?.name ?? "Someone"} gave {g.amount}
          {g.note ? ` — "${g.note}"` : ""}
        </div>
      ))}
      {hasMore && (
        <button disabled={loading} onClick={loadMore}>
          Load more
        </button>
      )}
    </>
  );
}
```

Call `refresh` after issuing a grant to pull the new row and updated totals.

## Parameters

<ParamField type="string | null">What this user received.</ParamField>
<ParamField type="string | null">What this user sent.</ParamField>

<ParamField type="&#x22;entity&#x22; | &#x22;comment&#x22; | &#x22;chat-message&#x22; | null">
  Who rewarded this item. Supplied together with `targetId`.
</ParamField>

<ParamField type="string | null">The rewarded record's ID. Supplied together with `targetType`.</ParamField>
<ParamField type="number">Page size. Defaults to `10`. The server's maximum is `100`; a larger value is rejected with `400 reputation-grant/invalid-query` rather than clamped.</ParamField>

<ParamField type="string | string[]">
  Associations to expand. Only `"user"` is supported — it hydrates both the sender and the recipient.
</ParamField>

<ParamField type="object">
  Opt-in per-user space reputation on the hydrated users. `{ spaceId: "context" }` scores each user against that grant's own space. See [Reputation](/data-models/reputation#reading-space-scoped-reputation).
</ParamField>

## Returns

<ResponseField name="grants" type="ReputationGrant[]">The accumulated [grants](/data-models/reputation-grant), newest first.</ResponseField>

<ResponseField name="summary" type="GrantSummary | null">
  `{ total, count, viewerTotal }` for the target. Populated **only** on the target filter shape; `null` otherwise.
</ResponseField>

<ResponseField name="loading" type="boolean">`true` while fetching.</ResponseField>
<ResponseField name="hasMore" type="boolean">Whether more pages remain.</ResponseField>
<ResponseField name="loadMore" type="() => void">Advance to the next page and append.</ResponseField>
<ResponseField name="refresh" type="() => void">Re-run the query from page 1.</ResponseField>

<Note>
  **Chat-message targets are private to their conversation.** With `targetType: "chat-message"`, the list is populated only when the logged-in user is a member of that message's conversation — someone who has left it still counts; for anyone outside it, `grants` stays empty and `summary` comes back as `{ total: 0, count: 0, viewerTotal: 0 }` rather than erroring. The `recipientId` / `senderId` shapes apply the same test per row, so a user's own feed keeps the grants made on messages in their own conversations while a caller outside them never sees those rows. Grants on a message moderation has removed are hidden on both shapes, members included. See [useFetchManyReputationGrants](/hooks/reputation/use-fetch-many-reputation-grants#chat-message-targets).
</Note>

<Note>
  `summary` is set from the first page and is not re-read by `loadMore` — it describes the whole target, not the rows loaded so far. Because grant lists are never block-filtered, the rows you render always add up to it.
</Note>

## See Also

* [useFetchManyReputationGrants](/hooks/reputation/use-fetch-many-reputation-grants)
* [Reputation Grants Overview](/sdk/reputation/overview)
* [Fetch Many Reputation Grants API](/api-reference/reputation-grants/fetch-many-reputation-grants)


# Ask content
Source: https://docs.sublay.io/v7/hooks/search/use-ask-content

Ask a natural language question and stream a generated answer from project content

## Overview

Streams an AI-generated answer to a natural language question, grounded in your project's content. Uses SSE (Server-Sent Events) to deliver tokens incrementally. Returns source citations once the stream completes.

For integration guidance, see [Ask Content](/sdk/search/ask).

## Usage Example

```tsx theme={null}
import { useAskContent } from "@sublay/react-js";

function AskUI() {
  const { answer, sources, streaming, loading, error, ask, reset } = useAskContent();

  return (
    <div>
      <button onClick={() => ask({ query: "How do I reset my password?" })} disabled={loading || streaming}>
        Ask
      </button>
      {answer && <p>{answer}{streaming && " ▋"}</p>}
      {sources.map((s) => <div key={s.record.id}>[{s.sourceType}] {s.record.id}</div>)}
    </div>
  );
}
```

## Parameters

Call `ask` with:

<ParamField type="string">
  The natural language question.
</ParamField>

<ParamField type="(&#x22;entity&#x22; | &#x22;comment&#x22; | &#x22;message&#x22;)[]">
  Limit the content types searched for context.
</ParamField>

<ParamField type="string">
  Scope context lookup to a specific space.
</ParamField>

<ParamField type="boolean">
  Only applies with `spaceId`. When `true`, the context lookup also covers every space nested under it — children, grandchildren, the whole subtree at any depth — so you can ask across a community and all of its channels at once. Ignored without `spaceId`.
</ParamField>

<ParamField type="string">
  Scope context lookup to a specific conversation.
</ParamField>

<ParamField type="number">
  Maximum number of source records to use as context.
</ParamField>

<SpaceReputationParams />

## Returns

<ResponseField name="answer" type="string">
  The AI-generated answer. Grows token by token while `streaming` is `true`.
</ResponseField>

<ResponseField name="sources" type="ContentSearchResult[]">
  Source records used as context. Populated after streaming ends. When `spaceReputation` is requested, each record's embedded author carries an added `spaceReputation` number. See [Reputation](/data-models/reputation).
</ResponseField>

<ResponseField name="streaming" type="boolean">
  `true` while the SSE stream is open and tokens are arriving.
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` from `ask()` call until the first token arrives.
</ResponseField>

<ResponseField name="error" type="string | null">
  Error message if the request failed.
</ResponseField>

<ResponseField name="ask" type="(props) => void">
  Starts a new question. Aborts any in-flight stream first.
</ResponseField>

<ResponseField name="reset" type="() => void">
  Aborts in-flight stream and clears all state.
</ResponseField>

<Note>
  In React Native, SSE streaming requires polyfills for `fetch`, `ReadableStream`, and `TextDecoder`. Install `react-native-fetch-api`, `web-streams-polyfill@^3`, `react-native-polyfill-globals`, and `text-encoding`, then call the targeted sub-polyfills once at app startup, before using this hook:

  ```ts theme={null}
  import { polyfill as polyfillEncoding } from "react-native-polyfill-globals/src/encoding";
  import { polyfill as polyfillReadableStream } from "react-native-polyfill-globals/src/readable-stream";
  import { polyfill as polyfillFetch } from "react-native-polyfill-globals/src/fetch";

  polyfillEncoding();
  polyfillReadableStream();
  polyfillFetch(); // last, so it wins over the built-in fetch
  ```

  Prefer these targeted polyfills over the all-in-one `polyfillGlobals()`: that helper also pulls in `react-native-get-random-values`, a native module that forces a development-client rebuild. The three above are pure JavaScript, so a Metro reload is enough. Pin `web-streams-polyfill` to v3 — v4 removed the `ponyfill/es6` subpath that `react-native-polyfill-globals` requires.
</Note>


# Match users
Source: https://docs.sublay.io/v7/hooks/search/use-match-users

Match people by activity-derived interest facets, passively or by topic

## Overview

Returns state and a `match` function for ranking users by **activity-derived interest facets**. In `passive` mode it matches against the current user's own facets ("who is like me?"); in `directed` mode it matches against a free-text topic ("who is into biotech?").

For setup and the underlying model, see the [Interest Matching](/v7/interest-matching) guide.

## Usage Example

```tsx theme={null}
import { useMatchUsers } from "@sublay/react-js";

function PeopleForYou() {
  const { results, loading, match } = useMatchUsers();

  return (
    <div>
      <button onClick={() => match({ mode: "passive", limit: 10 })}>
        Find people like me
      </button>
      {results.map((r) => (
        <div key={r.user.id}>
          {r.user.name} — {r.score.toFixed(2)}
        </div>
      ))}
    </div>
  );
}
```

## Parameters

Call `match` with:

<ParamField type="'passive' | 'directed'">
  `"passive"` matches against the current user's facets; `"directed"` matches against `query`.
</ParamField>

<ParamField type="string">
  The free-text topic to match against. Required in `directed` mode; must be non-empty (a blank directed query is a no-op). Not used in `passive` mode.
</ParamField>

<ParamField type="number">
  Maximum number of matched users (max `50`).
</ParamField>

<ParamField type="string">
  Restrict candidates to users active in this space.
</ParamField>

<ParamField type="boolean">
  With `spaceId`, also include users active in the space's subtree.
</ParamField>

<ParamField type="boolean">
  Request illustrative sample content per matched facet (only honored when the project has `exposeSampleContent` enabled).
</ParamField>

<ParamField type="boolean">
  Exclude the current user from results. Defaults to `true` server-side.
</ParamField>

## Returns

<ResponseField name="results" type="UserMatchResult[]">
  Ranked matches (descending by `score`).

  <Expandable title="UserMatchResult properties">
    <ResponseField name="user" type="User">
      The matched user. See [User data model](/data-models/user).
    </ResponseField>

    <ResponseField name="score" type="number">
      Aggregate match score.
    </ResponseField>

    <ResponseField name="matchedFacets" type="MatchedFacet[]">
      Per-facet breakdown: `similarity`, `candidateFacet` (), `askerFacet` (present in passive mode), and `sampleContent` (only when both sample gates are on).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` while a match is in progress.
</ResponseField>

<ResponseField name="error" type="string | null">
  Error message if the last match failed.
</ResponseField>

<ResponseField name="match" type="(props) => Promise<void>">
  Executes the match and updates `results`.
</ResponseField>

<ResponseField name="reset" type="() => void">
  Clears `results` and `error`.
</ResponseField>


# Search content
Source: https://docs.sublay.io/v7/hooks/search/use-search-content

Semantic search over entities, comments, and messages

## Overview

Returns state and a `search` function for executing natural language searches over project content. Supports filtering by content type and scoping by space or conversation.

For integration guidance, see [Semantic Search](/sdk/search/semantic-search).

## Usage Example

```tsx theme={null}
import { useSearchContent } from "@sublay/react-js";

function Search() {
  const { results, loading, search, reset } = useSearchContent();

  return (
    <div>
      <button onClick={() => search({ query: "onboarding tips", sourceTypes: ["entity"] })}>
        Search
      </button>
      {results.map((r) => (
        <div key={r.record.id}>{r.sourceType} — {r.similarity.toFixed(3)}</div>
      ))}
    </div>
  );
}
```

## Parameters

This hook returns an object. Call `search` with:

<ParamField type="string">
  The natural language query string.
</ParamField>

<ParamField type="(&#x22;entity&#x22; | &#x22;comment&#x22; | &#x22;message&#x22;)[]">
  Limit results to specific content types. Omit to search all types.
</ParamField>

<ParamField type="string">
  Scope results to a specific space.
</ParamField>

<ParamField type="boolean">
  Only applies with `spaceId`. When `true`, results also cover every space nested under it — children, grandchildren, the whole subtree at any depth — not just the named space. Ignored without `spaceId`.
</ParamField>

<ParamField type="string">
  Scope results to a specific conversation.
</ParamField>

<ParamField type="number">
  Maximum number of results to return.
</ParamField>

<SpaceReputationParams />

## Returns

<ResponseField name="results" type="ContentSearchResult[]">
  Ranked search results.

  <Expandable title="ContentSearchResult properties">
    <ResponseField name="sourceType" type="&#x22;entity&#x22; | &#x22;comment&#x22; | &#x22;message&#x22;">
      The type of the matched record.
    </ResponseField>

    <ResponseField name="similarity" type="number">
      Cosine similarity score (0–1).
    </ResponseField>

    <ResponseField name="record" type="Entity | Comment | ChatMessage">
      The full matched record. When `spaceReputation` is requested, its embedded author carries an added `spaceReputation` number. See [Reputation](/data-models/reputation).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` while a search request is in progress.
</ResponseField>

<ResponseField name="error" type="string | null">
  Error message if the last search failed, otherwise `null`.
</ResponseField>

<ResponseField name="search" type="(props: UseSearchContentProps) => Promise<void>">
  Executes the search and updates `results`.
</ResponseField>

<ResponseField name="reset" type="() => void">
  Clears `results` and `error`.
</ResponseField>


# Search spaces
Source: https://docs.sublay.io/v7/hooks/search/use-search-spaces

Semantic search for spaces by natural language query

## Overview

Returns state and a `search` function for finding spaces by natural language query. Matches against space name, description, and other text fields using vector similarity.

For integration guidance, see [Semantic Search](/sdk/search/semantic-search).

<Note>
  Only `public` spaces are returned. `unlisted` and `private` spaces are never surfaced in search results for non-members. Hidden spaces stay indexed but filtered out, so re-listing a space (setting it back to `"public"`) makes it searchable again immediately. See [Space visibility](/data-models/space#visibility).
</Note>

## Usage Example

```tsx theme={null}
import { useSearchSpaces } from "@sublay/react-js";

function SpaceSearch() {
  const { results, loading, search } = useSearchSpaces();

  return (
    <div>
      <button onClick={() => search({ query: "photography communities", limit: 10 })}>
        Search
      </button>
      {results.map((r) => (
        <div key={r.record.id}>{r.record.name} — {r.similarity.toFixed(3)}</div>
      ))}
    </div>
  );
}
```

## Parameters

Call `search` with:

<ParamField type="string">
  The natural language query string.
</ParamField>

<ParamField type="number">
  Maximum number of results to return.
</ParamField>

## Returns

<ResponseField name="results" type="SpaceSearchResult[]">
  Ranked space results.

  <Expandable title="SpaceSearchResult properties">
    <ResponseField name="similarity" type="number">
      Cosine similarity score (0–1).
    </ResponseField>

    <ResponseField name="record" type="Space">
      The matched space. See [Space data model](/data-models/space).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` while a search is in progress.
</ResponseField>

<ResponseField name="error" type="string | null">
  Error message if the last search failed.
</ResponseField>

<ResponseField name="search" type="(props) => Promise<void>">
  Executes the search and updates `results`.
</ResponseField>

<ResponseField name="reset" type="() => void">
  Clears `results` and `error`.
</ResponseField>


# Search users
Source: https://docs.sublay.io/v7/hooks/search/use-search-users

Semantic search for users by natural language query

## Overview

Returns state and a `search` function for finding users by natural language query. Matches against user profile text (name, username, bio, etc.) using vector similarity.

For integration guidance, see [Semantic Search](/sdk/search/semantic-search).

## Usage Example

```tsx theme={null}
import { useSearchUsers } from "@sublay/react-js";

function UserSearch() {
  const { results, loading, search } = useSearchUsers();

  return (
    <div>
      <button onClick={() => search({ query: "frontend developers", limit: 10 })}>
        Search
      </button>
      {results.map((r) => (
        <div key={r.record.id}>{r.record.name} — {r.similarity.toFixed(3)}</div>
      ))}
    </div>
  );
}
```

## Parameters

Call `search` with:

<ParamField type="string">
  The natural language query string.
</ParamField>

<ParamField type="number">
  Maximum number of results to return.
</ParamField>

## Returns

<ResponseField name="results" type="UserSearchResult[]">
  Ranked user results.

  <Expandable title="UserSearchResult properties">
    <ResponseField name="similarity" type="number">
      Cosine similarity score (0–1).
    </ResponseField>

    <ResponseField name="record" type="User">
      The matched user profile. See [User data model](/data-models/user).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` while a search is in progress.
</ResponseField>

<ResponseField name="error" type="string | null">
  Error message if the last search failed.
</ResponseField>

<ResponseField name="search" type="(props) => Promise<void>">
  Executes the search and updates `results`.
</ResponseField>

<ResponseField name="reset" type="() => void">
  Clears `results` and `error`.
</ResponseField>


# Upload file
Source: https://docs.sublay.io/v7/hooks/storage/use-upload-file

Upload a generic file (document, video, or other) without server-side processing

## Overview

Uploads a file to Sublay storage without any server-side processing. The raw file is stored and a proxy URL is returned. Use this for PDFs, videos, Office documents, or any file type where you don't need variant generation.

For images that need resizing or format conversion, use [`useUploadImage`](/hooks/storage/use-upload-image) instead.

<Note>Requires an authenticated user. The hook uses the private axios instance and will throw if no session is active.</Note>

## Usage Example

```tsx theme={null}
import { useUploadFile } from "@sublay/react-js";

function DocumentUploader({ entityId }: { entityId: string }) {
  const uploadFile = useUploadFile();

  const handleFile = async (file: File) => {
    const result = await uploadFile(file, ["documents", entityId], {
      entityId,
      metadata: { label: "Attachment" },
    });

    console.log(result.publicPath); // Use this URL to reference the file
  };

  return <input type="file" onChange={e => e.target.files && handleFile(e.target.files[0])} />;
}
```

## Parameters

`uploadFile(file, pathParts, options?)` accepts three arguments:

<ParamField type="BrowserFile | RNFile">
  The file to upload. In the browser, pass a standard `File` object. In React Native, pass `{ uri, name, type? }`.
</ParamField>

<ParamField type="string[]">
  Storage path segments. The file is stored under the joined path, with a UUID sub-folder appended automatically for uniqueness. For example, `["documents", "user-123"]` stores the file at `documents/user-123/<uuid>/<filename>`.
</ParamField>

<ParamField type="UploadFileOptions">
  Optional associations and metadata.
</ParamField>

### Options

<ParamField type="string">
  Associates the file with an entity. The file is deleted when the entity is deleted.
</ParamField>

<ParamField type="string">
  Associates the file with a comment. The file is deleted when the comment is deleted.
</ParamField>

<ParamField type="string">
  Associates the file with a space.
</ParamField>

<ParamField type="number">
  Display order when a record has multiple attachments. Defaults to `0`.
</ParamField>

<ParamField type="Record<string, any>">
  Custom key-value data stored alongside the file record.
</ParamField>

## Returns

The hook returns the `uploadFile` function directly (no state wrappers). The function returns a `Promise<UploadResponse>`:

```ts theme={null}
{
  fileId: string;
  type: "image" | "video" | "document" | "other"; // Inferred from MIME type
  relativePath: string;    // Internal storage path
  publicPath: string;      // Proxy URL for client access
  size: number;            // Bytes
  mimeType: string;
  createdAt: string;       // ISO 8601
}
```

<Note>The `type` field is inferred automatically from the file's MIME type. PDFs and Office documents become `"document"`, video files become `"video"`, images become `"image"`, and everything else becomes `"other"`.</Note>


# Upload image
Source: https://docs.sublay.io/v7/hooks/storage/use-upload-image

Upload an image with server-side processing and named variant generation

## Overview

Uploads an image to Sublay storage. The server processes the image using Sharp, generates named variants according to the specified mode, and returns an [`Image`](/data-models/file) object with proxy URLs for all variants.

Works in both browser and React Native environments. Provides upload progress tracking.

<Note>Requires an authenticated user. The hook uses the private axios instance and will throw if no session is active.</Note>

## Usage Example

```tsx theme={null}
import { useUploadImage } from "@sublay/react-js";

function AvatarUploader() {
  const { uploadImage, uploading, progress } = useUploadImage();

  const handleFile = async (file: File) => {
    const image = await uploadImage(file, {
      mode: "exact-dimensions",
      dimensions: {
        avatar: { width: 200, height: 200 },
        thumbnail: { width: 64, height: 64 },
      },
      format: "webp",
      quality: 85,
    });

    console.log(image.original.publicPath);
    console.log(image.variants.avatar.publicPath);
  };

  return (
    <div>
      <input type="file" accept="image/*" onChange={e => e.target.files && handleFile(e.target.files[0])} />
      {uploading && <p>Uploading... {progress}%</p>}
    </div>
  );
}
```

## Parameters

`uploadImage(file, options)` accepts two arguments:

<ParamField type="BrowserFile | RNFile">
  The image to upload. In the browser, pass a standard `File` object. In React Native, pass `{ uri, name, type? }`.
</ParamField>

<ParamField type="UploadImageOptions">
  Processing configuration. Must include a `mode` field. See [Processing Modes](#processing-modes) below.
</ParamField>

### Common Options (all modes)

<ParamField type="number">
  JPEG/WebP quality, 1–100. Defaults to `85`.
</ParamField>

<ParamField type="&#x22;webp&#x22; | &#x22;jpeg&#x22; | &#x22;png&#x22; | &#x22;original&#x22;">
  Output format for all variants. Defaults to `"webp"`.
</ParamField>

<ParamField type="boolean">
  Whether to remove EXIF metadata from the output. Defaults to `true`.
</ParamField>

<ParamField type="string[]">
  Storage path segments. The file is stored under the joined path. Defaults to `["images", <fileId>]`.
</ParamField>

<ParamField type="string">
  Associates the file with an entity for cascade deletion.
</ParamField>

<ParamField type="string">
  Associates the file with a comment for cascade deletion.
</ParamField>

<ParamField type="string">
  Associates the file with a space for cascade deletion.
</ParamField>

<ParamField type="(progress: number) => void">
  Called with upload percentage (0–100) during the multipart upload.
</ParamField>

## Processing Modes

### `exact-dimensions`

Each variant has an explicit pixel width and height.

```ts theme={null}
{
  mode: "exact-dimensions",
  dimensions: {
    thumbnail: { width: 64, height: 64 },
    card:      { width: 400, height: 300 },
  },
  fit?: "cover" | "contain" | "inside" | "outside", // default: "cover"
}
```

### `aspect-ratio-width-based`

All variants share a fixed aspect ratio. You specify widths; heights are computed.

```ts theme={null}
{
  mode: "aspect-ratio-width-based",
  aspectRatio: { width: 16, height: 9 },
  widths: { small: 320, medium: 640, large: 1280 },
  fit?: "cover" | "contain" | "inside" | "outside",
}
```

### `aspect-ratio-height-based`

All variants share a fixed aspect ratio. You specify heights; widths are computed.

```ts theme={null}
{
  mode: "aspect-ratio-height-based",
  aspectRatio: { width: 1, height: 1 },
  heights: { small: 100, medium: 200 },
  fit?: "cover" | "contain" | "inside" | "outside",
}
```

### `original-aspect`

Preserves the original image's aspect ratio. You specify the longest-edge size for each variant.

```ts theme={null}
{
  mode: "original-aspect",
  sizes: { thumbnail: 100, medium: 400, full: 1200 },
  fit?: "inside" | "outside",
}
```

### `multi-aspect-ratio`

Generates variants across multiple aspect ratios with explicit sizes.

```ts theme={null}
{
  mode: "multi-aspect-ratio",
  aspectRatios: [{ width: 1, height: 1 }, { width: 16, height: 9 }],
  sizes: { small: 200, large: 800 },
  fit?: "cover" | "contain" | "inside" | "outside",
}
```

## Returns

<ResponseField name="uploadImage" type="(file, options) => Promise<Image>">
  Async function that performs the upload and returns an [`Image`](/data-models/file) object on success.
</ResponseField>

<ResponseField name="uploading" type="boolean">
  `true` while the upload is in progress.
</ResponseField>

<ResponseField name="progress" type="number">
  Upload percentage (0–100). Resets to `0` when the upload finishes.
</ResponseField>

## Return Value Shape (`Image`)

```ts theme={null}
{
  fileId: string;
  imageId: string;         // Same as fileId
  status: "completed" | "failed";
  original: ImageVariant;  // { path, publicPath, width, height, size, format }
  variants: Record<string, ImageVariant>;
  metadata: {
    originalFormat: string;
    originalSize: number;
    exifStripped: boolean;
    processingTime: number; // ms
  };
  createdAt: string;       // ISO 8601
}
```


# Use table
Source: https://docs.sublay.io/v7/hooks/tables/use-table

Read and mutate a custom table's rows with pagination, sorting, filtering, and soft-delete

## Overview

`useTable` is the React/React Native hook for a custom table's rows, backed by RTK Query against the `/db` surface. It returns the current page of rows plus loading/refetch state, query controls, and row CRUD actions. The query knobs (page, limit, sort, filters, `includeDeleted`) are stored in the `tables` Redux slice keyed by table name, so multiple consumers of the same table share one view.

See [Custom Tables — Overview](/v7/sdk/tables/overview) for a guide, and [Custom Tables](/v7/custom-tables) for the feature concept.

## Usage Example

```tsx theme={null}
import { useTable } from "@sublay/react-js";

interface EventRow {
  id: string;
  name: string;
  capacity: number;
  createdAt: string;
}

function Events() {
  const {
    rows,
    pagination,
    loading,
    setPage,
    setSort,
    setFilters,
    createRow,
    updateRow,
    deleteRow,
  } = useTable<EventRow>("Events");

  return (
    <>
      {loading && <Spinner />}
      {rows.map((e) => (
        <Row key={e.id} event={e} onSave={(d) => updateRow(e.id, d)} onDelete={() => deleteRow(e.id)} />
      ))}
      {pagination?.hasMore && <button onClick={() => setPage(pagination.page + 1)}>Next</button>}
    </>
  );
}
```

## Parameters

<ParamField type="string">
  The **logical** custom-table name (without the `custom_` prefix). Must be stable across renders.
</ParamField>

<ParamField type="Partial<TableViewState>">
  Optional initial view — any of `page`, `limit`, `sortBy`, `sortDir`, `filters`, `includeDeleted`. Used to seed the stored view the first time this table is read.
</ParamField>

## Return Values

<ResponseField name="rows" type="T[]">
  The current page of rows.
</ResponseField>

<ResponseField name="pagination" type="PaginationMetadata | null">
  Pagination metadata (`page`, `pageSize`, `totalPages`, `totalItems`, `hasMore`), or `null` before the first load.
</ResponseField>

<ResponseField name="loading" type="boolean">
  `true` while the current query is in flight.
</ResponseField>

<ResponseField name="error" type="unknown">
  The query error, if any.
</ResponseField>

<ResponseField name="refetch" type="() => void">
  Re-runs the current query.
</ResponseField>

<ResponseField name="view" type="TableViewState">
  The current stored view: `{ page, limit, sortBy, sortDir, filters, includeDeleted }`.
</ResponseField>

<ResponseField name="setView" type="(view: Partial<TableViewState>) => void">
  Merge-updates the stored view.
</ResponseField>

<ResponseField name="setPage" type="(page: number) => void">
  Changes the current page.
</ResponseField>

<ResponseField name="setFilters" type="(filters: DbFilter[]) => void">
  Replaces the filter clauses (and resets to page 1). Each clause is `{ column, operator, value }`; operators are `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `contains`, `like`, `isNull`, AND-combined.
</ResponseField>

<ResponseField name="setSort" type="(sortBy?: string, sortDir?: 'asc' | 'desc') => void">
  Sets the sort column/direction (and resets to page 1).
</ResponseField>

<ResponseField name="setIncludeDeleted" type="(includeDeleted: boolean) => void">
  On a paranoid table, toggles whether soft-deleted rows are included (resets to page 1).
</ResponseField>

<ResponseField name="createRow" type="(data: Record<string, unknown>) => Promise<T>">
  Inserts a row. Managed columns (`id`/`createdAt`/`updatedAt`/`deletedAt`) are server-set and rejected from the body.
</ResponseField>

<ResponseField name="updateRow" type="(rowId: string, data: Record<string, unknown>) => Promise<T>">
  Updates a row; `updatedAt` is bumped automatically on a timestamped table.
</ResponseField>

<ResponseField name="deleteRow" type="(rowId: string, opts?: { force?: boolean }) => Promise<{ deleted: boolean; soft: boolean }>">
  Deletes a row. Soft-deletes on a paranoid table by default; pass `{ force: true }` to hard-delete.
</ResponseField>

<ResponseField name="restoreRow" type="(rowId: string) => Promise<T>">
  Clears `deletedAt` on a soft-deleted row (paranoid tables only).
</ResponseField>


# Count Unread Notifications
Source: https://docs.sublay.io/v7/api-reference/app-notifications/count-unread

GET /v7/:projectId/app-notifications/count
Get the number of unread app notifications for the authenticated user

Returns a single integer representing the total number of unread app notifications for the currently authenticated user. Use this to populate notification badge counts in your UI.

<Note>
  This endpoint requires an authenticated user. Include a valid `Authorization: Bearer <accessToken>` header.
</Note>

## Response

Returns HTTP `200` with a plain integer (not a JSON object):

```json theme={null}
7
```

## Error Responses

<AccordionGroup>
  <Accordion title="Missing token — 401">
    No `Authorization` header was sent. The body is `text/plain`, not JSON:

    ```text theme={null}
    Unauthorized
    ```
  </Accordion>

  <Accordion title="Expired or invalid token — 403">
    The header was sent but the token failed verification. Refresh the access
    token and retry. The body is `text/plain`, not JSON:

    ```text theme={null}
    Forbidden
    ```
  </Accordion>
</AccordionGroup>

## See Also

* [`useAppNotifications` hook](/hooks/app-notifications/use-app-notifications) — exposes `unreadCount` directly
* [Fetch Notifications](/api-reference/app-notifications/fetch-notifications)


# Fetch Notifications
Source: https://docs.sublay.io/v7/api-reference/app-notifications/fetch-notifications

GET /v7/:projectId/app-notifications
Get a paginated list of app notifications for the authenticated user

Returns a paginated list of app notifications for the currently authenticated user, ordered newest first. Notifications are scoped to the calling user — a user cannot read another user's notifications.

<Note>
  This endpoint requires an authenticated user. Include a valid `Authorization: Bearer <accessToken>` header.
</Note>

## Query Parameters

<ParamField type="number">
  Page number (1-indexed).
</ParamField>

<ParamField type="number">
  Number of results per page. Maximum `50`.
</ParamField>

## Response

Returns a paginated envelope containing an array of notification objects.

<ResponseField name="data" type="array">
  List of app notification objects.

  <Expandable title="AppNotification properties">
    <ResponseField name="id" type="string">
      Unique notification ID (UUID).
    </ResponseField>

    <ResponseField name="projectId" type="string">
      ID of the project this notification belongs to.
    </ResponseField>

    <ResponseField name="userId" type="string">
      ID of the user this notification belongs to.
    </ResponseField>

    <ResponseField name="type" type="string">
      Notification type string (e.g., `"new-follower"`, `"comment-reply"`). Defined by your webhook integration.
    </ResponseField>

    <ResponseField name="action" type="string">
      Deep-link action string used by the client to route the user when the notification is tapped.
    </ResponseField>

    <ResponseField name="isRead" type="boolean">
      Whether the user has marked this notification as read.
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Arbitrary key-value data attached to the notification. Contents depend on the notification type.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp when the notification was created.
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      ISO 8601 timestamp when the notification was last updated.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination metadata.

  <Expandable title="properties">
    <ResponseField name="page" type="number">Current page number.</ResponseField>
    <ResponseField name="pageSize" type="number">Number of results per page.</ResponseField>
    <ResponseField name="totalPages" type="number">Total number of pages.</ResponseField>
    <ResponseField name="totalItems" type="number">Total number of notifications.</ResponseField>
    <ResponseField name="hasMore" type="boolean">Whether more pages exist after this one.</ResponseField>
  </Expandable>
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="Missing token — 401">
    No `Authorization` header was sent. The body is `text/plain`, not JSON:

    ```text theme={null}
    Unauthorized
    ```
  </Accordion>

  <Accordion title="Expired or invalid token — 403">
    The header was sent but the token failed verification. Refresh the access
    token and retry. The body is `text/plain`, not JSON:

    ```text theme={null}
    Forbidden
    ```
  </Accordion>

  <Accordion title="Invalid Query — 400">
    ```json theme={null}
    {
      "error": "...",
      "code": "app-notification/invalid-query"
    }
    ```
  </Accordion>
</AccordionGroup>

## See Also

* [`useAppNotifications` hook](/hooks/app-notifications/use-app-notifications)
* [App Notifications overview](/sdk/app-notifications/overview)


# Mark All Notifications as Read
Source: https://docs.sublay.io/v7/api-reference/app-notifications/mark-all-as-read

PATCH /v7/:projectId/app-notifications/mark-all-as-read
Mark all unread notifications as read for the authenticated user

Marks all unread notifications as read for the currently authenticated user. Only notifications that are currently `isRead: false` are updated.

<Note>
  This endpoint requires an authenticated user. Include a valid `Authorization: Bearer <accessToken>` header.
</Note>

## Response

Returns HTTP `200` with the number of notifications that were updated:

<ResponseField name="markedAsRead" type="number">
  The count of notifications that were updated from unread to read. Returns `0` if there were no unread notifications.
</ResponseField>

**Example:**

```json theme={null}
{
  "markedAsRead": 12
}
```

## Error Responses

<AccordionGroup>
  <Accordion title="Missing token — 401">
    No `Authorization` header was sent. The body is `text/plain`, not JSON:

    ```text theme={null}
    Unauthorized
    ```
  </Accordion>

  <Accordion title="Expired or invalid token — 403">
    The header was sent but the token failed verification. Refresh the access
    token and retry. The body is `text/plain`, not JSON:

    ```text theme={null}
    Forbidden
    ```
  </Accordion>
</AccordionGroup>

## See Also

* [Mark Single Notification as Read](/api-reference/app-notifications/mark-as-read)
* [`useAppNotifications` hook](/hooks/app-notifications/use-app-notifications)


# Mark Notification as Read
Source: https://docs.sublay.io/v7/api-reference/app-notifications/mark-as-read

PATCH /v7/:projectId/app-notifications/:notificationId/mark-as-read
Mark a single notification as read by its ID

Marks a specific notification as read. The notification must belong to the authenticated user — users cannot mark another user's notifications as read.

<Note>
  This endpoint requires an authenticated user. Include a valid `Authorization: Bearer <accessToken>` header.
</Note>

## Path Parameters

<ParamField type="string">
  The UUID of the notification to mark as read.
</ParamField>

## Response

Returns HTTP `200` on success with no response body.

## Error Responses

<AccordionGroup>
  <Accordion title="Notification Not Found — 404">
    ```json theme={null}
    {
      "error": "Notification not found",
      "code": "app-notification/not-found"
    }
    ```

    Returned when the notification does not exist or does not belong to the authenticated user.
  </Accordion>

  <Accordion title="Invalid Params — 400">
    ```json theme={null}
    {
      "error": "...",
      "code": "app-notification/invalid-params"
    }
    ```

    Returned when `notificationId` is not a valid UUID.
  </Accordion>

  <Accordion title="Missing token — 401">
    No `Authorization` header was sent. The body is `text/plain`, not JSON:

    ```text theme={null}
    Unauthorized
    ```
  </Accordion>

  <Accordion title="Expired or invalid token — 403">
    The header was sent but the token failed verification. Refresh the access
    token and retry. The body is `text/plain`, not JSON:

    ```text theme={null}
    Forbidden
    ```
  </Accordion>
</AccordionGroup>

## See Also

* [Mark All Notifications as Read](/api-reference/app-notifications/mark-all-as-read)
* [`useAppNotifications` hook](/hooks/app-notifications/use-app-notifications)


# Fetch Blocked Users
Source: https://docs.sublay.io/v7/api-reference/blocks/fetch-blocks

GET /v7/:projectId/blocks
Get the acting user's own paginated list of blocked users

Returns a paginated list of the users the acting user has blocked (their **outbound** blocks), each row carrying a public summary of the blocked user. This is the private "manage / way back to unblock" surface.

<Warning>
  A block list is **private** — only the blocker can read their own list. It exposes only the caller's outbound blocks; there is no way to read who has blocked the caller.
</Warning>

<Note>
  **Requires the `moderation` bundle.** A project without the moderation bundle returns `403 database/tables-not-available`. See [Bundles](/bundles).
</Note>

## Query Parameters

<ParamField type="number">
  Page number for pagination.
</ParamField>

<ParamField type="number">
  Number of results per page. Max `100`.
</ParamField>

<ParamField type="string">
  The user whose own block list to read (the blocker). Only service/master keys may supply a `userId` other than the caller's own; with a user token the subject is derived from the token.
</ParamField>

## Response

On success, returns HTTP `200` with a paginated response:

<ResponseField name="data" type="array">
  Array of block entries.

  <Expandable title="item properties">
    <ResponseField name="id" type="string">
      ID of the block record.
    </ResponseField>

    <ResponseField name="blockedUser" type="object">
      Public profile of the blocked user. Sensitive fields (email, hash, salt, secureMetadata, etc.) are excluded. May be `null` if the user is unavailable.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO timestamp of when the block was created.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination metadata.

  <Expandable title="properties">
    <ResponseField name="page" type="number">
      Current page number.
    </ResponseField>

    <ResponseField name="pageSize" type="number">
      Number of items per page.
    </ResponseField>

    <ResponseField name="totalItems" type="number">
      Total number of blocked users.
    </ResponseField>

    <ResponseField name="totalPages" type="number">
      Total number of pages.
    </ResponseField>

    <ResponseField name="hasMore" type="boolean">
      Whether there are more pages after the current one.
    </ResponseField>
  </Expandable>
</ResponseField>

## See Also

* [`useFetchBlockedUsers` hook](/hooks/blocks/use-fetch-blocked-users)
* [Block User](/api-reference/users/blocks/block-user)
* [Block data model](/data-models/block)


# Create Direct Conversation
Source: https://docs.sublay.io/v7/api-reference/chat/conversations/create-direct

POST /v7/:projectId/chat/conversations/direct
Get or create a 1:1 direct conversation with another user

Returns an existing DM between the caller and the target user, or creates one if it does not yet exist. Only one direct conversation can exist per user pair per project — this endpoint is idempotent.

Returns `201` when a new conversation was created, `200` when an existing one was found.

## Body Parameters

<ParamField type="string">
  The ID of the user to start a direct conversation with. Must belong to the same project.
</ParamField>

## Response

Returns a [Conversation](/data-models/conversation) object with `type: "direct"`.

<Note>
  Direct conversations cannot be updated or deleted, and members cannot leave them. They persist as long as either user's account exists.
</Note>

## Error Responses

<AccordionGroup>
  <Accordion title="Invalid Member — 400 Bad Request">
    ```json theme={null}
    { "error": "Target user does not belong to this project.", "code": "chat/invalid-member" }
    ```
  </Accordion>
</AccordionGroup>


# Create Group Conversation
Source: https://docs.sublay.io/v7/api-reference/chat/conversations/create-group

POST /v7/:projectId/chat/conversations
Create a new multi-member group conversation

Creates a group conversation. The caller is automatically added as an `admin`. All provided `memberIds` are validated to belong to the project and added as `member`.

## Body Parameters

<ParamField type="string">
  Must be `"group"`.
</ParamField>

<ParamField type="string">
  Display name of the conversation. Maximum 200 characters. Optional.
</ParamField>

<ParamField type="string">
  Optional description for the conversation. Maximum 1000 characters.
</ParamField>

<ParamField type="string[]">
  Array of user IDs to add to the conversation. Defaults to `[]`. The caller's own ID is ignored if included — they are always added as admin. All IDs must belong to the same project.
</ParamField>

<ParamField type="object">
  Custom key-value data to attach to the conversation. Optional.
</ParamField>

## Response

Returns the created [Conversation](/data-models/conversation) object with HTTP `201`.

## Error Responses

<AccordionGroup>
  <Accordion title="Invalid Member — 400 Bad Request">
    ```json theme={null}
    { "error": "User 'abc' does not belong to this project.", "code": "chat/invalid-member" }
    ```

    One or more provided user IDs do not exist in this project.
  </Accordion>
</AccordionGroup>


# Delete Conversation
Source: https://docs.sublay.io/v7/api-reference/chat/conversations/delete-conversation

DELETE /v7/:projectId/chat/conversations/:conversationId
Delete a group or space conversation and all its messages

Permanently deletes a conversation and all associated messages, members, reactions, and file attachments. This action is irreversible.

Direct conversations (`type: "direct"`) cannot be deleted.

**Authorization:**

* `group` conversations: caller must be an active `admin` member.
* `space` conversations: caller must have `admin` role in the parent Space.

## Path Parameters

<ParamField type="string">
  The ID of the conversation to delete.
</ParamField>

## Response

```json theme={null}
{ "message": "Conversation deleted." }
```

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Conversation not found.", "code": "chat/not-found" }
    ```
  </Accordion>

  <Accordion title="Cannot Delete DM — 400 Bad Request">
    ```json theme={null}
    { "error": "Direct conversations cannot be deleted.", "code": "chat/cannot-delete-dm" }
    ```
  </Accordion>

  <Accordion title="Forbidden (group) — 403">
    ```json theme={null}
    { "error": "Only group admins can delete this conversation.", "code": "chat/not-a-member" }
    ```
  </Accordion>

  <Accordion title="Forbidden (space) — 403">
    ```json theme={null}
    { "error": "Only space admins can delete the space conversation.", "code": "chat/not-a-member" }
    ```
  </Accordion>
</AccordionGroup>


# Fetch Conversation
Source: https://docs.sublay.io/v7/api-reference/chat/conversations/fetch-conversation

GET /v7/:projectId/chat/conversations/:conversationId
Fetch a single conversation by ID

Returns a [Conversation](/data-models/conversation) object with the caller's membership row and active member count included.

## Path Parameters

<ParamField type="string">
  The ID of the conversation to fetch.
</ParamField>

## Response

Returns a [Conversation](/data-models/conversation) with two additional fields:

<ResponseField name="currentMember" type="ConversationMember | null">
  The calling user's membership row for this conversation. `null` if the user has no membership record.
</ResponseField>

<ResponseField name="memberCount" type="number">
  Number of currently active members.
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Conversation not found.", "code": "chat/not-found" }
    ```
  </Accordion>
</AccordionGroup>


# List Conversations
Source: https://docs.sublay.io/v7/api-reference/chat/conversations/list-conversations

GET /v7/:projectId/chat/conversations
Get the current user's conversations, ordered by most recent activity

Returns a cursor-paginated list of `ConversationPreview` objects for the authenticated user. Only active memberships are included. Results are ordered by `lastMessageAt` descending (conversations with no messages appear last, ordered by `createdAt`).

## Query Parameters

<ParamField type="string">
  Comma-separated list of conversation types to include. Valid values: `direct`, `group`, `space`. If omitted, all types are returned. Example: `types=direct,group`
</ParamField>

<ParamField type="string">
  The `lastMessageAt` timestamp of the last item in the previous page. Used for cursor pagination. Omit for the first page.
</ParamField>

<ParamField type="string">
  The `createdAt` timestamp of the last item in the previous page. Required together with `cursor` when paginating.
</ParamField>

<ParamField type="number">
  Number of conversations to return per page. Defaults to `20`. Maximum `50`.
</ParamField>

## Response

<ResponseField name="conversations" type="ConversationPreview[]">
  Array of conversation preview objects. Each item is a [Conversation](/data-models/conversation) extended with the following fields:

  <Expandable title="ConversationPreview fields">
    <ResponseField name="unreadCount" type="number">
      Number of unread messages in this conversation for the current user.
    </ResponseField>

    <ResponseField name="memberCount" type="number">
      Number of active members.
    </ResponseField>

    <ResponseField name="lastMessageId" type="string | null">
      ID of the most recent message. `null` if no messages exist.
    </ResponseField>

    <ResponseField name="lastMessagePreview" type="string | null">
      Content of the most recent message, truncated to 100 characters. `null` if no messages exist.
    </ResponseField>

    <ResponseField name="lastMessageCreatedAt" type="string | null">
      ISO timestamp of the most recent message. `null` if no messages exist.
    </ResponseField>

    <ResponseField name="lastMessageUserId" type="string | null">
      ID of the user who sent the most recent message. `null` if no messages exist.
    </ResponseField>

    <ResponseField name="otherMembers" type="object[]">
      Up to 5 active members of the conversation other than the requesting user, each with public user fields (`id`, `name`, `username`, `avatar`). Populated for `direct` and `group` conversations only — a DM/group has no `name`, so the counterparty is how a client renders the title and avatar. Capped at 5 (a preview avatar stack needs a few, not all — use `memberCount` for the full group total). Always an empty array (`[]`) for `space` conversations (whose membership can be large and which carry their own `name`). Ordered by member join time.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="hasMore" type="boolean">
  Whether more conversations exist beyond this page.
</ResponseField>


# Mute Conversation
Source: https://docs.sublay.io/v7/api-reference/chat/conversations/mute-conversation

POST /v7/:projectId/chat/conversations/:conversationId/mute
Set or clear the authenticated user's mute on a conversation

Sets or clears the acting user's mute on a conversation. Muting suppresses the `message` push for this conversation only — the message is still delivered, socket-emitted, and readable. Timed mutes expire lazily (push resumes once the window passes).

Requires authentication. **Acting-user-scoped:** an end-user token (`Authorization: Bearer <accessToken>`) mutes its own membership. A service/master key acts on behalf of a named user via the optional body `userId` — a service key without `userId` is rejected, and an end-user token may not name a different user (both consistent with every other per-user write). Requires the `chat` bundle.

## Path Parameters

<ParamField type="string">
  The ID of the conversation to mute or unmute.
</ParamField>

## Body Parameters

<ParamField type="string | null">
  The mute **duration choice** — send the choice, never a raw timestamp. One of:

  * `"8h"` — mute for 8 hours from now
  * `"24h"` — mute for 24 hours from now
  * `"1w"` — mute for 1 week from now
  * `"forever"` — mute indefinitely
  * `null` — clear the mute (unmute)

  The server resolves the window from its own clock, so client clock skew can't distort it.
</ParamField>

<ParamField type="string">
  The acting user whose membership is muted. **Service/master keys only** — a service key must pass it (there is no implicit session user); an end-user token infers it from the auth token and may not name a different user.
</ParamField>

## Response

Returns `200` with the acting user's own (self-serialized) member row under `currentMember`. The `mutedUntil` / `mutedForever` fields reflect the new state.

```json theme={null}
{
  "currentMember": {
    "id": "mbr_abc123",
    "conversationId": "cnv_abc123",
    "userId": "usr_abc123",
    "role": "member",
    "mutedForever": true,
    "mutedUntil": null,
    "isActive": true
  }
}
```

<Warning>
  **"Forever" is an explicit signal.** A `forever` mute returns `mutedForever: true` with `mutedUntil: null` — the far-future storage sentinel is never exposed as a date. A timed mute returns `mutedForever: false` with a real ISO `mutedUntil`. An unmuted conversation returns `mutedForever: false`, `mutedUntil: null`. Read the boolean; never string-match a date.
</Warning>

## Error Responses

<AccordionGroup>
  <Accordion title="Unauthorized — 401 / 403">
    ```json theme={null}
    { "error": "Unauthorized", "code": "chat/unauthorized" }
    ```

    `403 chat/unauthorized` when an end-user token names a `userId` other than its own. A `401` is returned when no valid credential is present.
  </Accordion>

  <Accordion title="Missing User ID — 400">
    ```json theme={null}
    { "error": "Missing user ID", "code": "chat/missing-user-id" }
    ```

    Returned when a service/master key omits the required `userId` (it has no implicit session user).
  </Accordion>

  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Conversation not found.", "code": "chat/not-found" }
    ```
  </Accordion>

  <Accordion title="Not a Member — 400">
    ```json theme={null}
    { "error": "You are not an active member of this conversation.", "code": "chat/not-a-member" }
    ```
  </Accordion>

  <Accordion title="Invalid Body — 400">
    ```json theme={null}
    { "error": "...", "code": "chat/invalid-body" }
    ```

    Returned when `duration` is not one of the accepted choices (or `null`).
  </Accordion>
</AccordionGroup>

## See Also

* [Notification Preferences & Mute](/notification-preferences)
* [`useMuteConversation`](/hooks/chat/conversations/use-mute-conversation)
* [Node SDK — `chat.muteConversation`](/node-sdk/push-notifications#muteconversation)


# Get Unread Count
Source: https://docs.sublay.io/v7/api-reference/chat/conversations/unread-count

GET /v7/:projectId/chat/conversations/unread-count
Get the total unread message count and unread conversation count for the current user

Returns two aggregate counts across all of the current user's active conversations: the total number of unread messages and the number of conversations that have at least one unread message.

Thread replies are excluded from unread counts. Only main-stream messages are counted.

## Response

<ResponseField name="totalUnread" type="number">
  Total number of unread messages across all conversations.
</ResponseField>

<ResponseField name="unreadConversationCount" type="number">
  Number of conversations with at least one unread message.
</ResponseField>


# Update Conversation
Source: https://docs.sublay.io/v7/api-reference/chat/conversations/update-conversation

PATCH /v7/:projectId/chat/conversations/:conversationId
Update a group or space conversation's name, description, avatar, or posting permissions

Updates one or more fields on a conversation. Only `group` and `space` conversations can be updated — direct conversations return a 400.

**Authorization:**

* `group` conversations: caller must be an active `admin` member.
* `space` conversations: caller must have `admin` or `moderator` role in the parent Space.

## Path Parameters

<ParamField type="string">
  The ID of the conversation to update.
</ParamField>

## Body Parameters

All fields are optional. Only provided fields are updated.

<ParamField type="string">
  New display name for the conversation. Maximum 200 characters.
</ParamField>

<ParamField type="string">
  New description. Maximum 1000 characters.
</ParamField>

<ParamField type="string | null">
  ID of an uploaded [File](/data-models/file) to use as the conversation avatar. Pass `null` to remove the current avatar. If a previous avatar exists, it is deleted from storage automatically.
</ParamField>

<ParamField type="string">
  Who can post messages. Only valid for `space` conversations. Accepted values: `"members"` (any active member), `"admins"` (only space admins and moderators).
</ParamField>

## Response

Returns the updated [Conversation](/data-models/conversation) object, with `avatarFile` populated if set.

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Conversation not found.", "code": "chat/not-found" }
    ```
  </Accordion>

  <Accordion title="Cannot Update DM — 400 Bad Request">
    ```json theme={null}
    { "error": "Direct conversations cannot be updated.", "code": "chat/cannot-update-dm" }
    ```
  </Accordion>

  <Accordion title="Invalid Field — 400 Bad Request">
    ```json theme={null}
    { "error": "'postingPermission' can only be set on space conversations.", "code": "chat/invalid-field" }
    ```
  </Accordion>

  <Accordion title="Forbidden (group) — 403">
    ```json theme={null}
    { "error": "Only group admins can update this conversation.", "code": "chat/not-a-member" }
    ```
  </Accordion>

  <Accordion title="Forbidden (space) — 403">
    ```json theme={null}
    { "error": "Only space admins and moderators can update the space conversation.", "code": "chat/not-a-member" }
    ```
  </Accordion>
</AccordionGroup>


# Add Member
Source: https://docs.sublay.io/v7/api-reference/chat/members/add-member

POST /v7/:projectId/chat/conversations/:conversationId/members
Add a user to a group conversation

Adds a user to a group conversation. Only group conversations support explicit member management — this endpoint returns a 400 for direct and space conversations.

The caller must be an active `admin` of the conversation. The target user must belong to the same project.

If the user was previously a member who left or was removed, they are re-activated (their `isActive` is set back to `true` and `lastReadAt` is reset to now).

## Path Parameters

<ParamField type="string">
  The ID of the conversation.
</ParamField>

## Body Parameters

<ParamField type="string">
  The ID of the user to add. Must belong to the same project.
</ParamField>

## Response

Returns the [ConversationMember](/data-models/conversation-member) record for the added user.

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Conversation not found.", "code": "chat/not-found" }
    ```
  </Accordion>

  <Accordion title="Invalid Type — 400 Bad Request">
    ```json theme={null}
    { "error": "Members can only be added to group conversations.", "code": "chat/invalid-type" }
    ```
  </Accordion>

  <Accordion title="Forbidden — 403">
    ```json theme={null}
    { "error": "Only group admins can add members.", "code": "chat/not-a-member" }
    ```
  </Accordion>

  <Accordion title="Invalid Member — 400 Bad Request">
    ```json theme={null}
    { "error": "Target user does not belong to this project.", "code": "chat/invalid-member" }
    ```
  </Accordion>
</AccordionGroup>


# Leave Conversation
Source: https://docs.sublay.io/v7/api-reference/chat/members/leave-conversation

DELETE /v7/:projectId/chat/conversations/:conversationId/leave
Leave a group or space conversation

Removes the current user from a conversation. Direct conversations (`type: "direct"`) cannot be left.

For group conversations, if the caller is the last `admin`, they must promote another member before leaving. The caller is evicted from the real-time room immediately.

## Path Parameters

<ParamField type="string">
  The ID of the conversation to leave.
</ParamField>

## Response

```json theme={null}
{ "message": "Left conversation." }
```

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Conversation not found.", "code": "chat/not-found" }
    ```
  </Accordion>

  <Accordion title="Cannot Leave DM — 400 Bad Request">
    ```json theme={null}
    { "error": "Direct conversations cannot be left.", "code": "chat/cannot-leave-dm" }
    ```
  </Accordion>

  <Accordion title="Not a Member — 400 Bad Request">
    ```json theme={null}
    { "error": "You are not an active member of this conversation.", "code": "chat/not-a-member" }
    ```
  </Accordion>

  <Accordion title="Last Admin — 400 Bad Request">
    ```json theme={null}
    { "error": "You are the last admin. Promote another member before leaving.", "code": "chat/last-admin" }
    ```
  </Accordion>
</AccordionGroup>


# List Members
Source: https://docs.sublay.io/v7/api-reference/chat/members/list-members

GET /v7/:projectId/chat/conversations/:conversationId/members
List the active members of a conversation

Returns a paginated list of active [ConversationMember](/data-models/conversation-member) objects, each with the member's user profile included. The caller must be a member (any status) to access this endpoint.

## Path Parameters

<ParamField type="string">
  The ID of the conversation.
</ParamField>

## Query Parameters

<ParamField type="number">
  Page number (1-based). Defaults to 1.
</ParamField>

<ParamField type="number">
  Number of members per page. Defaults to 50. Maximum 100.
</ParamField>

<ParamField type="string">
  Filter by role. Accepted values: `admin`, `member`. If omitted, all roles are returned.
</ParamField>

### Space-scoped reputation

This endpoint has a space in context, so it accepts the opt-in reputation params. They add a `spaceReputation` field to each returned member's `user`, alongside the always-present `reputation` total. Requires the `reputation` bundle. See the [Reputation data model](/data-models/reputation) for the full contract.

<SpaceReputationParams />

## Response

<ResponseField name="data" type="ConversationMember[]">
  Array of active membership records. Each includes a `user` field with `id`, `name`, `username`, `avatar`, and `metadata`.
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="properties">
    <ResponseField name="page" type="number">Current page number.</ResponseField>
    <ResponseField name="pageSize" type="number">Items per page.</ResponseField>
    <ResponseField name="totalPages" type="number">Total number of pages.</ResponseField>
    <ResponseField name="totalItems" type="number">Total number of active members.</ResponseField>
    <ResponseField name="hasMore" type="boolean">Whether more pages exist.</ResponseField>
  </Expandable>
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="Forbidden — 403">
    ```json theme={null}
    { "error": "You are not a member of this conversation.", "code": "chat/not-a-member" }
    ```
  </Accordion>
</AccordionGroup>


# Remove Member
Source: https://docs.sublay.io/v7/api-reference/chat/members/remove-member

DELETE /v7/:projectId/chat/conversations/:conversationId/members/:userId
Remove a user from a group conversation

Removes an active member from a group conversation. The caller must be an active `admin`. Only group conversations support member removal.

The removed user's membership row is soft-deactivated (`isActive: false`, `leftAt` set to now). They are evicted from the real-time room immediately.

## Path Parameters

<ParamField type="string">
  The ID of the conversation.
</ParamField>

<ParamField type="string">
  The ID of the user to remove.
</ParamField>

## Response

```json theme={null}
{ "message": "Member removed." }
```

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Conversation not found.", "code": "chat/not-found" }
    ```
  </Accordion>

  <Accordion title="Invalid Type — 400 Bad Request">
    ```json theme={null}
    { "error": "Members can only be removed from group conversations.", "code": "chat/invalid-type" }
    ```
  </Accordion>

  <Accordion title="Forbidden — 403">
    ```json theme={null}
    { "error": "Only group admins can remove members.", "code": "chat/not-a-member" }
    ```
  </Accordion>

  <Accordion title="Member Not Found — 404">
    ```json theme={null}
    { "error": "Member not found in this conversation.", "code": "chat/member-not-found" }
    ```
  </Accordion>
</AccordionGroup>


# Update Member Role
Source: https://docs.sublay.io/v7/api-reference/chat/members/update-member-role

PATCH /v7/:projectId/chat/conversations/:conversationId/members/:userId/role
Change a member's role in a group conversation

Updates the role of an active member in a group conversation. Only group conversations have roles — this endpoint returns a 400 for direct and space conversations.

The caller must be an active `admin`.

## Path Parameters

<ParamField type="string">
  The ID of the conversation.
</ParamField>

<ParamField type="string">
  The ID of the member whose role is being changed.
</ParamField>

## Body Parameters

<ParamField type="string">
  The new role. Accepted values: `"admin"`, `"member"`.
</ParamField>

## Response

Returns the updated [ConversationMember](/data-models/conversation-member) record.

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Conversation not found.", "code": "chat/not-found" }
    ```
  </Accordion>

  <Accordion title="Invalid Type — 400 Bad Request">
    ```json theme={null}
    { "error": "Roles can only be changed in group conversations.", "code": "chat/invalid-type" }
    ```
  </Accordion>

  <Accordion title="Forbidden — 403">
    ```json theme={null}
    { "error": "Only group admins can change member roles.", "code": "chat/not-a-member" }
    ```
  </Accordion>

  <Accordion title="Member Not Found — 404">
    ```json theme={null}
    { "error": "Member not found in this conversation.", "code": "chat/member-not-found" }
    ```
  </Accordion>
</AccordionGroup>


# Delete Message
Source: https://docs.sublay.io/v7/api-reference/chat/messages/delete-message

DELETE /v7/:projectId/chat/conversations/:conversationId/messages/:messageId
Delete or moderate a chat message

Deletes a message. The behavior differs based on who is deleting:

* **Author self-delete**: The message is soft-deleted. The row is retained as a `[Message deleted]` placeholder — content, GIF, mentions, and metadata are cleared, and `userDeletedAt` is set. File attachments are deleted from storage.
* **Group admin moderation delete**: The message is marked `moderationStatus: "removed"` and excluded from all future queries. Content is not cleared; the record is retained for moderation audit purposes.

The caller must be either the message author or a group `admin`.

## Path Parameters

<ParamField type="string">
  The ID of the conversation.
</ParamField>

<ParamField type="string">
  The ID of the message to delete.
</ParamField>

## Response

For author self-delete:

```json theme={null}
{ "message": "Message deleted.", "userDeletedAt": "2025-01-15T10:30:00.000Z" }
```

For admin moderation:

```json theme={null}
{ "message": "Message removed by admin." }
```

## Error Responses

<AccordionGroup>
  <Accordion title="Forbidden — 403 (not a member)">
    ```json theme={null}
    { "error": "You are not a member of this conversation.", "code": "chat/not-a-member" }
    ```
  </Accordion>

  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Message not found.", "code": "chat/message-not-found" }
    ```
  </Accordion>

  <Accordion title="Forbidden — 403 (no permission)">
    ```json theme={null}
    { "error": "You do not have permission to delete this message.", "code": "chat/forbidden" }
    ```
  </Accordion>
</AccordionGroup>


# Edit Message
Source: https://docs.sublay.io/v7/api-reference/chat/messages/edit-message

PATCH /v7/:projectId/chat/conversations/:conversationId/messages/:messageId
Edit the content of a message

Updates the content, GIF, mentions, or metadata of an existing message. Only the message author can edit their own messages. Deleted or moderator-removed messages cannot be edited.

If no fields actually changed, the endpoint returns the current message without updating `editedAt`.

## Path Parameters

<ParamField type="string">
  The ID of the conversation.
</ParamField>

<ParamField type="string">
  The ID of the message to edit.
</ParamField>

## Body Parameters

All fields are optional. Only provided fields are updated.

<ParamField type="string">
  New text content. After editing, the message must still have at least one of: content, GIF, or an attached file.
</ParamField>

<ParamField type="object">
  Updated GIF attachment. See [GifData](/data-models/chat-message#gifdata) for the expected shape. Set to `null` to remove the GIF.
</ParamField>

<ParamField type="array">
  Updated array of [Mention](/data-models/chat-message#mention) objects.
</ParamField>

<ParamField type="object">
  Updated metadata.
</ParamField>

## Response

Returns the updated [ChatMessage](/data-models/chat-message), with `editedAt` set to the current time.

## Error Responses

<AccordionGroup>
  <Accordion title="Forbidden — 403 (not a member)">
    ```json theme={null}
    { "error": "You are not a member of this conversation.", "code": "chat/not-a-member" }
    ```
  </Accordion>

  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Message not found.", "code": "chat/message-not-found" }
    ```
  </Accordion>

  <Accordion title="Forbidden — 403 (not the author)">
    ```json theme={null}
    { "error": "Only the message author can edit this message.", "code": "chat/forbidden" }
    ```
  </Accordion>

  <Accordion title="Message Deleted — 400 Bad Request">
    ```json theme={null}
    { "error": "Deleted messages cannot be edited.", "code": "chat/message-deleted" }
    ```
  </Accordion>

  <Accordion title="Message Removed — 400 Bad Request">
    ```json theme={null}
    { "error": "Removed messages cannot be edited.", "code": "chat/message-removed" }
    ```
  </Accordion>

  <Accordion title="Empty Result — 400 Bad Request">
    ```json theme={null}
    { "error": "Edited message must have at least content, a GIF, or a file.", "code": "chat/empty-message" }
    ```
  </Accordion>
</AccordionGroup>


# Fetch Message
Source: https://docs.sublay.io/v7/api-reference/chat/messages/fetch-message

GET /v7/:projectId/chat/conversations/:conversationId/messages/:messageId
Fetch a single message by ID

Returns a single [ChatMessage](/data-models/chat-message) by ID, fully populated with `user`, `quotedMessage`, `files`, `reactionCounts`, and `userReactions`. The caller must be a member of the conversation.

## Path Parameters

<ParamField type="string">
  The ID of the conversation.
</ParamField>

<ParamField type="string">
  The ID of the message to fetch.
</ParamField>

## Query Parameters

<ParamField type="string">
  Comma-separated list of extra fields to include. Supports `grants` — the [reputation-grant summary](/data-models/reputation-grant#grantsummary) for this message.
</ParamField>

### Space-scoped reputation

This endpoint has a space in context, so it accepts the opt-in reputation params. They add a `spaceReputation` field to the message sender's `user`, alongside the always-present `reputation` total. Requires the `reputation` bundle. See the [Reputation data model](/data-models/reputation) for the full contract.

<SpaceReputationParams />

## Response

Returns a [ChatMessage](/data-models/chat-message) with all populated fields including `reactionCounts` and `userReactions` for the requesting user.

## Error Responses

<AccordionGroup>
  <Accordion title="Forbidden — 403">
    ```json theme={null}
    { "error": "You are not a member of this conversation.", "code": "chat/not-a-member" }
    ```
  </Accordion>

  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Message not found.", "code": "chat/message-not-found" }
    ```
  </Accordion>
</AccordionGroup>


# Fetch Reaction Users
Source: https://docs.sublay.io/v7/api-reference/chat/messages/fetch-reaction-users

GET /v7/:projectId/chat/conversations/:conversationId/messages/:messageId/reactions
List users who reacted to a message with a specific emoji

Returns a paginated list of users who reacted with a given emoji on a message. Useful for rendering a "who reacted" popover. The caller must be a member of the conversation.

## Path Parameters

<ParamField type="string">
  The ID of the conversation.
</ParamField>

<ParamField type="string">
  The ID of the message.
</ParamField>

## Query Parameters

<ParamField type="string">
  The emoji to filter by.
</ParamField>

<ParamField type="number">
  Page number (1-based). Defaults to 1.
</ParamField>

<ParamField type="number">
  Number of reactions per page. Defaults to 50. Max 100.
</ParamField>

### Space-scoped reputation

This endpoint has a space in context, so it accepts the opt-in reputation params. They add a `spaceReputation` field to each reactor's `user`, alongside the always-present `reputation` total. Requires the `reputation` bundle. See the [Reputation data model](/data-models/reputation) for the full contract.

<SpaceReputationParams />

## Response

<ResponseField name="data" type="array">
  Array of reaction entries, ordered by `createdAt` ascending.

  <Expandable title="properties">
    <ResponseField name="user" type="object">
      User who reacted. Includes `id`, `name`, `username`, `avatar`.
    </ResponseField>

    <ResponseField name="emoji" type="string">
      The emoji for this reaction.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      Timestamp when the reaction was added.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="properties">
    <ResponseField name="page" type="number">Current page.</ResponseField>
    <ResponseField name="limit" type="number">Items per page.</ResponseField>
    <ResponseField name="total" type="number">Total number of reactions for this emoji.</ResponseField>
    <ResponseField name="hasMore" type="boolean">Whether more pages exist.</ResponseField>
  </Expandable>
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="Forbidden — 403">
    ```json theme={null}
    { "error": "You are not a member of this conversation.", "code": "chat/not-a-member" }
    ```
  </Accordion>

  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Message not found.", "code": "chat/message-not-found" }
    ```
  </Accordion>
</AccordionGroup>


# List Messages
Source: https://docs.sublay.io/v7/api-reference/chat/messages/list-messages

GET /v7/:projectId/chat/conversations/:conversationId/messages
Fetch messages in a conversation or thread

Returns a cursor-paginated list of [ChatMessage](/data-models/chat-message) objects. By default returns the main conversation stream (excludes thread replies). Pass `parentId` to fetch replies for a specific thread.

The caller must be a member. Former members (who left) can only read messages up to when they left.

## Path Parameters

<ParamField type="string">
  The ID of the conversation.
</ParamField>

## Query Parameters

<ParamField type="string">
  If provided, returns thread replies to this message instead of the main stream.
</ParamField>

<ParamField type="string">
  ISO 8601 timestamp. Returns messages created before this time. Used for loading older messages. Mutually exclusive with `after`.
</ParamField>

<ParamField type="string">
  ISO 8601 timestamp. Returns messages created after this time. Used for loading newer messages. Mutually exclusive with `before`.
</ParamField>

<ParamField type="number">
  Number of messages to return. Defaults to 50.
</ParamField>

<ParamField type="string">
  Sort order: `asc` or `desc`. Defaults to `desc` for the main stream, `asc` for threads.
</ParamField>

<ParamField type="string">
  Comma-separated list of extra fields to include: `files` (attachments) and `grants` (the [reputation-grant summary](/data-models/reputation-grant#grantsummary)). Combine them as `include=files,grants`.
</ParamField>

<ParamField type="object">
  Optional filters object, serialized as bracket-notation query params (e.g. `filters[hasReplies]=true`).

  * `hasReplies` (boolean) — When `true`, returns only messages that have thread replies (`threadReplyCount > 0`). When `false`, returns only messages with no thread replies. This filters by **thread replies**, not quotings (`quotedMessageId`).

  <Note>Threads are one level deep — a reply can never have its own replies. So `filters[hasReplies]=true` combined with `parentId` always returns an empty list; the response includes a `notice` field explaining why.</Note>
</ParamField>

### Space-scoped reputation

This endpoint has a space in context, so it accepts the opt-in reputation params. They add a `spaceReputation` field to each message sender's `user`, alongside the always-present `reputation` total. Requires the `reputation` bundle. See the [Reputation data model](/data-models/reputation) for the full contract.

<SpaceReputationParams />

## Response

<ResponseField name="messages" type="ChatMessage[]">
  Array of message objects. Each includes `reactionCounts`, `userReactions`, `user`, and `quotedMessage` fields. File attachments are included only when `include=files` is specified.
</ResponseField>

<ResponseField name="hasMore" type="boolean">
  Whether more messages exist in the requested direction.
</ResponseField>

<ResponseField name="oldestCreatedAt" type="string | null">
  ISO timestamp of the oldest message in this page. `null` if no messages were returned.
</ResponseField>

<ResponseField name="newestCreatedAt" type="string | null">
  ISO timestamp of the newest message in this page. `null` if no messages were returned.
</ResponseField>

<ResponseField name="notice" type="string">
  Present only when a filter combination can't return results — e.g. `hasReplies: true` together with `parentId`. Explains why the list is empty.
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="Forbidden — 403">
    ```json theme={null}
    { "error": "You are not a member of this conversation.", "code": "chat/not-a-member" }
    ```
  </Accordion>
</AccordionGroup>


# Mark as Read
Source: https://docs.sublay.io/v7/api-reference/chat/messages/mark-as-read

POST /v7/:projectId/chat/conversations/:conversationId/read
Advance the current user's read cursor to a given message

Updates the current user's `lastReadAt` timestamp on their conversation membership to the `createdAt` of the specified message. This reduces the unread count for the conversation.

The operation is monotonic — `lastReadAt` is never moved backward. If the provided message is older than the current `lastReadAt`, the call is a no-op.

## Path Parameters

<ParamField type="string">
  The ID of the conversation.
</ParamField>

## Body Parameters

<ParamField type="string">
  The ID of the message to mark as read. The user's `lastReadAt` will be set to this message's `createdAt`.
</ParamField>

## Response

```json theme={null}
{ "message": "Marked as read." }
```

## Error Responses

<AccordionGroup>
  <Accordion title="Forbidden — 403">
    ```json theme={null}
    { "error": "You are not an active member of this conversation.", "code": "chat/not-a-member" }
    ```
  </Accordion>
</AccordionGroup>


# Send Message
Source: https://docs.sublay.io/v7/api-reference/chat/messages/send-message

POST /v7/:projectId/chat/conversations/:conversationId/messages
Send a message to a conversation

Creates a new message in a conversation. The caller must be an active member. At least one of `content`, `gif`, or a file attachment is required.

For space conversations with `postingPermission: "admins"`, only users with `admin` or `moderator` role in the parent Space can send messages.

This endpoint accepts `multipart/form-data` to support file attachments alongside message content.

## Path Parameters

<ParamField type="string">
  The ID of the conversation to send the message to.
</ParamField>

## Body Parameters

<ParamField type="string">
  Text content of the message. Optional if a GIF or file is provided.
</ParamField>

<ParamField type="object">
  GIF attachment. Optional. See [GifData](/data-models/chat-message#gifdata) for the expected shape.
</ParamField>

<ParamField type="array">
  Array of [Mention](/data-models/chat-message#mention) objects for @mentions in the message content. Optional.
</ParamField>

<ParamField type="string">
  ID of a message in this conversation to reply to in a thread. The referenced message must be a main-stream message (threads are one level deep only). Optional.
</ParamField>

<ParamField type="string">
  ID of a message to quote inline. The message stays in the main stream but renders the quoted content as a preview. Optional.
</ParamField>

<ParamField type="object">
  Custom key-value data. Limited to 10 KB. Optional.
</ParamField>

<ParamField type="string">
  Client-generated identifier for optimistic deduplication. The server echoes it back in the response but never stores it. Optional.
</ParamField>

<ParamField type="file[]">
  File attachments (multipart/form-data). Up to 10 files per message. Optional.
</ParamField>

## Query Parameters

### Space-scoped reputation

This endpoint has a space in context, so it accepts the opt-in reputation params. They add a `spaceReputation` field to the message sender's `user`, alongside the always-present `reputation` total. Requires the `reputation` bundle. See the [Reputation data model](/data-models/reputation) for the full contract.

<SpaceReputationParams />

## Response

Returns the created [ChatMessage](/data-models/chat-message) object, fully populated with `user`, `quotedMessage`, `files`, `reactionCounts` (empty on creation), and `userReactions` (empty on creation). If `localId` was provided, it is echoed in the response.

## Error Responses

<AccordionGroup>
  <Accordion title="Empty Message — 400 Bad Request">
    ```json theme={null}
    { "error": "Message must have content, a GIF, or at least one file.", "code": "chat/empty-message" }
    ```
  </Accordion>

  <Accordion title="Forbidden — 403">
    ```json theme={null}
    { "error": "You are not a member of this conversation.", "code": "chat/not-a-member" }
    ```
  </Accordion>

  <Accordion title="Invalid Parent — 400 Bad Request">
    ```json theme={null}
    { "error": "Parent message not found, not in this conversation, already removed, or is itself a reply.", "code": "chat/invalid-parent" }
    ```
  </Accordion>
</AccordionGroup>


# Toggle Message Reaction
Source: https://docs.sublay.io/v7/api-reference/chat/messages/toggle-reaction

POST /v7/:projectId/chat/conversations/:conversationId/messages/:messageId/reactions
Add or remove an emoji reaction on a chat message

Toggles an emoji reaction on a message. If the current user has not yet reacted with this emoji, the reaction is added. If they already have, it is removed. The caller must be an active member.

The `emoji` must be exactly one grapheme cluster (a single visible character, including multi-codepoint emoji like `👨‍👩‍👧`).

## Path Parameters

<ParamField type="string">
  The ID of the conversation.
</ParamField>

<ParamField type="string">
  The ID of the message to react to.
</ParamField>

## Body Parameters

<ParamField type="string">
  The emoji to toggle. Must be exactly one grapheme cluster.
</ParamField>

## Response

<ResponseField name="reactionCounts" type="Record<string, number>">
  Updated emoji reaction counts for this message (e.g. `{ "👍": 3, "❤️": 1 }`).
</ResponseField>

<ResponseField name="userReactions" type="string[]">
  The current user's full set of reactions on this message after the toggle.
</ResponseField>

<ResponseField name="delta" type="number">
  `1` if a reaction was added, `-1` if removed.
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="Invalid Emoji — 400 Bad Request">
    ```json theme={null}
    { "error": "Emoji must be exactly one grapheme cluster.", "code": "chat/invalid-emoji" }
    ```
  </Accordion>

  <Accordion title="Forbidden — 403">
    ```json theme={null}
    { "error": "You are not a member of this conversation.", "code": "chat/not-a-member" }
    ```
  </Accordion>

  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Message not found.", "code": "chat/message-not-found" }
    ```
  </Accordion>
</AccordionGroup>


# Add Entity to Collection
Source: https://docs.sublay.io/v7/api-reference/collections/add-entity

POST /v7/:projectId/collections/:collectionId/entities
Save an entity into a collection

Saves an entity into the specified collection. This operation is idempotent — if the entity is already in the collection, it returns success without creating a duplicate.

## Path Parameters

<ParamField type="string">
  The ID of the collection to save the entity into.
</ParamField>

## Body Parameters

<ParamField type="string">
  The ID of the entity to save.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Always `true` on success.
</ResponseField>

<ResponseField name="collection" type="object">
  Updated collection metadata.

  <Expandable>
    <ResponseField name="id" type="string">Collection ID.</ResponseField>
    <ResponseField name="entityCount" type="number">New entity count after the save.</ResponseField>
  </Expandable>
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="Collection Not Found — 404">
    ```json theme={null}
    { "error": "Collection not found", "code": "collection/not-found" }
    ```
  </Accordion>

  <Accordion title="Entity Not Found — 404">
    ```json theme={null}
    { "error": "Entity not found", "code": "entity/not-found" }
    ```
  </Accordion>

  <Accordion title="Server Error — 500">
    ```json theme={null}
    { "error": "Internal server error.", "code": "collection/server-error" }
    ```
  </Accordion>
</AccordionGroup>


# Create Sub-Collection
Source: https://docs.sublay.io/v7/api-reference/collections/create-sub-collection

POST /v7/:projectId/collections/:collectionId/sub-collections
Create a new sub-collection inside an existing collection

Creates a new named sub-collection under the specified parent collection. Returns `400` if the parent collection does not exist.

## Path Parameters

<ParamField type="string">
  The ID of the parent collection. Use the root collection's ID to create a top-level folder.
</ParamField>

## Body Parameters

<ParamField type="string">
  The name for the new collection.
</ParamField>

## Response

Returns the newly created [Collection](/data-models/collection) object with `status 201`.

## Error Responses

<AccordionGroup>
  <Accordion title="Invalid Parent — 400 Bad Request">
    ```json theme={null}
    { "error": "Invalid parent collection ID for sub-collection", "code": "collection/invalid-parent" }
    ```
  </Accordion>

  <Accordion title="Server Error — 500">
    ```json theme={null}
    { "error": "Server error", "code": "collection/server-error" }
    ```
  </Accordion>
</AccordionGroup>


# Delete Collection
Source: https://docs.sublay.io/v7/api-reference/collections/delete-collection

DELETE /v7/:projectId/collections/:collectionId
Delete a sub-collection

Deletes a sub-collection and all its contents (cascade). The root collection cannot be deleted.

Returns `204 No Content` on success.

## Path Parameters

<ParamField type="string">
  The ID of the collection to delete.
</ParamField>

## Error Responses

<AccordionGroup>
  <Accordion title="Collection Not Found — 404">
    Returned when the collection doesn't exist, doesn't belong to the authenticated user, or is the root collection (which cannot be deleted).

    ```json theme={null}
    { "error": "Collection not found", "code": "collection/not-found" }
    ```
  </Accordion>

  <Accordion title="Server Error — 500">
    ```json theme={null}
    { "error": "Server error", "code": "collection/server-error" }
    ```
  </Accordion>
</AccordionGroup>


# Fetch Collection Entities
Source: https://docs.sublay.io/v7/api-reference/collections/fetch-entities

GET /v7/:projectId/collections/:collectionId/entities
Get paginated entities saved in a collection

Returns a paginated list of entities saved in the specified collection. The collection must belong to the authenticated user.

## Path Parameters

<ParamField type="string">
  The ID of the collection to fetch entities from.
</ParamField>

## Query Parameters

<ParamField type="number">
  Page number (1-indexed). Default: `1`.
</ParamField>

<ParamField type="number">
  Number of entities per page. Default: `20`.
</ParamField>

<ParamField type="&#x22;new&#x22; | &#x22;top&#x22; | &#x22;hot&#x22; | &#x22;added&#x22;">
  Sort mode. `added` sorts by when the entity was saved; others sort by entity properties. Default: `"new"`.
</ParamField>

<ParamField type="&#x22;asc&#x22; | &#x22;desc&#x22;">
  Sort direction. Default: `"desc"`.
</ParamField>

<ParamField type="string">
  Comma-separated list of associations to include: `user`, `space`, `topcomment`, `grants` (the [reputation-grant summary](/data-models/reputation-grant#grantsummary)).
</ParamField>

## Response

<ResponseField name="data" type="Entity[]">
  The page of entity objects. Each entity includes `isSaved: true`.
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination metadata.

  <Expandable>
    <ResponseField name="page" type="number">Current page.</ResponseField>
    <ResponseField name="limit" type="number">Page size.</ResponseField>
    <ResponseField name="totalPages" type="number">Total number of pages.</ResponseField>
    <ResponseField name="totalItems" type="number">Total count of saved entities.</ResponseField>
    <ResponseField name="hasMore" type="boolean">`true` if more pages exist.</ResponseField>
  </Expandable>
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="Collection Not Found — 404">
    ```json theme={null}
    { "error": "Collection not found", "code": "collection/not-found" }
    ```
  </Accordion>

  <Accordion title="Server Error — 500">
    ```json theme={null}
    { "error": "Internal server error.", "code": "collection/server-error" }
    ```
  </Accordion>
</AccordionGroup>


# Fetch Root Collection
Source: https://docs.sublay.io/v7/api-reference/collections/fetch-root

GET /v7/:projectId/collections/root
Get or create the current user's root collection

Returns the root collection for the authenticated user. If no root collection exists yet, one is created automatically with the name `"root"`.

## Response

Returns a [Collection](/data-models/collection) object with `parentId: null` and `isRoot: true`.

<Note>
  This endpoint is the entry point for the collections system. Call it once on load to initialize the user's collection tree. Sub-collections are fetched separately via the sub-collections endpoint.
</Note>

## Error Responses

<AccordionGroup>
  <Accordion title="Server Error — 500">
    ```json theme={null}
    { "error": "Server error", "code": "collection/server-error" }
    ```
  </Accordion>
</AccordionGroup>


# Fetch Sub-Collections
Source: https://docs.sublay.io/v7/api-reference/collections/fetch-sub-collections

GET /v7/:projectId/collections/:collectionId/sub-collections
List all direct child collections of a given collection

Returns all sub-collections directly under the specified collection, owned by the authenticated user.

## Path Parameters

<ParamField type="string">
  The ID of the parent collection whose direct children should be returned.
</ParamField>

## Response

Returns an array of [Collection](/data-models/collection) objects.

```json theme={null}
[
  {
    "id": "col_abc",
    "name": "To Read",
    "parentId": "col_root",
    "entityCount": 5,
    "createdAt": "2025-01-15T10:00:00.000Z",
    "updatedAt": "2025-01-15T10:00:00.000Z"
  }
]
```

## Error Responses

<AccordionGroup>
  <Accordion title="Server Error — 500">
    ```json theme={null}
    { "error": "Server error", "code": "collection/server-error" }
    ```
  </Accordion>
</AccordionGroup>


# Remove Entity from Collection
Source: https://docs.sublay.io/v7/api-reference/collections/remove-entity

DELETE /v7/:projectId/collections/:collectionId/entities/:entityId
Remove a saved entity from a collection

Removes an entity from the specified collection. This operation is idempotent — if the entity is not in the collection, it still returns success.

## Path Parameters

<ParamField type="string">
  The ID of the collection.
</ParamField>

<ParamField type="string">
  The ID of the entity to remove.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Always `true` on success.
</ResponseField>

<ResponseField name="collection" type="object">
  Updated collection metadata.

  <Expandable>
    <ResponseField name="id" type="string">Collection ID.</ResponseField>
    <ResponseField name="entityCount" type="number">New entity count after the removal.</ResponseField>
  </Expandable>
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="Collection Not Found — 404">
    ```json theme={null}
    { "error": "Collection not found", "code": "collection/not-found" }
    ```
  </Accordion>

  <Accordion title="Server Error — 500">
    ```json theme={null}
    { "error": "Internal server error.", "code": "collection/server-error" }
    ```
  </Accordion>
</AccordionGroup>


# Update Collection
Source: https://docs.sublay.io/v7/api-reference/collections/update-collection

PATCH /v7/:projectId/collections/:collectionId
Rename a collection

Updates the name of a sub-collection. The root collection cannot be renamed (it has `parentId: null`, which this endpoint rejects).

## Path Parameters

<ParamField type="string">
  The ID of the collection to update.
</ParamField>

## Body Parameters

<ParamField type="string">
  The new name for the collection. Must be a non-empty string.
</ParamField>

## Response

Returns the updated [Collection](/data-models/collection) object.

## Error Responses

<AccordionGroup>
  <Accordion title="Invalid Body — 400">
    Returned when `name` is missing or an empty string. The `error` message names the offending field.

    ```json theme={null}
    { "error": "name: Invalid input: expected string, received undefined", "code": "collection/invalid-body" }
    ```
  </Accordion>

  <Accordion title="Collection Not Found — 404">
    Returned when the collection doesn't exist, doesn't belong to the user, or is the root collection (which cannot be renamed).

    ```json theme={null}
    { "error": "Collection not found", "code": "collection/not-found" }
    ```
  </Accordion>

  <Accordion title="Server Error — 500">
    ```json theme={null}
    { "error": "Server error", "code": "collection/server-error" }
    ```
  </Accordion>
</AccordionGroup>


# Add Comment Reaction
Source: https://docs.sublay.io/v7/api-reference/comments/add-reaction

POST /v7/:projectId/comments/:commentId/reactions
Add or update a reaction on a comment

Adds a reaction of the specified type to a comment. If the user already has a reaction on this comment, it is replaced with the new type. The comment's `reactionCounts` map is updated accordingly.

**Authentication required.**

## Path Parameters

<ParamField type="string">
  The UUID of the comment to react to.
</ParamField>

## Body Parameters

<ParamField type="string">
  The type of reaction to add. One of: `upvote`, `downvote`, `like`, `love`, `wow`, `sad`, `angry`, `funny`.
</ParamField>

<ParamField type="string">
  Override which user the reaction is attributed to. **Service or master key only.**
</ParamField>

## Response

Returns the updated [Comment](/data-models/comment) object with the new `reactionCounts` map.

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Comment not found.", "code": "comment/not-found" }
    ```
  </Accordion>
</AccordionGroup>


# Create Comment
Source: https://docs.sublay.io/v7/api-reference/comments/create-comment

POST /v7/:projectId/comments
Create a new comment or reply on an entity

Creates a new comment on an entity, or a reply to an existing comment. The comment is attributed to the authenticated user. Notifications are sent to the entity owner, parent comment author (for replies), and mentioned users.

**Authentication required.**

## Body Parameters

<ParamField type="string">
  The UUID of the entity this comment belongs to.
</ParamField>

<ParamField type="string">
  The text content of the comment. At least one of `content`, `gif`, or `attachments` must be provided.
</ParamField>

<ParamField type="object">
  A GIF to attach to the comment. At least one of `content`, `gif`, or `attachments` must be provided.

  ```json theme={null}
  {
    "id": "gif-id",
    "altText": "laughing cat",
    "gifUrl": "https://media.giphy.com/...",
    "gifPreviewUrl": "https://media.giphy.com/...",
    "url": "https://giphy.com/...",
    "aspectRatio": "1.5"
  }
  ```

  `aspectRatio` is width ÷ height as a decimal string. Colon notation like `"16:9"` is rejected by clients that compute layout from it.
</ParamField>

<ParamField type="object[]">
  An array of generic attachment objects. At least one of `content`, `gif`, or `attachments` must be provided.
</ParamField>

<ParamField type="string">
  The UUID of the parent comment. When provided, this comment is treated as a reply to that comment. The parent comment's author receives a reply notification.
</ParamField>

<ParamField type="string">
  The UUID of a comment being quoted or referenced. Used for quote-replies.
</ParamField>

<ParamField type="string">
  Your application's identifier for this comment.
</ParamField>

<ParamField type="object[]">
  Users or spaces mentioned in the comment. Each mentioned user receives an in-app notification.

  * `{ type: "user", id: string, username: string, foreignId?: string }`
  * `{ type: "space", id: string, slug: string }`
</ParamField>

<ParamField type="object">
  A free-form JSON object for any custom data your application needs alongside the comment.
</ParamField>

<ParamField type="string">
  Attribute the comment to a specific user. **Service or master key only.** Useful for backfilling comments from external systems.
</ParamField>

<ParamField type="string">
  ISO 8601 datetime to backfill a creation timestamp. **Service or master key only.**
</ParamField>

<ParamField type="string">
  ISO 8601 datetime for `updatedAt`. Requires `createdAt`. Must be ≥ `createdAt`. **Service or master key only.**
</ParamField>

## Response

Returns `201 Created` with the new [Comment](/data-models/comment) object, populated with the author's user profile.

## Error Responses

<AccordionGroup>
  <Accordion title="Entity Not Found — 404">
    ```json theme={null}
    { "error": "Entity not found", "code": "comment/entity-not-found" }
    ```
  </Accordion>

  <Accordion title="Missing User — 400">
    ```json theme={null}
    { "error": "Missing user ID", "code": "comment/missing-user-id" }
    ```
  </Accordion>

  <Accordion title="No Content — 400">
    Returned when none of `content`, `gif`, or `attachments` is provided.
  </Accordion>
</AccordionGroup>


# Delete Comment
Source: https://docs.sublay.io/v7/api-reference/comments/delete-comment

DELETE /v7/:projectId/comments/:commentId
Delete a comment

Deletes a comment. Only the comment's author, or a request with a service or master key, can delete a comment.

**Authentication required.**

All deletes are soft-deletes: the comment's content, gif, mentions, and attachments are cleared and `userDeletedAt` is set. The record is preserved as a stripped placeholder in thread view to maintain the reply tree structure (Reddit-style).

## Path Parameters

<ParamField type="string">
  The UUID of the comment to delete.
</ParamField>

## Response

Returns `204 No Content` on success.

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Comment not found", "code": "comment/not-found" }
    ```
  </Accordion>

  <Accordion title="Already Deleted — 404">
    ```json theme={null}
    { "error": "Comment already deleted", "code": "comment/already-deleted" }
    ```
  </Accordion>

  <Accordion title="Forbidden — 403">
    ```json theme={null}
    { "error": "You do not have permission to delete this comment.", "code": "comment/not-authorized" }
    ```
  </Accordion>
</AccordionGroup>


# Fetch Comment
Source: https://docs.sublay.io/v7/api-reference/comments/fetch-comment

GET /v7/:projectId/comments/:commentId
Get a single comment by ID

Returns a single comment by its Sublay UUID.

<Note>
  If the comment author is block-edged with the signed-in caller, in either
  direction, this returns `404` with `comment/not-found` — identical to a
  comment that does not exist. An embedded `parentComment` is nulled under the
  same rule. Requires the `moderation` bundle.
</Note>

## Path Parameters

<ParamField type="string">
  The UUID of the comment to fetch.
</ParamField>

## Query Parameters

<ParamField type="string">
  Comma-separated list of associations to include. Valid values: `user`, `entity`, `space`, `parent`, `grants` (the [reputation-grant summary](/data-models/reputation-grant#grantsummary)).
</ParamField>

### Space-scoped reputation

This endpoint has a space in context, so it accepts the opt-in reputation params. They add a `spaceReputation` field to the populated author `user`, alongside the always-present `reputation` total. Requires the `reputation` bundle. See the [Reputation data model](/data-models/reputation) for the full contract.

<SpaceReputationParams />

## Response

Returns a `200 OK` with the following shape:

```json theme={null}
{
  "comment": { ...Comment }
}
```

The `comment` field is a [Comment](/data-models/comment) object. If the comment has been removed (user-deleted or moderation-removed) and the viewer is not the author, identifying fields (`userId`, `user`, `content`, `gif`, `mentions`, `attachments`) are nulled out as a Reddit-style placeholder.

<Note>
  This endpoint **nests the record under a `comment` key**, unlike every other read surface, which returns the record bare. So a requested grants summary lives at `comment.grants` — see [GrantSummary](/data-models/reputation-grant#grantsummary).
</Note>

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Comment not found", "code": "comment/not-found" }
    ```
  </Accordion>
</AccordionGroup>


# Fetch Comment by Foreign ID
Source: https://docs.sublay.io/v7/api-reference/comments/fetch-comment-by-foreign-id

GET /v7/:projectId/comments/by-foreign-id
Get a comment by its foreign ID

Returns a single comment matching the given `foreignId` within the project. Useful for looking up comments using your own application's identifiers.

<Note>
  If the comment author is block-edged with the signed-in caller, in either
  direction, this returns `404` with `comment/not-found` — identical to a
  comment that does not exist. An embedded `parentComment` is nulled under the
  same rule. Requires the `moderation` bundle.
</Note>

## Query Parameters

<ParamField type="string">
  The foreign ID to look up.
</ParamField>

<ParamField type="string">
  Comma-separated list of associations to include. Valid values: `user`, `entity`, `space`, `parent`, `grants` (the [reputation-grant summary](/data-models/reputation-grant#grantsummary)).
</ParamField>

## Response

Returns a `200 OK` with the following shape:

```json theme={null}
{
  "comment": { ...Comment }
}
```

The `comment` field is a [Comment](/data-models/comment) object. If the comment has been removed (user-deleted or moderation-removed) and the viewer is not the author, identifying fields (`userId`, `user`, `content`, `gif`, `mentions`, `attachments`) are nulled out as a Reddit-style placeholder.

<Note>
  This endpoint **nests the record under a `comment` key**, unlike every other read surface, which returns the record bare. So a requested grants summary lives at `comment.grants` — see [GrantSummary](/data-models/reputation-grant#grantsummary).
</Note>

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Comment not found", "code": "comment/not-found" }
    ```
  </Accordion>
</AccordionGroup>


# Fetch Many Comments
Source: https://docs.sublay.io/v7/api-reference/comments/fetch-many-comments

GET /v7/:projectId/comments
Get a paginated, sorted list of comments

Returns a paginated list of comments. Used for both top-level comment threads (filter by `entityId`) and reply threads (filter by `parentId`). Also used for user profile comment history (filter by `userId`).

Deleted comments in thread view appear as stripped placeholders to preserve tree structure (Reddit-style). Authors viewing their own comments always see full data.

## Query Parameters

<ParamField type="string">
  Filter comments by entity. Returns all comments (top-level and replies) for this entity.
</ParamField>

<ParamField type="string">
  Filter to replies of a specific comment. Used to fetch a reply thread.
</ParamField>

<ParamField type="string">
  Filter to comments by a specific user. When this matches the authenticated user's ID, soft-deleted comments are included with full data.
</ParamField>

<ParamField type="string">
  Filter by the `sourceId` of the entity. Only effective when `include` contains `entity`.
</ParamField>

<ParamField type="string">
  Controls how comments authored by users the viewer is [block-edged](/sdk/moderation/overview#blocking) with are treated. `"exclude"` (default) hides those comments. `"include-outbound-blocked"` re-includes comments authored **only** by users the viewer themselves blocked (their own "view anyway" choice); it never surfaces content from users who blocked the viewer. Counts reflect what the viewer sees (computed post-filter). Has no effect when the `moderation` bundle is not installed.
</ParamField>

<ParamField type="string">
  Sort order. One of:

  * `createdAt` — chronological by creation time (honors `sortDir`; newest first by default)
  * `top` — by net upvotes (upvotes minus downvotes)
  * `controversial` — high total votes with a close up/down split (comments with no votes sort last)
</ParamField>

<ParamField type="string">
  Sort direction for `sortBy=createdAt`. `ASC` or `DESC`.
</ParamField>

<Note>
  `new` and `old` are deprecated aliases (removed in v8). `new` === `createdAt`
  with `sortDir=desc`; `old` === `createdAt` with `sortDir=asc`. They still work
  identically, but requests using them receive a non-blocking `Deprecation`
  response header — switch to `createdAt` (+ `sortDir`).
</Note>

<ParamField type="number">
  Page number (1-indexed).
</ParamField>

<ParamField type="number">
  Number of comments per page. Maximum `100`.
</ParamField>

<ParamField type="string">
  Comma-separated list of associations to include. Valid values: `user`, `entity`, `space`, `grants` (the [reputation-grant summary](/data-models/reputation-grant#grantsummary). Note `parent` is accepted by validation on this endpoint but is only resolved on the single-comment reads.)

  <Note>
    Requesting `space` automatically includes `entity` as well, since space membership is resolved via the entity.
    Requesting `user` also includes the user's avatar and banner file URLs.
  </Note>
</ParamField>

### Space-scoped reputation

This endpoint has a space in context, so it accepts the opt-in reputation params. They add a `spaceReputation` field to each populated author `user`, alongside the always-present `reputation` total. Requires the `reputation` bundle. See the [Reputation data model](/data-models/reputation) for the full contract.

<SpaceReputationParams />

## Response

Returns a paginated response:

```json theme={null}
{
  "data": [ ...Comment[] ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 54,
    "totalPages": 6,
    "hasMore": true
  }
}
```

Each item is a [Comment](/data-models/comment). In thread view (no `userId` filter), removed comments appear as stripped placeholders: `userId`, `user`, `content`, `gif`, `mentions`, and `attachments` are nulled out. Structural fields such as `id`, `parentId`, `entityId`, `reactionCounts`, `repliesCount`, `createdAt`, `updatedAt`, `metadata`, and `foreignId` are retained so the tree can be rendered. This applies to both user-deleted comments (always stripped) and moderation-removed comments (stripped for non-authors; the author sees full data).


# Fetch Comment Reactions
Source: https://docs.sublay.io/v7/api-reference/comments/fetch-reactions

GET /v7/:projectId/comments/:commentId/reactions
Get a paginated list of reactions on a comment

Returns a paginated list of reactions for a comment, each with the reacting user's profile. Useful for displaying "reacted by" lists or per-type reaction breakdowns.

Authentication is optional — the endpoint works without a token. When the caller is signed in, reactions from users with a block between them and the caller, in either direction, are excluded from both the results and the count. Block filtering requires the `moderation` bundle.

## Path Parameters

<ParamField type="string">
  The UUID of the comment.
</ParamField>

## Query Parameters

<ParamField type="number">
  Page number (1-indexed).
</ParamField>

<ParamField type="number">
  Number of reactions per page. Maximum `100`.
</ParamField>

<ParamField type="string">
  Filter to a specific reaction type. One of: `upvote`, `downvote`, `like`, `love`, `wow`, `sad`, `angry`, `funny`. When omitted, all types are returned.
</ParamField>

<ParamField type="string">
  Sort by creation time. `ASC` or `DESC`.
</ParamField>

### Space-scoped reputation

This endpoint has a space in context, so it accepts the opt-in reputation params. They add a `spaceReputation` field to each reactor's `user`, alongside the always-present `reputation` total. Requires the `reputation` bundle. See the [Reputation data model](/data-models/reputation) for the full contract.

<SpaceReputationParams />

## Response

```json theme={null}
{
  "data": [
    {
      "id": "uuid",
      "reactionType": "like",
      "userId": "uuid",
      "targetId": "commentId",
      "targetType": "comment",
      "user": {
        "id": "uuid",
        "name": "Alice",
        "username": "alice",
        "avatar": "https://...",
        "reputation": 120
      },
      "createdAt": "2025-01-01T00:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 8,
    "totalPages": 1,
    "hasMore": false
  }
}
```

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Comment not found.", "code": "comment/not-found" }
    ```
  </Accordion>
</AccordionGroup>


# Get User Reaction
Source: https://docs.sublay.io/v7/api-reference/comments/get-user-reaction

GET /v7/:projectId/comments/:commentId/reactions/me
Get the authenticated user's reaction on a comment

Returns the authenticated user's current reaction on the specified comment, or `null` if they have not reacted.

**Authentication required.**

## Path Parameters

<ParamField type="string">
  The UUID of the comment.
</ParamField>

## Response

```json theme={null}
{ "reactionType": "like" }
```

or, if the user has no reaction:

```json theme={null}
{ "reactionType": null }
```


# Remove Comment Reaction
Source: https://docs.sublay.io/v7/api-reference/comments/remove-reaction

DELETE /v7/:projectId/comments/:commentId/reactions
Remove the authenticated user's reaction from a comment

Removes the authenticated user's reaction from a comment. The comment's `reactionCounts` map is decremented for the removed reaction type.

**Authentication required.**

## Path Parameters

<ParamField type="string">
  The UUID of the comment to remove the reaction from.
</ParamField>

## Response

Returns the updated [Comment](/data-models/comment) object with the new `reactionCounts`.

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Comment not found.", "code": "comment/not-found" }
    ```
  </Accordion>
</AccordionGroup>


# Update Comment
Source: https://docs.sublay.io/v7/api-reference/comments/update-comment

PATCH /v7/:projectId/comments/:commentId
Edit a comment's content and/or metadata

Updates a comment's content, its metadata, or both. Only the comment's author, or a request with a service or master key, can update a comment.

**Authentication required.**

## Path Parameters

<ParamField type="string">
  The UUID of the comment to update.
</ParamField>

## Body Parameters

Both fields are individually optional, but **at least one must be provided**.

<ParamField type="string">
  The new text content for the comment. Cannot be empty. Omit to leave the existing content untouched.
</ParamField>

<ParamField type="object">
  Arbitrary JSON metadata, up to 1 MB. **Replaces** the stored metadata wholesale rather than merging into it.
</ParamField>

## Response

Returns the updated [Comment](/data-models/comment) object.

## Error Responses

<AccordionGroup>
  <Accordion title="Invalid Body — 400">
    Returned when neither `content` nor `metadata` is supplied, when `content` is an empty string, or when `metadata` exceeds 1 MB.

    ```json theme={null}
    { "error": "Either content or metadata must be provided", "code": "comment/invalid-body" }
    ```
  </Accordion>

  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Comment not found", "code": "comment/not-found" }
    ```
  </Accordion>

  <Accordion title="Forbidden — 403">
    ```json theme={null}
    { "error": "You do not have permission to update this comment.", "code": "comment/forbidden" }
    ```
  </Accordion>
</AccordionGroup>


# Accept Connection
Source: https://docs.sublay.io/v7/api-reference/connections/accept-connection

PATCH /v7/:projectId/connections/:connectionId/accept
Accept a pending connection request

Accepts a pending connection request. Only the receiver of the original request can accept it. A notification is sent to the original requester.

## Path Parameters

<ParamField type="string">
  The ID (UUID) of the pending connection record to accept.
</ParamField>

## Response

On success, returns HTTP `200`:

<ResponseField name="id" type="string">
  Connection record ID.
</ResponseField>

<ResponseField name="status" type="string">
  `"accepted"`.
</ResponseField>

<ResponseField name="respondedAt" type="string">
  ISO timestamp of when the connection was accepted.
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    {
      "error": "Pending connection request not found.",
      "code": "connection/not-found"
    }
    ```
  </Accordion>

  <Accordion title="Unauthorized — 403">
    ```json theme={null}
    {
      "error": "Only the receiver can accept a connection request.",
      "code": "connection/unauthorized"
    }
    ```
  </Accordion>
</AccordionGroup>

## See Also

* [`useAcceptConnection` hook](/hooks/connections/use-accept-connection)
* [Decline Connection](/api-reference/connections/decline-connection)


# Decline Connection
Source: https://docs.sublay.io/v7/api-reference/connections/decline-connection

PATCH /v7/:projectId/connections/:connectionId/decline
Decline a pending connection request

Declines a pending connection request. Only the receiver of the original request can decline it. The connection record status is updated to `"declined"` rather than being deleted.

## Path Parameters

<ParamField type="string">
  The ID (UUID) of the pending connection record to decline.
</ParamField>

## Response

On success, returns HTTP `200`:

<ResponseField name="id" type="string">
  Connection record ID.
</ResponseField>

<ResponseField name="status" type="string">
  `"declined"`.
</ResponseField>

<ResponseField name="respondedAt" type="string">
  ISO timestamp of when the request was declined.
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    {
      "error": "Pending connection request not found.",
      "code": "connection/not-found"
    }
    ```
  </Accordion>

  <Accordion title="Unauthorized — 403">
    ```json theme={null}
    {
      "error": "Only the receiver can decline a connection request.",
      "code": "connection/unauthorized"
    }
    ```
  </Accordion>
</AccordionGroup>

## See Also

* [`useDeclineConnection` hook](/hooks/connections/use-decline-connection)
* [Accept Connection](/api-reference/connections/accept-connection)


# Fetch Connections
Source: https://docs.sublay.io/v7/api-reference/connections/fetch-connections

GET /v7/:projectId/connections
Get a paginated list of the authenticated user's accepted connections

Returns a paginated list of accepted connections for the authenticated user. Each entry includes the connected user's public profile. Unlike the [user-scoped endpoint](/api-reference/users/connections/get-connections), this route always returns data for the current authenticated user.

<Note>
  Users with a block between them and you, in either direction, are excluded
  from the results. Requires the `moderation` bundle.
</Note>

## Query Parameters

<ParamField type="number">
  Page number for pagination. Defaults to `1`.
</ParamField>

<ParamField type="number">
  Number of results per page. Defaults to `20`. Max `100`.
</ParamField>

<ParamField type="string">
  Optional search term. Filters the list to connections whose connected user's username or name contains this text (case-insensitive). When omitted, no filtering is applied.
</ParamField>

<ParamField type="string">
  Restricts which field `query` matches against — `username` or `name`. When omitted, `query` matches either field.
</ParamField>

## Response

On success, returns HTTP `200` with a paginated response:

<ResponseField name="data" type="array">
  Array of connection entries.

  <Expandable title="item properties">
    <ResponseField name="id" type="string">
      Connection record ID.
    </ResponseField>

    <ResponseField name="connectedUser" type="object">
      Public profile of the connected user (the other party). Sensitive fields are excluded.
    </ResponseField>

    <ResponseField name="connectedAt" type="string">
      ISO timestamp of when the connection was accepted.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination metadata.

  <Expandable title="properties">
    <ResponseField name="page" type="number">
      Current page number.
    </ResponseField>

    <ResponseField name="pageSize" type="number">
      Number of items per page.
    </ResponseField>

    <ResponseField name="totalItems" type="number">
      Total number of accepted connections.
    </ResponseField>

    <ResponseField name="totalPages" type="number">
      Total number of pages.
    </ResponseField>

    <ResponseField name="hasMore" type="boolean">
      Whether there are more pages after the current one.
    </ResponseField>
  </Expandable>
</ResponseField>

## See Also

* [`useFetchConnections` hook](/hooks/connections/use-fetch-connections)
* [Get Connections (by user ID)](/api-reference/users/connections/get-connections)


# Fetch Connections Count
Source: https://docs.sublay.io/v7/api-reference/connections/fetch-connections-count

GET /v7/:projectId/connections/count
Get the number of accepted connections for the authenticated user

Returns the total number of accepted connections for the authenticated user.

<Note>
  Users with a block between them and you, in either direction, are excluded
  from the count. Requires the `moderation` bundle.
</Note>

## Response

On success, returns HTTP `200`:

<ResponseField name="count" type="number">
  Total number of accepted connections for the authenticated user.
</ResponseField>

## See Also

* [`useFetchConnectionsCount` hook](/hooks/connections/use-fetch-connections-count)


# Fetch Received Pending Connections
Source: https://docs.sublay.io/v7/api-reference/connections/fetch-received-pending

GET /v7/:projectId/connections/pending/received
Get connection requests received by the authenticated user that are still pending

Returns a paginated list of connection requests that other users have sent to the authenticated user and that have not yet been responded to.

<Note>
  Users with a block between them and you, in either direction, are excluded
  from the results. Requires the `moderation` bundle.
</Note>

## Query Parameters

<ParamField type="number">
  Page number for pagination. Defaults to `1`.
</ParamField>

<ParamField type="number">
  Number of results per page. Defaults to `20`. Max `100`.
</ParamField>

## Response

On success, returns HTTP `200` with a paginated response:

<ResponseField name="data" type="array">
  Array of pending connection request entries.

  <Expandable title="item properties">
    <ResponseField name="id" type="string">
      Connection record ID.
    </ResponseField>

    <ResponseField name="type" type="string">
      Always `"received"` for this endpoint.
    </ResponseField>

    <ResponseField name="user" type="object">
      Public profile of the user who sent the request. Sensitive fields are excluded.
    </ResponseField>

    <ResponseField name="message" type="string | null">
      Optional message included with the request.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO timestamp of when the request was sent.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination metadata.

  <Expandable title="properties">
    <ResponseField name="page" type="number">
      Current page number.
    </ResponseField>

    <ResponseField name="pageSize" type="number">
      Number of items per page.
    </ResponseField>

    <ResponseField name="totalItems" type="number">
      Total number of received pending requests.
    </ResponseField>

    <ResponseField name="totalPages" type="number">
      Total number of pages.
    </ResponseField>

    <ResponseField name="hasMore" type="boolean">
      Whether there are more pages after the current one.
    </ResponseField>
  </Expandable>
</ResponseField>

## See Also

* [`useFetchReceivedPendingConnections` hook](/hooks/connections/use-fetch-received-pending-connections)
* [Fetch Sent Pending Connections](/api-reference/connections/fetch-sent-pending)


# Fetch Sent Pending Connections
Source: https://docs.sublay.io/v7/api-reference/connections/fetch-sent-pending

GET /v7/:projectId/connections/pending/sent
Get connection requests sent by the authenticated user that are still pending

Returns a paginated list of connection requests that the authenticated user has sent and that have not yet been accepted, declined, or withdrawn.

<Note>
  Users with a block between them and you, in either direction, are excluded
  from the results. Requires the `moderation` bundle.
</Note>

## Query Parameters

<ParamField type="number">
  Page number for pagination. Defaults to `1`.
</ParamField>

<ParamField type="number">
  Number of results per page. Defaults to `20`. Max `100`.
</ParamField>

## Response

On success, returns HTTP `200` with a paginated response:

<ResponseField name="data" type="array">
  Array of pending connection request entries.

  <Expandable title="item properties">
    <ResponseField name="id" type="string">
      Connection record ID.
    </ResponseField>

    <ResponseField name="type" type="string">
      Always `"sent"` for this endpoint.
    </ResponseField>

    <ResponseField name="user" type="object">
      Public profile of the user who received the request. Sensitive fields are excluded.
    </ResponseField>

    <ResponseField name="message" type="string | null">
      Optional message included with the request.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO timestamp of when the request was sent.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination metadata.

  <Expandable title="properties">
    <ResponseField name="page" type="number">
      Current page number.
    </ResponseField>

    <ResponseField name="pageSize" type="number">
      Number of items per page.
    </ResponseField>

    <ResponseField name="totalItems" type="number">
      Total number of sent pending requests.
    </ResponseField>

    <ResponseField name="totalPages" type="number">
      Total number of pages.
    </ResponseField>

    <ResponseField name="hasMore" type="boolean">
      Whether there are more pages after the current one.
    </ResponseField>
  </Expandable>
</ResponseField>

## See Also

* [`useFetchSentPendingConnections` hook](/hooks/connections/use-fetch-sent-pending-connections)
* [Fetch Received Pending Connections](/api-reference/connections/fetch-received-pending)


# Remove Connection
Source: https://docs.sublay.io/v7/api-reference/connections/remove-connection

DELETE /v7/:projectId/connections/:connectionId
Withdraw a pending request or disconnect an accepted connection by connection ID

Removes a connection record by its ID. The behavior depends on the connection's current status:

* **Pending** — only the requester can withdraw the request (record is deleted).
* **Accepted** — either connected user can disconnect (record is deleted).

Use [Remove Connection (by user ID)](/api-reference/users/connections/remove-connection) if you only have the other user's ID.

## Path Parameters

<ParamField type="string">
  The ID (UUID) of the connection record to remove.
</ParamField>

## Response

On success, returns HTTP `200`:

<ResponseField name="message" type="string">
  Human-readable description: `"Connection request withdrawn successfully."` or `"Connection removed successfully."`.
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    {
      "error": "Connection not found or cannot be withdrawn.",
      "code": "connection/not-found"
    }
    ```
  </Accordion>

  <Accordion title="Unauthorized — 403">
    ```json theme={null}
    {
      "error": "Only the requester can withdraw a pending connection request.",
      "code": "connection/unauthorized"
    }
    ```
  </Accordion>
</AccordionGroup>

## See Also

* [`useRemoveConnection` hook](/hooks/connections/use-remove-connection)
* [Remove Connection (by user ID)](/api-reference/users/connections/remove-connection)


# Add Entity Reaction
Source: https://docs.sublay.io/v7/api-reference/entities/add-reaction

POST /v7/:projectId/entities/:entityId/reactions
Add or update a reaction on an entity

<Note>
  **Requires the `entities` bundle.** A project without the entities bundle returns `403 database/tables-not-available`. See [Bundles](/bundles).
</Note>

Adds a reaction of the specified type to an entity. If the user already has a reaction on this entity, it is replaced with the new type. The entity's `reactionCounts` map is updated accordingly.

**Authentication required.**

## Path Parameters

<ParamField type="string">
  The UUID of the entity to react to.
</ParamField>

## Body Parameters

<ParamField type="string">
  The type of reaction to add. One of: `upvote`, `downvote`, `like`, `love`, `wow`, `sad`, `angry`, `funny`.
</ParamField>

<ParamField type="string">
  Override which user the reaction is attributed to. **Service or master key only.** Useful for backfilling reactions from an external system.
</ParamField>

## Response

Returns the updated [Entity](/data-models/entity) object with the new `reactionCounts` map.

<Note>
  The entity owner receives an in-app notification when someone reacts to their entity. Milestone notifications are also sent at reaction count thresholds (e.g., 10, 50, 100 reactions).
</Note>

## Error Responses

<AccordionGroup>
  <Accordion title="Missing User — 400">
    ```json theme={null}
    { "error": "Missing user ID", "code": "entity/missing-user-id" }
    ```

    Returned when no user is authenticated and no `userId` override is provided.
  </Accordion>

  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Entity not found.", "code": "entity/not-found" }
    ```
  </Accordion>
</AccordionGroup>


# Create Entity
Source: https://docs.sublay.io/v7/api-reference/entities/create-entity

POST /v7/:projectId/entities
Create a new entity, with optional file upload support

<Note>
  **Requires the `entities` bundle.** A project without the entities bundle returns `403 database/tables-not-available`. See [Bundles](/bundles).
</Note>

Creates a new entity in your project. Supports optional file uploads via `multipart/form-data`. When no files are attached, use `application/json`. The entity is attributed to the authenticated user unless `excludeUserId` is set.

## Body Parameters

<ParamField type="string">
  Your application's identifier for this entity (URL, slug, database ID, etc.). Used to fetch or create entities without knowing the Sublay ID.
</ParamField>

<ParamField type="string">
  Groups entities by source. Use a topic ID or page ID to scope feeds to a specific context.
</ParamField>

<ParamField type="string">
  The ID of the space this entity belongs to. The space must exist in the same project.
</ParamField>

<ParamField type="string">
  Attribute the entity to a specific user. Must match the authenticated user ID unless the request uses a service or master key.
</ParamField>

<ParamField type="string">
  A title or headline for the entity.
</ParamField>

<ParamField type="string">
  The main body text of the entity.
</ParamField>

<ParamField type="object[]">
  An array of generic attachment objects. Each item is a free-form JSON object — structure is defined by your application.
</ParamField>

<ParamField type="string[]">
  Tags or keywords associated with this entity. Used for keyword-based filtering in the list endpoint.
</ParamField>

<ParamField type="object[]">
  Users or spaces mentioned in this entity. Each object is a discriminated union:

  * `{ type: "user", id: string, username: string, foreignId?: string }`
  * `{ type: "space", id: string, slug: string }`

  Mentioned users receive an in-app notification.
</ParamField>

<ParamField type="object">
  Geographic coordinates for this entity. Enables proximity-based filtering.

  ```json theme={null}
  { "latitude": 40.7128, "longitude": -74.0060 }
  ```
</ParamField>

<ParamField type="object">
  A free-form JSON object for any custom data your application needs alongside the entity. Supports rich filtering via `metadataFilters` in the list endpoint.
</ParamField>

<ParamField type="boolean">
  When `true`, the entity is saved as a draft and excluded from public feeds. Publish it later via the [Publish Entity](/api-reference/entities/publish-entity) endpoint.
</ParamField>

<ParamField type="boolean">
  When `true`, the entity is created without user attribution even if a user is authenticated.
</ParamField>

<ParamField type="boolean">
  When `true`, returns `401` if no user is authenticated.
</ParamField>

<ParamField type="string">
  ISO 8601 datetime to backfill a creation timestamp. **Service or master key only.**
</ParamField>

<ParamField type="string">
  ISO 8601 datetime for `updatedAt`. Requires `createdAt` to also be set. Must be ≥ `createdAt`. **Service or master key only.**
</ParamField>

### File Uploads (multipart/form-data)

When uploading files, send the request as `multipart/form-data`. All JSON fields above are sent as form fields.

Form fields can only carry strings, so the object and array fields — `attachments`, `keywords`, `mentions`, `location` and `metadata` — must be JSON-stringified. Booleans are sent as `"true"` / `"false"`. Plain strings such as `title` and `content` are sent as-is.

```js theme={null}
const form = new FormData();
form.append("title", "Sunset over the bay");
form.append("keywords", JSON.stringify(["sunset", "bay"]));
form.append("location", JSON.stringify({ latitude: 40.7128, longitude: -74.006 }));
form.append("metadata", JSON.stringify({ category: "photo" }));
form.append("nsfw", "false");
form.append("images.files", file);
form.append("images.options", JSON.stringify({ mode: "original-aspect", sizes: { full: 1080 } }));
```

<Note>
  The SDKs handle this for you — [`useCreateEntity`](/hooks/entities/use-create-entity) switches to `multipart/form-data` and stringifies these fields automatically as soon as you pass `images` or `files`.
</Note>

<ParamField type="file[]">
  Image files to attach. Maximum 10 images, 50 MB each. Must be valid images. Requires `images.options`.
</ParamField>

<ParamField type="string">
  Stringified JSON describing how to process uploaded images. Must include a `mode` field:

  * `"exact-dimensions"` — resize to specific pixel dimensions per variant
  * `"aspect-ratio-width-based"` — resize by width maintaining aspect ratio
  * `"aspect-ratio-height-based"` — resize by height maintaining aspect ratio
  * `"original-aspect"` — preserve original ratio, resize by max dimension
  * `"multi-aspect-ratio"` — generate crops at multiple aspect ratios

  Optional fields: `quality` (1–100), `format` (`webp`, `jpeg`, `png`, `original`), `stripExif` (boolean), `pathParts` (string\[]).
</ParamField>

<ParamField type="file[]">
  Generic files to attach. Maximum 10 files, 50 MB each.
</ParamField>

<ParamField type="string">
  Stringified JSON for file options. Optional `pathParts` (string\[]) customizes the storage path.
</ParamField>

## Response

Returns the created [Entity](/data-models/entity) object. When files are uploaded, the entity includes a `files` array with signed URLs for each attachment.

<Note>
  Draft entities are invisible to all users until published. Use [Fetch Drafts](/api-reference/entities/fetch-drafts) to list an author's unpublished drafts.
</Note>

## Error Responses

<AccordionGroup>
  <Accordion title="User Required — 401">
    ```json theme={null}
    { "error": "Authentication required to create this entity.", "code": "entity/user-required" }
    ```
  </Accordion>

  <Accordion title="Unauthorized User ID — 403">
    ```json theme={null}
    { "error": "User is not authorized to create this entity.", "code": "entity/unauthorized" }
    ```
  </Accordion>

  <Accordion title="Space Not Found — 404">
    ```json theme={null}
    { "error": "Space not found", "code": "entity/space-not-found" }
    ```
  </Accordion>

  <Accordion title="Invalid Timestamp — 400">
    ```json theme={null}
    { "error": "Cannot set updatedAt without also setting createdAt.", "code": "entity/invalid-timestamp" }
    ```

    Also returned when `updatedAt` is earlier than `createdAt`:

    ```json theme={null}
    { "error": "updatedAt must be the same or after createdAt.", "code": "entity/invalid-timestamp" }
    ```
  </Accordion>

  <Accordion title="File Too Large — 413">
    ```json theme={null}
    { "code": "entity/file-too-large", "message": "Image \"photo.jpg\" exceeds 50MB limit." }
    ```
  </Accordion>

  <Accordion title="Invalid Image — 422">
    ```json theme={null}
    { "code": "entity/invalid-image", "message": "File \"doc.txt\" is not a valid image: ..." }
    ```
  </Accordion>
</AccordionGroup>


# Delete Entity
Source: https://docs.sublay.io/v7/api-reference/entities/delete-entity

DELETE /v7/:projectId/entities/:entityId
Delete an entity

<Note>
  **Requires the `entities` bundle.** A project without the entities bundle returns `403 database/tables-not-available`. See [Bundles](/bundles).
</Note>

Deletes an entity and its associated data. Only the entity's author, or a request with a service or master key, can delete an entity.

**Authentication required.**

Deletion behavior depends on your project's `entityDeletion` settings:

* **Hard delete** (default): The entity and all its files are permanently removed.
* **Soft delete**: The entity is marked as deleted but retained in the database. File preservation is configurable separately.

## Path Parameters

<ParamField type="string">
  The UUID of the entity to delete.
</ParamField>

## Response

Returns `204 No Content` on success.

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Entity not found.", "code": "entity/not-found" }
    ```
  </Accordion>

  <Accordion title="Already Deleted — 404">
    ```json theme={null}
    { "error": "Entity not found or already deleted.", "code": "entity/delete-failed" }
    ```

    Returned when the entity record exists but could not be deleted (e.g., it was already soft-deleted).
  </Accordion>

  <Accordion title="Unauthorized — 403">
    ```json theme={null}
    { "error": "Not authorized to delete this entity.", "code": "entity/not-authorized" }
    ```
  </Accordion>
</AccordionGroup>


# Fetch Drafts
Source: https://docs.sublay.io/v7/api-reference/entities/fetch-drafts

GET /v7/:projectId/entities/drafts
Get the authenticated user's draft entities

<Note>
  **Requires the `entities` bundle.** A project without the entities bundle returns `403 database/tables-not-available`. See [Bundles](/bundles).
</Note>

Returns a paginated list of draft entities belonging to the authenticated user. Drafts are invisible to all other users and excluded from all other entity list endpoints until published.

**Authentication required.**

## Query Parameters

<ParamField type="number">
  Page number (1-indexed).
</ParamField>

<ParamField type="number">
  Number of drafts per page. Maximum `100`.
</ParamField>

<ParamField type="string">
  Filter drafts by `sourceId`. Pass `"null"` to return drafts with no `sourceId`.
</ParamField>

<ParamField type="string">
  Filter drafts by space ID.
</ParamField>

<ParamField type="string">
  Comma-separated list of associations to include:

  * `user` — the author's user profile
  * `space` — the space the entity belongs to
  * `files` — uploaded file/image attachments
  * `grants` — the [reputation-grant summary](/data-models/reputation-grant#grantsummary) for the entity

  <Note>`topComment` and `saved` are not supported for drafts.</Note>
</ParamField>

## Response

Returns a paginated response:

```json theme={null}
{
  "data": [ ...Entity[] ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 3,
    "totalPages": 1,
    "hasMore": false
  }
}
```

Each item is an [Entity](/data-models/entity) with `isDraft: true`. Results are ordered by most recently updated.

## Error Responses

<AccordionGroup>
  <Accordion title="Unauthorized — 401">
    Returned when no user is authenticated.
  </Accordion>
</AccordionGroup>


# Fetch Entity
Source: https://docs.sublay.io/v7/api-reference/entities/fetch-entity

GET /v7/:projectId/entities/:entityId
Get a single entity by its Sublay ID

<Note>
  **Requires the `entities` bundle.** A project without the entities bundle returns `403 database/tables-not-available`. See [Bundles](/bundles).
</Note>

Returns a single entity by its Sublay UUID. Always returns the entity regardless of moderation status, so the client can display the appropriate moderation state. Drafts are only returned to their author (or with a service/master key).

## Path Parameters

<ParamField type="string">
  The UUID of the entity to fetch.
</ParamField>

## Query Parameters

<ParamField type="string">
  Comma-separated list of associations to include:

  * `user` — the author's user profile
  * `space` — the space the entity belongs to
  * `topComment` — the highest-voted comment
  * `saved` — whether the authenticated user has saved this entity (requires auth)
  * `files` — uploaded file/image attachments
  * `grants` — the [reputation-grant summary](/data-models/reputation-grant#grantsummary) for the entity
</ParamField>

### Space-scoped reputation

This endpoint has a space in context, so it accepts the opt-in reputation params. They add a `spaceReputation` field to the populated author `user`, alongside the always-present `reputation` total. Requires the `reputation` bundle. See the [Reputation data model](/data-models/reputation) for the full contract.

<SpaceReputationParams />

## Response

Returns an [Entity](/data-models/entity) object.

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Entity not found", "code": "entity/not-found" }
    ```

    Also returned for draft entities when the requester is not the author.
  </Accordion>
</AccordionGroup>


# Fetch Entity by Foreign ID
Source: https://docs.sublay.io/v7/api-reference/entities/fetch-entity-by-foreign-id

GET /v7/:projectId/entities/by-foreign-id
Get an entity by its foreign ID, optionally creating it if not found

<Note>
  **Requires the `entities` bundle.** A project without the entities bundle returns `403 database/tables-not-available`. See [Bundles](/bundles).
</Note>

Returns an entity matching the given `foreignId` within the project. Optionally creates a blank entity if none exists — useful for automatically bootstrapping entities when a user first visits a page or URL in your application.

## Query Parameters

<ParamField type="string">
  The foreign ID to look up. This is the identifier from your application (URL, slug, database ID, etc.).
</ParamField>

<ParamField type="string">
  When `"true"`, creates a blank entity with this `foreignId` if no entity is found. The new entity has no title, content, or user attribution. Defaults to `"false"`.
</ParamField>

<ParamField type="string">
  Comma-separated list of associations to include:

  * `user` — the author's user profile
  * `space` — the space the entity belongs to
  * `topComment` — the highest-voted comment
  * `saved` — whether the authenticated user has saved this entity
  * `files` — uploaded file/image attachments
  * `grants` — the [reputation-grant summary](/data-models/reputation-grant#grantsummary) for the entity
</ParamField>

## Response

Returns an [Entity](/data-models/entity) object.

<Note>
  This endpoint returns entities regardless of moderation status, so the client can display the appropriate moderation state. Draft entities are only returned to their author (or with a service/master key).
</Note>

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Entity not found", "code": "entity/not-found" }
    ```

    Returned when no entity with this `foreignId` exists and `createIfNotFound` is not `"true"`.
  </Accordion>
</AccordionGroup>


# Fetch Entity by Short ID
Source: https://docs.sublay.io/v7/api-reference/entities/fetch-entity-by-short-id

GET /v7/:projectId/entities/by-short-id
Get an entity by its short ID

<Note>
  **Requires the `entities` bundle.** A project without the entities bundle returns `403 database/tables-not-available`. See [Bundles](/bundles).
</Note>

Returns a single entity matching the given `shortId`. Short IDs are compact, URL-friendly identifiers automatically assigned to each entity. They are useful for building shareable deep links.

## Query Parameters

<ParamField type="string">
  The short ID of the entity to fetch.
</ParamField>

<ParamField type="string">
  Comma-separated list of associations to include:

  * `user` — the author's user profile
  * `space` — the space the entity belongs to
  * `topComment` — the highest-voted comment
  * `saved` — whether the authenticated user has saved this entity
  * `files` — uploaded file/image attachments
  * `grants` — the [reputation-grant summary](/data-models/reputation-grant#grantsummary) for the entity
</ParamField>

## Response

Returns an [Entity](/data-models/entity) object.

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Entity not found", "code": "entity/not-found" }
    ```
  </Accordion>
</AccordionGroup>


# Fetch Many Entities
Source: https://docs.sublay.io/v7/api-reference/entities/fetch-many-entities

GET /v7/:projectId/entities
Get a paginated, filtered list of entities

<Note>
  **Requires the `entities` bundle.** A project without the entities bundle returns `403 database/tables-not-available`. See [Bundles](/bundles).
</Note>

Returns a paginated list of entities for the project. Supports rich filtering by source, space, user, keywords, metadata, title, content, location, and time. Excludes drafts — use [Fetch Drafts](/api-reference/entities/fetch-drafts) for those.

## Query Parameters

### Pagination

<ParamField type="number">
  Page number (1-indexed).
</ParamField>

<ParamField type="number">
  Number of entities per page. Maximum `100`.
</ParamField>

### Sorting

<ParamField type="string">
  Sort algorithm. One of:

  * `createdAt` — chronological by creation time (honors `sortDir`; newest first by default)
  * `top` — by reaction count (use `sortByReaction` to specify which type)
  * `hot` — by computed engagement score (decays over time)
  * `controversial` — high total votes with a close up/down split (entities with no votes sort last)
  * `metadata.<property>` — sort by a metadata field (e.g. `metadata.memberCount`)
</ParamField>

<Note>
  `new` is a deprecated alias for `createdAt` (removed in v8). It still works and
  behaves identically, but requests using it receive a non-blocking `Deprecation`
  response header — switch to `createdAt`.
</Note>

<ParamField type="string">
  Sort direction. `ASC` or `DESC`.
</ParamField>

<ParamField type="string">
  When using `sortBy=metadata.*`, the type of the metadata field. One of `auto`, `numeric`, `text`, `boolean`, `timestamp`. `auto` infers the type at query time.
</ParamField>

<ParamField type="string">
  When `sortBy=top`, which reaction type to rank by. One of `upvote`, `downvote`, `like`, `love`, `wow`, `sad`, `angry`, `funny`.
</ParamField>

### Filtering

<ParamField type="string">
  Restrict to entities created within the last period. One of `hour`, `day`, `week`, `month`, `year`.
</ParamField>

<ParamField type="string">
  Filter by `sourceId`. Pass `"null"` to return entities with no `sourceId`.
</ParamField>

<ParamField type="string">
  Filter by space ID.
</ParamField>

<ParamField type="string">
  Filter by the author's user ID. When this matches the authenticated user's ID, moderation-removed entities are also included (author can see their own removed posts).
</ParamField>

<ParamField type="string">
  When `"true"`, only returns entities from users the authenticated user follows. Requires authentication.
</ParamField>

<ParamField type="string">
  Controls how entities authored by users the viewer is [block-edged](/sdk/moderation/overview#blocking) with are treated. `"exclude"` (default) hides those entities. `"include-outbound-blocked"` re-includes entities authored **only** by users the viewer themselves blocked (their own "view anyway" choice); it never surfaces content from users who blocked the viewer. Counts reflect what the viewer sees (computed post-filter). Has no effect when the `moderation` bundle is not installed.
</ParamField>

<ParamField type="object">
  Filter by keywords. Pass as a JSON string or bracket-notation query params:

  ```json theme={null}
  { "includes": ["react", "typescript"], "doesNotInclude": ["vue"] }
  ```
</ParamField>

<ParamField type="object">
  Filter by title content:

  ```json theme={null}
  {
    "hasTitle": "true",
    "includes": "tutorial",
    "doesNotInclude": "beginner"
  }
  ```

  * `hasTitle`: `"true"` or `"false"` — filter for presence/absence of a title
  * `includes`: substring(s) to match (case-insensitive)
  * `doesNotInclude`: substring(s) to exclude
</ParamField>

<ParamField type="object">
  Filter by content text. Same structure as `titleFilters` (`hasContent`, `includes`, `doesNotInclude`).
</ParamField>

<ParamField type="object">
  Filter by attachment presence:

  ```json theme={null}
  { "hasAttachments": "true" }
  ```
</ParamField>

<ParamField type="object">
  Filter to entities within a radius of a point:

  ```json theme={null}
  { "latitude": "40.7128", "longitude": "-74.0060", "radius": "5000" }
  ```

  `radius` is in meters.
</ParamField>

<ParamField type="object">
  Filter by metadata values. Supports complex conditions:

  ```json theme={null}
  {
    "includes": { "status": "published" },
    "includesAny": [{ "type": "video" }, { "type": "image" }],
    "doesNotInclude": { "hidden": true },
    "exists": ["category"],
    "doesNotExist": ["archivedAt"]
  }
  ```

  * `includes` — all key/value pairs must match (AND)
  * `includesAny` — at least one object must match (OR)
  * `doesNotInclude` — none of these key/value pairs may match
  * `exists` — keys that must be present
  * `doesNotExist` — keys that must be absent
</ParamField>

### Optional Associations

<ParamField type="string">
  Comma-separated list of associations to include in each entity:

  * `user` — the author's user profile
  * `space` — the space the entity belongs to
  * `topComment` — the highest-voted comment
  * `saved` — whether the authenticated user has saved this entity
  * `files` — uploaded file/image attachments
  * `grants` — the [reputation-grant summary](/data-models/reputation-grant#grantsummary) for the entity
</ParamField>

### Space-scoped reputation

This endpoint has a space in context, so it accepts the opt-in reputation params. They add a `spaceReputation` field to each populated author `user`, alongside the always-present `reputation` total. Requires the `reputation` bundle. See the [Reputation data model](/data-models/reputation) for the full contract.

<SpaceReputationParams />

## Response

Returns a paginated response object:

```json theme={null}
{
  "data": [ ...Entity[] ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 42,
    "totalPages": 5,
    "hasMore": true
  }
}
```

Each item in `data` is an [Entity](/data-models/entity) object. File URLs are signed and ready to use.

<Note>
  Viewing scores (`hot` sort) are updated asynchronously after each fetch. Scores use a configurable half-life that can be set per project in your project settings.
</Note>

## See Also

* [Reputation data model](/data-models/reputation) — the `spaceReputation` object contract
* [Entity data model](/data-models/entity)


# Fetch Entity Reactions
Source: https://docs.sublay.io/v7/api-reference/entities/fetch-reactions

GET /v7/:projectId/entities/:entityId/reactions
Get a paginated list of reactions on an entity

<Note>
  **Requires the `entities` bundle.** A project without the entities bundle returns `403 database/tables-not-available`. See [Bundles](/bundles).
</Note>

Returns a paginated list of reactions for an entity, each with the reacting user's profile. Useful for displaying "liked by" lists or reaction breakdowns.

Authentication is optional — the endpoint works without a token. When the caller is signed in, reactions from users with a block between them and the caller, in either direction, are excluded from both the results and the count. Block filtering requires the `moderation` bundle.

## Path Parameters

<ParamField type="string">
  The UUID of the entity.
</ParamField>

## Query Parameters

<ParamField type="number">
  Page number (1-indexed).
</ParamField>

<ParamField type="number">
  Number of reactions per page. Maximum `100`.
</ParamField>

<ParamField type="string">
  Filter to a specific reaction type. One of: `upvote`, `downvote`, `like`, `love`, `wow`, `sad`, `angry`, `funny`. When omitted, all reaction types are returned.
</ParamField>

<ParamField type="string">
  Sort by creation time. `ASC` or `DESC`.
</ParamField>

### Space-scoped reputation

This endpoint has a space in context, so it accepts the opt-in reputation params. They add a `spaceReputation` field to each reactor's `user`, alongside the always-present `reputation` total. Requires the `reputation` bundle. See the [Reputation data model](/data-models/reputation) for the full contract.

<SpaceReputationParams />

## Response

```json theme={null}
{
  "data": [
    {
      "id": "uuid",
      "reactionType": "like",
      "userId": "uuid",
      "targetId": "entityId",
      "targetType": "entity",
      "user": {
        "id": "uuid",
        "name": "Alice",
        "username": "alice",
        "avatar": "https://...",
        "reputation": 120
      },
      "createdAt": "2025-01-01T00:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "totalPages": 3,
    "hasMore": true
  }
}
```

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Entity not found.", "code": "entity/not-found" }
    ```
  </Accordion>
</AccordionGroup>


# Fetch Top Comment
Source: https://docs.sublay.io/v7/api-reference/entities/fetch-top-comment

GET /v7/:projectId/entities/:entityId/top-comment
Get the highest-voted comment on an entity

<Note>
  **Requires the `entities` bundle.** A project without the entities bundle returns `403 database/tables-not-available`. See [Bundles](/bundles).
</Note>

Returns the single comment with the most upvotes for the given entity. Useful for previewing the best comment alongside an entity in a feed. When multiple comments are tied, the oldest is returned.

Returns `null` if the entity has no comments.

## Path Parameters

<ParamField type="string">
  The UUID of the entity.
</ParamField>

## Response

Returns a [Comment](/data-models/comment) object, or `null` if there are no comments.

```json theme={null}
null
```

or

```json theme={null}
{
  "id": "uuid",
  "content": "Great post!",
  "upvotes": ["userId1", "userId2"],
  ...
}
```


# Get User Reaction
Source: https://docs.sublay.io/v7/api-reference/entities/get-user-reaction

GET /v7/:projectId/entities/:entityId/reactions/me
Get the authenticated user's reaction on an entity

<Note>
  **Requires the `entities` bundle.** A project without the entities bundle returns `403 database/tables-not-available`. See [Bundles](/bundles).
</Note>

Returns the authenticated user's current reaction on the specified entity, or `null` if they have not reacted.

**Authentication required.**

## Path Parameters

<ParamField type="string">
  The UUID of the entity.
</ParamField>

## Response

```json theme={null}
{ "reactionType": "like" }
```

or, if the user has no reaction:

```json theme={null}
{ "reactionType": null }
```


# Is Entity Saved
Source: https://docs.sublay.io/v7/api-reference/entities/is-entity-saved

GET /v7/:projectId/entities/is-entity-saved
Check whether an entity is saved in any of the current user's collections

<Note>
  **Requires the `entities` bundle.** A project without the entities bundle returns `403 database/tables-not-available`. See [Bundles](/bundles).
</Note>

Returns whether the specified entity is saved in any collection belonging to the authenticated user, along with the list of matching collections.

## Query Parameters

<ParamField type="string">
  The ID of the entity to check.
</ParamField>

## Response

<ResponseField name="saved" type="boolean">
  `true` if the entity is saved in at least one collection.
</ResponseField>

<ResponseField name="collections" type="Array<{ id: string; name: string }>">
  List of collections (by ID and name) that contain this entity.
</ResponseField>

```json theme={null}
{
  "saved": true,
  "collections": [
    { "id": "col_abc", "name": "To Read" },
    { "id": "col_xyz", "name": "Favorites" }
  ]
}
```

## Error Responses

<AccordionGroup>
  <Accordion title="Server Error — 500">
    ```json theme={null}
    { "error": "Internal server error.", "code": "collection/server-error" }
    ```
  </Accordion>
</AccordionGroup>


# Publish Entity
Source: https://docs.sublay.io/v7/api-reference/entities/publish-entity

PATCH /v7/:projectId/entities/:entityId/publish
Publish a draft entity, making it publicly visible

<Note>
  **Requires the `entities` bundle.** A project without the entities bundle returns `403 database/tables-not-available`. See [Bundles](/bundles).
</Note>

Publishes a draft entity. After publishing, the entity appears in normal feeds and is visible to all users. The entity's `isDraft` field is set to `false` and `createdAt` is reset to the current time.

**Authentication required.** Only the entity's author, or a request with a service or master key, can publish a draft.

## Path Parameters

<ParamField type="string">
  The UUID of the draft entity to publish.
</ParamField>

## Response

Returns the published [Entity](/data-models/entity) object with `isDraft: false`.

<Note>
  Publishing resets `createdAt` to the current time, so the entity appears as "new" in chronological feeds regardless of when the draft was created.
</Note>

<Note>
  Mention notifications are sent when publishing, not when the draft is created. Users mentioned in the entity receive notifications at publish time.
</Note>

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Draft entity not found", "code": "entity/not-found" }
    ```

    Returned when no draft with this ID exists (or the entity is not a draft).
  </Accordion>

  <Accordion title="Unauthorized — 403">
    ```json theme={null}
    { "error": "Not authorized to publish this draft.", "code": "entity/unauthorized" }
    ```
  </Accordion>
</AccordionGroup>


# Remove Entity Reaction
Source: https://docs.sublay.io/v7/api-reference/entities/remove-reaction

DELETE /v7/:projectId/entities/:entityId/reactions
Remove the authenticated user's reaction from an entity

<Note>
  **Requires the `entities` bundle.** A project without the entities bundle returns `403 database/tables-not-available`. See [Bundles](/bundles).
</Note>

Removes the authenticated user's reaction from an entity. The entity's `reactionCounts` map is decremented for the removed reaction type.

**Authentication required.**

## Path Parameters

<ParamField type="string">
  The UUID of the entity to remove the reaction from.
</ParamField>

## Response

Returns the updated [Entity](/data-models/entity) object with the new `reactionCounts`.

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Entity not found.", "code": "entity/not-found" }
    ```
  </Accordion>
</AccordionGroup>


# Update Entity
Source: https://docs.sublay.io/v7/api-reference/entities/update-entity

PATCH /v7/:projectId/entities/:entityId
Update an entity's content and metadata

<Note>
  **Requires the `entities` bundle.** A project without the entities bundle returns `403 database/tables-not-available`. See [Bundles](/bundles).
</Note>

Updates the fields of an existing entity. Only the fields you include in the request body are updated — omitted fields are left unchanged. Only the entity's author, or a request with a service or master key, can update an entity.

**Authentication required.**

## Path Parameters

<ParamField type="string">
  The UUID of the entity to update.
</ParamField>

## Body Parameters

<ParamField type="string">
  New title for the entity.
</ParamField>

<ParamField type="string">
  New content body for the entity.
</ParamField>

<ParamField type="object[]">
  Replaces the entity's `attachments` array with the provided value.
</ParamField>

<ParamField type="string[]">
  Replaces the entity's `keywords` array.
</ParamField>

<ParamField type="object[]">
  Replaces the entity's `mentions` array. Each item is:

  * `{ type: "user", id: string, username: string, foreignId?: string }`
  * `{ type: "space", id: string, slug: string }`
</ParamField>

<ParamField type="object">
  New geographic coordinates:

  ```json theme={null}
  { "latitude": 40.7128, "longitude": -74.0060 }
  ```
</ParamField>

<ParamField type="object">
  Replaces the entity's `metadata` object entirely.
</ParamField>

## Response

Returns the updated [Entity](/data-models/entity) object, populated with the author's user profile.

<Note>
  If `title` or `content` changed, the entity's semantic search embeddings are automatically re-queued for projects with AI search enabled.
</Note>

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Entity not found.", "code": "entity/not-found" }
    ```
  </Accordion>

  <Accordion title="Unauthorized — 403">
    ```json theme={null}
    { "error": "Not authorized to update this entity.", "code": "entity/not-authorized" }
    ```
  </Accordion>
</AccordionGroup>


# Delete Follow
Source: https://docs.sublay.io/v7/api-reference/follows/delete-follow

DELETE /v7/:projectId/follows/:followId
Remove a follow relationship by its follow ID

Removes a follow relationship by the follow record ID. Only the follower (the user who created the follow) can delete it. Use [Unfollow User](/api-reference/users/follows/unfollow-user) instead if you only have the target user's ID.

## Path Parameters

<ParamField type="string">
  The ID (UUID) of the follow record to delete.
</ParamField>

## Response

On success, returns HTTP `204` with no body.

## Error Responses

<AccordionGroup>
  <Accordion title="Follow Not Found — 404">
    ```json theme={null}
    {
      "error": "Follow relationship does not exist.",
      "code": "follow/not-found"
    }
    ```
  </Accordion>

  <Accordion title="Forbidden — 403">
    ```json theme={null}
    {
      "error": "You do not have permission to delete this follow relationship.",
      "code": "follow/forbidden"
    }
    ```
  </Accordion>
</AccordionGroup>

## See Also

* [`useUnfollowByFollowId` hook](/hooks/follows/use-unfollow-by-follow-id)
* [Unfollow User (by user ID)](/api-reference/users/follows/unfollow-user)


# Fetch Followers
Source: https://docs.sublay.io/v7/api-reference/follows/fetch-followers

GET /v7/:projectId/follows/followers
Get a paginated list of the authenticated user's followers

Returns a paginated list of users who follow the authenticated user. Unlike the [user-scoped endpoint](/api-reference/users/follows/get-followers), this route always returns data for the current authenticated user.

<Note>
  Users with a block between them and you, in either direction, are excluded
  from the results. Requires the `moderation` bundle.
</Note>

## Query Parameters

<ParamField type="number">
  Page number for pagination. Defaults to `1`.
</ParamField>

<ParamField type="number">
  Number of results per page. Defaults to `20`. Max `100`.
</ParamField>

<ParamField type="string">
  Optional search term. Filters the list to users whose username or name contains this text (case-insensitive). When omitted, no filtering is applied.
</ParamField>

<ParamField type="string">
  Restricts which field `query` matches against — `username` or `name`. When omitted, `query` matches either field.
</ParamField>

## Response

On success, returns HTTP `200` with a paginated response:

<ResponseField name="data" type="array">
  Array of follow entries.

  <Expandable title="item properties">
    <ResponseField name="followId" type="string">
      ID of the follow record.
    </ResponseField>

    <ResponseField name="user" type="object">
      Public profile of the follower user. Sensitive fields (email, hash, secureMetadata, etc.) are excluded.
    </ResponseField>

    <ResponseField name="followedAt" type="string">
      ISO timestamp of when the follow was created.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination metadata.

  <Expandable title="properties">
    <ResponseField name="page" type="number">
      Current page number.
    </ResponseField>

    <ResponseField name="pageSize" type="number">
      Number of items per page.
    </ResponseField>

    <ResponseField name="totalItems" type="number">
      Total number of followers.
    </ResponseField>

    <ResponseField name="totalPages" type="number">
      Total number of pages.
    </ResponseField>

    <ResponseField name="hasMore" type="boolean">
      Whether there are more pages after the current one.
    </ResponseField>
  </Expandable>
</ResponseField>

## See Also

* [`useFetchFollowers` hook](/hooks/follows/use-fetch-followers)
* [Get Followers (by user ID)](/api-reference/users/follows/get-followers)


# Fetch Followers Count
Source: https://docs.sublay.io/v7/api-reference/follows/fetch-followers-count

GET /v7/:projectId/follows/followers-count
Get the number of followers the authenticated user has

Returns the total number of users following the authenticated user.

<Note>
  Users with a block between them and you, in either direction, are excluded
  from the count. Requires the `moderation` bundle.
</Note>

## Response

On success, returns HTTP `200`:

<ResponseField name="count" type="number">
  Total number of users following the authenticated user.
</ResponseField>

## See Also

* [`useFetchFollowersCount` hook](/hooks/follows/use-fetch-followers-count)


# Fetch Following
Source: https://docs.sublay.io/v7/api-reference/follows/fetch-following

GET /v7/:projectId/follows/following
Get a paginated list of users the authenticated user follows

Returns a paginated list of users that the authenticated user is following. Unlike the [user-scoped endpoint](/api-reference/users/follows/get-following), this route always returns data for the current authenticated user.

<Note>
  Users with a block between them and you, in either direction, are excluded
  from the results. Requires the `moderation` bundle.
</Note>

## Query Parameters

<ParamField type="number">
  Page number for pagination. Defaults to `1`.
</ParamField>

<ParamField type="number">
  Number of results per page. Defaults to `20`. Max `100`.
</ParamField>

<ParamField type="string">
  Optional search term. Filters the list to users whose username or name contains this text (case-insensitive). When omitted, no filtering is applied.
</ParamField>

<ParamField type="string">
  Restricts which field `query` matches against — `username` or `name`. When omitted, `query` matches either field.
</ParamField>

## Response

On success, returns HTTP `200` with a paginated response:

<ResponseField name="data" type="array">
  Array of follow entries.

  <Expandable title="item properties">
    <ResponseField name="followId" type="string">
      ID of the follow record.
    </ResponseField>

    <ResponseField name="user" type="object">
      Public profile of the followed user. Sensitive fields (email, hash, secureMetadata, etc.) are excluded.
    </ResponseField>

    <ResponseField name="followedAt" type="string">
      ISO timestamp of when the follow was created.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination metadata.

  <Expandable title="properties">
    <ResponseField name="page" type="number">
      Current page number.
    </ResponseField>

    <ResponseField name="pageSize" type="number">
      Number of items per page.
    </ResponseField>

    <ResponseField name="totalItems" type="number">
      Total number of users being followed.
    </ResponseField>

    <ResponseField name="totalPages" type="number">
      Total number of pages.
    </ResponseField>

    <ResponseField name="hasMore" type="boolean">
      Whether there are more pages after the current one.
    </ResponseField>
  </Expandable>
</ResponseField>

## See Also

* [`useFetchFollowing` hook](/hooks/follows/use-fetch-following)
* [Get Following (by user ID)](/api-reference/users/follows/get-following)


# Fetch Following Count
Source: https://docs.sublay.io/v7/api-reference/follows/fetch-following-count

GET /v7/:projectId/follows/following-count
Get the number of users the authenticated user follows

Returns the total number of users that the authenticated user is following.

<Note>
  Users with a block between them and you, in either direction, are excluded
  from the count. Requires the `moderation` bundle.
</Note>

## Response

On success, returns HTTP `200`:

<ResponseField name="count" type="number">
  Total number of users the authenticated user follows.
</ResponseField>

## See Also

* [`useFetchFollowingCount` hook](/hooks/follows/use-fetch-following-count)


# Deregister Device
Source: https://docs.sublay.io/v7/api-reference/push-notifications/deregister-device

DELETE /v7/:projectId/push-notifications/devices
Remove a device registration so the authenticated user stops receiving push notifications on it

Removes the calling user's push device registration. The device is identified the same way it was registered — by its token (iOS/Android) or subscription endpoint (Web).

**Deregistration is idempotent.** The endpoint returns `200` whether or not a matching registration existed — the contract is "this binding is gone", and it is equally gone if an earlier call removed it or it never existed. There is no not-found error.

Only the calling user's own binding is removed. A device can be registered by several accounts at once, so deregistering unbinds the caller's account from that device and leaves every other account's binding on the same device intact — callers cannot deregister devices they don't own.

Requires end-user authentication. Service and master keys are rejected for the same reason as [Register Device](/api-reference/push-notifications/register-device#security-note).

Requires the `push` bundle.

## Body Parameters

<ParamField type="string">
  The device platform. One of `"ios"`, `"android"`, or `"web"`.
</ParamField>

<ParamField type="string">
  The APNs or FCM device token. Required when `platform` is `"ios"` or `"android"`.
</ParamField>

<ParamField type="object">
  The Web Push subscription object. Required when `platform` is `"web"`. The server uses only the `endpoint` field to identify the registration.

  <Expandable title="subscription fields">
    <ParamField type="string">
      The push subscription endpoint URL.
    </ParamField>

    <ParamField type="string">
      P-256 key (Base64). Must match the original registration.
    </ParamField>

    <ParamField type="string">
      Auth secret (Base64). Must match the original registration.
    </ParamField>
  </Expandable>
</ParamField>

## Response

Returns `200` on success, including when no matching registration existed.

```json theme={null}
{ "success": true }
```

## Error Responses

<AccordionGroup>
  <Accordion title="No Credential — 401">
    Plain-text `Unauthorized`, with no JSON body and no `code`. Returned when the
    request carries no `Authorization` header at all.
  </Accordion>

  <Accordion title="Rejected Credential — 403">
    Plain-text `Forbidden`, with no JSON body and no `code`. Returned when the
    access token is malformed, has the wrong signature, or has **expired** — the
    common case, since access tokens live 30 minutes. Refresh the access token
    and retry; do not treat this as a permanent refusal.
  </Accordion>

  <Accordion title="Service Key Rejected — 401">
    ```json theme={null}
    { "error": "Unauthorized", "code": "push-device/unauthorized" }
    ```

    Returned when a service or master key is used. This endpoint has no
    impersonation path by design (see [Security note](/api-reference/push-notifications/register-device#security-note)).
  </Accordion>

  <Accordion title="Invalid Body — 400">
    ```json theme={null}
    { "error": "...", "code": "push-device/invalid-body" }
    ```
  </Accordion>

  <Accordion title="Bundle Not Installed — 403">
    ```json theme={null}
    {
      "code": "database/tables-not-available",
      "missingTables": ["PushProviderConfigs", "PushDevices", "NotificationPreferences"],
      "dashboardUrl": "https://…/<projectId>/database"
    }
    ```
  </Accordion>

  <Accordion title="Bundle Provisioning — 503">
    ```json theme={null}
    {
      "code": "database/tables-provisioning",
      "missingTables": ["PushProviderConfigs", "PushDevices", "NotificationPreferences"],
      "bundleId": "push"
    }
    ```

    Returned while the `push` bundle is mid-install. Retry shortly.
  </Accordion>

  <Accordion title="Server Error — 500">
    ```json theme={null}
    { "error": "Internal server error.", "code": "push-device/server-error" }
    ```

    The deletion could not be performed. No diagnostic detail is returned; retry.
  </Accordion>
</AccordionGroup>

**Rate limit:** 50 requests per 5 minutes per IP. Exceeding it returns `429` with a plain-text message and no `code`.

## See Also

* [Register Device](/api-reference/push-notifications/register-device)
* [`usePushRegistration`](/hooks/push/use-push-registration)


# Get Notification Preferences
Source: https://docs.sublay.io/v7/api-reference/push-notifications/get-preferences

GET /v7/:projectId/push-notifications/preferences
Read the authenticated user's disabled push notification types

Returns the set of notification event types the acting user has disabled for push. A user with no preference row is **all-on** — the response is an empty `disabledTypes` array.

Disabling a type only suppresses **push**; the in-app notification is still written.

Requires authentication. **Acting-user-scoped:** an end-user token (`Authorization: Bearer <accessToken>`) reads its own preferences. A service/master key acts on behalf of a named user via the optional `userId` query param — a service key without `userId` is rejected, and an end-user token may not name a different user. Requires the `push` bundle.

## Query Parameters

<ParamField type="string">
  The acting user whose preferences are read. **Service/master keys only** — a service key must pass it; an end-user token infers it from the auth token and may not name a different user.
</ParamField>

## Response

Returns `200`.

```json theme={null}
{ "disabledTypes": ["new-follow", "message"] }
```

<ResponseField name="disabledTypes" type="string[]">
  The event types the user has opted out of. Empty when no preferences are set (all-on). Values are drawn from the [event palette](/notification-preferences#the-event-palette).
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="No Credential — 401">
    Plain-text `Unauthorized`, with no JSON body and no `code`. Returned when the
    request carries no `Authorization` header at all.
  </Accordion>

  <Accordion title="Rejected Credential — 403">
    Plain-text `Forbidden`, with no JSON body and no `code`. Returned when the
    access token is malformed, has the wrong signature, or has **expired** — the
    common case, since access tokens live 30 minutes. Refresh the access token
    and retry.
  </Accordion>

  <Accordion title="Acting As Another User — 403">
    ```json theme={null}
    { "error": "Unauthorized", "code": "notification-preferences/unauthorized" }
    ```

    Returned when an end-user token names a `userId` other than its own.
  </Accordion>

  <Accordion title="Invalid Query — 400">
    ```json theme={null}
    { "error": "...", "code": "notification-preferences/invalid-query" }
    ```

    Returned when the `userId` query parameter is not a valid identifier.
  </Accordion>

  <Accordion title="Missing User ID — 400">
    ```json theme={null}
    { "error": "Missing user ID", "code": "notification-preferences/missing-user-id" }
    ```

    Returned when a service/master key omits the required `userId` (it has no implicit session user).
  </Accordion>

  <Accordion title="Bundle Not Installed — 403">
    ```json theme={null}
    {
      "code": "database/tables-not-available",
      "missingTables": ["PushProviderConfigs", "PushDevices", "NotificationPreferences"],
      "dashboardUrl": "https://…/<projectId>/database"
    }
    ```

    Returned when the `push` bundle is not installed for this project.
  </Accordion>

  <Accordion title="Bundle Provisioning — 503">
    ```json theme={null}
    {
      "code": "database/tables-provisioning",
      "missingTables": ["PushProviderConfigs", "PushDevices", "NotificationPreferences"],
      "bundleId": "push"
    }
    ```

    Returned while the `push` bundle is mid-install. Retry shortly.
  </Accordion>

  <Accordion title="Server Error — 500">
    ```json theme={null}
    {
      "error": "Internal server error.",
      "code": "notification-preferences/server-error"
    }
    ```
  </Accordion>
</AccordionGroup>

**Rate limit:** 100 requests per 5 minutes per IP. Exceeding it returns `429` with a plain-text message and no `code`.

## See Also

* [Update Notification Preferences](/api-reference/push-notifications/update-preferences)
* [`useNotificationPreferences`](/hooks/push/use-notification-preferences)
* [Notification Preferences & Mute](/notification-preferences)


# Get VAPID Public Key
Source: https://docs.sublay.io/v7/api-reference/push-notifications/get-vapid-public-key

GET /v7/:projectId/push-notifications/vapid-public-key
Retrieve the project's VAPID public key for Web Push subscriptions

Returns the VAPID (Voluntary Application Server Identification) public key for this project. The browser's `PushManager.subscribe()` requires this key as `applicationServerKey` when creating a Web Push subscription.

This endpoint is intentionally **unauthenticated** — a VAPID public key is not a secret (only the matching private key, which is never returned by any endpoint, provides security). The `webPushTokenAdapter` calls this automatically before the user has signed in, which is a common browser pattern.

Returns `{ publicKey: null }` if the `web-push` provider has not been configured for the project.

Requires the `push` bundle.

## Response

<ResponseField name="publicKey" type="string | null">
  The Base64url-encoded VAPID public key, or `null` if Web Push is not configured.
</ResponseField>

```json theme={null}
{ "publicKey": "BGE1YqnfxcY...Bm7uB4" }
```

## Error Responses

<AccordionGroup>
  <Accordion title="Bundle Not Installed — 403">
    ```json theme={null}
    {
      "code": "database/tables-not-available",
      "missingTables": ["PushProviderConfigs", "PushDevices", "NotificationPreferences"],
      "dashboardUrl": "https://…/<projectId>/database"
    }
    ```
  </Accordion>

  <Accordion title="Bundle Provisioning — 503">
    ```json theme={null}
    {
      "code": "database/tables-provisioning",
      "missingTables": ["PushProviderConfigs", "PushDevices", "NotificationPreferences"],
      "bundleId": "push"
    }
    ```

    Returned while the `push` bundle is mid-install. Retry shortly.
  </Accordion>

  <Accordion title="Server Error — 500">
    ```json theme={null}
    { "error": "Internal server error.", "code": "push-vapid-key/server-error" }
    ```
  </Accordion>
</AccordionGroup>

**Rate limit:** 50 requests per 5 minutes per IP. Exceeding it returns `429` with a plain-text message and no `code`.

## See Also

* [Push Notifications overview](/push-notifications)
* [`usePushRegistration`](/hooks/push/use-push-registration)


# Register Device
Source: https://docs.sublay.io/v7/api-reference/push-notifications/register-device

POST /v7/:projectId/push-notifications/devices
Register a device to receive push notifications for the authenticated user

Registers a push device for the currently authenticated user. Re-registering the same physical device for the same user updates the existing record instead of creating a duplicate.

A device can serve several accounts at once. Registrations are unique per `(device, user)` pair, so registering a device that is already registered by a different user (e.g. a shared device, or a second account signed in on the same phone) **adds a second binding** — it does not reassign or replace the first user's registration. Each bound account then receives its own notifications on that device.

Requires end-user authentication (`Authorization: Bearer <accessToken>`). Service and master keys are explicitly rejected — this endpoint has no impersonation path by design (see [Security note](#security-note)).

Requires the `push` bundle.

## Body Parameters

<ParamField type="string">
  The device platform. One of `"ios"`, `"android"`, or `"web"`.
</ParamField>

<ParamField type="string">
  The APNs or FCM device token. Required when `platform` is `"ios"` or `"android"`.
</ParamField>

<ParamField type="object">
  The Web Push subscription object. Required when `platform` is `"web"`.

  <Expandable title="subscription fields">
    <ParamField type="string">
      The push subscription endpoint URL provided by the browser's `PushManager`.
    </ParamField>

    <ParamField type="string">
      The P-256 Diffie-Hellman public key, Base64-encoded.
    </ParamField>

    <ParamField type="string">
      The authentication secret, Base64-encoded.
    </ParamField>
  </Expandable>
</ParamField>

## Response

Returns `200` with the stored device record on success.

```json theme={null}
{
  "id": "b6f2…",
  "userId": "a41c…",
  "platform": "ios",
  "payload": "apns-device-token",
  "deviceKey": "apns-device-token",
  "createdAt": "2026-08-19T10:12:04.881Z",
  "updatedAt": "2026-08-19T10:12:04.881Z"
}
```

## Error Responses

<AccordionGroup>
  <Accordion title="No Credential — 401">
    Plain-text `Unauthorized`, with no JSON body and no `code`. Returned when the
    request carries no `Authorization` header at all.
  </Accordion>

  <Accordion title="Rejected Credential — 403">
    Plain-text `Forbidden`, with no JSON body and no `code`. Returned when the
    access token is malformed, has the wrong signature, or has **expired** — the
    common case, since access tokens live 30 minutes. Refresh the access token
    and retry; do not treat this as a permanent refusal.
  </Accordion>

  <Accordion title="Service Key Rejected — 401">
    ```json theme={null}
    { "error": "Unauthorized", "code": "push-device/unauthorized" }
    ```

    Returned when a service or master key is used. This endpoint has no
    impersonation path by design (see [Security note](#security-note)).
  </Accordion>

  <Accordion title="Invalid Body — 400">
    ```json theme={null}
    { "error": "...", "code": "push-device/invalid-body" }
    ```

    Returned when `platform` is unrecognized, or when the required `token` / `subscription` field is missing for the given platform.
  </Accordion>

  <Accordion title="Bundle Not Installed — 403">
    ```json theme={null}
    {
      "code": "database/tables-not-available",
      "missingTables": ["PushProviderConfigs", "PushDevices", "NotificationPreferences"],
      "dashboardUrl": "https://…/<projectId>/database"
    }
    ```

    Returned when the `push` bundle is not installed for this project.
  </Accordion>

  <Accordion title="Bundle Provisioning — 503">
    ```json theme={null}
    {
      "code": "database/tables-provisioning",
      "missingTables": ["PushProviderConfigs", "PushDevices", "NotificationPreferences"],
      "bundleId": "push"
    }
    ```

    Returned while the `push` bundle is mid-install. Retry shortly.
  </Accordion>

  <Accordion title="Server Error — 500">
    ```json theme={null}
    { "error": "Internal server error.", "code": "push-device/server-error" }
    ```

    The registration could not be written. No diagnostic detail is returned;
    retry.
  </Accordion>
</AccordionGroup>

**Rate limit:** 50 requests per 5 minutes per IP. Exceeding it returns `429` with a plain-text message and no `code`.

## Security note

Unlike most other write endpoints, this endpoint does not accept a `userId` body parameter and cannot be called with a service key. Allowing a backend to register an arbitrary token for an arbitrary user would let it redirect that user's push notifications to an attacker-controlled device. Registration must always come from the end user's own session.

## See Also

* [Delete Device](/api-reference/push-notifications/deregister-device)
* [`usePushRegistration`](/hooks/push/use-push-registration)
* [Push Notifications overview](/push-notifications)


# Send Push Notification
Source: https://docs.sublay.io/v7/api-reference/push-notifications/send

POST /v7/:projectId/push-notifications/send
Send a push notification to one or more users across all their registered devices

Fans a push notification out to every registered device binding belonging to the listed users. The server dispatches to APNs (iOS), FCM (Android), and the Web Push protocol in parallel, using whichever platform credentials are configured for this project.

Requires a service or master key (`Authorization: Bearer <serviceKey>`). End-user tokens are rejected — this endpoint is intended for your backend, not for end users calling it directly.

Requires the `push` bundle.

## Body Parameters

<ParamField type="string[]">
  Array of Sublay user IDs to notify. Between 1 and 100 IDs per request.
</ParamField>

<ParamField type="string">
  Notification title. Displayed as the bold heading on the device.
</ParamField>

<ParamField type="string">
  Notification body text.
</ParamField>

<ParamField type="object">
  Optional key-value data payload forwarded to the app alongside the notification. Values must be strings or serializable primitives. Use this to pass deep-link targets, IDs, or any context your app needs when the user taps the notification.

  **`recipientUserId` is reserved.** The server stamps every dispatched copy with the id of the account that copy is for, so a device signed into several accounts can tell which one a notification belongs to. A value you supply under that key is overwritten — an account-routing key has to be trustworthy.
</ParamField>

<Note>
  **One notification per account, not per device.** A physical device can be bound to several accounts at once. If two of the `userIds` are signed in on the same device, that device receives two notifications — one per account, each with its own `recipientUserId`.
</Note>

### Rich payload fields

All optional. Each is mapped to whichever platform(s) support it at dispatch time and silently ignored on platforms that have no equivalent. See the [Push Notifications guide](/push-notifications#rich-notification-payloads) for the client-side setup some of these require (Android channels, the iOS Notification Service Extension, your web service worker).

<ParamField type="string">
  Sound file to play. iOS: APNs `sound`. Android: governed by the channel on 8+ — pair with `channelId`. Web: forwarded to the service worker.
</ParamField>

<ParamField type="number">
  iOS app-icon badge count (APNs `badge`). No Android equivalent. The caller supplies the number; Sublay tracks no unread state.
</ParamField>

<ParamField type="string">
  Android notification channel id (FCM `android.notification.channel_id`). The channel must be created client-side; on Android 8+ it owns sound/importance/vibration.
</ParamField>

<ParamField type="string">
  `"high"` or `"normal"`. iOS: APNs `apns-priority` (10/5). Android: FCM `android.priority`. `high` wakes the device for time-sensitive pushes. Defaults to `high` when omitted.
</ParamField>

<ParamField type="string">
  iOS subtitle line under the title (APNs `alert.subtitle`).
</ParamField>

<ParamField type="string">
  Rich/big-picture image URL. Android (FCM `image`) and Web work out of the box. iOS additionally requires a Notification Service Extension in the app — the URL is forwarded in the payload and `mutable-content` is set automatically.
</ParamField>

<ParamField type="string">
  Display-replace key so notifications collapse in the UI (FCM `android.notification.tag`, Web `tag`). Scoped per recipient, exactly like `collapseId` below.

  **The device receives a different string than you sent.** Scoping appends `~` and a short digest of the recipient's user id, so a push sent with `tag: "thread-42"` arrives carrying something like `thread-42~9f3c1a8b`. Client code that reads the delivered `tag` — a service worker matching open notifications, for instance — must not compare it to the value it sent. Match on a prefix, or carry your own key in `data` instead, which is passed through untouched.
</ParamField>

<ParamField type="string">
  Transport-level collapse identifier (APNs `apns-collapse-id`, FCM `collapse_key`) — a newer push supersedes an undelivered one carrying the same id **for the same account**.

  **Scoped per recipient.** Two accounts signed in on one physical device share one transport destination, so the server appends a short digest of the recipient's id to the key you supply before handing it to the provider — the provider therefore sees a different string than you sent. Each account gets its own collapse namespace on the shared device and cannot supersede the other's notification, while collapsing within a single account behaves exactly as the field describes.

  **Over-length keys are folded rather than refused.** APNs caps `apns-collapse-id` at 64 bytes. When your key plus the recipient digest would exceed that, the server replaces the whole scoped key with a fixed-width digest of it — still deterministic and still per-recipient, so collapsing keeps working — instead of letting APNs reject the send with `BadCollapseId`. FCM's `collapse_key` and the display `tag` have no comparable documented ceiling, so nothing is folded on those paths. The parameter itself has no maximum: any non-empty string is accepted.
</ParamField>

<ParamField type="string">
  iOS notification grouping (APNs `thread-id`).
</ParamField>

<ParamField type="number">
  Time-to-live in seconds for offline devices (APNs `apns-expiration` computed from now, FCM `android.ttl`).
</ParamField>

<ParamField type="boolean">
  iOS `mutable-content` flag, enabling the app's Notification Service Extension to modify the payload (e.g. attach `imageUrl`). Set implicitly when `imageUrl` is provided.
</ParamField>

## Response

Returns `200` with a `results` map keyed by user ID. Every requested `userId` is present in the response — users with no registered devices get an empty array rather than being omitted.

```json theme={null}
{
  "results": {
    "usr_abc123": [
      { "platform": "ios", "success": true },
      { "platform": "android", "success": true }
    ],
    "usr_def456": [],
    "usr_ghi789": [
      { "platform": "web", "success": false, "reason": "credentials_not_configured" }
    ]
  }
}
```

<ResponseField name="results" type="object">
  Map from user ID to an array of per-device delivery results.

  <Expandable title="per-device result fields">
    <ResponseField name="platform" type="&#x22;ios&#x22; | &#x22;android&#x22; | &#x22;web&#x22;">
      The platform this result is for.
    </ResponseField>

    <ResponseField name="success" type="boolean">
      Whether the push was accepted by the upstream provider (APNs, FCM, or Web Push).
    </ResponseField>

    <ResponseField name="reason" type="string">
      Present only when `success` is `false`. Common values:

      * `"credentials_not_configured"` — no provider config exists for this platform (or it is disabled)
      * Provider-specific error codes returned by APNs/FCM/Web Push
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  Tokens or subscriptions reported as permanently invalid by the upstream provider (e.g. APNs `BadDeviceToken`, FCM `UNREGISTERED`, Web Push HTTP 410) are automatically deleted during the send — no separate cleanup step is needed. A dead token is dead for the whole device, so **every** account bound to it is unbound, including accounts that were not part of this request.
</Note>

## Error Responses

<AccordionGroup>
  <Accordion title="Invalid Body — 400">
    ```json theme={null}
    { "error": "...", "code": "push-send/invalid-body" }
    ```

    Returned when `userIds` is empty, exceeds 100 entries, or required fields are missing.
  </Accordion>

  <Accordion title="Elevated Auth Required — 403">
    ```json theme={null}
    {
      "error": "Service or master key required.",
      "code": "auth/elevated-auth-required"
    }
    ```

    Returned when called with an end-user access token instead of a service/master key.
  </Accordion>

  <Accordion title="Bundle Not Installed — 403">
    ```json theme={null}
    {
      "code": "database/tables-not-available",
      "missingTables": ["PushProviderConfigs", "PushDevices", "NotificationPreferences"],
      "dashboardUrl": "https://…/<projectId>/database"
    }
    ```
  </Accordion>

  <Accordion title="Bundle Provisioning — 503">
    ```json theme={null}
    {
      "code": "database/tables-provisioning",
      "missingTables": ["PushProviderConfigs", "PushDevices", "NotificationPreferences"],
      "bundleId": "push"
    }
    ```

    Returned while the `push` bundle is mid-install. Retry shortly.
  </Accordion>

  <Accordion title="Server Error — 500">
    ```json theme={null}
    { "error": "Internal server error.", "code": "push-send/server-error" }
    ```

    The fan-out itself failed. Nothing beyond this code is returned. Note that a
    failure while pruning dead tokens *after* delivery does not reach here — the
    pushes were delivered and the response is still `200`.
  </Accordion>
</AccordionGroup>

**Rate limit:** 50 requests per 5 minutes per IP. Exceeding it returns `429` with a plain-text message and no `code`.

## See Also

* [Node SDK — push.send](/node-sdk/push-notifications)
* [Register Device](/api-reference/push-notifications/register-device)
* [Push Notifications overview](/push-notifications)


# Update Notification Preferences
Source: https://docs.sublay.io/v7/api-reference/push-notifications/update-preferences

PUT /v7/:projectId/push-notifications/preferences
Set the authenticated user's disabled push notification types

Upserts the acting user's push notification preferences. The request **replaces** the whole disabled-types set — send the complete set you want stored, not a delta. Duplicates are collapsed; only valid event type names are accepted.

Requires authentication. **Acting-user-scoped:** an end-user token (`Authorization: Bearer <accessToken>`) writes its own preferences. A service/master key acts on behalf of a named user via the optional body `userId` — a service key without `userId` is rejected, and an end-user token may not name a different user. Requires the `push` bundle.

## Body Parameters

<ParamField type="string[]">
  The complete set of event types to disable for push. Each value must be one of the server's exact event type names (see the [event palette](/notification-preferences#the-event-palette)) — unknown names are rejected. Pass `[]` to re-enable everything (all-on).
</ParamField>

<ParamField type="string">
  The acting user whose preferences are written. **Service/master keys only** — a service key must pass it; an end-user token infers it from the auth token and may not name a different user.
</ParamField>

## Response

Returns `200` with the stored set (deduplicated).

```json theme={null}
{ "disabledTypes": ["comment-mention"] }
```

## Error Responses

<AccordionGroup>
  <Accordion title="No Credential — 401">
    Plain-text `Unauthorized`, with no JSON body and no `code`. Returned when the
    request carries no `Authorization` header at all.
  </Accordion>

  <Accordion title="Rejected Credential — 403">
    Plain-text `Forbidden`, with no JSON body and no `code`. Returned when the
    access token is malformed, has the wrong signature, or has **expired** — the
    common case, since access tokens live 30 minutes. Refresh the access token
    and retry.
  </Accordion>

  <Accordion title="Acting As Another User — 403">
    ```json theme={null}
    { "error": "Unauthorized", "code": "notification-preferences/unauthorized" }
    ```

    Returned when an end-user token names a `userId` other than its own.
  </Accordion>

  <Accordion title="Missing User ID — 400">
    ```json theme={null}
    { "error": "Missing user ID", "code": "notification-preferences/missing-user-id" }
    ```

    Returned when a service/master key omits the required `userId` (it has no implicit session user).
  </Accordion>

  <Accordion title="Invalid Body — 400">
    ```json theme={null}
    { "error": "...", "code": "notification-preferences/invalid-body" }
    ```

    Returned when `disabledTypes` contains a value that is not a recognized event type name.
  </Accordion>

  <Accordion title="Bundle Not Installed — 403">
    ```json theme={null}
    {
      "code": "database/tables-not-available",
      "missingTables": ["PushProviderConfigs", "PushDevices", "NotificationPreferences"],
      "dashboardUrl": "https://…/<projectId>/database"
    }
    ```

    Returned when the `push` bundle is not installed for this project.
  </Accordion>

  <Accordion title="Bundle Provisioning — 503">
    ```json theme={null}
    {
      "code": "database/tables-provisioning",
      "missingTables": ["PushProviderConfigs", "PushDevices", "NotificationPreferences"],
      "bundleId": "push"
    }
    ```

    Returned while the `push` bundle is mid-install. Retry shortly.
  </Accordion>

  <Accordion title="Server Error — 500">
    ```json theme={null}
    {
      "error": "Internal server error.",
      "code": "notification-preferences/server-error"
    }
    ```
  </Accordion>
</AccordionGroup>

**Rate limit:** 50 requests per 5 minutes per IP. Exceeding it returns `429` with a plain-text message and no `code`.

## See Also

* [Get Notification Preferences](/api-reference/push-notifications/get-preferences)
* [`useNotificationPreferences`](/hooks/push/use-notification-preferences)
* [Notification Preferences & Mute](/notification-preferences)


# Create Report
Source: https://docs.sublay.io/v7/api-reference/reports/create-report

POST /v7/:projectId/reports
Submit a content report for an entity, comment, or chat message

Submits a report on an entity, comment, or chat message. If an **open** report already exists for the target, the authenticated user's report is added to it (increments `reporterCount`). If the same user already reported that open report, a `200` is returned without creating a duplicate.

Resolved reports (`dismissed` / `actioned`) are closed: a later report of the same target creates a **new** report rather than reopening the old one. A target therefore has at most one open report at a time, alongside any number of resolved ones.

**Authentication required.** **Rate limit**: 25 requests per 5 minutes.

## Body Parameters

<ParamField type="string">
  The UUID of the entity, comment, or chat message being reported. For a
  message this is the message id — the conversation is resolved server-side,
  so no `conversationId` is needed.
</ParamField>

<ParamField type="string">
  The type of content being reported. One of: `entity`, `comment`, `message`.
</ParamField>

<ParamField type="string">
  The reason for the report. Must be one of: `spam`, `inappropriateContent`,
  `harassment`, `misinformation`, `hateSpeech`, `violence`, `illegalActivity`,
  `selfHarm`, `other`. Any other value is rejected with `report/invalid-body` —
  use `other` plus `details` for anything the taxonomy doesn't cover.
</ParamField>

<ParamField type="string">
  Optional additional context or description provided by the reporter.
</ParamField>

## Response

Returns `201 Created` when a new report is created:

```json theme={null}
{ "message": "Report submitted successfully", "code": "report/created" }
```

Returns `200 OK` when an existing report is updated with a new reporter:

```json theme={null}
{ "message": "Report updated successfully", "code": "report/updated" }
```

Returns `200 OK` when the user has already reported this target:

```json theme={null}
{ "message": "Report already registered by this user", "code": "report/already-reported" }
```

## Error Responses

<AccordionGroup>
  <Accordion title="Target Not Found — 404">
    ```json theme={null}
    { "error": "<targetType> not found", "code": "report/target-not-found" }
    ```

    The error message reflects the reported type, e.g. `"entity not found"` or `"comment not found"`.
  </Accordion>

  <Accordion title="Self Report — 400">
    ```json theme={null}
    { "error": "You cannot report your own <targetType>.", "code": "report/self-report" }
    ```

    A user cannot report content they authored.
  </Accordion>

  <Accordion title="Not a Conversation Member — 403">
    ```json theme={null}
    { "error": "You are not a member of this conversation.", "code": "chat/not-a-member" }
    ```

    Only members of a conversation may report a message in it. Applies to
    `targetType: "message"` only.
  </Accordion>

  <Accordion title="Invalid Body — 400">
    ```json theme={null}
    { "error": "...", "code": "report/invalid-body" }
    ```

    Returned for a malformed `targetId`, an unknown `targetType`, or a `reason`
    outside the accepted set.
  </Accordion>
</AccordionGroup>


# Fetch Moderated Reports
Source: https://docs.sublay.io/v7/api-reference/reports/fetch-moderated-reports

GET /v7/:projectId/reports/moderated
Get content reports for spaces the authenticated user can moderate

Returns a paginated list of reports for spaces where the authenticated user has the `admin` or `moderator` role. If `spaceId` is omitted, reports from all spaces the user moderates are returned.

**Authentication required.** Must be a space admin or moderator.

## Query Parameters

<ParamField type="string">
  Filter to a specific space. The user must be an admin or moderator of that space. When omitted, reports from all moderated spaces are returned.
</ParamField>

<ParamField type="string">
  Filter by content type. One of: `entity`, `comment`, `message`. Message
  reports appear in this queue only for conversations attached to a space —
  DM and group reports have no space, so they are project-level and surface in
  the Sublay dashboard instead.
</ParamField>

<ParamField type="string">
  Filter by report status. One of: `pending`, `on-hold`, `escalated`, `dismissed`, `actioned`.
</ParamField>

<ParamField type="string">
  Sort order. One of: `new` (newest first), `old` (oldest first).
</ParamField>

<ParamField type="number">
  Page number (1-indexed).
</ParamField>

<ParamField type="number">
  Number of reports per page.
</ParamField>

### Space-scoped reputation

This endpoint has a space in context, so it accepts the opt-in reputation params. They add a `spaceReputation` field to each reported content author's populated `user`, alongside the always-present `reputation` total. Requires the `reputation` bundle. See the [Reputation data model](/data-models/reputation) for the full contract.

<SpaceReputationParams />

## Response

```json theme={null}
{
  "data": [
    {
      "id": "uuid",
      "targetId": "uuid",
      "targetType": "comment",
      "spaceId": "uuid",
      "status": "pending",
      "reporterCount": 3,
      "target": { ...Comment object... },
      "space": { ...Space object... },
      "userReports": [
        { "userId": "uuid", "reason": "spam", "details": "..." }
      ],
      "createdAt": "2025-01-01T00:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalPages": 2,
    "totalItems": 35,
    "hasMore": true
  }
}
```

Each report includes the full reported content (`target`), the space it belongs to, and all individual user reports (`userReports`).

## Error Responses

<AccordionGroup>
  <Accordion title="Forbidden — 403">
    ```json theme={null}
    { "error": "Moderator access required for this space", "code": "report/forbidden" }
    ```

    Returned when `spaceId` is provided but the user is not a moderator of that space.
  </Accordion>
</AccordionGroup>


# Search Content
Source: https://docs.sublay.io/v7/api-reference/search/search-content

POST /v7/:projectId/search/content
Semantic search over entities, comments, and messages

Performs vector-similarity search over project content (entities, comments, and chat messages) using AI embeddings. Returns the most semantically relevant results for the given query.

**Requires a paid plan with semantic search enabled.**

**Requires an authenticated user.** Send the user's access token as `Authorization: Bearer <token>` — missing token → `401`, invalid/expired token → `403` (refresh and retry).

## Body Parameters

<ParamField type="string">
  The natural language search query.
</ParamField>

<ParamField type="string[]">
  Content types to search. Any combination of `entity`, `comment`, `message`.
</ParamField>

<ParamField type="string">
  Restrict search to a specific space.
</ParamField>

<ParamField type="boolean">
  Only applies with a `spaceId`. When `true`, the search also includes every space nested under it — children, grandchildren, the whole subtree at any depth — not just the named space. Ignored without a `spaceId`.
</ParamField>

<ParamField type="string">
  Restrict message search to a specific conversation.
</ParamField>

<ParamField type="number">
  Maximum number of results to return. Maximum `50`.
</ParamField>

## Query Parameters

### Space-scoped reputation

This endpoint has a space in context, so it accepts the opt-in reputation params. They add a `spaceReputation` field to each result record's populated `user`, alongside the always-present `reputation` total. Requires the `reputation` bundle. See the [Reputation data model](/data-models/reputation) for the full contract.

<SpaceReputationParams />

## Response

Returns an array of result objects ordered by similarity (highest first):

```json theme={null}
[
  {
    "sourceType": "entity",
    "similarity": 0.87,
    "record": { ...Entity | Comment | ChatMessage... }
  }
]
```

Each result includes:

* `sourceType` — one of `"entity"`, `"comment"`, or `"message"`, indicating which type of record was matched.
* `similarity` — cosine similarity score between the query and the matched content.
* `record` — the fully populated entity, comment, or chat message object.

## Error Responses

<AccordionGroup>
  <Accordion title="Authentication Required — 401 / 403">
    The endpoint requires an authenticated user. A missing token returns a bare `401`; an invalid or expired token returns a bare `403` — refresh the access token and retry.
  </Accordion>

  <Accordion title="Plan Required — 403">
    ```json theme={null}
    { "error": "Semantic search requires a paid plan", "code": "project/plan-required" }
    ```
  </Accordion>
</AccordionGroup>


# Block User
Source: https://docs.sublay.io/v7/api-reference/users/blocks/block-user

POST /v7/:projectId/users/:userId/block
Block a user by their ID

Creates a block edge from the acting user (the blocker) to the specified user (the target). Blocking is **non-disclosing** — the blocked user is never notified and can never tell they've been blocked.

On a **new** block, Sublay retroactively tears down the existing relationship between the two users in one transaction: any follow in either direction is removed, and any connection or pending connection request in either direction is removed. Nothing is restored on unblock. See [Block enforcement](/sdk/moderation/overview#blocking) for the full list of what a block prevents and hides.

<Note>
  **Requires the `moderation` bundle.** Blocking ships with reporting and suspensions as part of the trust & safety package. A project without the moderation bundle returns `403 database/tables-not-available`. See [Bundles](/bundles).
</Note>

## Path Parameters

<ParamField type="string">
  The Sublay user ID (UUID) of the user to block (the target).
</ParamField>

## Body Parameters

<ParamField type="string">
  The user performing the block (the blocker). Only service/master keys may supply an `actingUserId` other than the caller's own; with a user token the blocker is derived from the token and this field is ignored.
</ParamField>

## Response

On a **new** block, returns HTTP `201` with the created block record. Re-blocking an already-blocked user is an idempotent success and returns HTTP `200` with the existing record.

<ResponseField name="id" type="string">
  Unique block record ID (UUID).
</ResponseField>

<ResponseField name="blockerId" type="string">
  ID of the user who created the block (the acting user).
</ResponseField>

<ResponseField name="blockedId" type="string">
  ID of the user being blocked (the target).
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO timestamp of when the block was created.
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="Self-Block — 400">
    ```json theme={null}
    {
      "error": "A user cannot block themselves.",
      "code": "block/self-block"
    }
    ```
  </Accordion>

  <Accordion title="User Not Found — 404">
    ```json theme={null}
    {
      "error": "One or both users involved in the block do not exist.",
      "code": "block/user-not-found"
    }
    ```
  </Accordion>
</AccordionGroup>

## See Also

* [`useBlockManager` hook](/hooks/blocks/use-block-manager)
* [Unblock User](/api-reference/users/blocks/unblock-user)
* [Get Block Status](/api-reference/users/blocks/get-block-status)
* [Block data model](/data-models/block)


# Get Block Status
Source: https://docs.sublay.io/v7/api-reference/users/blocks/get-block-status

GET /v7/:projectId/users/:userId/block
Check whether the acting user blocks a specific user

Returns **only the acting user's outbound block state** — whether *I* block `:userId`. This powers a block/unblock toggle in your app's UI.

<Warning>
  This endpoint is **outbound-only by design**. It never reveals the inbound direction (whether `:userId` has blocked the caller). Exposing the inbound state would let a blocked user poll this endpoint to discover a block — the exact disclosure the feature exists to prevent.
</Warning>

<Note>
  **Requires the `moderation` bundle.** A project without the moderation bundle returns `403 database/tables-not-available`. See [Bundles](/bundles).
</Note>

## Path Parameters

<ParamField type="string">
  The Sublay user ID (UUID) of the user to check block status against (the target).
</ParamField>

## Query Parameters

<ParamField type="string">
  The user whose outbound state is being checked (the blocker). Only service/master keys may supply an `actingUserId` other than the caller's own; with a user token the blocker is derived from the token.
</ParamField>

## Response

On success, returns HTTP `200`.

<ResponseField name="blocked" type="boolean">
  `true` if the acting user blocks the target user; otherwise `false`.
</ResponseField>

<ResponseField name="blockId" type="string">
  ID of the block record. Present only when `blocked` is `true`.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO timestamp of when the block was created. Present only when `blocked` is `true`.
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="Self-Check — 400">
    ```json theme={null}
    {
      "error": "Cannot check block status with yourself.",
      "code": "block/self-check"
    }
    ```
  </Accordion>
</AccordionGroup>

## See Also

* [`useFetchBlockStatus` hook](/hooks/blocks/use-fetch-block-status)
* [Block User](/api-reference/users/blocks/block-user)
* [Block data model](/data-models/block)


# Unblock User
Source: https://docs.sublay.io/v7/api-reference/users/blocks/unblock-user

DELETE /v7/:projectId/users/:userId/block
Unblock a user by their ID

Removes the block edge from the acting user (the blocker) to the specified user (the target). The barrier lifts immediately.

Unblocking is **idempotent** — unblocking a user who isn't blocked is a success no-op. Nothing that the block tore down is restored: removed follows and connections stay gone and the two users must re-establish them from scratch. A previously frozen 1:1 conversation becomes usable again (the conversation record still exists).

<Note>
  **Requires the `moderation` bundle.** A project without the moderation bundle returns `403 database/tables-not-available`. See [Bundles](/bundles).
</Note>

## Path Parameters

<ParamField type="string">
  The Sublay user ID (UUID) of the user to unblock (the target).
</ParamField>

## Query Parameters

<ParamField type="string">
  The user performing the unblock (the blocker). Only service/master keys may supply an `actingUserId` other than the caller's own; with a user token the blocker is derived from the token.
</ParamField>

## Response

On success, returns HTTP `204` with no body.

## See Also

* [`useBlockManager` hook](/hooks/blocks/use-block-manager)
* [Block User](/api-reference/users/blocks/block-user)
* [Block data model](/data-models/block)


# Check Username Availability
Source: https://docs.sublay.io/v7/api-reference/users/check-username-availability

GET /v7/:projectId/users/check-username
Check whether a username is already taken in this project

Checks whether the specified username is already in use within the project. Returns a simple availability flag. Use this before prompting users to set a username to give instant feedback.

## Query Parameters

<ParamField type="string">
  The username to check. Lookup is exact-match against the stored (lowercased)
  value.
</ParamField>

## Response

On success, returns HTTP `200` with:

<ResponseField name="available" type="boolean">
  `true` if the username is not yet taken; `false` if it is already in use.
</ResponseField>

**Example — available:**

```json theme={null}
{ "available": true }
```

**Example — taken:**

```json theme={null}
{ "available": false }
```

## Error Responses

<AccordionGroup>
  <Accordion title="Invalid Query — 400">
    ```json theme={null}
    {
      "error": "...",
      "code": "username/invalid-query"
    }
    ```
  </Accordion>
</AccordionGroup>

## See Also

* [`useCheckUsernameAvailability` hook](/hooks/users/use-check-username-availability)


# Get Connection Status
Source: https://docs.sublay.io/v7/api-reference/users/connections/get-connection-status

GET /v7/:projectId/users/:userId/connection
Check the connection status between the authenticated user and another user

Returns the connection status between the authenticated user and the specified user. The response shape varies depending on whether there is no connection, a pending request, an accepted connection, or a declined request.

## Path Parameters

<ParamField type="string">
  The Sublay user ID (UUID) of the other user.
</ParamField>

## Response

On success, returns HTTP `200`. The shape depends on the connection state:

**No connection:**

<ResponseField name="status" type="string">
  `"none"`.
</ResponseField>

**Pending request:**

<ResponseField name="status" type="string">
  `"pending"`.
</ResponseField>

<ResponseField name="type" type="string">
  `"sent"` if the authenticated user sent the request; `"received"` if they received it.
</ResponseField>

<ResponseField name="connectionId" type="string">
  ID of the connection record.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO timestamp of when the request was sent.
</ResponseField>

**Accepted (connected):**

<ResponseField name="status" type="string">
  `"connected"`.
</ResponseField>

<ResponseField name="connectionId" type="string">
  ID of the connection record.
</ResponseField>

<ResponseField name="connectedAt" type="string">
  ISO timestamp of when the connection was accepted.
</ResponseField>

<ResponseField name="requestedAt" type="string">
  ISO timestamp of the original request.
</ResponseField>

**Declined:**

<ResponseField name="status" type="string">
  `"declined"`.
</ResponseField>

<ResponseField name="type" type="string">
  `"sent"` or `"received"` — perspective of the authenticated user.
</ResponseField>

<ResponseField name="connectionId" type="string">
  ID of the connection record.
</ResponseField>

<ResponseField name="respondedAt" type="string">
  ISO timestamp of when the request was declined.
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="Self-Check — 400">
    ```json theme={null}
    {
      "error": "Cannot check connection status with yourself",
      "code": "connection/self-check"
    }
    ```
  </Accordion>
</AccordionGroup>

## See Also

* [`useFetchConnectionStatus` hook](/hooks/connections/use-fetch-connection-status)
* [Connection data model](/data-models/connection)


# Get Connections
Source: https://docs.sublay.io/v7/api-reference/users/connections/get-connections

GET /v7/:projectId/users/:userId/connections
Get a paginated list of a user's accepted connections

Returns a paginated list of accepted connections for the specified user. Each entry includes the connected user's public profile. Authentication is optional — the endpoint works without a token. When the caller is signed in, any user with a block between them and the caller, in either direction, is excluded from the results. Block filtering requires the `moderation` bundle.

## Path Parameters

<ParamField type="string">
  The Sublay user ID (UUID) of the user whose connections to retrieve.
</ParamField>

## Query Parameters

<ParamField type="number">
  Page number for pagination. Defaults to `1`.
</ParamField>

<ParamField type="number">
  Number of results per page. Defaults to `20`, maximum `100`.
</ParamField>

<ParamField type="string">
  Optional search term. Filters the list to connections whose connected user's username or name contains this text (case-insensitive). When omitted, no filtering is applied.
</ParamField>

<ParamField type="string">
  Restricts which field `query` matches against — `username` or `name`. When omitted, `query` matches either field.
</ParamField>

### Space-scoped reputation

This endpoint has no space in context, so the opt-in `spaceReputation` object accepts a `spaceId` of a space **`<uuid>`** or **`none`** only — `context` is rejected (400). It adds a `spaceReputation` field to each returned user, alongside the always-present `reputation` total. Requires the `reputation` bundle. See the [Reputation data model](/data-models/reputation).

<SpaceReputationParams />

## Response

On success, returns HTTP `200` with a paginated response:

<ResponseField name="data" type="array">
  Array of connection entries.

  <Expandable title="item properties">
    <ResponseField name="id" type="string">
      Connection record ID.
    </ResponseField>

    <ResponseField name="connectedUser" type="object">
      Public profile of the connected user (the user who is not `:userId`). Sensitive fields are excluded.
    </ResponseField>

    <ResponseField name="connectedAt" type="string">
      ISO timestamp of when the connection was accepted.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="totalCount" type="number">
  Total number of accepted connections.
</ResponseField>

<ResponseField name="page" type="number">
  Current page number.
</ResponseField>

<ResponseField name="limit" type="number">
  Page size used for this response.
</ResponseField>

## See Also

* [`useFetchConnectionsByUserId` hook](/hooks/connections/use-fetch-connections-by-user-id)
* [Connection data model](/data-models/connection)


# Get Connections Count
Source: https://docs.sublay.io/v7/api-reference/users/connections/get-connections-count

GET /v7/:projectId/users/:userId/connections-count
Get the number of accepted connections for a user

Returns the total number of accepted connections for the specified user. Authentication is optional — the endpoint works without a token. When the caller is signed in, any user with a block between them and the caller, in either direction, is excluded from the count. Block filtering requires the `moderation` bundle.

## Path Parameters

<ParamField type="string">
  The Sublay user ID (UUID) of the user whose connection count to retrieve.
</ParamField>

## Response

On success, returns HTTP `200`:

<ResponseField name="count" type="number">
  Total number of accepted connections for this user.
</ResponseField>

## See Also

* [`useFetchConnectionsCountByUserId` hook](/hooks/connections/use-fetch-connections-count-by-user-id)


# Remove Connection
Source: https://docs.sublay.io/v7/api-reference/users/connections/remove-connection

DELETE /v7/:projectId/users/:userId/connection
Remove, withdraw, or decline a connection by user ID

Removes the connection relationship between the authenticated user and the specified user. The behavior depends on the current connection state:

* **Pending (sent by current user)** — withdraws the request (record is deleted).
* **Pending (sent by other user)** — declines the request (status updated to `"declined"`).
* **Accepted** — disconnects both users (record is deleted).

## Path Parameters

<ParamField type="string">
  The Sublay user ID (UUID) of the other user.
</ParamField>

## Response

On success, returns HTTP `200`.

**When withdrawn or disconnected:**

<ResponseField name="message" type="string">
  Human-readable description of the action taken.
</ResponseField>

<ResponseField name="action" type="string">
  `"withdraw"` or `"disconnect"`.
</ResponseField>

**When declined:**

<ResponseField name="id" type="string">
  Connection record ID.
</ResponseField>

<ResponseField name="status" type="string">
  `"declined"`.
</ResponseField>

<ResponseField name="respondedAt" type="string">
  ISO timestamp of when the request was declined.
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="Self-Disconnect — 400">
    ```json theme={null}
    {
      "error": "Cannot disconnect from yourself",
      "code": "connection/self-disconnect"
    }
    ```
  </Accordion>

  <Accordion title="No Connection Found — 404">
    ```json theme={null}
    {
      "error": "No connection found between these users that can be removed.",
      "code": "connection/not-found"
    }
    ```
  </Accordion>
</AccordionGroup>

## See Also

* [`useRemoveConnectionByUserId` hook](/hooks/connections/use-remove-connection-by-user-id)
* [Remove Connection by ID](/api-reference/connections/remove-connection) — remove by connection ID instead


# Request Connection
Source: https://docs.sublay.io/v7/api-reference/users/connections/request-connection

POST /v7/:projectId/users/:userId/connection
Send a connection request to a user

Sends a connection request from the authenticated user to the specified user. An optional message can be included. A notification is sent to the receiving user.

## Path Parameters

<ParamField type="string">
  The Sublay user ID (UUID) of the user to send a connection request to.
</ParamField>

## Body Parameters

<ParamField type="string">
  Optional message to include with the connection request.
</ParamField>

## Response

On success, returns HTTP `201` with the created connection record:

<ResponseField name="id" type="string">
  Unique connection record ID (UUID).
</ResponseField>

<ResponseField name="status" type="string">
  Always `"pending"` for a new request.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO timestamp of when the request was sent.
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="Self-Request — 400">
    ```json theme={null}
    {
      "error": "A user cannot send a connection request to themselves.",
      "code": "connection/self-request"
    }
    ```
  </Accordion>

  <Accordion title="User Not Found — 404">
    ```json theme={null}
    {
      "error": "One or both users involved in the connection do not exist.",
      "code": "connection/user-not-found"
    }
    ```
  </Accordion>

  <Accordion title="Already Pending — 409">
    ```json theme={null}
    {
      "error": "A connection request is already pending between these users.",
      "code": "connection/request-pending"
    }
    ```
  </Accordion>

  <Accordion title="Already Connected — 409">
    ```json theme={null}
    {
      "error": "Users are already connected.",
      "code": "connection/already-connected"
    }
    ```
  </Accordion>

  <Accordion title="Request Previously Declined — 409">
    ```json theme={null}
    {
      "error": "Connection request was declined. Only the receiver can initiate a new request.",
      "code": "connection/request-declined"
    }
    ```
  </Accordion>
</AccordionGroup>

## See Also

* [`useRequestConnection` hook](/hooks/connections/use-request-connection)
* [Connection data model](/data-models/connection)


# Delete User
Source: https://docs.sublay.io/v7/api-reference/users/delete-user

DELETE /v7/:projectId/users/:userId
Permanently delete a user and cascade cleanup across all of their related data

Permanently deletes the specified user and cascades cleanup across all of their related records. Reactions, files, follows, connections, notifications, collections, reports, and mentions are removed, and the user's entities and comments are stripped of their authored content. This is the same full-cascade delete performed from the dashboard.

<Warning>
  This is a hard, irreversible delete. It cannot be undone.
</Warning>

## Authentication

Requires a **service or master key**. User auth tokens are rejected with a `403`.

## Path Parameters

<ParamField type="string">
  The Sublay user ID (UUID) to delete.
</ParamField>

## Response

On success, returns HTTP `204 No Content` with an empty body.

## Error Responses

<AccordionGroup>
  <Accordion title="Elevated Auth Required — 403">
    ```json theme={null}
    {
      "error": "Service or master key required.",
      "code": "auth/elevated-auth-required"
    }
    ```
  </Accordion>

  <Accordion title="User Not Found — 404">
    ```json theme={null}
    {
      "error": "User not found.",
      "code": "user/not-found"
    }
    ```
  </Accordion>

  <Accordion title="Invalid Params — 400">
    ```json theme={null}
    {
      "error": "...",
      "code": "user/invalid-params"
    }
    ```
  </Accordion>

  <Accordion title="Server Error — 500">
    ```json theme={null}
    {
      "error": "Failed to delete the user.",
      "code": "user/server-error"
    }
    ```
  </Accordion>
</AccordionGroup>

## See Also

* [Node SDK: `deleteUser`](/v7/node-sdk/users#deleteuser)
* [User data model](/data-models/user)


# Fetch User by Username
Source: https://docs.sublay.io/v7/api-reference/users/fetch-user-by-username

GET /v7/:projectId/users/by-username
Look up a user by their username

Finds a user within the project by their `username`. Optionally includes file associations for avatar and banner images.

<Note>
  If the profile owner has blocked the signed-in caller, this returns `404` — the
  same response as a user who does not exist. The reverse is not true: a user
  *you* have blocked stays visible, so you keep a way to find and unblock them. Requires the `moderation` bundle.
</Note>

## Query Parameters

<ParamField type="string">
  The username to look up. Lookup is exact-match and case-sensitive to the
  stored value (usernames are lowercased on write).
</ParamField>

<ParamField type="string">
  Comma-separated list of associations to include. Pass `"files"` to include
  the processed `avatarFile` and `bannerFile` objects.
</ParamField>

### Space-scoped reputation

This endpoint has no space in context, so the opt-in `spaceReputation` object accepts a `spaceId` of a space **`<uuid>`** or **`none`** only — `context` is rejected (400). It adds a `spaceReputation` field to each returned user, alongside the always-present `reputation` total. Requires the `reputation` bundle. See the [Reputation data model](/data-models/reputation).

<SpaceReputationParams />

## Response

On success, returns HTTP `200` with the user object:

<ResponseField name="id" type="string">
  Unique user ID (UUID).
</ResponseField>

<ResponseField name="foreignId" type="string | null">
  External identifier from your system.
</ResponseField>

<ResponseField name="projectId" type="string">
  Project this user belongs to.
</ResponseField>

<ResponseField name="name" type="string | null">
  Display name.
</ResponseField>

<ResponseField name="username" type="string | null">
  The user's username.
</ResponseField>

<ResponseField name="avatar" type="string | null">
  Avatar image URL.
</ResponseField>

<ResponseField name="bio" type="string | null">
  Short bio text.
</ResponseField>

<ResponseField name="metadata" type="object | null">
  Public custom key-value data.
</ResponseField>

<ResponseField name="reputation" type="number">
  Reputation score.
</ResponseField>

<ResponseField name="avatarFile" type="object | null">
  Processed avatar image with variants. Only present when `include=files` is
  requested.
</ResponseField>

<ResponseField name="bannerFile" type="object | null">
  Processed banner image with variants. Only present when `include=files` is
  requested.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO timestamp of account creation.
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="User Not Found — 404">
    ```json theme={null}
    {
      "error": "User not found",
      "code": "user/not-found"
    }
    ```
  </Accordion>

  <Accordion title="Invalid Query — 400">
    ```json theme={null}
    {
      "error": "...",
      "code": "user/invalid-query"
    }
    ```
  </Accordion>
</AccordionGroup>

## See Also

* [`useFetchUserByUsername` hook](/hooks/users/use-fetch-user-by-username)
* [User data model](/data-models/user)


# Fetch User Suggestions
Source: https://docs.sublay.io/v7/api-reference/users/fetch-user-suggestions

GET /v7/:projectId/users/suggestions
Search for users by username prefix — for @mention autocomplete

Returns up to 5 users whose usernames contain the provided query string, ranked by prefix match first, then alphabetically. Designed for `@mention` autocomplete and user search UIs.

<Note>
  Sensitive fields (email, hash, salt, `isVerified`, `isActive`,
  `lastActive`) are excluded from suggestions results.
</Note>

## Query Parameters

<ParamField type="string">
  The search string. Matches usernames that contain this value
  (case-insensitive). Users whose usernames start with `query` are ranked
  first.
</ParamField>

### Space-scoped reputation

This endpoint has no space in context, so the opt-in `spaceReputation` object accepts a `spaceId` of a space **`<uuid>`** or **`none`** only — `context` is rejected (400). It adds a `spaceReputation` field to each returned user, alongside the always-present `reputation` total. Requires the `reputation` bundle. See the [Reputation data model](/data-models/reputation).

<SpaceReputationParams />

## Response

On success, returns HTTP `200` with an array of up to 5 user objects:

<ResponseField name="id" type="string">
  Unique user ID (UUID).
</ResponseField>

<ResponseField name="foreignId" type="string | null">
  External identifier from your system.
</ResponseField>

<ResponseField name="name" type="string | null">
  Display name.
</ResponseField>

<ResponseField name="username" type="string | null">
  The user's username.
</ResponseField>

<ResponseField name="avatar" type="string | null">
  Avatar image URL.
</ResponseField>

<ResponseField name="bio" type="string | null">
  Short bio text.
</ResponseField>

<ResponseField name="metadata" type="object | null">
  Public custom key-value data.
</ResponseField>

<ResponseField name="reputation" type="number">
  Reputation score.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO timestamp of account creation.
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="Invalid Query — 400">
    ```json theme={null}
    {
      "error": "...",
      "code": "user/invalid-query"
    }
    ```
  </Accordion>
</AccordionGroup>

## See Also

* [`useFetchUserSuggestions` hook](/hooks/users/use-fetch-user-suggestions)
* [`useUserMentions` hook](/hooks/users/use-user-mentions)


# Follow User
Source: https://docs.sublay.io/v7/api-reference/users/follows/follow-user

POST /v7/:projectId/users/:userId/follow
Follow a user by their ID

Creates a follow relationship from the authenticated user to the specified user. A notification is sent to the followed user.

## Path Parameters

<ParamField type="string">
  The Sublay user ID (UUID) of the user to follow.
</ParamField>

## Response

On success, returns HTTP `201` with the created follow record:

<ResponseField name="id" type="string">
  Unique follow record ID (UUID).
</ResponseField>

<ResponseField name="followerId" type="string">
  ID of the user who followed (the authenticated user).
</ResponseField>

<ResponseField name="followedId" type="string">
  ID of the user being followed.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO timestamp of when the follow was created.
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="Self-Follow — 400">
    ```json theme={null}
    {
      "error": "A user cannot follow themselves.",
      "code": "follow/self-follow"
    }
    ```
  </Accordion>

  <Accordion title="User Not Found — 404">
    ```json theme={null}
    {
      "error": "One or both users involved in the follow do not exist.",
      "code": "follow/user-not-found"
    }
    ```
  </Accordion>

  <Accordion title="Already Following — 409">
    ```json theme={null}
    {
      "error": "Follow relationship already exists.",
      "code": "follow/already-exists"
    }
    ```
  </Accordion>
</AccordionGroup>

## See Also

* [`useFollowManager` hook](/hooks/follows/use-follow-manager)
* [Follow data model](/data-models/follow)


# Get Follow Status
Source: https://docs.sublay.io/v7/api-reference/users/follows/get-follow-status

GET /v7/:projectId/users/:userId/follow
Check whether the authenticated user follows a specific user

Returns the follow status between the authenticated user and the specified user. If the authenticated user is following, the response includes the follow record ID and timestamp.

## Path Parameters

<ParamField type="string">
  The Sublay user ID (UUID) of the user to check follow status for.
</ParamField>

## Response

On success, returns HTTP `200`. The shape differs based on follow status:

**When following:**

<ResponseField name="isFollowing" type="boolean">
  `true` — the authenticated user follows this user.
</ResponseField>

<ResponseField name="followId" type="string">
  ID of the follow record.
</ResponseField>

<ResponseField name="followedAt" type="string">
  ISO timestamp of when the follow was created.
</ResponseField>

**When not following:**

<ResponseField name="isFollowing" type="boolean">
  `false`.
</ResponseField>

## See Also

* [`useFetchFollowStatus` hook](/hooks/follows/use-fetch-follow-status)
* [Follow data model](/data-models/follow)


# Get Followers
Source: https://docs.sublay.io/v7/api-reference/users/follows/get-followers

GET /v7/:projectId/users/:userId/followers
Get a paginated list of users who follow a specific user

Returns a paginated list of users who follow the specified user. Authentication is optional — the endpoint works without a token. When the caller is signed in, any user with a block between them and the caller, in either direction, is excluded from the results. Block filtering requires the `moderation` bundle.

## Path Parameters

<ParamField type="string">
  The Sublay user ID (UUID) of the user whose followers to retrieve.
</ParamField>

## Query Parameters

<ParamField type="number">
  Page number for pagination. Defaults to `1`.
</ParamField>

<ParamField type="number">
  Number of results per page. Defaults to `20`, maximum `100`.
</ParamField>

<ParamField type="string">
  Optional search term. Filters the list to users whose username or name contains this text (case-insensitive). When omitted, no filtering is applied.
</ParamField>

<ParamField type="string">
  Restricts which field `query` matches against — `username` or `name`. When omitted, `query` matches either field.
</ParamField>

### Space-scoped reputation

This endpoint has no space in context, so the opt-in `spaceReputation` object accepts a `spaceId` of a space **`<uuid>`** or **`none`** only — `context` is rejected (400). It adds a `spaceReputation` field to each returned user, alongside the always-present `reputation` total. Requires the `reputation` bundle. See the [Reputation data model](/data-models/reputation).

<SpaceReputationParams />

## Response

On success, returns HTTP `200` with a paginated response:

<ResponseField name="data" type="array">
  Array of follow entries.

  <Expandable title="item properties">
    <ResponseField name="followId" type="string">
      ID of the follow record.
    </ResponseField>

    <ResponseField name="user" type="object">
      Public profile of the follower user. Sensitive fields (email, hash, secureMetadata, etc.) are excluded.
    </ResponseField>

    <ResponseField name="followedAt" type="string">
      ISO timestamp of when the follow was created.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="totalCount" type="number">
  Total number of followers.
</ResponseField>

<ResponseField name="page" type="number">
  Current page number.
</ResponseField>

<ResponseField name="limit" type="number">
  Page size used for this response.
</ResponseField>

## See Also

* [`useFetchFollowers` hook](/hooks/follows/use-fetch-followers)
* [`useFetchFollowersByUserId` hook](/hooks/follows/use-fetch-followers-by-user-id)
* [Follow data model](/data-models/follow)


# Get Followers Count
Source: https://docs.sublay.io/v7/api-reference/users/follows/get-followers-count

GET /v7/:projectId/users/:userId/followers-count
Get the number of followers for a specific user

Returns the total number of users following the specified user. Authentication is optional — the endpoint works without a token. When the caller is signed in, any user with a block between them and the caller, in either direction, is excluded from the count. Block filtering requires the `moderation` bundle.

## Path Parameters

<ParamField type="string">
  The Sublay user ID (UUID) of the user whose follower count to retrieve.
</ParamField>

## Response

On success, returns HTTP `200`:

<ResponseField name="count" type="number">
  Total number of users following this user.
</ResponseField>

## See Also

* [`useFetchFollowersCount` hook](/hooks/follows/use-fetch-followers-count)
* [`useFetchFollowersCountByUserId` hook](/hooks/follows/use-fetch-followers-count-by-user-id)


# Get Following
Source: https://docs.sublay.io/v7/api-reference/users/follows/get-following

GET /v7/:projectId/users/:userId/following
Get a paginated list of users that a specific user follows

Returns a paginated list of users that the specified user follows. Authentication is optional — the endpoint works without a token. When the caller is signed in, any user with a block between them and the caller, in either direction, is excluded from the results. Block filtering requires the `moderation` bundle.

## Path Parameters

<ParamField type="string">
  The Sublay user ID (UUID) of the user whose following list to retrieve.
</ParamField>

## Query Parameters

<ParamField type="number">
  Page number for pagination. Defaults to `1`.
</ParamField>

<ParamField type="number">
  Number of results per page. Defaults to `20`, maximum `100`.
</ParamField>

<ParamField type="string">
  Optional search term. Filters the list to users whose username or name contains this text (case-insensitive). When omitted, no filtering is applied.
</ParamField>

<ParamField type="string">
  Restricts which field `query` matches against — `username` or `name`. When omitted, `query` matches either field.
</ParamField>

### Space-scoped reputation

This endpoint has no space in context, so the opt-in `spaceReputation` object accepts a `spaceId` of a space **`<uuid>`** or **`none`** only — `context` is rejected (400). It adds a `spaceReputation` field to each returned user, alongside the always-present `reputation` total. Requires the `reputation` bundle. See the [Reputation data model](/data-models/reputation).

<SpaceReputationParams />

## Response

On success, returns HTTP `200` with a paginated response:

<ResponseField name="data" type="array">
  Array of follow entries.

  <Expandable title="item properties">
    <ResponseField name="followId" type="string">
      ID of the follow record.
    </ResponseField>

    <ResponseField name="user" type="object">
      Public profile of the followed user. Sensitive fields (email, hash, secureMetadata, etc.) are excluded.
    </ResponseField>

    <ResponseField name="followedAt" type="string">
      ISO timestamp of when the follow was created.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="totalCount" type="number">
  Total number of users being followed.
</ResponseField>

<ResponseField name="page" type="number">
  Current page number.
</ResponseField>

<ResponseField name="limit" type="number">
  Page size used for this response.
</ResponseField>

## See Also

* [`useFetchFollowing` hook](/hooks/follows/use-fetch-following)
* [`useFetchFollowingByUserId` hook](/hooks/follows/use-fetch-following-by-user-id)
* [Follow data model](/data-models/follow)


# Get Following Count
Source: https://docs.sublay.io/v7/api-reference/users/follows/get-following-count

GET /v7/:projectId/users/:userId/following-count
Get the number of users that a specific user follows

Returns the total number of users that the specified user follows. Authentication is optional — the endpoint works without a token. When the caller is signed in, any user with a block between them and the caller, in either direction, is excluded from the count. Block filtering requires the `moderation` bundle.

## Path Parameters

<ParamField type="string">
  The Sublay user ID (UUID) of the user whose following count to retrieve.
</ParamField>

## Response

On success, returns HTTP `200`:

<ResponseField name="count" type="number">
  Total number of users this user is following.
</ResponseField>

## See Also

* [`useFetchFollowingCount` hook](/hooks/follows/use-fetch-following-count)
* [`useFetchFollowingCountByUserId` hook](/hooks/follows/use-fetch-following-count-by-user-id)


# Unfollow User
Source: https://docs.sublay.io/v7/api-reference/users/follows/unfollow-user

DELETE /v7/:projectId/users/:userId/follow
Unfollow a user by their user ID

Removes the follow relationship between the authenticated user and the specified user. This is a convenience alternative to [Delete Follow](/api-reference/follows/delete-follow) — it looks up the follow record by user ID rather than requiring the follow ID.

## Path Parameters

<ParamField type="string">
  The Sublay user ID (UUID) of the user to unfollow.
</ParamField>

## Response

On success, returns HTTP `204` with no body.

## Error Responses

<AccordionGroup>
  <Accordion title="Not Following — 404">
    ```json theme={null}
    {
      "error": "Follow relationship does not exist.",
      "code": "follow/not-found"
    }
    ```
  </Accordion>
</AccordionGroup>

## See Also

* [`useUnfollowUserByUserId` hook](/hooks/follows/use-unfollow-user-by-user-id)
* [Delete Follow](/api-reference/follows/delete-follow) — remove by follow ID instead


# Update User
Source: https://docs.sublay.io/v7/api-reference/users/update-user

PATCH /v7/:projectId/users/:userId
Update a user's profile fields, including avatar and banner images

Updates one or more profile fields for the specified user. The requesting user must own the account, or use a service or master token to update any user.

Supports direct image uploads for the avatar and banner via `multipart/form-data`. Uploaded images are processed, stored in Supabase, and the old files are automatically cleaned up after a successful update.

<Note>
  Send `application/json` for text-only updates. Use `multipart/form-data`
  when uploading image files.
</Note>

## Authentication

Requires a valid user auth token. The authenticated user must match `:userId`, or the request must carry a service/master token.

## Path Parameters

<ParamField type="string">
  The Sublay user ID (UUID) to update.
</ParamField>

## Body Parameters

All fields are optional. Only the fields provided are updated.

<ParamField type="string">
  Display name.
</ParamField>

<ParamField type="string">
  New username. Automatically lowercased and sanitized. Returns 409 if already
  taken by another user.
</ParamField>

<ParamField type="string">
  URL of the user's avatar image. Ignored if `avatarFile` is also provided.
</ParamField>

<ParamField type="string">
  Short bio text.
</ParamField>

<ParamField type="string">
  ISO 8601 datetime string for the user's date of birth (e.g. `"1990-06-15T00:00:00.000Z"`).
</ParamField>

<ParamField type="object">
  Geographic location stored as a PostGIS point.

  <Expandable title="properties">
    <ParamField type="number">
      Latitude between -90 and 90.
    </ParamField>

    <ParamField type="number">
      Longitude between -180 and 180.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="object">
  Public custom key-value data. Replaces the existing value.
</ParamField>

<ParamField type="object">
  Private custom key-value data. Not returned to other users. Replaces the
  existing value.
</ParamField>

<ParamField type="file">
  Avatar image file (multipart). Maximum 50 MB. Must be a valid image.
  Requires `avatarFile.options` to be present in the same request.
</ParamField>

<ParamField type="file">
  Banner image file (multipart). Maximum 50 MB. Must be a valid image.
  Requires `bannerFile.options` to be present in the same request.
</ParamField>

## Response

On success, returns HTTP `200` with the updated user's authenticated profile:

<ResponseField name="id" type="string">
  Unique user ID (UUID).
</ResponseField>

<ResponseField name="foreignId" type="string | null">
  External identifier from your system.
</ResponseField>

<ResponseField name="role" type="string">
  User role (e.g., `"visitor"`).
</ResponseField>

<ResponseField name="email" type="string | null">
  User's email address.
</ResponseField>

<ResponseField name="name" type="string | null">
  Updated display name.
</ResponseField>

<ResponseField name="username" type="string | null">
  Updated username.
</ResponseField>

<ResponseField name="avatar" type="string | null">
  Avatar URL.
</ResponseField>

<ResponseField name="bio" type="string | null">
  Bio text.
</ResponseField>

<ResponseField name="metadata" type="object | null">
  Public custom key-value data.
</ResponseField>

<ResponseField name="reputation" type="number | null">
  Reputation score.
</ResponseField>

<ResponseField name="isVerified" type="boolean | null">
  Whether the user's email has been verified.
</ResponseField>

<ResponseField name="isActive" type="boolean | null">
  Whether the user account is active.
</ResponseField>

<ResponseField name="lastActive" type="string | null">
  ISO timestamp of the user's last activity.
</ResponseField>

<ResponseField name="suspensions" type="array">
  Active suspensions on the account.
</ResponseField>

<ResponseField name="avatarFile" type="object | null">
  Processed avatar image with variants.
</ResponseField>

<ResponseField name="bannerFile" type="object | null">
  Processed banner image with variants.
</ResponseField>

<ResponseField name="authMethods" type="string[]">
  Active auth methods (e.g., `["password", "google"]`).
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO timestamp of account creation.
</ResponseField>

<Note>
  When `name`, `username`, or `bio` changes, the user's semantic search
  embedding is automatically updated asynchronously.
</Note>

## Error Responses

<AccordionGroup>
  <Accordion title="Not Authorized — 403">
    ```json theme={null}
    {
      "error": "Not authorized to update this user.",
      "code": "user/not-authorized"
    }
    ```
  </Accordion>

  <Accordion title="User Not Found — 404">
    ```json theme={null}
    {
      "error": "User not found",
      "code": "user/not-found"
    }
    ```
  </Accordion>

  <Accordion title="File Too Large — 413">
    ```json theme={null}
    {
      "message": "Avatar image exceeds 50MB limit.",
      "code": "user/file-too-large"
    }
    ```
  </Accordion>

  <Accordion title="Invalid Image — 422">
    ```json theme={null}
    {
      "message": "Avatar file is not a valid image: ...",
      "code": "user/invalid-image"
    }
    ```
  </Accordion>

  <Accordion title="Missing Image Options — 400">
    ```json theme={null}
    {
      "message": "Image options are required when uploading an avatar. Must include mode property.",
      "code": "user/missing-image-options"
    }
    ```
  </Accordion>

  <Accordion title="Validation Failed — 400">
    ```json theme={null}
    {
      "error": "User validation failed",
      "code": "user/validation-failed"
    }
    ```
  </Accordion>

  <Accordion title="Invalid Params — 400">
    ```json theme={null}
    {
      "error": "...",
      "code": "user/invalid-params"
    }
    ```
  </Accordion>
</AccordionGroup>

## See Also

* [`useUserActions` hook](/hooks/user/use-user-actions) — `updateUser`
* [Storage: Upload Image](/api-reference/storage/upload-image)
* [User data model](/data-models/user)


# Sign Testing JWT
Source: https://docs.sublay.io/v7/api-reference/crypto/sign-testing-jwt

POST /v7/:projectId/crypto/sign-testing-jwt
Generate a signed RS256 JWT for development and testing

Signs a short-lived JWT (5 minutes) using your project's RSA private key. Use this during development to generate tokens for testing [external auth](/sdk/authentication/external) without needing to implement JWT signing in your test environment.

<Warning>
  Never use this endpoint in production. It requires your RSA private key in the request body, which must be kept secret. Use it only in local development or CI environments.
</Warning>

## Body Parameters

<ParamField type="string">
  Your RSA private key encoded as a Base64 string. This is the private key associated with the public key configured in your project's external auth settings.
</ParamField>

<ParamField type="object">
  The JWT payload. Must include at least an `id` field (the user's ID in your system). All fields are included in the `userData` claim.

  ```json theme={null}
  {
    "id": "user-123",
    "email": "alice@example.com",
    "name": "Alice"
  }
  ```
</ParamField>

<ParamField type="string">
  The project ID. Can be provided in the body or as a URL path parameter (`:projectId`). The body value takes precedence if both are provided.
</ParamField>

## Response

Returns the signed JWT as a plain text string (not JSON):

```
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
```

The JWT is signed with `RS256`, expires in 5 minutes, and includes:

* `sub` — the user's `id` from the payload
* `iss` — the project ID
* `aud` — `"sublay.io"`
* `userData` — the full payload object

## Error Responses

<AccordionGroup>
  <Accordion title="Missing Parameters — 400">
    ```
    Missing params in request body
    ```

    Returned when `projectId`, `privateKey`, or `payload` is missing.
  </Accordion>

  <Accordion title="Missing User ID — 400">
    ```json theme={null}
    { "error": "Missing user id in payload.", "code": "crypto/missing-params" }
    ```

    Returned when the `payload` object does not include an `id` field.
  </Accordion>
</AccordionGroup>


# Add Host
Source: https://docs.sublay.io/v7/api-reference/events/add-host

POST /v7/:projectId/events/:eventId/hosts
Grant a user host privileges on an event (host-only)

Adds a user to the event's `hostIds`. **Host-only** — the caller must already be a host (service/master keys bypass this). The operation is idempotent (adding an existing host is a no-op) and takes a row-level lock to serialize concurrent host changes.

There is no requirement that the target be a space member or invitee — any user can be made a host.

## Path Parameters

<ParamField type="string">
  UUID of the event.
</ParamField>

## Body Parameters

<ParamField type="string">
  The user to grant host on the event.
</ParamField>

## Response

Returns the updated [Event](/data-models/event) with the new `hostIds`.

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Event not found", "code": "event/not-found" }
    ```
  </Accordion>

  <Accordion title="Forbidden (not a host) — 403">
    ```json theme={null}
    { "error": "Only a host of this event may manage its hosts.", "code": "event/forbidden" }
    ```
  </Accordion>
</AccordionGroup>

See also: [useAddHost](/hooks/events/use-add-host)


# Add Invite
Source: https://docs.sublay.io/v7/api-reference/events/add-invite

POST /v7/:projectId/events/:eventId/invites
Invite a user to an event (host-only)

Creates an [EventInvite](/data-models/event-invite) for a user. **Host-only** (service/master keys bypass the check). The invite is keyed on a Sublay `userId` (never a foreign ID) and is idempotent against the unique `(eventId, userId)` constraint — re-inviting an already-invited user is a no-op success.

For an `invite`-visibility event, the invited user can now see and RSVP to the event. When the `notifications` bundle is present, the invitee receives an `event-invite` notification (best-effort).

## Path Parameters

<ParamField type="string">
  UUID of the event.
</ParamField>

## Body Parameters

<ParamField type="string">
  The user to invite.
</ParamField>

## Response

Returns the updated [Event](/data-models/event).

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Event not found", "code": "event/not-found" }
    ```
  </Accordion>

  <Accordion title="Forbidden (not a host) — 403">
    ```json theme={null}
    { "error": "Only a host of this event may manage its invites.", "code": "event/forbidden" }
    ```
  </Accordion>
</AccordionGroup>

See also: [useAddInvite](/hooks/events/use-add-invite)


# Cancel Event
Source: https://docs.sublay.io/v7/api-reference/events/cancel-event

POST /v7/:projectId/events/:eventId/cancel
Cancel an event without deleting it (host-only)

Cancels an event by setting its `status` to `"cancelled"`. The event remains fetchable, but new and changed RSVPs are rejected. **Host-only** (service/master keys bypass the host check).

On cancel, an `event-cancelled` notification is fanned out to all `going`/`maybe` RSVPs (best-effort, requires the `notifications` bundle).

To remove an event entirely, use [Delete Event](/api-reference/events/delete-event).

## Path Parameters

<ParamField type="string">
  UUID of the event to cancel.
</ParamField>

## Response

Returns the updated [Event](/data-models/event) object with `status: "cancelled"`.

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Event not found", "code": "event/not-found" }
    ```
  </Accordion>

  <Accordion title="Forbidden (not a host) — 403">
    ```json theme={null}
    { "error": "Only a host of this event may cancel it.", "code": "event/forbidden" }
    ```
  </Accordion>
</AccordionGroup>

See also: [useCancelEvent](/hooks/events/use-cancel-event)


# Create Event
Source: https://docs.sublay.io/v7/api-reference/events/create-event

POST /v7/:projectId/events
Create an event, optionally with a cover image and gallery

Creates an event. The authenticated user becomes the creator (`userId`) and is automatically added to `hostIds`. Supports inline cover and gallery image upload via `multipart/form-data`.

The required location fields depend on `type`: `online` needs a `url`; `physical` needs an `address` or `location`; `hybrid` needs both a `url` and an `address`/`location`.

Requires authentication. Space-scoped events (`spaceId`) require the `spaces` bundle and active membership of the space. Image upload requires the `files-images` bundle.

## Body Parameters

<ParamField type="string">
  Event title. 1–300 characters.
</ParamField>

<ParamField type="string">
  ISO datetime when the event starts. RSVPs close at this moment.
</ParamField>

<ParamField type="string">
  `"online"`, `"physical"`, or `"hybrid"`. Controls which location fields are required.
</ParamField>

<ParamField type="string">
  Optional description.
</ParamField>

<ParamField type="string">
  Optional ISO datetime when the event ends.
</ParamField>

<ParamField type="string">
  Optional IANA timezone string, e.g. `"America/New_York"`.
</ParamField>

<ParamField type="string">
  Join/stream URL. Required for `online` and `hybrid` events.
</ParamField>

<ParamField type="string">
  Optional venue name.
</ParamField>

<ParamField type="string">
  Street address. Required (alone or with `location`) for `physical` and `hybrid` events.
</ParamField>

<ParamField type="{ latitude: number; longitude: number }">
  Geographic coordinates. Stored as a GeoJSON point and used for proximity search. On multipart requests, send as a JSON string.
</ParamField>

<ParamField type="string">
  Optional UUID of a space to scope the event to. Requires the `spaces` bundle and active membership. Mandatory when `visibility` is `"members"`.
</ParamField>

<ParamField type="string">
  `"public"`, `"members"`, or `"invite"`. Defaults to `"public"`. `"members"` requires a `spaceId`.
</ParamField>

<ParamField type="number">
  Maximum number of `going` RSVPs. Positive integer. Omit for unlimited.
</ParamField>

<ParamField type="boolean">
  Whether a `"maybe"` RSVP is allowed. Defaults to `true`.
</ParamField>

<ParamField type="boolean">
  Whether non-hosts can view the named guest list. Defaults to `true`.
</ParamField>

<ParamField type="string[]">
  Additional host user IDs. The creator is always added automatically. On multipart requests, send as a JSON string.
</ParamField>

<ParamField type="object">
  Arbitrary key-value data. Up to 1 MB.
</ParamField>

<ParamField type="string">
  Service/master key only. Create the event on behalf of this user (who becomes the creator and first host).
</ParamField>

<ParamField type="file">
  Optional single cover image. Multipart file field. Requires `cover.options` when provided.
</ParamField>

<ParamField type="string">
  JSON-stringified image-processing options for the cover (the same discriminated union used by [Upload Image](/api-reference/storage/upload-image)).
</ParamField>

<ParamField type="file[]">
  Optional gallery images (up to 10). Multipart file field. Requires `gallery.options` when provided.
</ParamField>

<ParamField type="string">
  JSON-stringified image-processing options applied to every gallery image.
</ParamField>

## Response

Returns `201` with the created [Event](/data-models/event) object, including inline `rsvpCounts` and (with images) the `files` association.

## Error Responses

<AccordionGroup>
  <Accordion title="Invalid Body — 400">
    ```json theme={null}
    { "error": "Online events require a `url`.", "code": "event/invalid-body" }
    ```
  </Accordion>

  <Accordion title="files-images Bundle Required — 403">
    ```json theme={null}
    { "error": "Event cover/gallery images require the files-images bundle. Enable it for this project.", "code": "event/files-images-bundle-required" }
    ```
  </Accordion>

  <Accordion title="spaces Bundle Required — 403">
    ```json theme={null}
    { "error": "Space-scoped events require the spaces bundle. Enable it for this project.", "code": "event/spaces-bundle-required" }
    ```
  </Accordion>

  <Accordion title="Space Not Found — 404">
    ```json theme={null}
    { "error": "Space not found", "code": "event/space-not-found" }
    ```
  </Accordion>

  <Accordion title="Not a Space Member — 403">
    ```json theme={null}
    { "error": "You must be an active member of this space to create an event in it.", "code": "event/not-space-member" }
    ```
  </Accordion>

  <Accordion title="File Too Large — 413">
    ```json theme={null}
    { "code": "event/file-too-large", "message": "Image \"cover.jpg\" exceeds 50MB limit." }
    ```
  </Accordion>

  <Accordion title="Invalid Image — 422">
    ```json theme={null}
    { "code": "event/invalid-image", "message": "File \"cover.jpg\" is not a valid image: ..." }
    ```
  </Accordion>
</AccordionGroup>

See also: [useCreateEvent](/hooks/events/use-create-event) · [node-sdk](/v7/node-sdk/events) · [js-sdk](/v7/js-sdk/events)


# Delete Event
Source: https://docs.sublay.io/v7/api-reference/events/delete-event

DELETE /v7/:projectId/events/:eventId
Permanently or soft-delete an event and clean up its children (host-only)

Deletes an event. **Host-only** (service/master keys bypass the host check). The event's child `EventRsvps` and `EventInvites` are cleaned up, and—depending on settings—its files.

Deletion honors the project's `eventDeletion` settings:

* `softDelete` (default `false`) — when `true`, the event is soft-deleted (a `deletedAt` timestamp is set) and drops out of listings while the row is retained.
* `preserveFilesOnSoftDelete` (default `true`) — on a soft delete, keep the event's files. On a hard delete, files are always removed.

## Path Parameters

<ParamField type="string">
  UUID of the event to delete.
</ParamField>

## Response

Returns `204 No Content` on success.

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Event not found", "code": "event/not-found" }
    ```
  </Accordion>

  <Accordion title="Forbidden (not a host) — 403">
    ```json theme={null}
    { "error": "Only a host of this event may delete it.", "code": "event/forbidden" }
    ```
  </Accordion>

  <Accordion title="Already Deleted — 404">
    ```json theme={null}
    { "error": "Event not found or already deleted.", "code": "event/delete-failed" }
    ```
  </Accordion>
</AccordionGroup>

See also: [useDeleteEvent](/hooks/events/use-delete-event)


# Fetch Event
Source: https://docs.sublay.io/v7/api-reference/events/fetch-event

GET /v7/:projectId/events/:eventId
Fetch a single event by ID, with visibility enforced

Returns a single event by UUID. The [server-side visibility predicate](/data-models/event#visibility) is applied: if the event does not exist **or** the caller cannot see it, the response is `404` (existence is never leaked).

The response always includes inline `rsvpCounts`. Authentication is optional; pass the `userRsvp` include with an authenticated caller to populate `userRsvp`.

## Path Parameters

<ParamField type="string">
  UUID of the event.
</ParamField>

## Query Parameters

<ParamField type="string">
  Comma-separated associations to expand: `"user"`, `"space"`, `"files"`, `"userRsvp"`.
</ParamField>

<ParamField type="string">
  The requester id, used for visibility resolution and `userRsvp` enrichment. Inferred from the token for normal callers; service/master keys may pass it explicitly.
</ParamField>

## Response

Returns the [Event](/data-models/event) object.

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found / No Access — 404">
    ```json theme={null}
    { "error": "Event not found", "code": "event/not-found" }
    ```
  </Accordion>
</AccordionGroup>

See also: [useFetchEvent](/hooks/events/use-fetch-event) · [EventProvider & useEvent](/sdk/events/provider-and-hook)


# Fetch Event RSVPs
Source: https://docs.sublay.io/v7/api-reference/events/fetch-event-rsvps

GET /v7/:projectId/events/:eventId/rsvps
List the named guest list (who RSVP'd) for an event

Returns a paginated list of [EventRsvp](/data-models/event-rsvp) records, each with the `user` populated — the **named** guest list. Results are ordered by `createdAt` descending.

Authentication is optional. The event is first loaded behind the [visibility predicate](/data-models/event#visibility), so a caller without access to the event gets `404`. The named list itself is then gated:

* **Hosts** can always see it.
* **Any viewer** (including anonymous) can see it when the event's `guestListVisible` is `true`.
* **Service/master keys** bypass the gate.
* Otherwise the response is `403`.

Aggregate RSVP **counts** are always public via the event's `rsvpCounts` — this endpoint only governs the per-user list.

## Path Parameters

<ParamField type="string">
  UUID of the event.
</ParamField>

## Query Parameters

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Capped at `100`. Defaults to `10`.
</ParamField>

<ParamField type="string">
  Comma-separated RSVP statuses to filter by, e.g. `"going,maybe"`. When omitted, all statuses are returned.
</ParamField>

## Response

Returns a paginated response: `{ data: EventRsvp[], pagination: {...} }`.

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found / No Access — 404">
    ```json theme={null}
    { "error": "Event not found", "code": "event/not-found" }
    ```
  </Accordion>

  <Accordion title="Guest List Hidden — 403">
    ```json theme={null}
    { "error": "This event's guest list is not visible.", "code": "event/guest-list-hidden" }
    ```
  </Accordion>
</AccordionGroup>

See also: [useFetchEventRsvps](/hooks/events/use-fetch-event-rsvps)


# Fetch Invitees
Source: https://docs.sublay.io/v7/api-reference/events/fetch-invitees

GET /v7/:projectId/events/:eventId/invites
List an event's invited users (host-only)

Returns a paginated list of [EventInvite](/data-models/event-invite) records, each with the invited `user` populated. **Host-only** — a non-host receives `403`, and a non-existent event receives `404` (service/master keys bypass the host check). Results are ordered by `invitedAt` descending.

## Path Parameters

<ParamField type="string">
  UUID of the event.
</ParamField>

## Query Parameters

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Capped at `100`. Defaults to `10`.
</ParamField>

## Response

Returns a paginated response: `{ data: EventInvite[], pagination: {...} }`.

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Event not found", "code": "event/not-found" }
    ```
  </Accordion>

  <Accordion title="Forbidden (not a host) — 403">
    ```json theme={null}
    { "error": "Only a host of this event may view its invite list.", "code": "event/forbidden" }
    ```
  </Accordion>
</AccordionGroup>

See also: [useFetchInvitees](/hooks/events/use-fetch-invitees)


# Fetch Many Events
Source: https://docs.sublay.io/v7/api-reference/events/fetch-many-events

GET /v7/:projectId/events
List events with visibility enforcement, filtering, sorting, geo, and free-text search

Returns a paginated list of events. The [server-side visibility predicate](/data-models/event#visibility) is always applied: anonymous callers see only `public` events; authenticated callers additionally see `members` events of spaces they belong to, `invite` events they were invited to, and any event they host. Service/master keys see everything.

Each event includes inline `rsvpCounts`, and—with the `userRsvp` include and an authenticated caller—the caller's own `userRsvp`.

Authentication is optional (`optionalUserAuth`). Several filters interact with the caller's identity (`myRsvp`, `userRsvp`).

## Query Parameters

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Capped at `100`. Defaults to `10`.
</ParamField>

<ParamField type="string">
  `"startTime"` (chronological) or `"going"` (by going-RSVP count). Defaults to `"startTime"`.
</ParamField>

<ParamField type="string">
  `"asc"` or `"desc"`. Defaults to `"asc"`.
</ParamField>

<ParamField type="string">
  Derived time window: `"upcoming"` (`startTime` in the future), `"ongoing"` (started, has an `endTime`, not yet ended), or `"past"`. Events without an `endTime` become `past` once they start.
</ParamField>

<ParamField type="string">
  ISO datetime. Only events starting after this. ANDed with `timeWindow`.
</ParamField>

<ParamField type="string">
  ISO datetime. Only events starting before this.
</ParamField>

<ParamField type="string">
  Restrict to events scoped to this space. Omit for all scopes.
</ParamField>

<ParamField type="string">
  Only events hosted by this user (array containment on `hostIds`).
</ParamField>

<ParamField type="string">
  Filter by `"online"`, `"physical"`, or `"hybrid"`.
</ParamField>

<ParamField type="string">
  `"active"` or `"cancelled"`. Defaults to `"active"`.
</ParamField>

<ParamField type="string">
  Comma-separated RSVP statuses the caller responded with, e.g. `"going,maybe"`. Requires an authenticated caller (or a service/master key passing `userId`); otherwise returns `400`.
</ParamField>

<ParamField type="object">
  Proximity filter `{ latitude, longitude, radius }` (radius in meters). Uses `ST_DWithin`.
</ParamField>

<ParamField type="object">
  Free-text filter on `title`: `{ hasTitle?, includes?, doesNotInclude? }`. `includes`/`doesNotInclude` accept a string or array.
</ParamField>

<ParamField type="object">
  Free-text filter on `description`: `{ hasDescription?, includes?, doesNotInclude? }`.
</ParamField>

<ParamField type="string">
  Comma-separated associations to expand: `"user"`, `"space"`, `"files"`, `"userRsvp"`.
</ParamField>

<ParamField type="string">
  The requester id. Used for the `myRsvp` filter, `userRsvp` enrichment, and visibility resolution. For non-privileged callers the server infers this from the auth token; service/master keys may pass it explicitly.
</ParamField>

## Response

Returns a paginated response: `{ data: Event[], pagination: { page, limit, totalItems, hasMore, ... } }`. See [Event](/data-models/event).

## Error Responses

<AccordionGroup>
  <Accordion title="myRsvp Requires Auth — 400">
    ```json theme={null}
    { "error": "The myRsvp filter requires an authenticated caller (or a service/master key acting via a userId query param).", "code": "event/my-rsvp-requires-auth" }
    ```
  </Accordion>

  <Accordion title="Invalid Query — 400">
    ```json theme={null}
    { "error": "Limit must be a positive number", "code": "event/invalid-query" }
    ```
  </Accordion>
</AccordionGroup>

See also: [useFetchManyEvents](/hooks/events/use-fetch-many-events) · [useFetchManyEventsWrapper](/hooks/events/use-fetch-many-events-wrapper)


# Remove Host
Source: https://docs.sublay.io/v7/api-reference/events/remove-host

DELETE /v7/:projectId/events/:eventId/hosts
Revoke a user's host privileges on an event (host-only)

Removes a user from the event's `hostIds`. **Host-only** (service/master keys bypass the check). The mutation runs under a row-level lock and enforces the **at-least-one-host invariant**: a removal that would leave the event with zero hosts is rejected with `409`.

The target user is supplied in the request body (symmetric with [Withdraw RSVP](/api-reference/events/withdraw-rsvp)).

## Path Parameters

<ParamField type="string">
  UUID of the event.
</ParamField>

## Body Parameters

<ParamField type="string">
  The host to remove.
</ParamField>

## Response

Returns the updated [Event](/data-models/event) with the new `hostIds`.

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Event not found", "code": "event/not-found" }
    ```
  </Accordion>

  <Accordion title="Forbidden (not a host) — 403">
    ```json theme={null}
    { "error": "Only a host of this event may manage its hosts.", "code": "event/forbidden" }
    ```
  </Accordion>

  <Accordion title="Last Host — 409">
    ```json theme={null}
    { "error": "An event must have at least one host.", "code": "event/last-host" }
    ```
  </Accordion>
</AccordionGroup>

See also: [useRemoveHost](/hooks/events/use-remove-host)


# Remove Invite
Source: https://docs.sublay.io/v7/api-reference/events/remove-invite

DELETE /v7/:projectId/events/:eventId/invites
Revoke a user's invite to an event (host-only)

Removes a user's [EventInvite](/data-models/event-invite). **Host-only** (service/master keys bypass the check). Removing the invite **revokes access** to an `invite`-only event and also **deletes that user's RSVP** (decrementing the matching `rsvpCounts` entry), all under a row-level lock. Removing a non-invited user is an idempotent no-op success.

## Path Parameters

<ParamField type="string">
  UUID of the event.
</ParamField>

## Body Parameters

<ParamField type="string">
  The invitee to remove.
</ParamField>

## Response

Returns the updated [Event](/data-models/event) with refreshed `rsvpCounts`.

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Event not found", "code": "event/not-found" }
    ```
  </Accordion>

  <Accordion title="Forbidden (not a host) — 403">
    ```json theme={null}
    { "error": "Only a host of this event may manage its invites.", "code": "event/forbidden" }
    ```
  </Accordion>
</AccordionGroup>

See also: [useRemoveInvite](/hooks/events/use-remove-invite)


# Set RSVP
Source: https://docs.sublay.io/v7/api-reference/events/set-rsvp

POST /v7/:projectId/events/:eventId/rsvp
Set or change the caller's RSVP to an event

Sets or changes the caller's RSVP. A new RSVP is created, or an existing one is switched, and the event's `rsvpCounts` are updated atomically. Requires authentication, and the caller must be able to [see the event](/data-models/event#visibility) (otherwise `404`).

Transitions into `going` are capacity-checked under a row-level lock, so an event can never be oversold.

**Rules:**

* RSVPs close at `startTime`.
* A `cancelled` event rejects RSVPs.
* `"maybe"` is rejected when the event's `allowMaybe` is `false`.
* `"going"` (new or switched into) is rejected when `rsvpCounts.going` has reached `capacity`.

## Path Parameters

<ParamField type="string">
  UUID of the event.
</ParamField>

## Body Parameters

<ParamField type="string">
  `"going"`, `"maybe"`, or `"not_going"`.
</ParamField>

<ParamField type="string">
  Service/master key only. RSVP on behalf of this user.
</ParamField>

## Response

Returns the [Event](/data-models/event) with refreshed `rsvpCounts` and the caller's `userRsvp`.

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found / No Access — 404">
    ```json theme={null}
    { "error": "Event not found", "code": "event/not-found" }
    ```
  </Accordion>

  <Accordion title="Event Cancelled — 409">
    ```json theme={null}
    { "error": "This event has been cancelled.", "code": "event/cancelled" }
    ```
  </Accordion>

  <Accordion title="RSVPs Closed — 409">
    ```json theme={null}
    { "error": "RSVPs are closed for this event.", "code": "event/rsvp-closed" }
    ```
  </Accordion>

  <Accordion title="Maybe Disabled — 409">
    ```json theme={null}
    { "error": "This event does not allow a 'maybe' RSVP.", "code": "event/maybe-disabled" }
    ```
  </Accordion>

  <Accordion title="At Capacity — 409">
    ```json theme={null}
    { "error": "This event is at capacity.", "code": "event/full" }
    ```
  </Accordion>
</AccordionGroup>

See also: [useSetRsvp](/hooks/events/use-set-rsvp)


# Update Event
Source: https://docs.sublay.io/v7/api-reference/events/update-event

PATCH /v7/:projectId/events/:eventId
Edit an event's mutable fields and curate its images (host-only)

Updates an event. **Host-only** — the caller must be in `hostIds` (service/master keys bypass this). Every provided field is updated; omitted fields are left untouched. Type-conditional location validation is re-applied when `type` is present.

`hostIds`, `status`, and `spaceId` are **not** editable here — manage hosts via the [host endpoints](/api-reference/events/add-host), cancel via [Cancel Event](/api-reference/events/cancel-event); the space is immutable.

Images can be curated in one request: a new `cover` **replaces** the existing cover, `gallery` files are **appended**, and `removeImageIds` deletes existing event images by File ID. Any image operation requires the `files-images` bundle.

When a time field (`startTime`/`endTime`/`timezone`) or a location field (`location`/`url`/`venueName`/`address`) actually changes, an `event-updated` notification is fanned out to all `going`/`maybe` RSVPs (best-effort, requires the `notifications` bundle).

## Path Parameters

<ParamField type="string">
  UUID of the event to update.
</ParamField>

## Body Parameters

<ParamField type="string">Event title. 1–300 characters.</ParamField>
<ParamField type="string">New description.</ParamField>
<ParamField type="string">New ISO start datetime.</ParamField>
<ParamField type="string">New ISO end datetime.</ParamField>
<ParamField type="string">New IANA timezone.</ParamField>
<ParamField type="string">`"online"`, `"physical"`, or `"hybrid"`. Re-triggers location validation.</ParamField>
<ParamField type="string">Join/stream URL.</ParamField>
<ParamField type="string">Venue name.</ParamField>
<ParamField type="string">Street address.</ParamField>
<ParamField type="{ latitude: number; longitude: number }">New coordinates. On multipart requests, send as a JSON string.</ParamField>
<ParamField type="string">`"public"`, `"members"`, or `"invite"`.</ParamField>
<ParamField type="number">New capacity (positive integer).</ParamField>
<ParamField type="boolean">Whether `"maybe"` RSVPs are allowed.</ParamField>
<ParamField type="boolean">Whether non-hosts can view the guest list.</ParamField>
<ParamField type="object">Arbitrary key-value data. Up to 1 MB.</ParamField>

<ParamField type="string[]">
  File IDs of existing event images to remove (gallery photos and/or the current cover). Each must belong to this event. On multipart requests, send as a JSON string.
</ParamField>

<ParamField type="file">
  New cover image (replaces the current cover). Multipart file field. Requires `cover.options`.
</ParamField>

<ParamField type="string">
  JSON-stringified image-processing options for the new cover.
</ParamField>

<ParamField type="file[]">
  Gallery images to append (up to 10). Multipart file field. Requires `gallery.options`.
</ParamField>

<ParamField type="string">
  JSON-stringified image-processing options for the appended gallery images.
</ParamField>

## Response

Returns the updated [Event](/data-models/event) object.

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Event not found", "code": "event/not-found" }
    ```
  </Accordion>

  <Accordion title="Forbidden (not a host) — 403">
    ```json theme={null}
    { "error": "Only a host of this event may update it.", "code": "event/forbidden" }
    ```
  </Accordion>

  <Accordion title="files-images Bundle Required — 403">
    ```json theme={null}
    { "error": "Event cover/gallery images require the files-images bundle. Enable it for this project.", "code": "event/files-images-bundle-required" }
    ```
  </Accordion>

  <Accordion title="Invalid removeImageIds — 400">
    ```json theme={null}
    { "error": "Some removeImageIds do not belong to this event.", "code": "event/invalid-remove-image-ids" }
    ```
  </Accordion>
</AccordionGroup>

See also: [useUpdateEvent](/hooks/events/use-update-event)


# Withdraw RSVP
Source: https://docs.sublay.io/v7/api-reference/events/withdraw-rsvp

DELETE /v7/:projectId/events/:eventId/rsvp
Remove the caller's RSVP from an event

Removes the caller's RSVP. The RSVP row is deleted and the matching `rsvpCounts` entry is decremented. Requires authentication, and the caller must be able to [see the event](/data-models/event#visibility) (otherwise `404`).

Withdrawing is idempotent — withdrawing when there is no RSVP succeeds and changes nothing.

## Path Parameters

<ParamField type="string">
  UUID of the event.
</ParamField>

## Body Parameters

<ParamField type="string">
  Service/master key only. Withdraw on behalf of this user.
</ParamField>

## Response

Returns the [Event](/data-models/event) with refreshed `rsvpCounts`.

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found / No Access — 404">
    ```json theme={null}
    { "error": "Event not found", "code": "event/not-found" }
    ```
  </Accordion>
</AccordionGroup>

See also: [useWithdrawRsvp](/hooks/events/use-withdraw-rsvp)


# Match Users
Source: https://docs.sublay.io/v7/api-reference/match/match-users

POST /v7/:projectId/match/users
Match people by activity-derived interest facets

Ranks other users against an asker's interests, using **activity-derived interest facets** — clusters of what each user has actually engaged with over time, not a static profile. The endpoint returns a structured match breakdown (who, how strongly, and on which facets), optionally with sample content that illustrates each overlap.

Matching runs in two modes:

* **`passive`** — match against the *asker's own* interest facets. Answers "who is like me?" No free-text; the asker's top facets are the query.
* **`directed`** — match against a free-text `query` topic. Answers "who is into biotech?" The query is embedded and ranked against candidate facets.

<Note>
  Requires a **paid plan**, the **`ai-search`** bundle, the **`interest-matching`** bundle, and `interestMatching.enabled` set on the project. See the [Interest Matching](/v7/interest-matching) guide for setup.
</Note>

## Authentication

The endpoint **requires an authenticated user**. A missing token is rejected with a bare `401` before the controller runs; an invalid or expired token is rejected with `403` (refresh and retry). Both modes act on behalf of that user:

* **`passive`** ranks candidates against the asker's own facets — the authenticated user *is* the query.
* **`directed`** ranks candidates against a free-text `query`, still on behalf of the authenticated user.

A master or service key passes the auth layer without binding to a specific user; when acting that way the controller still needs an identified user and returns `401 auth/user-required` if none is resolved.

## Body Parameters

<ParamField type="string">
  `"passive"` or `"directed"`.
</ParamField>

<ParamField type="string">
  The free-text topic to match against. **Required in `directed` mode; rejected in `passive` mode.**
</ParamField>

<ParamField type="number">
  Maximum number of matched users to return. Maximum `50`.
</ParamField>

<ParamField type="string">
  Restrict candidates to users active in this space.
</ParamField>

<ParamField type="boolean">
  Only applies with `spaceId`. When `true`, candidates active anywhere in the space's subtree are eligible. Ignored without `spaceId`.
</ParamField>

<ParamField type="boolean">
  Gate 2 of the two-gate sample exposure. When `true` **and** the project setting `interestMatching.exposeSampleContent` is on, each matched facet includes a few illustrative content snippets from the candidate. Requesting samples while the project setting is off returns `403 match/sample-content-disabled`.
</ParamField>

<ParamField type="boolean">
  Exclude the asker from the results.
</ParamField>

## Response

Returns the `{ results: [...] }` envelope (a deliberate divergence from `search/*`, which return bare arrays). Results are ordered by descending `score`.

```json theme={null}
{
  "results": [
    {
      "user": { "id": "usr_...", "name": "..." },
      "score": 3.14,
      "matchedFacets": [
        {
          "similarity": 0.62,
          "askerFacet": { "id": "fac_...", "hotness": 4.2 },
          "candidateFacet": { "id": "fac_...", "hotness": 3.8 },
          "sampleContent": [
            {
              "sourceType": "entity",
              "recordId": "ent_...",
              "content": "…",
              "similarity": 0.71
            }
          ]
        }
      ]
    }
  ]
}
```

**Breakdown fields**

* `score` — the aggregate match score. In `passive` mode this is additive over the top matched facet-pairs (two moderate overlaps can outrank one very strong overlap); in `directed` mode it is the single best facet's `similarity · weight(hotness)`.
* `matchedFacets[].similarity` — cosine similarity of the facet pair.
* `matchedFacets[].askerFacet` — the asker's side of the pair. Present in `passive` mode; **omitted in `directed` mode** (there is no asker facet — the query is the anchor) and for the cold-start bio fallback.
* `matchedFacets[].candidateFacet` — the candidate's facet: its `id` and lazily-decayed `hotness`.
* `matchedFacets[].sampleContent` — present **only** when both sample gates are satisfied. Never contains moderation-removed, soft-deleted, or private-DM content.

The always-returned breakdown (users, scores, facet ids, similarities, hotness) carries **no readable content** — raw content appears only behind the two gates.

## Cold-start fallback

In `passive` mode, if the asker has no facet above the significance threshold, the endpoint falls back to the asker's **bio embedding** (from `UserEmbeddings`) as a single pseudo-facet, so a brand-new user can still get matches. Cold-start matches omit `askerFacet` on the breakdown.

## Candidate exclusions

Candidates are excluded when they are: the asker (unless `excludeSelf: false`), users with an **active** suspension (a future-dated suspension does *not* count as active), and — for a space-scoped match — users **banned** in that space.

## Error Responses

<AccordionGroup>
  <Accordion title="User Required — 401">
    ```json theme={null}
    { "error": "Passive match requires an identified user", "code": "auth/user-required" }
    ```
  </Accordion>

  <Accordion title="Plan Required — 403">
    ```json theme={null}
    { "error": "Interest matching requires a paid plan", "code": "project/plan-required" }
    ```
  </Accordion>

  <Accordion title="Interest Matching Disabled — 403">
    ```json theme={null}
    { "error": "Interest matching is not enabled for this project", "code": "project/interest-matching-disabled" }
    ```
  </Accordion>

  <Accordion title="Sample Content Disabled — 403">
    ```json theme={null}
    { "error": "Sample content is not enabled for this project", "code": "match/sample-content-disabled" }
    ```
  </Accordion>

  <Accordion title="Tables Not Available — 403">
    The `interest-matching` bundle is not installed.

    ```json theme={null}
    { "code": "database/tables-not-available", "missingTables": ["UserInterestFacets"] }
    ```
  </Accordion>
</AccordionGroup>


# Create Reputation Grant
Source: https://docs.sublay.io/v7/api-reference/reputation-grants/create-reputation-grant

POST /v7/:projectId/reputation-grants
Transfer reputation from one user's bucket to another user's bucket in the same space

Transfers reputation between two users. This is a **debited transfer**: the amount leaves the sender's bucket and lands in the recipient's bucket for the same space. Nothing is created — see [Mint Reputation Grant](/api-reference/reputation-grants/mint-reputation-grant) for that.

Requires authentication. A user token sends from the token's own user. A service or master key may name any sender via `actingUserId`, which is how an app performs a **mediated transfer** — enforcing its own economic rules before letting the transfer through. Mediated transfers skip the project-level user-grant switch and ignore block relationships; they are otherwise identical to a user grant, including the balance check.

Requires the `reputation` bundle (both `ReputationBuckets` and `ReputationGrants` must be present in the project's schema).

## Body Parameters

<ParamField type="string">
  UUID of the user receiving the reputation. Must differ from the sender.
</ParamField>

<ParamField type="number">
  Whole number from `1` to `2147483647` (the signed 32-bit maximum, which is also the width of a reputation balance). A transfer can never be zero, negative, or fractional, and it can never exceed what the sender holds in the source bucket.
</ParamField>

<ParamField type="string | null">
  UUID of the space whose bucket pays. Omitted or `null` means the project-general bucket. The reputation always lands in the recipient's bucket for the same space — reputation never crosses between the general bucket and a space bucket.

  The space is validated before anything moves: an ID that names no space is rejected with `404 reputation-grant/space-not-found`, and naming a space on a project without the `spaces` bundle is rejected with `403 database/tables-not-available`.
</ParamField>

<ParamField type="string | null">
  Free-text note. Trimmed, up to 2000 characters.
</ParamField>

<ParamField type="object">
  Arbitrary key-value data. Up to 1 MB. Omit the key when unused — `null` is not accepted.
</ParamField>

<ParamField type="string">
  What the grant is for: `"entity"`, `"comment"`, or `"chat-message"`. Must be supplied together with `targetId`. The target is an annotation — it never determines which bucket is used, and it does not have to be authored by the recipient.
</ParamField>

<ParamField type="string">
  UUID of the rewarded record. Must be supplied together with `targetType`, and must exist at the time of granting.
</ParamField>

<ParamField type="string">
  Service/master key only. The **sender** — the user reputation is debited from. Spelled `actingUserId` rather than `userId` because this body already names a target user (`recipientId`). A user token may only name itself.
</ParamField>

## Response

Returns `201` with the created [ReputationGrant](/data-models/reputation-grant), written with `sourceType: "user"`.

Both balances move: the sender's bucket and profile total drop by `amount`, the recipient's rise by the same. The recipient is notified (a `reputation-grant` [app notification](/data-models/app-notification)), and a `chat-message`-targeted grant is broadcast to the conversation as [`message:grant`](/sdk/chat/real-time).

## Gating and blocks

* **Project setting.** The switch is `settings.reputationGrants.allowUserInitiated`, flipped from **Settings → SDK** in the dashboard. Only an explicit `false` closes the endpoint to user tokens — an absent key means grants are allowed — and the stored value survives unrelated settings updates, so it changes only when that key is explicitly sent. When the switch is off a user token is rejected with `403 reputation-grant/user-grants-disabled`; service and master keys still work, so peer transfers remain available when routed through your backend.
* **Blocks.** If either party has blocked the other, a user grant is rejected in both directions — with the same non-disclosing answer as a missing user. Service and master keys ignore block relationships.
* **Suspension.** A suspended user cannot send a grant, including on the mediated path — a service key naming a suspended `actingUserId` is rejected too. A master key bypasses the check. A suspended user can always receive a grant.

## Error Responses

<AccordionGroup>
  <Accordion title="Invalid Body — 400">
    ```json theme={null}
    { "error": "amount: Too small: expected number to be >=1", "code": "reputation-grant/invalid-body" }
    ```

    Field-level failures are prefixed with the field path, so `error` reads `"<path>: <message>"` — `"amount: Invalid input: expected int, received number"` for a fractional amount, `"recipientId: Invalid UUID format"` for a malformed ID. The one whole-body rule has no path and so no prefix: supplying `targetType` without `targetId` (or the reverse) returns `"targetType and targetId must be supplied together"`.
  </Accordion>

  <Accordion title="Self Grant — 400">
    ```json theme={null}
    { "error": "A user cannot grant reputation to themselves.", "code": "reputation-grant/self-grant" }
    ```
  </Accordion>

  <Accordion title="Missing Sender — 400">
    ```json theme={null}
    { "error": "Missing user ID", "code": "reputation-grant/missing-user-id" }
    ```

    A service or master key called the endpoint without naming an `actingUserId`.
  </Accordion>

  <Accordion title="User Grants Disabled — 403">
    ```json theme={null}
    { "error": "User-initiated reputation grants are disabled for this project.", "code": "reputation-grant/user-grants-disabled" }
    ```
  </Accordion>

  <Accordion title="Unauthorized Sender — 403">
    ```json theme={null}
    { "error": "Unauthorized", "code": "reputation-grant/unauthorized" }
    ```

    A user token named an `actingUserId` other than its own.
  </Accordion>

  <Accordion title="Suspended — 403">
    ```json theme={null}
    {
      "error": "This account is suspended and cannot perform this action.",
      "code": "user/suspended",
      "reason": "...",
      "endDate": "..."
    }
    ```

    `reason` and `endDate` are `null` when the suspension carries neither.
  </Accordion>

  <Accordion title="Tables Not Available — 403">
    ```json theme={null}
    {
      "code": "database/tables-not-available",
      "missingTables": ["ReputationBuckets", "ReputationGrants"],
      "dashboardUrl": "https://…/<projectId>/database"
    }
    ```

    The `reputation` bundle is missing — the route names both of its tables, so a project without it is told about both — or the target's bundle is missing (e.g. a `chat-message` target without `chat`), or a `spaceId` was supplied on a project without `spaces`. `missingTables` names exactly what is absent.
  </Accordion>

  <Accordion title="Space Not Found — 404">
    ```json theme={null}
    { "error": "The space this grant targets does not exist.", "code": "reputation-grant/space-not-found" }
    ```

    The `spaceId` names no space in this project. Checked before any balance is touched, so nothing moves.
  </Accordion>

  <Accordion title="User Not Found — 404">
    ```json theme={null}
    { "error": "One or both users involved in this grant do not exist.", "code": "reputation-grant/user-not-found" }
    ```

    One answer for both parties, deliberately non-disclosing — and the same answer returned when a block edge exists in either direction.
  </Accordion>

  <Accordion title="Target Not Found — 404">
    ```json theme={null}
    { "error": "The grant target does not exist.", "code": "reputation-grant/target-not-found" }
    ```

    The target record does not exist — or, for a `chat-message` target, the sender is not an active member of that conversation. The two cases are byte-identical so a caller holding a message ID cannot probe whether it exists. Mediated transfers are membership-checked on the named sender exactly as user tokens are.
  </Accordion>

  <Accordion title="Insufficient Reputation — 409">
    ```json theme={null}
    { "error": "The sender does not have enough reputation in the source bucket.", "code": "reputation-grant/insufficient-reputation" }
    ```

    Nothing moves. Also the answer when the `spaceId` names a real space the sender holds no funded bucket in.
  </Accordion>

  <Accordion title="Conflict — 409">
    ```json theme={null}
    { "error": "The grant conflicted with a concurrent write. Retry.", "code": "reputation-grant/conflict" }
    ```

    Retryable. Two simultaneous transfers from the same bucket can never both succeed against the same balance.
  </Accordion>
</AccordionGroup>

**Rate limit:** 50 requests per 5 minutes per IP. Exceeding it returns `429` with a plain-text message and no `code`.

See also: [useCreateReputationGrant](/hooks/reputation/use-create-reputation-grant) · [node-sdk](/v7/node-sdk/reputation) · [js-sdk](/v7/js-sdk/reputation)


# Fetch Many Reputation Grants
Source: https://docs.sublay.io/v7/api-reference/reputation-grants/fetch-many-reputation-grants

GET /v7/:projectId/reputation-grants
List positive reputation grants by recipient, by sender, or by rewarded item

Returns a paginated list of reputation grants, newest first. Requires authentication (user token, service key, or master key) and the `reputation` bundle.

<Warning>
  **Only positive grants are ever returned — for every caller.** The `amount > 0` filter is baked into the query, so negative grants (your app's private moderation deductions) are unreachable here for a service or master key exactly as they are for a user token. Read them from [Fetch User Grant History](/api-reference/reputation-grants/fetch-user-grant-history) instead.
</Warning>

## One filter shape per request

Exactly one filter is required, and the three shapes are **mutually exclusive** — they are not AND-ed:

| Shape        | Parameters                | Answers                  |
| ------------ | ------------------------- | ------------------------ |
| By recipient | `recipientId`             | What this user received. |
| By sender    | `senderId`                | What this user sent.     |
| By target    | `targetType` + `targetId` | Who rewarded this item.  |

Grants pointing at a **chat message** are private to that conversation, which is what makes the choice of shape matter — see [Chat-message targets](#chat-message-targets-are-private) below.

Supplying none returns `400 reputation-grant/missing-filter`; supplying more than one returns `400 reputation-grant/invalid-filter`. Combining shapes is rejected rather than intersected, because a target list narrowed by sender would render rows that no longer reconcile with the `summary` printed above them.

## Query Parameters

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Defaults to `20`; the maximum is `100`. A larger value is rejected with `400 reputation-grant/invalid-query`, not silently clamped.
</ParamField>

<ParamField type="string">
  UUID. Grants credited to this user.
</ParamField>

<ParamField type="string">
  UUID. Grants sent by this user.
</ParamField>

<ParamField type="string">
  `"entity"`, `"comment"`, or `"chat-message"`. Supplied together with `targetId`.
</ParamField>

<ParamField type="string">
  UUID of the rewarded record. Supplied together with `targetType`.
</ParamField>

<ParamField type="string">
  Comma-separated associations to expand. Only `"user"` is supported — it hydrates **both** the sender and the recipient on every row.
</ParamField>

## Chat-message targets are private

A grant row carries `targetType`, `targetId` and the granter's free-text `note`, and `include=user` hydrates both parties. On a `chat-message` target those facts describe a private conversation — who is talking to whom, and what one of them said about it — so the grant is exactly as private as the message it points at. Both filter shapes ask the same question — *can this caller see the underlying message?* — and answer it the same way:

* **The target shape is gated on conversation membership.** `targetType=chat-message` returns rows only to a caller who is a **member** of the message's conversation. The membership test is the one [Fetch Message](/api-reference/chat/messages/fetch-message) applies: any membership row counts, so a user who has left the conversation still reads the grants on a message chat itself still returns to them. Everyone else gets `200` with an empty `data` array, `totalItems: 0`, and the zero summary `{ "total": 0, "count": 0, "viewerTotal": 0 }` — never a `403`, because an error would itself confirm the message exists. That covers a user who was never a member, and every user token on a project without the `chat` bundle, where there is no membership to have. The answer is byte-identical to the one a completely made-up message ID returns.
* **The `recipientId` and `senderId` shapes carry the same test into the query.** A chat-message-targeted grant stays in these feeds for a caller who can see the message, and is excluded from both the page and `totalItems` for one who cannot. The predicate rides the same `where` clause the `COUNT` uses, so a filtered page and a filtered total always move together and `hasMore` never asserts rows the caller may not read. A user's own "reputation I received / sent" feed therefore includes the grants made on messages in their own conversations, and reconciles with the reputation shown on their profile.
* **A message removed by moderation takes its grants with it.** A `removed` message is invisible on every chat surface, so both shapes hide its grants: the target shape answers the same empty page, and the user-keyed shapes drop the rows from the page and `totalItems`. That holds for a member of the conversation as much as for a stranger.

Service and master keys are exempt on both shapes: they pass the target-shape membership gate unconditionally, and the user-keyed shapes apply no membership predicate to them at all — so a backend can enumerate every grant it minted, removed messages included. They are the app's own backend, which has no membership and is already trusted to mint grants and to read every conversation. They hold no viewer identity, so `viewerTotal` is `0` for them while `total` and `count` are real.

Entity and comment targets are unaffected — those items are public, and both shapes return them normally. Grants with no target at all are returned by every shape.

<Note>
  The inline `grants` summary on the chat surfaces needs none of this. [List Messages](/api-reference/chat/messages/list-messages) and [Fetch Message](/api-reference/chat/messages/fetch-message) already refuse a non-member with `403 chat/not-a-member` before they read a message, so `include=grants` there is behind the conversation gate already.
</Note>

### Space-scoped reputation

Grants carry their own `spaceId`, so this is a **context** endpoint: `spaceReputation: { spaceId: "context" }` scores each hydrated user against *that grant's own* space. The same granter appearing on two grants in different spaces therefore gets two correct numbers rather than one overwriting the other. Requires the `reputation` bundle — which this endpoint already does.

<SpaceReputationParams />

## Response

Returns `200` with the standard paginated envelope:

```json theme={null}
{
  "data": [ /* ReputationGrant[] */ ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalPages": 3,
    "totalItems": 47,
    "hasMore": true
  }
}
```

On the **target** shape only, a `summary` block rides alongside the envelope, so a standalone "who rewarded this" view doesn't have to fetch the parent item just to learn the totals:

```json theme={null}
{
  "data": [ /* ... */ ],
  "pagination": { /* ... */ },
  "summary": { "total": 120, "count": 4, "viewerTotal": 20 }
}
```

`viewerTotal` is the calling user's own summed grants on the target, and is `0` for a service or master key, which has no viewer identity. The other two shapes return no `summary` key at all.

See [ReputationGrant](/data-models/reputation-grant) for the row shape and [GrantSummary](/data-models/reputation-grant#grantsummary) for the summary.

<Note>
  **Grant reads are never block-filtered.** Unlike entity and comment feeds, this endpoint has no `blockedFilter` and applies no block exclusion. Hiding a blocked granter's row while still counting their amount in the total would produce a "120 total, 70 shown" discrepancy no app can explain — so nothing is hidden, and the amounts you display always reconcile with the totals you display.
</Note>

## Error Responses

<AccordionGroup>
  <Accordion title="Missing Filter — 400">
    ```json theme={null}
    { "error": "One filter is required: recipientId, senderId, or targetType + targetId.", "code": "reputation-grant/missing-filter" }
    ```
  </Accordion>

  <Accordion title="Invalid Filter — 400">
    ```json theme={null}
    { "error": "Filters are mutually exclusive: supply recipientId, senderId, or targetType + targetId — not more than one.", "code": "reputation-grant/invalid-filter" }
    ```

    Also returned when only one half of `targetType` / `targetId` is supplied.
  </Accordion>

  <Accordion title="Invalid Query — 400">
    ```json theme={null}
    { "error": "limit: Too big: expected number to be <=100", "code": "reputation-grant/invalid-query" }
    ```

    Shape failures from the query schema: a `limit` above `100`, a non-positive `page`, a malformed UUID (`"recipientId: Invalid UUID format"`), or a `targetType` outside the three accepted values. The field path prefixes the message, so `error` reads `"<path>: <message>"`.
  </Accordion>

  <Accordion title="Tables Not Available — 403">
    ```json theme={null}
    {
      "code": "database/tables-not-available",
      "missingTables": ["ReputationBuckets", "ReputationGrants"],
      "dashboardUrl": "https://…/<projectId>/database"
    }
    ```

    The route names both of the `reputation` bundle's tables, so a project without the bundle is told about both.
  </Accordion>
</AccordionGroup>

**Rate limit:** 100 requests per 5 minutes per IP. Exceeding it returns `429` with a plain-text message and no `code`.

See also: [useFetchManyReputationGrants](/hooks/reputation/use-fetch-many-reputation-grants) · [useFetchManyReputationGrantsWrapper](/hooks/reputation/use-fetch-many-reputation-grants-wrapper) · [node-sdk](/v7/node-sdk/reputation) · [js-sdk](/v7/js-sdk/reputation)


# Fetch User Grant History
Source: https://docs.sublay.io/v7/api-reference/reputation-grants/fetch-user-grant-history

GET /dashboard/users/:userId/reputation-grants
A single user's full grant history, negative grants included — the only surface that exposes them

Returns one user's complete reputation-grant history, received and sent, **including negative grants**. This is the only route on which negatives are readable: the public [list endpoint](/api-reference/reputation-grants/fetch-many-reputation-grants) bakes `amount > 0` into its query for every caller, so a service key sees no more there than an ordinary user does.

This is a dashboard route, not a `/v7/:projectId` route — it powers the grant-history dialog on a user's detail view in the [dashboard](https://dash.sublay.io) — but it is callable with a service or master key, which is how a backend reads its own moderation deductions back.

The route cannot issue grants. It is read-only.

## Authentication and headers

<ParamField type="string">
  The project UUID. **Required when you authenticate with a service key** — that header is how the server finds the project whose key you are presenting, and without it a raw project key is parsed as a dashboard session token and rejected with `403`. Master keys and dashboard sessions only need the project named somewhere on the request, and may send it as a `?projectId=` query parameter instead; supplying both is fine as long as they match.
</ParamField>

<ParamField type="string">
  Set to `true` when authenticating with a **master key**. Master keys are only recognized on requests carrying this header.
</ParamField>

A service key is presented as the bearer credential alongside `x-sublay-project-id`. Dashboard sessions authenticate with their client JWT as usual, naming the project in the header or the query string.

Requires the `reputation` bundle.

## Path Parameters

<ParamField type="string">
  UUID of the user whose history to read.
</ParamField>

## Query Parameters

<ParamField type="string">
  `"received"` (grants credited to this user), `"sent"` (grants they issued), or `"all"` (either side). Defaults to `"all"`.
</ParamField>

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Defaults to `20`; the maximum is `100`. A larger value is rejected with `400 user/invalid-query`, not silently clamped.
</ParamField>

## Response

Returns `200` with the dashboard list shape. `grants` is always an array, never `undefined`, and is ordered newest first.

```json theme={null}
{
  "grants": [
    {
      "id": "…",
      "sourceType": "app",
      "senderId": null,
      "recipientId": "…",
      "amount": -50,
      "spaceId": null,
      "targetType": "comment",
      "targetId": "…",
      "note": "Clawback: duplicate payout",
      "metadata": null,
      "sender": null,
      "recipient": { "id": "…", "name": "…", "username": "…", "avatar": "…" },
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "totalCount": 1
}
```

Both counterparties are hydrated with a display-only projection — `id`, `name`, `username`, `avatar`. No sensitive user columns are returned. See [ReputationGrant](/data-models/reputation-grant) for the row shape.

## Error Responses

<AccordionGroup>
  <Accordion title="Invalid Params — 400">
    ```json theme={null}
    { "error": "userId: Invalid UUID format", "code": "user/invalid-params" }
    ```
  </Accordion>

  <Accordion title="Invalid Query — 400">
    ```json theme={null}
    { "error": "limit: Too big: expected number to be <=100", "code": "user/invalid-query" }
    ```

    A `limit` above `100`, a non-positive `page`, or a `direction` outside `received` / `sent` / `all`. The field path prefixes the message, so `error` reads `"<path>: <message>"`.
  </Accordion>

  <Accordion title="Tables Not Available — 403">
    ```json theme={null}
    {
      "code": "database/tables-not-available",
      "missingTables": ["ReputationGrants"],
      "dashboardUrl": "https://…/<projectId>/database"
    }
    ```
  </Accordion>
</AccordionGroup>

**Rate limit:** 25 requests per 5 minutes per IP. Exceeding it returns `429` with a plain-text message and no `code`.

See also: [ReputationGrant](/data-models/reputation-grant) · [Fetch Many Reputation Grants](/api-reference/reputation-grants/fetch-many-reputation-grants)


# Mint Reputation Grant
Source: https://docs.sublay.io/v7/api-reference/reputation-grants/mint-reputation-grant

POST /v7/:projectId/reputation-grants/mint
Create reputation from nothing — or destroy it — and credit a user's bucket

Mints reputation: it is created from nothing and credited to a user, with no sender and nothing debited. A mint is the app speaking, not a person — contest payouts, bounty settlements, staff picks, welcome bonuses.

A mint may also be **negative**, which is the only way to take reputation away: a moderation clawback, a decay sweep, or a correction to a mistaken grant. A negative mint may drive a bucket below zero (buckets have no floor).

**Service or master key only.** A user token never reaches this route. Blocks are ignored, suspension is not consulted (there is no acting user), and a `chat-message` target is not membership-checked — the app is trusted.

Requires the `reputation` bundle.

## Body Parameters

<ParamField type="string">
  UUID of the user credited — or, with a negative amount, debited.
</ParamField>

<ParamField type="number">
  Any **non-zero** whole number between `-2147483648` and `2147483647`. Negatives destroy reputation.
</ParamField>

<ParamField type="string | null">
  UUID of the space whose bucket is credited. Omitted or `null` means the project-general bucket. The space is validated before anything is written — a bucket for a space that does not exist would count toward its owner's profile total while being invisible in every space-scoped view. An ID that names no space is rejected with `404 reputation-grant/space-not-found`, and naming a space on a project without the `spaces` bundle is rejected with `403 database/tables-not-available`. [Transfers](/api-reference/reputation-grants/create-reputation-grant) are validated the same way.
</ParamField>

<ParamField type="string | null">
  Free-text note. Trimmed, up to 2000 characters.
</ParamField>

<ParamField type="object">
  Arbitrary key-value data. Up to 1 MB. Omit the key when unused — `null` is not accepted.
</ParamField>

<ParamField type="string">
  What the grant is for: `"entity"`, `"comment"`, or `"chat-message"`. Must be supplied together with `targetId`.
</ParamField>

<ParamField type="string">
  UUID of the rewarded record. Must be supplied together with `targetType`, and must exist at the time of granting.
</ParamField>

There is deliberately **no actor field**. The grant is written with a `null` `senderId` and `sourceType: "app"`.

## Response

Returns `201` with the created [ReputationGrant](/data-models/reputation-grant).

A **positive** mint notifies the recipient and, for a `chat-message` target, broadcasts [`message:grant`](/sdk/chat/real-time) to the conversation. A **negative** mint is entirely silent: no notification, no broadcast, and invisible on every public read surface. Read it back from [Fetch User Grant History](/api-reference/reputation-grants/fetch-user-grant-history).

## Error Responses

<AccordionGroup>
  <Accordion title="Invalid Body — 400">
    ```json theme={null}
    { "error": "amount: amount must be non-zero", "code": "reputation-grant/invalid-body" }
    ```

    Also returned for a fractional amount (`"amount: Invalid input: expected int, received number"`) or one outside the signed 32-bit range (`"amount: Too big: expected number to be <=2147483647"`). Field-level failures are prefixed with the field path, so `error` reads `"<path>: <message>"`. The one whole-body rule has no path and so no prefix: supplying `targetType` without `targetId` (or the reverse) returns `"targetType and targetId must be supplied together"`.
  </Accordion>

  <Accordion title="Elevated Auth Required — 403">
    ```json theme={null}
    { "error": "Service or master key required.", "code": "auth/elevated-auth-required" }
    ```
  </Accordion>

  <Accordion title="Tables Not Available — 403">
    ```json theme={null}
    {
      "code": "database/tables-not-available",
      "missingTables": ["Spaces"],
      "dashboardUrl": "https://…/<projectId>/database"
    }
    ```

    The `reputation` bundle is missing, a `spaceId` was supplied on a project without `spaces`, or the target's bundle is absent (e.g. a `chat-message` target without `chat`). `missingTables` names exactly what is absent.
  </Accordion>

  <Accordion title="User Not Found — 404">
    ```json theme={null}
    { "error": "The recipient of this grant does not exist.", "code": "reputation-grant/user-not-found" }
    ```

    Returned whether the recipient was already gone or was deleted while the mint was in flight — the two answers are byte-identical, and neither leaks the underlying constraint.
  </Accordion>

  <Accordion title="Space Not Found — 404">
    ```json theme={null}
    { "error": "The space this grant targets does not exist.", "code": "reputation-grant/space-not-found" }
    ```
  </Accordion>

  <Accordion title="Target Not Found — 404">
    ```json theme={null}
    { "error": "The grant target does not exist.", "code": "reputation-grant/target-not-found" }
    ```

    The target record does not exist. A mint is not membership-checked, so a `chat-message` target only has to exist.
  </Accordion>

  <Accordion title="Conflict — 409">
    ```json theme={null}
    { "error": "The grant conflicted with a concurrent write. Retry.", "code": "reputation-grant/conflict" }
    ```
  </Accordion>
</AccordionGroup>

**Rate limit:** 50 requests per 5 minutes per IP. Exceeding it returns `429` with a plain-text message and no `code`.

See also: [node-sdk `mintGrant`](/v7/node-sdk/reputation) · [Create Reputation Grant](/api-reference/reputation-grants/create-reputation-grant)


# Ask Content
Source: https://docs.sublay.io/v7/api-reference/search/ask

POST /v7/:projectId/search/ask
AI-powered Q&A grounded in your project's content

Answers a natural language question using content from your project as context. The endpoint first performs semantic retrieval to find relevant content, then sends the context to an LLM to generate a grounded answer. Responds via **Server-Sent Events (SSE)** for streaming output.

**Requires a paid plan with semantic search enabled.**

**Requires an authenticated user.** Send the user's access token as `Authorization: Bearer <token>`. Requests without a valid token are rejected before any work is done — missing token → `401`, invalid/expired token → `403` (refresh the access token and retry).

## Body Parameters

<ParamField type="string">
  The question to answer. Typos and ambiguous phrasing are handled gracefully.
</ParamField>

<ParamField type="string[]">
  Content types to use as context. Any combination of `entity`, `comment`, `message`.
</ParamField>

<ParamField type="string">
  Restrict the context lookup to a specific space.
</ParamField>

<ParamField type="boolean">
  Only applies with a `spaceId`. When `true`, the context lookup also includes every space nested under it — children, grandchildren, the whole subtree at any depth — not just the named space. Use it to ask across a community and all of its channels at once. Ignored without a `spaceId`.
</ParamField>

<ParamField type="string">
  Restrict message context lookup to a specific conversation.
</ParamField>

<ParamField type="number">
  Maximum number of content chunks to retrieve for context. Maximum `50`.
</ParamField>

## Query Parameters

### Space-scoped reputation

This endpoint has a space in context, so it accepts the opt-in reputation params. They add a `spaceReputation` field to each source record's populated `user`, alongside the always-present `reputation` total. Requires the `reputation` bundle. See the [Reputation data model](/data-models/reputation) for the full contract.

<SpaceReputationParams />

## Response

The response is a **Server-Sent Events** stream with `Content-Type: text/event-stream`. Three event types are emitted:

**`token`** — streamed LLM answer tokens:

```
event: token
data: {"content": "Based on"}

event: token
data: {"content": " the discussion..."}
```

**`sources`** — the content records used as context, sent after the answer is complete:

```
event: sources
data: [{"sourceType": "entity", "similarity": 0.87, "record": {...}}, ...]
```

Each source object follows the same shape as the [Search Content](/api-reference/search/search-content) response — `sourceType`, `similarity`, and a fully populated `record`. An empty array is sent when no relevant context was found.

**`done`** — signals the stream is finished:

```
event: done
data: {}
```

<Note>
  If no relevant content is found above the similarity threshold, the LLM response is skipped and the answer event immediately says "I couldn't find any relevant content to answer your question."
</Note>

## Error Responses

<AccordionGroup>
  <Accordion title="Authentication Required — 401 / 403">
    The endpoint requires an authenticated user. A missing token returns a bare `401`; an invalid or expired token returns a bare `403` — refresh the access token and retry. These are returned before streaming starts.
  </Accordion>

  <Accordion title="Plan Required — 403">
    ```json theme={null}
    { "error": "Semantic search requires a paid plan", "code": "project/plan-required" }
    ```

    Only returned when headers have not yet been sent (i.e., before streaming starts).
  </Accordion>

  <Accordion title="Error Event (during stream)">
    If an error occurs after streaming starts:

    ```
    event: error
    data: {"error": "Internal server error"}
    ```
  </Accordion>
</AccordionGroup>


# Search Spaces
Source: https://docs.sublay.io/v7/api-reference/search/search-spaces

POST /v7/:projectId/search/spaces
Semantic search over project spaces

Performs vector-similarity search over spaces in the project using AI embeddings. Returns the most semantically relevant spaces for the given query.

**Requires a paid plan with semantic search enabled.**

**Requires an authenticated user.** Send the user's access token as `Authorization: Bearer <token>` — missing token → `401`, invalid/expired token → `403` (refresh and retry).

<Note>
  Only `public` spaces are returned. Spaces with `visibility` of `"unlisted"` or `"private"` are never surfaced in search results for non-members. Hidden spaces stay indexed but filtered out, so re-listing a space (setting it back to `"public"`) makes it searchable again immediately with no rebuild. See [Space visibility](/data-models/space#visibility).
</Note>

## Body Parameters

<ParamField type="string">
  The natural language search query (e.g., a topic, name, or description).
</ParamField>

<ParamField type="number">
  Maximum number of spaces to return. Maximum `50`.
</ParamField>

## Response

Returns an array of result objects ordered by similarity:

```json theme={null}
[
  {
    "similarity": 0.89,
    "record": { ...Space object... }
  }
]
```

## Error Responses

<AccordionGroup>
  <Accordion title="Authentication Required — 401 / 403">
    The endpoint requires an authenticated user. A missing token returns a bare `401`; an invalid or expired token returns a bare `403` — refresh the access token and retry.
  </Accordion>

  <Accordion title="Plan Required — 403">
    ```json theme={null}
    { "error": "Semantic search requires a paid plan", "code": "project/plan-required" }
    ```
  </Accordion>
</AccordionGroup>


# Search Users
Source: https://docs.sublay.io/v7/api-reference/search/search-users

POST /v7/:projectId/search/users
Semantic search over project users

Performs vector-similarity search over user profiles in the project using AI embeddings. Returns the most semantically relevant user profiles for the given query.

**Requires a paid plan with semantic search enabled.**

**Requires an authenticated user.** Send the user's access token as `Authorization: Bearer <token>` — missing token → `401`, invalid/expired token → `403` (refresh and retry).

## Body Parameters

<ParamField type="string">
  The natural language search query (e.g., a name, username, bio text, or description).
</ParamField>

<ParamField type="number">
  Maximum number of users to return. Maximum `50`.
</ParamField>

## Response

Returns an array of result objects ordered by similarity:

```json theme={null}
[
  {
    "similarity": 0.91,
    "record": { ...User object... }
  }
]
```

## Error Responses

<AccordionGroup>
  <Accordion title="Authentication Required — 401 / 403">
    The endpoint requires an authenticated user. A missing token returns a bare `401`; an invalid or expired token returns a bare `403` — refresh the access token and retry.
  </Accordion>

  <Accordion title="Plan Required — 403">
    ```json theme={null}
    { "error": "Semantic search requires a paid plan", "code": "project/plan-required" }
    ```
  </Accordion>
</AccordionGroup>


# Get Space Conversation
Source: https://docs.sublay.io/v7/api-reference/spaces/chat/get-space-conversation

GET /v7/:projectId/spaces/:spaceId/conversation
Get or create the chat conversation for a space

Returns the chat conversation associated with a space. If no conversation exists yet, one is created automatically. Requires authentication. The caller must have a space membership record that is not `"banned"` (pending members are allowed).

## Path Parameters

<ParamField type="string">
  UUID of the space.
</ParamField>

## Response

Returns a [Conversation](/data-models/conversation) object with two additional fields:

<ResponseField name="currentMember" type="object | null">
  The caller's `ConversationMember` record for this conversation. Created or re-activated on first call.
</ResponseField>

<ResponseField name="memberCount" type="number">
  Number of currently active members in the conversation.
</ResponseField>

<Note>Each space has at most one associated conversation. This endpoint is idempotent — calling it multiple times returns the same conversation.</Note>

## Error Responses

<AccordionGroup>
  <Accordion title="Not a Member — 403">
    ```json theme={null}
    { "error": "You are not a member of this space.", "code": "chat/not-a-member" }
    ```
  </Accordion>

  <Accordion title="Banned — 403">
    ```json theme={null}
    { "error": "You are banned from this space.", "code": "chat/banned" }
    ```
  </Accordion>
</AccordionGroup>

See also: [useFetchSpaceConversation hook](/hooks/chat/conversations/use-fetch-space-conversation)


# Check Slug Availability
Source: https://docs.sublay.io/v7/api-reference/spaces/check-slug

GET /v7/:projectId/spaces/check-slug
Check whether a space slug is available in the project

Checks if a slug is available for use in the current project. Useful for real-time validation in space creation forms.

## Query Parameters

<ParamField type="string">
  The slug to check. Must match the slug pattern (letters, numbers, hyphens, underscores).
</ParamField>

## Response

<ResponseField name="available" type="boolean">
  `true` if the slug is not in use.
</ResponseField>

See also: [useCheckSlugAvailability](/hooks/spaces/use-check-slug-availability)


# Create Space
Source: https://docs.sublay.io/v7/api-reference/spaces/create-space

POST /v7/:projectId/spaces
Create a new community space

Creates a new space. The authenticated user is automatically added as an admin. Supports optional avatar and banner image upload via multipart form data.

## Body Parameters

<ParamField type="string">
  Display name for the space. Must be 3–100 characters.
</ParamField>

<ParamField type="string">
  Optional URL slug. Must be unique per project. Supports Unicode letters, numbers, hyphens, and underscores.
</ParamField>

<ParamField type="string">
  Optional description. Up to 1,000 characters.
</ParamField>

<ParamField type="string">
  Who can read content: `"anyone"` or `"members"`. Defaults to `"anyone"`.
</ParamField>

<ParamField type="string">
  Who can post entities: `"anyone"`, `"members"`, or `"admins"`. Defaults to `"members"`.
</ParamField>

<ParamField type="string">
  Whether the space is listed and discoverable: `"public"`, `"unlisted"`, or `"private"`. Defaults to `"public"`. Governs discoverability only — independent of `readingPermission`, which governs content. `"unlisted"` hides the space from discovery and search but keeps it reachable by direct link; `"private"` currently behaves like `"unlisted"`. See [Space visibility](/data-models/space#visibility).
</ParamField>

<ParamField type="boolean">
  Whether new joins require approval. Defaults to `true`.
</ParamField>

<ParamField type="object">
  Optional arbitrary key-value data. Up to 1 MB.
</ParamField>

<ParamField type="string">
  Optional UUID of a parent space. The caller must be an admin of the parent space.
</ParamField>

<ParamField type="file">
  Optional avatar image. Multipart form field. Requires `avatarFile.options` when provided.
</ParamField>

<ParamField type="file">
  Optional banner image. Multipart form field. Requires `bannerFile.options` when provided.
</ParamField>

## Response

Returns the created [Space](/data-models/space) object with `membersCount`, `childSpacesCount`, and optional file associations.

## Error Responses

<AccordionGroup>
  <Accordion title="Auth Required — 401">
    ```json theme={null}
    { "error": "Authentication required to create a space.", "code": "space/auth-required" }
    ```
  </Accordion>

  <Accordion title="Slug Taken — 409">
    ```json theme={null}
    { "error": "A space with this slug already exists.", "code": "space/slug-taken" }
    ```
  </Accordion>

  <Accordion title="Parent Not Found — 404">
    ```json theme={null}
    { "error": "Parent space not found.", "code": "space/parent-not-found" }
    ```
  </Accordion>

  <Accordion title="Parent Admin Required — 403">
    ```json theme={null}
    { "error": "Only admins of the parent space can create child spaces.", "code": "space/parent-admin-required" }
    ```
  </Accordion>

  <Accordion title="Max Depth Exceeded — 400">
    ```json theme={null}
    { "error": "Maximum nesting depth (10) exceeded.", "code": "space/max-depth-exceeded" }
    ```
  </Accordion>

  <Accordion title="File Too Large — 413">
    ```json theme={null}
    { "code": "space/file-too-large", "message": "Avatar image exceeds 50MB limit." }
    ```
  </Accordion>
</AccordionGroup>

See also: [useCreateSpace](/hooks/spaces/use-create-space)


# Delete Space
Source: https://docs.sublay.io/v7/api-reference/spaces/delete-space

DELETE /v7/:projectId/spaces/:spaceId
Delete a space and all its associated data

Permanently deletes a space. All entities, members, child spaces, rules, and reports belonging to the space are also deleted. Only the space's **creator** (the original owner) can perform this action.

<Warning>This operation is irreversible. All associated data including child spaces will be permanently deleted.</Warning>

## Path Parameters

<ParamField type="string">
  UUID of the space to delete.
</ParamField>

## Response

<ResponseField name="message" type="string">
  Confirmation message: `"Space deleted successfully."`
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Space not found.", "code": "space/not-found" }
    ```
  </Accordion>

  <Accordion title="Deletion Disabled — 403">
    ```json theme={null}
    { "error": "Space deletion is disabled for this project.", "code": "space/deletion-disabled" }
    ```
  </Accordion>

  <Accordion title="Creator Required — 403">
    ```json theme={null}
    { "error": "Only the space creator can delete the space.", "code": "space/creator-required" }
    ```
  </Accordion>
</AccordionGroup>

See also: [useDeleteSpace](/hooks/spaces/use-delete-space)


# Fetch Space Breadcrumb
Source: https://docs.sublay.io/v7/api-reference/spaces/fetch-breadcrumb

GET /v7/:projectId/spaces/:spaceId/breadcrumb
Get the ancestor chain of a space for breadcrumb navigation

Returns an ordered list of spaces from the root ancestor down to and including the specified space itself, suitable for breadcrumb navigation.

## Path Parameters

<ParamField type="string">
  UUID of the space whose ancestors to fetch.
</ParamField>

## Response

<ResponseField name="breadcrumb" type="SpacePreview[]">
  Ordered array of ancestor [SpacePreview](/data-models/space) objects from the root down to the space itself. For a root-level space this array contains only that space. Each item includes: `id`, `shortId`, `name`, `slug`, `avatarFileId`, `parentSpaceId`, `depth`.
</ResponseField>

<ResponseField name="depth" type="number">
  Nesting depth of the requested space. `0` for root-level spaces.
</ResponseField>

See also: [useFetchSpaceBreadcrumb](/hooks/spaces/use-fetch-space-breadcrumb)


# Fetch Space Children
Source: https://docs.sublay.io/v7/api-reference/spaces/fetch-children

GET /v7/:projectId/spaces/:spaceId/children
Get the direct child spaces of a parent space

Returns a paginated list of child spaces for a given parent space. Authentication is optional — when provided, each child carries an `isMember` flag for the authenticated user.

Only children with `visibility: "public"` are listed, for every caller. Unlike [Fetch Spaces](/api-reference/spaces/fetch-spaces), authenticating does not surface unlisted or private children the caller belongs to.

## Path Parameters

<ParamField type="string">
  UUID of the parent space.
</ParamField>

## Query Parameters

<ParamField type="number">
  Page number. Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page.
</ParamField>

## Response

<ResponseField name="data" type="Space[]">
  Array of child [Space](/data-models/space) objects.
</ResponseField>

<ResponseField name="pagination" type="object">
  Standard pagination metadata.
</ResponseField>

See also: [useFetchSpaceChildren](/hooks/spaces/use-fetch-space-children)


# Fetch Mutual Spaces
Source: https://docs.sublay.io/v7/api-reference/spaces/fetch-mutual-spaces

GET /v7/:projectId/spaces/mutual/:userId
Get spaces shared between the authenticated user and another user

Returns a paginated list of spaces that both the authenticated user and another user are active members of — i.e. their spaces in common. Requires an authenticated user.

## Path Parameters

<ParamField type="string">
  The other user's Sublay ID. Mutual spaces are computed between this user and the authenticated user.
</ParamField>

## Query Parameters

<ParamField type="string">
  The authenticated user to act as. Only accepted with a **service or master key** — a user token always acts as itself and may not name a different user. Ignored (the token's user is used) for end-user requests.
</ParamField>

<ParamField type="number">
  Page number. Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Max `100`. Defaults to `20`.
</ParamField>

<ParamField type="string">
  Optional comma-separated includes. Pass `"files"` to include avatar and banner file objects on each space.
</ParamField>

## Response

<ResponseField name="data" type="Space[]">
  The spaces both users are active members of. Computed fields such as `membersCount` and `isMember` are populated from the authenticated user's perspective.
</ResponseField>

<ResponseField name="pagination" type="object">
  Standard pagination metadata (`page`, `pageSize`, `totalPages`, `totalItems`, `hasMore`).
</ResponseField>

See also: [useFetchMutualSpaces](/hooks/spaces/use-fetch-mutual-spaces)


# Fetch Space
Source: https://docs.sublay.io/v7/api-reference/spaces/fetch-space

GET /v7/:projectId/spaces/:spaceId
Get a single space by its UUID

Fetches a space by UUID. Returns full space details including membership permissions for the authenticated user, parent space, and child space previews.

## Path Parameters

<ParamField type="string">
  UUID of the space.
</ParamField>

## Query Parameters

<ParamField type="string">
  Optional. Pass `"files"` to include avatar and banner file objects.
</ParamField>

## Response

Returns a [SpaceDetailed](/data-models/space) object including `memberPermissions`, `parentSpace`, and `childSpaces`.

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Space not found.", "code": "space/not-found" }
    ```
  </Accordion>
</AccordionGroup>

See also: [useFetchSpace](/hooks/spaces/use-fetch-space)


# Fetch Space by Short ID
Source: https://docs.sublay.io/v7/api-reference/spaces/fetch-space-by-short-id

GET /v7/:projectId/spaces/by-short-id
Get a single space by its short identifier

Fetches a space using its `shortId`. Returns the same `SpaceDetailed` shape as the UUID fetch endpoint.

## Query Parameters

<ParamField type="string">
  The short identifier of the space.
</ParamField>

<ParamField type="string">
  Optional. Pass `"files"` to include file objects.
</ParamField>

## Response

Returns a [SpaceDetailed](/data-models/space) object.

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Space not found.", "code": "space/not-found" }
    ```
  </Accordion>
</AccordionGroup>

See also: [useFetchSpaceByShortId](/hooks/spaces/use-fetch-space-by-short-id)


# Fetch Space by Slug
Source: https://docs.sublay.io/v7/api-reference/spaces/fetch-space-by-slug

GET /v7/:projectId/spaces/by-slug
Get a single space by its URL slug

Fetches a space using its `slug`. Slugs are optional and unique per project.

## Query Parameters

<ParamField type="string">
  The URL slug of the space.
</ParamField>

<ParamField type="string">
  Optional. Pass `"files"` to include file objects.
</ParamField>

## Response

Returns a [SpaceDetailed](/data-models/space) object.

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Space not found.", "code": "space/not-found" }
    ```
  </Accordion>
</AccordionGroup>

See also: [useFetchSpaceBySlug](/hooks/spaces/use-fetch-space-by-slug)


# Fetch Spaces
Source: https://docs.sublay.io/v7/api-reference/spaces/fetch-spaces

GET /v7/:projectId/spaces
Get a paginated list of spaces with filtering and sorting

Fetches a paginated list of spaces. Supports filtering by search query, membership, and parent space. Authentication is optional — if provided, member-only spaces the user belongs to are included.

<Note>
  This is a discovery surface: only `public` spaces are listed. Spaces with `visibility` of `"unlisted"` or `"private"` are excluded for non-members (they remain reachable by direct link/slug via [Fetch Space by Slug](/api-reference/spaces/fetch-space-by-slug) or [by Short ID](/api-reference/spaces/fetch-space-by-short-id)). The exception is `memberOf=true`, which returns the caller's own spaces regardless of visibility. See [Space visibility](/data-models/space#visibility).
</Note>

## Query Parameters

<ParamField type="number">
  Page number. Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page.
</ParamField>

<ParamField type="string">
  Sort order: `"alphabetical"`, `"newest"`, or `"members"`. Defaults to `"members"`.
</ParamField>

<ParamField type="string">
  Filter by slug substring.
</ParamField>

<ParamField type="string">
  Filter by name substring.
</ParamField>

<ParamField type="string">
  Filter by description substring.
</ParamField>

<ParamField type="string">
  Search across name, slug, and description simultaneously.
</ParamField>

<ParamField type="boolean">
  When `true`, returns only spaces where the authenticated user is an active member.
</ParamField>

<ParamField type="string">
  Filter to child spaces of a specific parent. Pass `"null"` for root-level spaces only.
</ParamField>

<ParamField type="string">
  Optional comma-separated includes. Pass `"files"` to include avatar file objects.
</ParamField>

## Response

<ResponseField name="data" type="Space[]">
  Array of [Space](/data-models/space) objects.
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="properties">
    <ResponseField name="page" type="number">Current page.</ResponseField>
    <ResponseField name="pageSize" type="number">Results per page.</ResponseField>
    <ResponseField name="totalPages" type="number">Total number of pages.</ResponseField>
    <ResponseField name="totalItems" type="number">Total matching spaces.</ResponseField>
    <ResponseField name="hasMore" type="boolean">Whether more pages exist.</ResponseField>
  </Expandable>
</ResponseField>

See also: [useFetchManySpaces](/hooks/spaces/use-fetch-many-spaces)


# Fetch User Spaces
Source: https://docs.sublay.io/v7/api-reference/spaces/fetch-user-spaces

GET /v7/:projectId/spaces/user-spaces
Get spaces the authenticated user is a member of

Returns a paginated list of spaces the authenticated user has a membership in, along with their membership details for each space. By default only active memberships are returned; use `status` to list pending join requests or spaces the user was banned from.

## Query Parameters

<ParamField type="string">
  Membership status to list: `"active"` (default), `"pending"`, or `"banned"`.

  `"pending"` surfaces join requests still awaiting admin approval — useful for a "waiting to join" screen on spaces that have `requireJoinApproval` enabled.
</ParamField>

<ParamField type="number">
  Page number. Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Max `100`.
</ParamField>

<ParamField type="string">
  Filter by role. Single value (`"admin"`, `"moderator"`, `"member"`) or comma-separated list (e.g. `"admin,moderator"`).
</ParamField>

<ParamField type="string">
  Optional comma-separated includes. Pass `"files"` to include avatar and banner file objects on each space.
</ParamField>

<ParamField type="string">
  Pass `"true"` to return all memberships without pagination. When used, the response omits the `pagination` field.
</ParamField>

## Response

<ResponseField name="data" type="UserSpaceItem[]">
  Each item contains a `space` and a `membership` object.

  <Expandable title="membership properties">
    <ResponseField name="membershipId" type="string">Membership record UUID.</ResponseField>
    <ResponseField name="role" type="string">`"admin"`, `"moderator"`, or `"member"`.</ResponseField>
    <ResponseField name="status" type="string">`"active"`, `"pending"`, or `"banned"` — matches the requested `status` filter.</ResponseField>
    <ResponseField name="joinedAt" type="Date">When the membership was created.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  Standard pagination metadata.
</ResponseField>

See also: [useFetchUserSpaces](/hooks/spaces/use-fetch-user-spaces)


# Approve Member
Source: https://docs.sublay.io/v7/api-reference/spaces/membership/approve-member

PATCH /v7/:projectId/spaces/:spaceId/members/:memberId/approve
Approve a pending membership request

Sets a pending member's status to `"active"`. Requires the caller to be a moderator or admin.

## Path Parameters

<ParamField type="string">
  UUID of the space.
</ParamField>

<ParamField type="string">
  UUID of the membership record to approve.
</ParamField>

## Response

<ResponseField name="message" type="string">
  Confirmation message.
</ResponseField>

<ResponseField name="membership" type="object">
  Updated membership with `id`, `status: "active"`, and `joinedAt`.
</ResponseField>

See also: [useApproveMember](/hooks/spaces/use-approve-member)


# Ban Member
Source: https://docs.sublay.io/v7/api-reference/spaces/membership/ban-member

PATCH /v7/:projectId/spaces/:spaceId/members/:memberId/ban
Ban a member from a space

Sets a member's status to `"banned"`. Requires the caller to be a moderator or admin. Moderators can only ban regular members. Only the **space creator** can ban admins, and the last admin cannot be banned.

## Path Parameters

<ParamField type="string">
  UUID of the space.
</ParamField>

<ParamField type="string">
  UUID of the membership record to ban.
</ParamField>

## Response

<ResponseField name="message" type="string">
  Confirmation message.
</ResponseField>

<ResponseField name="membership" type="object">
  The updated membership record with `status: "banned"`.
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="Membership Not Found — 404">
    ```json theme={null}
    { "error": "Membership not found.", "code": "space/membership-not-found" }
    ```
  </Accordion>

  <Accordion title="Insufficient Permissions — 403">
    Moderators attempting to ban another moderator or admin.

    ```json theme={null}
    { "error": "Moderators can only ban regular members.", "code": "space/insufficient-permissions" }
    ```
  </Accordion>

  <Accordion title="Creator Required — 403">
    Non-creator attempting to ban an admin.

    ```json theme={null}
    { "error": "Only the space creator can ban admins.", "code": "space/creator-required" }
    ```
  </Accordion>

  <Accordion title="Last Admin — 400">
    ```json theme={null}
    { "error": "Cannot ban the last admin. Promote another member to admin first.", "code": "space/last-admin" }
    ```
  </Accordion>
</AccordionGroup>

See also: [useBanMember](/hooks/spaces/use-ban-member), [Unban Member](/api-reference/spaces/membership/unban-member)


# Check My Membership
Source: https://docs.sublay.io/v7/api-reference/spaces/membership/check-my-membership

GET /v7/:projectId/spaces/:spaceId/membership/me
Get the current user's membership status and permissions in a space

Returns the authenticated user's membership status and resolved permissions in a space. Returns membership info even for `pending` or `banned` states.

## Path Parameters

<ParamField type="string">
  UUID of the space.
</ParamField>

## Response

<ResponseField name="isMember" type="boolean">
  Whether the user has an active membership.
</ResponseField>

<ResponseField name="role" type="string | null">
  `"admin"`, `"moderator"`, `"member"`, or `null` if not a member.
</ResponseField>

<ResponseField name="status" type="string | null">
  `"pending"`, `"active"`, `"banned"`, `"rejected"`, or `null` if no membership record exists.
</ResponseField>

<ResponseField name="joinedAt" type="Date | null">
  When the membership was created. `null` if not a member.
</ResponseField>

<ResponseField name="permissions" type="object">
  <Expandable title="properties">
    <ResponseField name="canPost" type="boolean">Whether the user can post.</ResponseField>
    <ResponseField name="canModerate" type="boolean">Whether the user can moderate.</ResponseField>
    <ResponseField name="canRead" type="boolean">Whether the user can read content.</ResponseField>
    <ResponseField name="isAdmin" type="boolean">Whether the user is an admin.</ResponseField>
    <ResponseField name="isModerator" type="boolean">Whether the user is a moderator.</ResponseField>
  </Expandable>
</ResponseField>

See also: [useCheckMyMembership](/hooks/spaces/use-check-my-membership)


# Decline Member
Source: https://docs.sublay.io/v7/api-reference/spaces/membership/decline-member

PATCH /v7/:projectId/spaces/:spaceId/members/:memberId/decline
Decline a pending membership request

Sets a pending member's status to `"rejected"`. Requires the caller to be a moderator or admin.

## Path Parameters

<ParamField type="string">
  UUID of the space.
</ParamField>

<ParamField type="string">
  UUID of the membership record to decline.
</ParamField>

## Response

<ResponseField name="message" type="string">
  Confirmation message.
</ResponseField>

<ResponseField name="membership" type="object">
  Updated membership with `id` and `status: "rejected"`.
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Membership not found.", "code": "space/membership-not-found" }
    ```
  </Accordion>

  <Accordion title="Not Pending — 400">
    ```json theme={null}
    { "error": "Membership is already active.", "code": "space/not-pending" }
    ```
  </Accordion>
</AccordionGroup>

See also: [useDeclineMember](/hooks/spaces/use-decline-member)


# Join Space
Source: https://docs.sublay.io/v7/api-reference/spaces/membership/join-space

POST /v7/:projectId/spaces/:spaceId/join
Join a space or submit a membership request

Joins a space. If the space has `requireJoinApproval: true`, the membership is created with `status: "pending"` until approved. Otherwise it is immediately `active`.

## Path Parameters

<ParamField type="string">
  UUID of the space to join.
</ParamField>

## Response

<ResponseField name="message" type="string">
  Confirmation message.
</ResponseField>

<ResponseField name="membership" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="string">Membership record UUID.</ResponseField>
    <ResponseField name="spaceId" type="string">Space UUID.</ResponseField>
    <ResponseField name="userId" type="string">User UUID.</ResponseField>
    <ResponseField name="role" type="string">`"member"`</ResponseField>
    <ResponseField name="status" type="string">`"pending"` or `"active"`</ResponseField>
    <ResponseField name="joinedAt" type="Date">Creation timestamp.</ResponseField>
  </Expandable>
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="Space Not Found — 404">
    ```json theme={null}
    { "error": "Space not found.", "code": "space/not-found" }
    ```
  </Accordion>

  <Accordion title="Banned — 403">
    ```json theme={null}
    { "error": "You are banned from this space.", "code": "space/banned" }
    ```
  </Accordion>

  <Accordion title="Already a Member — 409">
    ```json theme={null}
    { "error": "You are already a member of this space.", "code": "space/already-member" }
    ```
  </Accordion>
</AccordionGroup>

See also: [useJoinSpace](/hooks/spaces/use-join-space)


# Leave Space
Source: https://docs.sublay.io/v7/api-reference/spaces/membership/leave-space

DELETE /v7/:projectId/spaces/:spaceId/leave
Leave a space

Removes the authenticated user's membership from a space.

## Path Parameters

<ParamField type="string">
  UUID of the space to leave.
</ParamField>

## Response

<ResponseField name="message" type="string">
  Confirmation message.
</ResponseField>

See also: [useLeaveSpace](/hooks/spaces/use-leave-space)


# List Space Members
Source: https://docs.sublay.io/v7/api-reference/spaces/membership/list-members

GET /v7/:projectId/spaces/:spaceId/members
Get a paginated list of members in a space

Returns a paginated list of space members with embedded user details.

## Path Parameters

<ParamField type="string">
  UUID of the space.
</ParamField>

## Query Parameters

<ParamField type="number">
  Page number. Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page.
</ParamField>

<ParamField type="string">
  Filter by status: `"pending"`, `"active"`, `"banned"`, or `"rejected"`.
</ParamField>

<ParamField type="string">
  Filter by role: `"admin"`, `"moderator"`, or `"member"`.
</ParamField>

### Space-scoped reputation

This endpoint has a space in context, so it accepts the opt-in reputation params. They add a `spaceReputation` field to each returned member's `user`, alongside the always-present `reputation` total. Requires the `reputation` bundle. See the [Reputation data model](/data-models/reputation) for the full contract.

<SpaceReputationParams />

## Response

<ResponseField name="data" type="SpaceMemberWithUser[]">
  Array of [SpaceMemberWithUser](/data-models/space-member) objects.
</ResponseField>

<ResponseField name="pagination" type="object">
  Standard pagination metadata.
</ResponseField>

See also: [useFetchSpaceMembers](/hooks/spaces/use-fetch-space-members)


# List Space Team
Source: https://docs.sublay.io/v7/api-reference/spaces/membership/list-team

GET /v7/:projectId/spaces/:spaceId/team
Get all admins and moderators of a space

Returns all admins and moderators of a space in a single non-paginated response.

## Path Parameters

<ParamField type="string">
  UUID of the space.
</ParamField>

## Query Parameters

### Space-scoped reputation

This endpoint has a space in context, so it accepts the opt-in reputation params. They add a `spaceReputation` field to each returned member's `user`, alongside the always-present `reputation` total. Requires the `reputation` bundle. See the [Reputation data model](/data-models/reputation) for the full contract.

<SpaceReputationParams />

## Response

<ResponseField name="data" type="SpaceMemberWithUser[]">
  Array of [SpaceMemberWithUser](/data-models/space-member) objects with `role` of `"admin"` or `"moderator"` and `status` of `"active"`.
</ResponseField>

See also: [useFetchSpaceTeam](/hooks/spaces/use-fetch-space-team)


# Unban Member
Source: https://docs.sublay.io/v7/api-reference/spaces/membership/unban-member

PATCH /v7/:projectId/spaces/:spaceId/members/:memberId/unban
Unban a previously banned member

Sets a banned member's status back to `"active"`. Requires the caller to be a moderator or admin. Moderators can only unban regular members, not other moderators or admins.

## Path Parameters

<ParamField type="string">
  UUID of the space.
</ParamField>

<ParamField type="string">
  UUID of the membership record to unban.
</ParamField>

## Response

<ResponseField name="message" type="string">
  Confirmation message.
</ResponseField>

<ResponseField name="membership" type="object">
  The updated membership record with `status: "active"`.
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Banned membership not found.", "code": "space/membership-not-found" }
    ```
  </Accordion>

  <Accordion title="Insufficient Permissions — 403">
    Moderators attempting to unban another moderator or admin.

    ```json theme={null}
    { "error": "Moderators can only unban regular members.", "code": "space/insufficient-permissions" }
    ```
  </Accordion>
</AccordionGroup>

See also: [useUnbanMember](/hooks/spaces/use-unban-member)


# Update Member Role
Source: https://docs.sublay.io/v7/api-reference/spaces/membership/update-member-role

PATCH /v7/:projectId/spaces/:spaceId/members/:memberId/role
Update a member's role within a space

Changes a member's role. Only space admins can perform this action.

## Path Parameters

<ParamField type="string">
  UUID of the space.
</ParamField>

<ParamField type="string">
  UUID of the membership record to update.
</ParamField>

## Body Parameters

<ParamField type="string">
  New role: `"admin"`, `"moderator"`, or `"member"`.
</ParamField>

## Response

<ResponseField name="message" type="string">
  Confirmation message.
</ResponseField>

<ResponseField name="membership" type="object">
  Updated membership with `id`, `role`, `status`, `joinedAt`, and `userId`.
</ResponseField>

See also: [useUpdateMemberRole](/hooks/spaces/use-update-member-role)


# Handle Comment Report
Source: https://docs.sublay.io/v7/api-reference/spaces/moderation/handle-comment-report

PATCH /v7/:projectId/spaces/:spaceId/reports/comment/:reportId
Resolve a reported comment within a space

Resolves a filed report against a comment in a space. Requires the caller to be a moderator or admin of that space.

## Path Parameters

<ParamField type="string">
  UUID of the space.
</ParamField>

<ParamField type="string">
  UUID of the comment report to resolve.
</ParamField>

## Body Parameters

<ParamField type="string">
  UUID of the reported comment. Used when performing `remove-comment`.
</ParamField>

<ParamField type="string[]">
  One or more actions to take. Must contain at least one value. Available actions:

  * `"remove-comment"` — marks the comment as removed via moderation
  * `"ban-user"` — bans the target user from the space (requires `userId` and `reason`)
  * `"dismiss"` — dismisses the report without action (requires `summary`; cannot be combined with other actions)
</ParamField>

<ParamField type="string">
  Summary of the action taken. Required when using `dismiss` or any non-dismiss action.
</ParamField>

<ParamField type="string">
  UUID of the user to ban. Required when `ban-user` is included in `actions`.
</ParamField>

<ParamField type="string">
  Reason for the ban. Required when `ban-user` is included in `actions`.
</ParamField>

## Response

Returns `201 Created`:

```json theme={null}
{ "message": "Report handled successfully", "code": "report/handled" }
```

## Error Responses

<AccordionGroup>
  <Accordion title="Report Not Found — 404">
    ```json theme={null}
    { "error": "Report not found", "code": "report/not-found" }
    ```
  </Accordion>

  <Accordion title="Report Not in Space — 404">
    ```json theme={null}
    { "error": "Report does not belong to this space", "code": "report/not-found-in-space" }
    ```
  </Accordion>

  <Accordion title="Comment Not Found — 404">
    ```json theme={null}
    { "error": "Comment not found", "code": "report/comment-not-found" }
    ```
  </Accordion>

  <Accordion title="Comment Not in Space — 404">
    ```json theme={null}
    { "error": "Comment does not belong to this space", "code": "report/comment-not-in-space" }
    ```
  </Accordion>

  <Accordion title="User Not Found — 404">
    ```json theme={null}
    { "error": "User not found in this project", "code": "report/user-not-found" }
    ```
  </Accordion>

  <Accordion title="User Not a Member — 404">
    ```json theme={null}
    { "error": "User is not a member of this space", "code": "space/member-not-found" }
    ```
  </Accordion>

  <Accordion title="Invalid Action Combination — 400">
    ```json theme={null}
    { "error": "Cannot combine 'dismiss' with other actions", "code": "report/invalid-actions" }
    ```
  </Accordion>

  <Accordion title="Missing Required Fields — 400">
    ```json theme={null}
    { "error": "Summary is required for dismissing a report", "code": "report/missing-fields" }
    ```

    Also returned when `ban-user` is used without `userId` or `reason`:

    ```json theme={null}
    { "error": "userId and reason are required for banning a user", "code": "report/missing-fields" }
    ```
  </Accordion>
</AccordionGroup>


# Handle Entity Report
Source: https://docs.sublay.io/v7/api-reference/spaces/moderation/handle-entity-report

PATCH /v7/:projectId/spaces/:spaceId/reports/entity/:reportId
Resolve an entity report within a space

Resolves a filed report against an entity in a space. Requires the caller to be a moderator or admin of that space.

## Path Parameters

<ParamField type="string">
  UUID of the space.
</ParamField>

<ParamField type="string">
  UUID of the entity report to resolve.
</ParamField>

## Body Parameters

<ParamField type="string">
  UUID of the reported entity. Used when performing `remove-entity`.
</ParamField>

<ParamField type="string[]">
  One or more actions to take. Must contain at least one value. Available actions:

  * `"remove-entity"` — marks the entity as removed via moderation
  * `"ban-user"` — bans the target user from the space (requires `userId` and `reason`)
  * `"dismiss"` — dismisses the report without action (requires `summary`; cannot be combined with other actions)
</ParamField>

<ParamField type="string">
  Summary of the action taken. Required when using `dismiss` or any non-dismiss action.
</ParamField>

<ParamField type="string">
  UUID of the user to ban. Required when `ban-user` is included in `actions`.
</ParamField>

<ParamField type="string">
  Reason for the ban. Required when `ban-user` is included in `actions`.
</ParamField>

## Response

Returns `201 Created`:

```json theme={null}
{ "message": "Report handled successfully", "code": "report/handled" }
```

## Error Responses

<AccordionGroup>
  <Accordion title="Report Not Found — 404">
    ```json theme={null}
    { "error": "Report not found", "code": "report/not-found" }
    ```
  </Accordion>

  <Accordion title="Report Not in Space — 404">
    ```json theme={null}
    { "error": "Report does not belong to this space", "code": "report/not-found-in-space" }
    ```
  </Accordion>

  <Accordion title="Entity Not Found — 404">
    ```json theme={null}
    { "error": "Entity not found", "code": "report/entity-not-found" }
    ```
  </Accordion>

  <Accordion title="Entity Not in Space — 404">
    ```json theme={null}
    { "error": "Entity does not belong to this space", "code": "report/entity-not-in-space" }
    ```
  </Accordion>

  <Accordion title="User Not Found — 404">
    ```json theme={null}
    { "error": "User not found in this project", "code": "report/user-not-found" }
    ```
  </Accordion>

  <Accordion title="User Not a Member — 404">
    ```json theme={null}
    { "error": "User is not a member of this space", "code": "space/member-not-found" }
    ```
  </Accordion>

  <Accordion title="Invalid Action Combination — 400">
    ```json theme={null}
    { "error": "Cannot combine 'dismiss' with other actions", "code": "report/invalid-actions" }
    ```
  </Accordion>

  <Accordion title="Missing Required Fields — 400">
    ```json theme={null}
    { "error": "Summary is required for dismissing a report", "code": "report/missing-fields" }
    ```

    Also returned when `ban-user` is used without `userId` or `reason`:

    ```json theme={null}
    { "error": "userId and reason are required for banning a user", "code": "report/missing-fields" }
    ```
  </Accordion>
</AccordionGroup>


# Handle Message Report
Source: https://docs.sublay.io/v7/api-reference/spaces/moderation/handle-message-report

PATCH /v7/:projectId/spaces/:spaceId/chat/reports/:reportId
Resolve a reported chat message within a space

Resolves a filed report against a chat message in a space's integrated conversation. Requires the caller to be a moderator or admin of that space.

## Path Parameters

<ParamField type="string">
  UUID of the space.
</ParamField>

<ParamField type="string">
  UUID of the chat message report to resolve.
</ParamField>

## Body Parameters

<ParamField type="string[]">
  One or more actions to take. Must contain at least one value. Available actions:

  * `"remove-message"` — marks the message as removed via moderation (requires `messageId`)
  * `"ban-user"` — bans the target user from the space (requires `userId` and `reason`)
  * `"dismiss"` — dismisses the report without action (cannot be combined with other actions)
</ParamField>

<ParamField type="string">
  UUID of the message to remove. Required when `remove-message` is included in `actions`.
</ParamField>

<ParamField type="string">
  Optional summary of the action taken. Stored as `actionTaken` on the report record.
</ParamField>

<ParamField type="string">
  UUID of the user to ban. Required when `ban-user` is included in `actions`.
</ParamField>

<ParamField type="string">
  Reason for the ban. Required when `ban-user` is included in `actions`.
</ParamField>

## Response

Returns `200 OK`:

```json theme={null}
{ "message": "Report handled successfully.", "code": "report/handled" }
```

## Error Responses

<AccordionGroup>
  <Accordion title="Report Not Found — 404">
    ```json theme={null}
    { "error": "Report not found.", "code": "report/not-found" }
    ```
  </Accordion>

  <Accordion title="Report Not in Space — 404">
    ```json theme={null}
    { "error": "Report does not belong to this space.", "code": "report/not-found-in-space" }
    ```
  </Accordion>

  <Accordion title="Message Not Found — 404">
    ```json theme={null}
    { "error": "Message not found.", "code": "chat/message-not-found" }
    ```
  </Accordion>

  <Accordion title="User Not Found — 404">
    ```json theme={null}
    { "error": "User not found.", "code": "report/user-not-found" }
    ```
  </Accordion>

  <Accordion title="User Not a Member — 404">
    ```json theme={null}
    { "error": "User is not a member of this space.", "code": "space/member-not-found" }
    ```
  </Accordion>

  <Accordion title="Invalid Action Combination — 400">
    ```json theme={null}
    { "error": "Cannot combine 'dismiss' with other actions.", "code": "report/invalid-actions" }
    ```
  </Accordion>
</AccordionGroup>


# Moderate Comment
Source: https://docs.sublay.io/v7/api-reference/spaces/moderation/moderate-comment

PATCH /v7/:projectId/spaces/:spaceId/comments/:commentId/moderation
Approve or remove a comment within a space

Takes a direct moderation action on a comment in a space. Requires the caller to be a moderator or admin.

## Path Parameters

<ParamField type="string">
  UUID of the space.
</ParamField>

<ParamField type="string">
  UUID of the comment to moderate.
</ParamField>

## Body Parameters

<ParamField type="string">
  The moderation action: `"approve"` or `"remove"`.
</ParamField>

<ParamField type="string">
  Optional reason for the moderation action. Up to 1,000 characters.
</ParamField>

## Response

<ResponseField name="message" type="string">
  Confirmation message.
</ResponseField>

<ResponseField name="moderationStatus" type="string">
  The resulting status: `"approved"` or `"removed"`.
</ResponseField>

See also: [useModerateSpaceComment](/hooks/spaces/use-moderate-space-comment)


# Moderate Entity
Source: https://docs.sublay.io/v7/api-reference/spaces/moderation/moderate-entity

PATCH /v7/:projectId/spaces/:spaceId/entities/:entityId/moderation
Approve or remove an entity within a space

Takes a direct moderation action on an entity in a space. Requires the caller to be a moderator or admin.

## Path Parameters

<ParamField type="string">
  UUID of the space.
</ParamField>

<ParamField type="string">
  UUID of the entity to moderate.
</ParamField>

## Body Parameters

<ParamField type="string">
  The moderation action: `"approve"` or `"remove"`.
</ParamField>

<ParamField type="string">
  Optional reason for the moderation action. Up to 1,000 characters.
</ParamField>

## Response

<ResponseField name="message" type="string">
  Confirmation message.
</ResponseField>

<ResponseField name="moderationStatus" type="string">
  The resulting status: `"approved"` or `"removed"`.
</ResponseField>

See also: [useModerateSpaceEntity](/hooks/spaces/use-moderate-space-entity)


# Moderate Message
Source: https://docs.sublay.io/v7/api-reference/spaces/moderation/moderate-message

PATCH /v7/:projectId/spaces/:spaceId/chat/messages/:messageId/moderation
Approve or remove a chat message within a space

Takes a direct moderation action on a chat message in a space's integrated conversation. Requires the caller to be a moderator or admin of the space.

## Path Parameters

<ParamField type="string">
  UUID of the space.
</ParamField>

<ParamField type="string">
  UUID of the chat message to moderate.
</ParamField>

## Body Parameters

<ParamField type="string">
  The moderation action. Only `"removed"` is supported — chat messages cannot be approved via this endpoint.
</ParamField>

<ParamField type="string">
  Optional reason for the removal. Up to 1,000 characters.
</ParamField>

## Response

<ResponseField name="message" type="string">
  Confirmation message.
</ResponseField>

<ResponseField name="moderationStatus" type="string">
  The resulting status: `"removed"`.
</ResponseField>


# Create Rule
Source: https://docs.sublay.io/v7/api-reference/spaces/rules/create-rule

POST /v7/:projectId/spaces/:spaceId/rules
Create a new community rule for a space

Creates a community rule. Only space admins can create rules. The new rule is appended to the end of the existing rule list.

## Path Parameters

<ParamField type="string">
  UUID of the space.
</ParamField>

## Body Parameters

<ParamField type="string">
  Short rule title.
</ParamField>

<ParamField type="string">
  Optional detailed description.
</ParamField>

## Response

The created Rule object with all fields including the assigned `order` value.

See also: [useCreateRule](/hooks/spaces/rules/use-create-rule)


# Delete Rule
Source: https://docs.sublay.io/v7/api-reference/spaces/rules/delete-rule

DELETE /v7/:projectId/spaces/:spaceId/rules/:ruleId
Delete a community rule from a space

Permanently deletes a rule. Only space admins can delete rules.

## Path Parameters

<ParamField type="string">
  UUID of the space.
</ParamField>

<ParamField type="string">
  UUID of the rule to delete.
</ParamField>

## Response

<ResponseField name="message" type="string">
  Confirmation message.
</ResponseField>

<ResponseField name="deletedRule" type="object">
  The `id` and `title` of the deleted rule.
</ResponseField>

See also: [useDeleteRule](/hooks/spaces/rules/use-delete-rule)


# Fetch Rule
Source: https://docs.sublay.io/v7/api-reference/spaces/rules/fetch-rule

GET /v7/:projectId/spaces/:spaceId/rules/:ruleId
Get a single community rule by its ID

Fetches a single rule by ID. Publicly accessible.

## Path Parameters

<ParamField type="string">
  UUID of the space.
</ParamField>

<ParamField type="string">
  UUID of the rule.
</ParamField>

## Response

A single Rule object with all fields.

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Rule not found.", "code": "rule/not-found" }
    ```
  </Accordion>
</AccordionGroup>

See also: [useFetchRule](/hooks/spaces/rules/use-fetch-rule)


# List Rules
Source: https://docs.sublay.io/v7/api-reference/spaces/rules/list-rules

GET /v7/:projectId/spaces/:spaceId/rules
Get all community rules for a space

Returns all community rules for a space, ordered by their `order` field. This endpoint is publicly accessible — no authentication is required.

## Path Parameters

<ParamField type="string">
  UUID of the space.
</ParamField>

## Response

<ResponseField name="data" type="Rule[]">
  Array of rule objects ordered by `order` ascending.
</ResponseField>

<ResponseField name="count" type="number">
  Total number of rules.
</ResponseField>

Each rule has: `id`, `spaceId`, `projectId`, `title`, `description`, `order`, `lastApprovedBy`, `createdAt`, `updatedAt`.

See also: [useFetchManyRules](/hooks/spaces/rules/use-fetch-many-rules)


# Reorder Rules
Source: https://docs.sublay.io/v7/api-reference/spaces/rules/reorder-rules

PATCH /v7/:projectId/spaces/:spaceId/rules/reorder
Reorder the community rules for a space

Sets the display order of all rules for a space by providing a new ordered array of rule IDs. Only space admins can reorder rules.

## Path Parameters

<ParamField type="string">
  UUID of the space.
</ParamField>

## Body Parameters

<ParamField type="string[]">
  Ordered array of all rule UUIDs in the desired display order.
</ParamField>

## Response

Returns the full array of all rules for the space in the new order (same shape as [List Rules](/api-reference/spaces/rules/list-rules)).

## Error Responses

<AccordionGroup>
  <Accordion title="Invalid Rule IDs — 400">
    One or more provided IDs do not exist in this space.

    ```json theme={null}
    { "error": "Some rule IDs were not found in this space.", "code": "rule/invalid-ids", "missingIds": ["..."] }
    ```
  </Accordion>
</AccordionGroup>

See also: [useReorderRules](/hooks/spaces/rules/use-reorder-rules)


# Update Rule
Source: https://docs.sublay.io/v7/api-reference/spaces/rules/update-rule

PATCH /v7/:projectId/spaces/:spaceId/rules/:ruleId
Update an existing community rule

Updates a rule's title or description. Only space admins can update rules.

## Path Parameters

<ParamField type="string">
  UUID of the space.
</ParamField>

<ParamField type="string">
  UUID of the rule to update.
</ParamField>

## Body Parameters

<ParamField type="string">
  Updated title.
</ParamField>

<ParamField type="string | null">
  Updated description. Pass `null` to clear.
</ParamField>

## Response

The updated Rule object.

See also: [useUpdateRule](/hooks/spaces/rules/use-update-rule)


# Update Space
Source: https://docs.sublay.io/v7/api-reference/spaces/update-space

PATCH /v7/:projectId/spaces/:spaceId
Update a space's settings, name, description, or images

Updates a space. Only the space's admin can update it. Supports multipart form data for avatar/banner image uploads.

## Path Parameters

<ParamField type="string">
  UUID of the space to update.
</ParamField>

## Body Parameters

All fields are optional. Only provided fields are updated.

<ParamField type="string">
  Updated display name. 3–100 characters.
</ParamField>

<ParamField type="string">
  Updated URL slug. Pass empty to clear.
</ParamField>

<ParamField type="string">
  Updated description.
</ParamField>

<ParamField type="string">
  `"anyone"` or `"members"`.
</ParamField>

<ParamField type="string">
  `"anyone"`, `"members"`, or `"admins"`.
</ParamField>

<ParamField type="string">
  `"public"`, `"unlisted"`, or `"private"`. Controls listing/discoverability, independent of `readingPermission`. Changes take effect immediately and are freely reversible. See [Space visibility](/data-models/space#visibility).
</ParamField>

<ParamField type="boolean">
  Whether joining the space needs admin approval. Applies to joins from this point on — memberships that are already pending or active are unaffected.
</ParamField>

<ParamField type="object">
  Updated metadata object.
</ParamField>

<ParamField type="file">
  New avatar image. Requires `avatarFile.options` when provided.
</ParamField>

<ParamField type="file">
  New banner image. Requires `bannerFile.options` when provided.
</ParamField>

## Response

Returns the updated [SpaceDetailed](/data-models/space) object.

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "Space not found.", "code": "space/not-found" }
    ```
  </Accordion>

  <Accordion title="Forbidden — 403">
    Caller is not an admin of the space.
  </Accordion>
</AccordionGroup>

See also: [useUpdateSpace](/hooks/spaces/use-update-space)


# Delete File
Source: https://docs.sublay.io/v7/api-reference/storage/delete-file

DELETE /v7/:projectId/storage/:fileId
Delete a file and all its variants from storage

Deletes a file record and removes all associated storage objects. For image files, all generated variants are also deleted.

Requires an authenticated user. **Delete is owner-or-service:** a user token may only delete files it owns; **service/master keys** may delete any file in the project. Backend-owned files (uploaded without a `userId`) are deletable only with a service/master key.

**Rate limit**: 50 requests per 5 minutes.

## Path Parameters

<ParamField type="string">
  The UUID of the file to delete.
</ParamField>

## Response

```json theme={null}
{
  "message": "File deleted successfully",
  "fileId": "uuid",
  "deletedPaths": [
    "images/abc123/original.webp",
    "images/abc123/thumbnail_original.webp",
    "images/abc123/medium_original.webp"
  ]
}
```

`deletedPaths` lists all storage paths that were removed, including the original file and any image variants.

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "File not found", "code": "storage/file-not-found" }
    ```
  </Accordion>

  <Accordion title="Unauthorized — 403">
    Returned when a user token attempts to delete a file it does not own.

    ```json theme={null}
    { "error": "Unauthorized", "code": "storage/unauthorized" }
    ```
  </Accordion>
</AccordionGroup>


# Fetch File
Source: https://docs.sublay.io/v7/api-reference/storage/fetch-file

GET /v7/:projectId/storage/:fileId
Retrieve file metadata and proxy URLs by file ID

Returns metadata and proxy URLs for a file. For image files, also returns the image extension data including all variants.

Requires an authenticated user.

**Rate limit**: 100 requests per 5 minutes.

## Path Parameters

<ParamField type="string">
  The UUID of the file to retrieve.
</ParamField>

## Response

### Base fields (all file types)

<ResponseField name="fileId" type="string">
  The file's UUID.
</ResponseField>

<ResponseField name="type" type="string">
  One of: `image`, `video`, `document`, `other`.
</ResponseField>

<ResponseField name="originalPath" type="string">
  Proxy URL for the original file.
</ResponseField>

<ResponseField name="originalSize" type="number">
  File size in bytes at the time of upload.
</ResponseField>

<ResponseField name="originalMimeType" type="string">
  MIME type of the uploaded file.
</ResponseField>

<ResponseField name="position" type="number">
  Display order in a multi-attachment context.
</ResponseField>

<ResponseField name="metadata" type="object">
  Custom metadata stored at upload time. Always includes `originalName` and `uploadedAt`.
</ResponseField>

<ResponseField name="userId" type="string">
  ID of the user who uploaded the file (present if associated).
</ResponseField>

<ResponseField name="entityId" type="string">
  ID of the associated entity (present if provided at upload).
</ResponseField>

<ResponseField name="commentId" type="string">
  ID of the associated comment (present if provided at upload).
</ResponseField>

<ResponseField name="spaceId" type="string">
  ID of the associated space (present if provided at upload).
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp.
</ResponseField>

<ResponseField name="updatedAt" type="string">
  ISO 8601 timestamp.
</ResponseField>

### Image extension (only when `type === "image"`)

<ResponseField name="image" type="object">
  Image processing details.

  <Expandable title="image fields">
    <ResponseField name="originalWidth" type="number">
      Pixel width of the source image before processing.
    </ResponseField>

    <ResponseField name="originalHeight" type="number">
      Pixel height of the source image before processing.
    </ResponseField>

    <ResponseField name="variants" type="object">
      Named variants. Each key maps to `{ publicPath, width, height, size, format }`.
    </ResponseField>

    <ResponseField name="processingStatus" type="string">
      `"completed"` or `"failed"`.
    </ResponseField>

    <ResponseField name="format" type="string">
      Output format (e.g., `"webp"`).
    </ResponseField>

    <ResponseField name="quality" type="number">
      Quality setting used during processing.
    </ResponseField>

    <ResponseField name="exifStripped" type="boolean">
      Whether EXIF metadata was removed.
    </ResponseField>
  </Expandable>
</ResponseField>

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found — 404">
    ```json theme={null}
    { "error": "File not found", "code": "storage/file-not-found" }
    ```
  </Accordion>
</AccordionGroup>


# Upload File
Source: https://docs.sublay.io/v7/api-reference/storage/upload-file

POST /v7/:projectId/storage
Upload a generic file without server-side processing

Uploads a file directly to storage without processing. Suitable for PDFs, videos, Office documents, and other non-image assets. The file type is inferred automatically from the MIME type.

This endpoint accepts `multipart/form-data`. Requires an authenticated user.

**Rate limit**: 10 requests per 5 minutes.

## Body Parameters

<ParamField type="file">
  The file to upload. Maximum 50 MB.
</ParamField>

<ParamField type="array">
  JSON-encoded array of path segments. The file is stored under the joined path with a UUID sub-folder appended. Example: `["documents", "user-123"]` → `documents/user-123/<uuid>/<filename>`.
</ParamField>

<ParamField type="string">
  Associates the file with an entity for cascade deletion.
</ParamField>

<ParamField type="string">
  Associates the file with a comment for cascade deletion.
</ParamField>

<ParamField type="string">
  Associates the file with a space.
</ParamField>

<ParamField type="number">
  Display order when a record has multiple attachments. Defaults to `0`.
</ParamField>

<ParamField type="object">
  Custom key-value data stored alongside the file record.
</ParamField>

<ParamField type="string">
  Attribute the upload to a specific user. With a user token the upload is
  already attributed to the caller; only **service/master keys** may name a
  different user. Omit for a backend/project-owned file (no owning user).
</ParamField>

## Response

```json theme={null}
{
  "fileId": "uuid",
  "type": "document",
  "relativePath": "documents/user-123/uuid/report.pdf",
  "publicPath": "/internal/files/documents/user-123/uuid/report.pdf",
  "size": 102400,
  "mimeType": "application/pdf",
  "createdAt": "2025-01-01T00:00:00.000Z"
}
```

The `type` field is one of: `image`, `video`, `document`, `other`. It is inferred from the MIME type.

## Error Responses

<AccordionGroup>
  <Accordion title="No File — 400 Bad Request">
    ```json theme={null}
    { "error": "No file provided", "code": "storage/no-file" }
    ```
  </Accordion>

  <Accordion title="File Too Large — 413">
    ```json theme={null}
    { "error": "File size exceeds the allowed limit of 50MB", "code": "storage/file-too-large" }
    ```
  </Accordion>
</AccordionGroup>


# Upload Image
Source: https://docs.sublay.io/v7/api-reference/storage/upload-image

POST /v7/:projectId/storage/images
Upload an image with server-side processing and named variant generation

Uploads an image, processes it with Sharp, and stores the original plus all requested variants. Returns proxy URLs for all variants immediately.

This endpoint accepts `multipart/form-data`. Requires an authenticated user.

**Rate limit**: 20 requests per 5 minutes.

## Body Parameters

<ParamField type="file">
  The image file to upload. Must be a valid image format recognized by Sharp (JPEG, PNG, WebP, AVIF, TIFF, GIF, SVG). Maximum 50 MB.
</ParamField>

<ParamField type="string">
  Processing mode. One of: `exact-dimensions`, `aspect-ratio-width-based`, `aspect-ratio-height-based`, `original-aspect`, `multi-aspect-ratio`.
</ParamField>

<ParamField type="object">
  Required for `exact-dimensions` mode. An object mapping variant names to `{ width, height }` pairs.

  ```json theme={null}
  { "thumbnail": { "width": 64, "height": 64 }, "card": { "width": 400, "height": 300 } }
  ```
</ParamField>

<ParamField type="object">
  Required for `aspect-ratio-width-based` and `aspect-ratio-height-based` modes. `{ width, height }` ratio.
</ParamField>

<ParamField type="object">
  Required for `aspect-ratio-width-based` mode. An object mapping variant names to pixel widths.
</ParamField>

<ParamField type="object">
  Required for `aspect-ratio-height-based` mode. An object mapping variant names to pixel heights.
</ParamField>

<ParamField type="object">
  Required for `original-aspect` and `multi-aspect-ratio` modes. An object mapping variant names to longest-edge pixel sizes.
</ParamField>

<ParamField type="array">
  Required for `multi-aspect-ratio` mode. Array of `{ width, height }` aspect ratio objects.
</ParamField>

<ParamField type="string">
  Sharp fit strategy. Defaults to `cover`. Valid values depend on the mode:

  * `exact-dimensions`, `aspect-ratio-width-based`, `aspect-ratio-height-based`, `multi-aspect-ratio`: `cover`, `contain`, `inside`, or `outside`
  * `original-aspect`: `inside` or `outside` only (`cover`/`contain` are not valid for this mode)
</ParamField>

<ParamField type="number">
  Output quality (1–100). Applies to JPEG and WebP. Defaults to `85`.
</ParamField>

<ParamField type="string">
  Output format: `webp`, `jpeg`, `png`, or `original`. Defaults to `webp`.
</ParamField>

<ParamField type="boolean">
  Remove EXIF metadata from output. Defaults to `true`.
</ParamField>

<ParamField type="array">
  Storage path segments as a JSON-encoded array. Defaults to `["images", "<fileId>"]`.
</ParamField>

<ParamField type="string">
  Associates the file with an entity for cascade deletion.
</ParamField>

<ParamField type="string">
  Associates the file with a comment for cascade deletion.
</ParamField>

<ParamField type="string">
  Associates the file with a space.
</ParamField>

<ParamField type="string">
  Attribute the upload to a specific user. With a user token the upload is
  already attributed to the caller; only **service/master keys** may name a
  different user. Omit for a backend/project-owned file (no owning user).
</ParamField>

## Response

```json theme={null}
{
  "fileId": "uuid",
  "type": "image",
  "originalPath": "/internal/files/...",
  "originalSize": 204800,
  "originalWidth": 1920,
  "originalHeight": 1080,
  "variants": {
    "thumbnail": {
      "publicPath": "/internal/files/...",
      "width": 64,
      "height": 64,
      "size": 3200,
      "format": "webp"
    }
  },
  "format": "webp",
  "quality": 85,
  "createdAt": "2025-01-01T00:00:00.000Z"
}
```

## Error Responses

<AccordionGroup>
  <Accordion title="No File — 400 Bad Request">
    ```json theme={null}
    { "error": "No file provided", "code": "storage/no-file" }
    ```
  </Accordion>

  <Accordion title="File Too Large — 413">
    ```json theme={null}
    { "error": "File size exceeds the allowed limit of 50MB", "code": "storage/file-too-large" }
    ```
  </Accordion>

  <Accordion title="Invalid Image — 422">
    ```json theme={null}
    { "error": "Invalid image file", "code": "storage/invalid-image" }
    ```
  </Accordion>
</AccordionGroup>


# Get URL Metadata
Source: https://docs.sublay.io/v7/api-reference/utils/get-metadata

GET /v7/:projectId/utils/get-metadata
Fetch Open Graph and social metadata for any URL

Fetches Open Graph, Twitter Card, and other structured metadata for a given URL. Results are cached in Redis for 24 hours to avoid repeated fetches. Useful for building link previews in comments or entity editors.

Requires an authenticated user.

**Rate limit**: 30 requests per 5 minutes.

## Query Parameters

<ParamField type="string">
  The URL to fetch metadata for. Must be a valid HTTP/HTTPS URL.
</ParamField>

## Response

```json theme={null}
{
  "title": "Example Page Title",
  "description": "A brief description of the page.",
  "siteName": "Example Site",
  "url": "https://example.com/page",
  "type": "article",
  "locale": "en_US",
  "charset": "utf-8",
  "favicon": "https://example.com/favicon.ico",
  "images": [
    {
      "url": "https://example.com/og-image.jpg",
      "width": 1200,
      "height": 630,
      "type": "image/jpeg",
      "alt": null
    }
  ],
  "videos": [],
  "audio": [],
  "twitter": {
    "card": "summary_large_image",
    "site": "@example",
    "creator": null,
    "title": "...",
    "description": "...",
    "images": [],
    "players": []
  },
  "article": {
    "publishedTime": "2025-01-01T00:00:00Z",
    "modifiedTime": null,
    "expirationTime": null,
    "author": null,
    "section": null,
    "tag": null
  },
  "appLinks": { "ios": null, "android": null, "web": null },
  "book": null,
  "music": null,
  "profile": null,
  "jsonLd": null,
  "requestUrl": "https://example.com/page",
  "success": true
}
```

All fields are nullable — the response always has the same shape regardless of which tags the target URL exposes.

## Error Responses

<AccordionGroup>
  <Accordion title="Extraction Failed — 422">
    ```json theme={null}
    {
      "error": "Failed to extract metadata from the provided URL",
      "code": "utils/metadata-extraction-failed"
    }
    ```

    Returned when the URL is reachable but no metadata could be extracted.
  </Accordion>
</AccordionGroup>


# Create Workspace
Source: https://docs.sublay.io/v7/api-reference/workspaces/create-workspace

POST /v7/:projectId/workspaces
Create a root or child workspace

Creates a workspace. The authenticated caller becomes the `ownerId`. Omit `parentWorkspaceId` to create a **root** workspace; pass it to create a **child**.

* **Root creation** requires the creator to have a **verified email** (else `403 workspace/email-not-verified`). This is **not** a key-bypass gate: a service or master key acting as a named `actingUserId` still requires *that* user to be verified. On a purely external-auth project this makes root creation unavailable — see [the external-auth limitation](/data-models/workspace-invitation#v1-external-auth-limitation).
* **Child creation** requires the `create-sub-workspace` capability on the parent (held directly or via reach). The creator becomes the **child's** owner. No separate verified-email gate (the capability-holder is already a verified member up-tree).

<Note>
  `inheritsFromParent` is **never** accepted from client input — it is server-set from the project default at creation, and cannot be overridden when the project's default is enforced. `depth` is likewise server-computed.
</Note>

## Body Parameters

<ParamField type="string">
  Display name for the workspace. 1–100 characters.
</ParamField>

<ParamField type="object">
  Optional arbitrary developer-defined data (opaque JSON). Defaults to `{}`.
</ParamField>

<ParamField type="string">
  Optional UUID of a parent workspace. Absent → root workspace. Requires the `create-sub-workspace` capability on the parent.
</ParamField>

<ParamField type="string">
  Service/master keys only — the user to act as (the created workspace's owner). **Required for a key:** this route has no unbounded path, so a key that names nobody is refused with `400 workspace/missing-user-id`. The named user must satisfy the same gates a self-driven call would: for a **root** workspace they must have a **verified email**.

  A plain user token omits it — the actor is the token's own user. The field is **not** ignored for such a token: sending your *own* user id is a harmless no-op, but sending **anyone else's** is a `403 workspace/unauthorized`. See [Acting on behalf of a user](/sdk/workspaces/overview#acting-on-behalf-of-a-user).
</ParamField>

## Response

Returns the created [Workspace](/data-models/workspace) object.

## Error Responses

<AccordionGroup>
  <Accordion title="Email Not Verified — 403">
    ```json theme={null}
    { "error": "A verified email is required to create a root workspace.", "code": "workspace/email-not-verified" }
    ```

    Also returned when a **service or master key** creates a root workspace on behalf of an unverified `actingUserId` — keys do not bypass this gate. Ownership has exactly three doors (create, accept an invite, receive a transfer) and all three enforce it identically, which is what guarantees every workspace participant has a confirmed email.
  </Accordion>

  <Accordion title="Unauthorized — 403">
    ```json theme={null}
    { "error": "The 'create-sub-workspace' capability on the parent is required.", "code": "workspace/unauthorized" }
    ```
  </Accordion>

  <Accordion title="Parent Not Found — 404">
    ```json theme={null}
    { "error": "Parent workspace not found.", "code": "workspace/not-found" }
    ```
  </Accordion>

  <Accordion title="Max Depth Exceeded — 400">
    ```json theme={null}
    { "error": "Maximum nesting depth (10) exceeded.", "code": "workspace/max-depth-exceeded" }
    ```
  </Accordion>

  <Accordion title="Missing Acting User — 400">
    ```json theme={null}
    { "error": "Missing user ID", "code": "workspace/missing-user-id" }
    ```

    A service/master key called this route without naming an `actingUserId`. There is no unbounded path here — a workspace has to be created *by* somebody, so the key must name that user.
  </Accordion>

  <Accordion title="Acted as Another User — 403">
    ```json theme={null}
    { "error": "Unauthorized", "code": "workspace/unauthorized" }
    ```

    A plain user token sent an `actingUserId` naming a **different** user. Only a service/master key may act as someone else.
  </Accordion>
</AccordionGroup>

See also: [useCreateWorkspace](/hooks/workspaces/use-create-workspace) · [createWorkspace (node-sdk)](/node-sdk/workspaces)


# Delete Workspace
Source: https://docs.sublay.io/v7/api-reference/workspaces/delete-workspace

DELETE /v7/:projectId/workspaces/:id
Owner-only delete that cascades the subtree

Deletes a workspace. **Owner-only** (the workspace's own owner, or an ancestor owner via the god path). **There is no `delete-workspace` capability.**

Deletion **cascades** the entire subtree in one transaction, bottom-up: invitations → members → workspaces. Every workspace actually deleted fires a `workspace.deleted` webhook (one per workspace).

<Note>
  **No per-member webhooks fire on this path.** The cascade does **not** emit `workspace.member.removed` for the memberships it tears down — one POST per member across a large subtree would flood a delivery layer with no retry or batching, and `workspace.deleted` already says the whole roster is gone. Treat each `workspace.deleted` as removing that node's entire roster. See [Webhooks & lifecycle](/sdk/workspaces/webhooks#deleting-a-workspace-does-not-emit-per-member-events).
</Note>

<Warning>
  Your own data tagged with a workspace id (docs, issues, etc.) is **not** deleted by Sublay — Sublay doesn't know about it. React to the `workspace.deleted` webhook to clean up your own workspace-tagged data.
</Warning>

## Path Parameters

<ParamField type="string">
  The workspace UUID.
</ParamField>

## Body Parameters

<ParamField type="string">
  Service/master keys only — the user to act as. Sent in the request body so the act-as-user path works on `DELETE`. **Enforced:** the owner-only guard runs against the named user, so a key naming a non-owner is refused exactly as that user would be. Omit it to act as the app itself (unbounded) — but on a call that cascade-deletes the whole subtree, prefer naming the owner so the request carries a user id. See [Acting on behalf of a user](/sdk/workspaces/overview#acting-on-behalf-of-a-user).

  The [node SDK](/node-sdk/workspaces) is stricter than this endpoint: it types `actingUserId` as **required** here, so omitting it is only possible by calling the REST route directly.

  Several shapes are refused rather than ignored on this path. `actingUserId: ""` or `null` is a `400` — it reads as an *attempt* to name someone, not as "nobody". So is **every top-level field this endpoint does not declare**, in the body and in the query string alike, for every caller: `onBehalfOf`, `acting_user_id` and `impersonate` all come back as `Unrecognized key: "…"` rather than being quietly dropped. A key that differs from `actingUserId` only in capitalization — `actingUserID`, `actinguserid` — is refused too, but with a "did you mean `actingUserId`?" message instead of the generic one. And when the request names nobody, so is any body whose `Content-Type` is not `application/json` — an unparsed body discards the `actingUserId` inside it just as surely as a misspelling would. See [Shapes the server rejects](/sdk/workspaces/overview#shapes-the-server-rejects).
</ParamField>

## Response

```json theme={null}
{ "message": "Workspace deleted successfully." }
```

## Error Responses

<AccordionGroup>
  <Accordion title="Unauthorized — 403">
    ```json theme={null}
    { "error": "Owner access required", "code": "workspace/unauthorized" }
    ```
  </Accordion>

  <Accordion title="Invalid Path Parameter — 400">
    ```json theme={null}
    { "error": "Invalid workspace id: expected a UUID.", "code": "workspace/invalid-params" }
    ```

    Every path id on the workspaces bundle is checked for UUID shape before the route runs, so a malformed one is a plain `400` rather than a `500` from the database.
  </Accordion>

  <Accordion title="Undeclared Field — 400">
    ```json theme={null}
    { "error": "Unrecognized key: \"onBehalfOf\"", "code": "workspace/invalid-body" }
    ```

    Every workspaces endpoint declares its fields exactly, and a top-level field it does not declare is refused rather than ignored — in the request body and in the query string alike, for every caller. Two or more at once are named together: `Unrecognized keys: "onBehalfOf", "impersonate"`. An offender in the query string carries `workspace/invalid-query` instead. Send only the fields documented above, plus `actingUserId` and `projectId`, which every workspaces route accepts. See [Shapes the server rejects](/sdk/workspaces/overview#shapes-the-server-rejects).
  </Accordion>

  <Accordion title="Unparsed Body — 400">
    ```json theme={null}
    {
      "error": "This request carries a body with content-type \"text/plain;charset=UTF-8\", which no parser reads, so any `actingUserId` inside it was discarded and this request names no acting user. Send the body as application/json.",
      "code": "workspace/invalid-body"
    }
    ```

    Returned when a service/master key sends a body with a `Content-Type` other than `application/json` **and** no `actingUserId` was read. Sublay parses only `application/json`, so the actor inside such a body is discarded and the request would fall through to the unbounded path. `fetch()` sends `text/plain;charset=UTF-8` when you pass a stringified body and set no headers — set the header. An empty JSON body and a bodiless request both pass. See [Shapes the server rejects](/sdk/workspaces/overview#shapes-the-server-rejects).
  </Accordion>
</AccordionGroup>


# Read Authority
Source: https://docs.sublay.io/v7/api-reference/workspaces/fetch-authority

GET /v7/:projectId/workspaces/:id/authority/me
The resolved standing of a user on a workspace — permissions as a service

Returns the caller's **resolved standing** on a workspace: `{ reasons, capabilities, permissions, rank }`, computed via the [authority resolver](/data-models/workspace#reach-and-the-wall-door-rule) (fast-path + bounded ancestor climb). This is the endpoint your authorization server reads (via the [node SDK](/node-sdk/workspaces)) to make its own app-level decisions.

`reasons` is an array of **structured entries** — `{ type, viaWorkspaceId? }` — distinguishing **`owner` / `ancestor-owner` / `member` / `reach-holder`**, so you always know *why* a user has what they have **and which workspace grants it**. It is the same object shape a [roster](/api-reference/workspaces/members/list-members) entry's `reasons` carries. `viaWorkspaceId` names the granting ancestor and is present on `ancestor-owner` / `reach-holder` only (`owner` / `member` are grants on the workspace itself). A user reaching in from several ancestors carries **one entry per granting ancestor**.

This read is inherently a **self** read (or a privileged-key read of a named user), so `capabilities` / `permissions` / `rank` are always returned in full here — unlike the [member-standing read](/api-reference/workspaces/members/fetch-member-standing), which fences them. (The fence exists to stop a caller reconstructing *someone else's* rank; there is nobody else in this payload.)

<Note>
  There is **no** convenience `?permission=` check and **no** `can()` middleware. Sublay never consumes your opaque `permissions`, so a permission check is a one-line `.includes()` on the returned record:

  ```ts theme={null}
  const authority = await sublay.workspaces.fetchWorkspaceAuthority({ workspaceId, actingUserId });
  if (authority.permissions.includes("deploy")) { /* allow */ }
  ```
</Note>

## Path Parameters

<ParamField type="string">
  The workspace UUID.
</ParamField>

## Query Parameters

<ParamField type="string">
  Service/master keys only — the user to act as, whose standing is resolved. **Required for a key:** this route has no unbounded path (there is no such thing as "the app's standing"), so a key that names nobody is refused with `400 workspace/missing-user-id`.

  A client token omits it — the subject is the token's own user. The field is **not** ignored for such a token: sending your *own* user id is a harmless no-op, but sending **anyone else's** is a `403 workspace/unauthorized`. See [Acting on behalf of a user](/sdk/workspaces/overview#acting-on-behalf-of-a-user).
</ParamField>

## Response

```json theme={null}
{
  "reasons": [
    { "type": "member" },
    { "type": "ancestor-owner", "viaWorkspaceId": "ws_root" }
  ],
  "capabilities": ["view", "invite", "remove-member"],
  "permissions": ["deploy"],
  "rank": 5
}
```

* `reasons` — structured standings; `viaWorkspaceId` is present on `ancestor-owner` / `reach-holder` only.
* `capabilities` — the fully-resolved set (direct + reach + ownership). **`view` is implied by every other capability** — any user with standing on the workspace resolves with `view`, including a member whose stored `capabilities` array is empty. A user with no relation at all resolves to an empty set.
* `permissions` — **per-node** (the direct membership on this workspace only; may be empty). Does not cascade.
* `rank` — the direct-membership rank, or `null` for owners / ancestor-owners / reach-only holders.
* There is **no `relativeRank`** on this read. It is an offset from the caller, and here the caller *is* the subject — so it could only ever be `0`, a constant dressed as a coordinate. `rank` is the position this endpoint reports. `relativeRank` is meaningful on the [roster](/api-reference/workspaces/members/list-members) and [member-standing](/api-reference/workspaces/members/fetch-member-standing) reads, where the subject is somebody else.

## Error Responses

<AccordionGroup>
  <Accordion title="Missing Acting User — 400">
    ```json theme={null}
    { "error": "Missing user ID", "code": "workspace/missing-user-id" }
    ```

    A service/master key called this route without naming an `actingUserId`. The read resolves *a user's* standing, so there is nobody to resolve it for.
  </Accordion>

  <Accordion title="Acted as Another User — 403">
    ```json theme={null}
    { "error": "Unauthorized", "code": "workspace/unauthorized" }
    ```

    A plain user token sent an `actingUserId` naming a **different** user. Only a service/master key may resolve someone else's standing.
  </Accordion>

  <Accordion title="Invalid Path Parameter — 400">
    ```json theme={null}
    { "error": "Invalid workspace id: expected a UUID.", "code": "workspace/invalid-params" }
    ```

    Every path id on the workspaces bundle is checked for UUID shape before the route runs, so a malformed one is a plain `400` rather than a `500` from the database.
  </Accordion>
</AccordionGroup>

See also: [useFetchWorkspaceAuthority](/hooks/workspaces/use-fetch-workspace-authority) · [fetchWorkspaceAuthority (node-sdk)](/node-sdk/workspaces) · [fetchWorkspaceAuthority (js-sdk)](/js-sdk/workspaces)


# Fetch Workspace
Source: https://docs.sublay.io/v7/api-reference/workspaces/fetch-workspace

GET /v7/:projectId/workspaces/:id
Read a single workspace, visibility-filtered

Returns a single [Workspace](/data-models/workspace), filtered by the caller's reach-visibility — a caller never sees a node their authority doesn't reach.

## Path Parameters

<ParamField type="string">
  The workspace UUID.
</ParamField>

## Query Parameters

<ParamField type="string">
  Comma-separated include flags. `memberCount` adds the workspace's **direct** member count as `memberCount` on the object.
</ParamField>

<ParamField type="string">
  Service/master keys only — the user to act as. Enforced: visibility resolves against the named user, so a key acting as someone with no relation to this workspace gets the same `404` that user would. Omit it to read as the app itself (unbounded) — where "omit" means **absent**: `actingUserId: ""` or `null` is a `400`, not a fall-through to that mode. See [Acting on behalf of a user](/sdk/workspaces/overview#acting-on-behalf-of-a-user).
</ParamField>

## Response

Returns the [Workspace](/data-models/workspace) object.

## Error Responses

<AccordionGroup>
  <Accordion title="Not Found / Not Visible — 404">
    ```json theme={null}
    { "error": "Workspace not found.", "code": "workspace/not-found" }
    ```
  </Accordion>

  <Accordion title="Invalid Path Parameter — 400">
    ```json theme={null}
    { "error": "Invalid workspace id: expected a UUID.", "code": "workspace/invalid-params" }
    ```

    Every path id on the workspaces bundle is checked for UUID shape before the route runs, so a malformed one is a plain `400` rather than a `500` from the database.
  </Accordion>
</AccordionGroup>

See also: [useFetchWorkspace](/hooks/workspaces/use-fetch-workspace)


# List Workspaces
Source: https://docs.sublay.io/v7/api-reference/workspaces/fetch-workspaces

GET /v7/:projectId/workspaces
List the caller's direct-membership + owned workspaces

Returns a paginated list of workspaces scoped to the caller's **direct memberships + owned workspaces** (both index-backed, no ancestor climb).

<Note>
  This is deliberately **not** an "everything I can reach" tree listing — that per-row reach resolution is deferred. Use this for the common "my workspaces" UI call.
</Note>

## Query Parameters

<ParamField type="number">
  Page number for pagination.
</ParamField>

<ParamField type="number">
  Page size.
</ParamField>

<ParamField type="string">
  Comma-separated include flags. `include=memberCount` adds a `memberCount` to **every row** — the workspace's **direct** member count, the same number [Fetch Workspace](/api-reference/workspaces/fetch-workspace) returns for one workspace, counting neither descendants nor reach-holders.

  It is resolved with a single grouped query over the page that was returned, so a workspace switcher showing counts costs one request rather than one per row. Omit the flag and the field is **absent** from each row — not `null`, not `0`. An unrecognized flag value is ignored rather than rejected.
</ParamField>

<ParamField type="string">
  Service/master keys only — the user to act as, whose workspaces are listed. **Required for a key:** this route has no unbounded path — the list is defined as *somebody's* memberships — so a key that names nobody is refused with `400 workspace/missing-user-id`.

  A plain user token omits it — the actor is the token's own user. The field is **not** ignored for such a token: sending your *own* user id is a harmless no-op, but sending **anyone else's** is a `403 workspace/unauthorized`. See [Acting on behalf of a user](/sdk/workspaces/overview#acting-on-behalf-of-a-user).
</ParamField>

## Response

Returns a paginated response of [Workspace](/data-models/workspace) objects.

```
GET /v7/:projectId/workspaces?page=1&limit=10&include=memberCount
```

```json theme={null}
{
  "data": [
    {
      "id": "0f1c7a6e-9d4b-4f2a-8c31-5b6e2a7d1c04",
      "name": "Acme HQ",
      "metadata": {},
      "ownerId": "3a9e5c11-72d8-4a6b-9f10-8c2d4e7b5a33",
      "parentWorkspaceId": null,
      "depth": 0,
      "inheritsFromParent": false,
      "createdAt": "2026-01-14T09:12:44.001Z",
      "updatedAt": "2026-01-14T09:12:44.001Z",
      "memberCount": 12
    }
  ],
  "pagination": { "page": 1, "pageSize": 10, "totalPages": 1, "totalItems": 1, "hasMore": false }
}
```

`memberCount` appears only when `include=memberCount` was sent. `limit` defaults to `20` when omitted, and `page` to `1`.

## Error Responses

<AccordionGroup>
  <Accordion title="Missing Acting User — 400">
    ```json theme={null}
    { "error": "Missing user ID", "code": "workspace/missing-user-id" }
    ```

    A service/master key called this route without naming an `actingUserId`. The listing is scoped to a user's own memberships and owned workspaces, so there is nobody to scope it to.
  </Accordion>

  <Accordion title="Acted as Another User — 403">
    ```json theme={null}
    { "error": "Unauthorized", "code": "workspace/unauthorized" }
    ```

    A plain user token sent an `actingUserId` naming a **different** user. Only a service/master key may act as someone else.
  </Accordion>

  <Accordion title="Undeclared Query Parameter — 400">
    ```json theme={null}
    { "error": "Unrecognized key: \"sort\"", "code": "workspace/invalid-query" }
    ```

    This route declares `page`, `limit`, `include`, `actingUserId` and `projectId`, and refuses anything else rather than ignoring it. Two or more at once are named together: `Unrecognized keys: "sort", "order"`. The two exceptions across the bundle are the cache-busters `_` and `_t`, which are dropped before the request is read. See [Shapes the server rejects](/sdk/workspaces/overview#shapes-the-server-rejects).
  </Accordion>
</AccordionGroup>

See also: [useFetchManyWorkspaces](/hooks/workspaces/use-fetch-many-workspaces) · [useFetchManyWorkspacesWrapper](/hooks/workspaces/use-fetch-many-workspaces-wrapper)


# Accept Invite
Source: https://docs.sublay.io/v7/api-reference/workspaces/invitations/accept-invite

POST /v7/:projectId/workspace-invites/:inviteId/accept
Accept an invitation — identity-matched + verified-email, no token

Accepts an invitation. Note the path is **not** `:id`-scoped — it is addressed by the (non-secret) invitation id.

**Acceptance is identity-matched + verified-email, no token:**

* The caller must **be** the invite's target (by `userId` or normalized `email`).
* The caller must have a **verified email** — required to accept **any** invite (userId- or email-addressed). An unverified accept returns `workspace/email-not-verified` so your app can prompt verification.
* Knowing the `inviteId` does **not** let a non-target accept.

<Warning>
  **A service/master key does not bypass either gate.** Naming an `actingUserId` means *being* that user, so a backend auto-join flow must satisfy the invitee's own conditions: the invitation must be **actually addressed to** the named user (otherwise `404 workspace/invite-not-found` — accepting Alice's invite while naming Bob does not work), and that user's **email must be verified** (otherwise `403 workspace/email-not-verified`). And there is **no** unbounded path here to fall back on: an acceptance has to land on somebody's membership row, so `actingUserId` is **required** for a key — omitting it is a `400 workspace/missing-user-id`, not a bypass. If your onboarding pre-accepts invites server-side, verify the address first. See [Acting on behalf of a user](/sdk/workspaces/overview#acting-on-behalf-of-a-user).
</Warning>

On accept, the stored grant is applied and the `WorkspaceMember` is created **transactionally**; the invite is marked `accepted`. Fires **both** `workspace.invite.accepted` **and** `workspace.member.added` (invitation-lifecycle vs roster-sync — intentionally two streams).

**Idempotence:** if the caller is already a member (or owner), accept is a **no-op** — the invite is marked `accepted`, no duplicate row is created, the existing grant is **not** overwritten, and **no** `workspace.member.added` fires.

## Path Parameters

<ParamField type="string">
  The (non-secret) invitation UUID.
</ParamField>

## Body Parameters

<ParamField type="string">
  Service/master keys only — the accepting user. **Required for a key:** an acceptance has to land on somebody's membership row, so there is no unbounded path — a key that names nobody is refused with `400 workspace/missing-user-id`. Enforced: both gates above run against *that* user.

  A plain user token omits it — the actor is the token's own user. The field is **not** ignored for such a token: sending your *own* user id is a harmless no-op, but sending **anyone else's** is a `403 workspace/unauthorized`. See [Acting on behalf of a user](/sdk/workspaces/overview#acting-on-behalf-of-a-user).
</ParamField>

## Response

```json theme={null}
{ "success": true, "workspaceId": "ws_abc" }
```

## Error Responses

<AccordionGroup>
  <Accordion title="Email Not Verified — 403">
    ```json theme={null}
    { "error": "A verified email is required to accept an invitation.", "code": "workspace/email-not-verified" }
    ```
  </Accordion>

  <Accordion title="Not the Target — 404">
    A caller who is not the invitation's target receives the **same** `404` as a
    non-existent invitation — knowing an invite id must never confirm to a
    non-target that it exists.

    ```json theme={null}
    { "error": "Invitation not found.", "code": "workspace/invite-not-found" }
    ```
  </Accordion>

  <Accordion title="Invite Expired — 409">
    ```json theme={null}
    { "error": "This invitation has expired.", "code": "workspace/invite-expired" }
    ```
  </Accordion>

  <Accordion title="Invite Not Found — 404">
    ```json theme={null}
    { "error": "Invitation not found.", "code": "workspace/invite-not-found" }
    ```
  </Accordion>

  <Accordion title="Invite Terminal — 409">
    ```json theme={null}
    { "error": "This invitation is no longer pending.", "code": "workspace/invite-terminal" }
    ```

    The invitation is already `accepted`, `declined`, or `revoked`.
  </Accordion>

  <Accordion title="Acting User Not Found — 404">
    ```json theme={null}
    { "error": "Acting user not found.", "code": "workspace/invalid-target" }
    ```

    The `actingUserId` a key named does not exist in this project. Naming is not authentication — the id is only looked up here.
  </Accordion>

  <Accordion title="Missing Acting User — 400">
    ```json theme={null}
    { "error": "Missing user ID", "code": "workspace/missing-user-id" }
    ```

    A service/master key called this route without naming an `actingUserId`. An acceptance creates *someone's* membership row, so there is nobody for it to land on.
  </Accordion>

  <Accordion title="Acted as Another User — 403">
    ```json theme={null}
    { "error": "Unauthorized", "code": "workspace/unauthorized" }
    ```

    A plain user token sent an `actingUserId` naming a **different** user. Only a service/master key may act as someone else.
  </Accordion>

  <Accordion title="Invalid Path Parameter — 400">
    ```json theme={null}
    { "error": "Invalid invitation id: expected a UUID.", "code": "workspace/invalid-params" }
    ```

    Every path id on the workspaces bundle is checked for UUID shape before the route runs, so a malformed one is a plain `400` rather than a `500` from the database.
  </Accordion>
</AccordionGroup>

See also: [useAcceptWorkspaceInvite](/hooks/workspaces/use-accept-workspace-invite)


# Create Invite
Source: https://docs.sublay.io/v7/api-reference/workspaces/invitations/create-invite

POST /v7/:projectId/workspaces/:id/invites
Invite a user by email, userId, or username

Creates an invitation, addressed by **exactly one** of `email`, `userId`, or `username`. Requires the `invite` capability. Always sends an email (no toggle). Fires `workspace.invite.created`.

<Warning>
  **Requires `workspaces.inviteAcceptUrl` on the project.** The invitation email's only call to action is a deep-link built from that setting, and it has no default — so an unconfigured project cannot create invitations at all. Without it this endpoint returns `409 workspace/missing-invite-accept-url` and persists nothing (no invitation row, no email, no webhook).

  This applies **even when the invitee already has an account** — there is no special case. See [Project settings](/sdk/workspaces/overview#project-settings) for how to configure it.
</Warning>

The invited `capabilities`/`permissions` are validated against the inviter's own resolved set on the workspace — no-escalation on both arrays. The rank floor applies **only when the inviter has a direct member row** on the workspace: then the invited rank must be strictly larger (less senior) than the inviter's own. A **reach-holder** inviter (holding `invite` via an open inherit chain, with no direct row) is not in the workspace's rank ladder and may invite at any rank.

The invited rank is named in **either coordinate** — `rank` (absolute) or `relativeRank` (an offset from the inviter) — and they are **mutually exclusive**. Supplying **neither** applies the default, `relativeRank: 1`: one rung below the inviter. Whichever arrives, it is resolved to an absolute number here and stored absolute on the invitation row. See [choosing a rank](/sdk/workspaces/overview#choosing-a-rank).

The inviter is the caller's own token subject, or — for a service/master key — the `actingUserId` it names. Both floors are skipped for an owner or ancestor owner, and for a key that names nobody.

<Note>
  **A tier cannot grow itself.** Because the rank floor is strict, a rank-5 manager with a direct member row can invite rank 6, 7, 8… but **never another rank 5**. Minting a peer needs someone above that tier, and no ranked member at all clears the floor for **rank 0**. If your product has a server-driven "add a manager" action, act as the owner for it.

  As stated above, the floor only binds an inviter who holds a **direct member row** here — an owner or ancestor owner, a reach-holder with no direct row, and a key naming nobody all skip it and may invite at any rank, rank 0 included.
</Note>

<Warning>
  **Omitting the rank field is the easiest way in the whole API to mint rank 0.** The default is `relativeRank: 1` — one rung below the inviter — and *apex* is where an inviter with no member row on this workspace stands. So for an **owner**, an **ancestor owner**, a **reach-holder** with no direct row, or a **service/master key acting as itself**, one below apex **is rank 0**: the most senior rung on the ladder, handed out by leaving a field off.

  That is semantically right — one below apex *is* the top rung — and it is not changing. But it inverts the intuition that omitting a field is the cautious choice, and it lands squarely on the path this page calls the happy path. The scenario to watch is the **backend invite flow**: a server route that invites people with a service key, sending an address and capabilities and no rank, mints a workspace full of rank-0 members — each one able to manage everyone else, and none of them manageable by anyone but the owner. If a service-key flow wants new members at the **bottom** of the ladder, it must name a coordinate (`rank: 10`, or `relativeRank` against an `actingUserId` who actually sits in the ladder) rather than rely on the default.

  **The milder collision applies to in-ladder inviters.** A rank-0 lead who invites six people with no rank field gets six rank-1 members, and equals cannot act on equals — none of those six can manage each other; only the lead can. Often correct for a flat team, and worth deciding on purpose rather than discovering later. If your product has tiers, name one on the invite.
</Warning>

**Duplicate handling:**

* Inviting an **existing member** → `409` (change the grant via [Update Member](/api-reference/workspaces/members/update-member)).
* A **live** invite (`pending` and not past `expiresAt`) for the same target → the existing invitation is **updated in place**, under the same `id`, and its 14-day expiry restarts. See [what a re-invite does to the grant](#what-a-re-invite-does-to-the-grant) — it is not a plain replace.
* A **terminal** (`accepted`/`declined`/`revoked`) or **effectively-expired** invite does **not** block — a fresh `pending` is created. (An `accepted` invite means the user is already a member, so re-inviting them returns `409` instead.)

Invite-by-email to an address that already has an account resolves and stores the `userId` at creation. The account lookup is **case-insensitive**, so an account stored as `Jane@Example.com` is still bound when invited as `jane@example.com`.

### What a re-invite does to the grant

This endpoint doubles as an **upsert**, so a second call for a target who already has a live invite edits that invitation rather than creating a second one. On that path, each grant field — `rank`/`relativeRank`, `capabilities`, `permissions`, `title` — is handled independently:

* **Omitted → preserved.** The stored value is kept as-is. It is *not* re-defaulted, and not blanked. This is what makes a bare "Resend invitation" button that sends only the address safe: a deliberate `rank: 10` contractor invite stays at rank 10 no matter who presses it.
* **Explicitly supplied → overwritten.** Refreshing a grant is a real use of this route, so naming a value still changes it. An explicitly empty array (`capabilities: []`) is a value, not an omission, and does clear the field.
* **An explicit `relativeRank` re-resolves against the *current* caller.** The offset is anchored on whoever is calling now, not on whoever created the invitation — so `relativeRank: 1` sent by a rank-3 member rewrites the invitation to rank 4, while the same field sent by the owner rewrites it to rank 0. If you mean "leave the rank alone", send neither rank field.

<Note>
  A re-invite may **preserve** a rank the current caller could not have minted themselves — omission is not a write, so no floor is re-applied to it. That is deliberate and matches [Resend Invite](/api-reference/workspaces/invitations/resend-invite), which extends the very same invitation, rank intact, on the same `invite` capability. Values you *do* supply are floored normally.
</Note>

## Path Parameters

<ParamField type="string">
  The workspace UUID.
</ParamField>

## Body Parameters

<ParamField type="string">
  Invitee email (trimmed + lowercased server-side). One of `email`/`userId`/`username` is required. Matching an existing account is **case-insensitive**, so an address that was stored with different capitalization (as OAuth-created accounts are) still binds its `userId`.
</ParamField>

<ParamField type="string">
  Invitee user id (existing users only). Here `userId` is the invite **target**, not an acting user.

  This route is the **one exception** to a bundle-wide rule: on every other workspace route a body or query `userId` is rejected with a `400`, because there it can only be a stale spelling of the actor. See [Shapes the server rejects](/sdk/workspaces/overview#shapes-the-server-rejects).

  **The exception is the body only.** A query `?userId=` is rejected here exactly as it is everywhere else — `400 workspace/invalid-query` — because this endpoint never reads one, so in the query string it can only be the stale actor spelling. Send the invitee in the JSON body.
</ParamField>

<ParamField type="string">
  Invitee username (existing users only).
</ParamField>

<ParamField type="string[]">
  Capabilities to apply on accept. Subject to no-escalation. Defaults to `[]` on a **new** invitation; on a [re-invite](#what-a-re-invite-does-to-the-grant) omitting it **preserves** the stored set, while `[]` explicitly clears it.
</ParamField>

<ParamField type="string[]">
  Opaque permissions to apply on accept. Subject to no-escalation. Defaults to `[]` on a **new** invitation; on a [re-invite](#what-a-re-invite-does-to-the-grant) omitting it **preserves** the stored set, while `[]` explicitly clears it.
</ParamField>

<ParamField type="number">
  Initial **absolute** rank to apply on accept, from `0` to `2147483647`. For a direct-member inviter it must be strictly larger (less senior) than their own; a reach-holder inviter (no direct row) may set any rank.

  **No longer required.** Omit it and `relativeRank` both, and the server applies `relativeRank: 1` on a **new** invitation — or, on a [re-invite](#what-a-re-invite-does-to-the-grant), preserves the rank already stored. Mutually exclusive with `relativeRank` — sending both is a `400`.
</ParamField>

<ParamField type="number">
  Initial rank expressed as an **offset from the inviter**: `1` = one rung below me, `2` = two rungs below. Must be `1` – `2147483647` — `0` would mean "a peer", which the assign rule forbids, and a negative offset would mint someone senior to the inviter; both are a `400`. The **resolved** rank is bounded too, so an in-range offset that overflows once anchored is also a `400`, never a `500`.

  The offset is anchored on the inviter's **own rank if they hold a member row on this workspace**, and on **apex** (one step above rank 0) if they do not — so an owner's `relativeRank: 1` lands on rank `0`, while a rank-3 member's lands on rank `4`. The anchor turns on the row, not on what kind of actor the inviter is: an ancestor owner who *also* holds a row here measures from that row.

  Relative input passes the rank floor by construction, which is why it is the default.

  **Each resolution is a snapshot.** The offset is resolved against the caller *at the moment of the call* and frozen on the invitation as an absolute number — it does not track the inviter's later promotions or demotions. It is a snapshot of the request, not of the invitation: sending `relativeRank` again on a [re-invite](#what-a-re-invite-does-to-the-grant) takes a **fresh** snapshot against whoever is calling then, and overwrites the stored rank. Omitting both rank fields on a re-invite takes no snapshot at all and preserves what is stored.
</ParamField>

<ParamField type="string">
  Optional initial cosmetic title. On a [re-invite](#what-a-re-invite-does-to-the-grant), omitting it preserves the stored title; sending `null` clears it.
</ParamField>

<ParamField type="string">
  Service/master keys only — the **inviter** to act as. Enforced: the no-escalation and rank floors above run against *that* user's resolved standing, so a key naming a rank-5 manager may only invite at rank 6+ and only with capabilities that manager holds. Omit it to invite as the app itself (unbounded; `invitedBy` then falls back to the workspace owner) — but omit means **absent**: `actingUserId: ""` or `null` is a `400`, not a fall-through to that mode. Every top-level field this endpoint does not declare is a `400` too — `Unrecognized key: "…"`, in the body and the query string alike, for every caller. The fields this endpoint *does* declare are accepted on their own terms: `username` reaches the server intact and behaves identically to `email` and `userId`. The **body** `userId` is the one declared field on the bundle that names a person and is not the actor, so it carries a carve-out from the bundle-wide `userId` rejection; a query `userId` is refused here as everywhere else. See [Acting on behalf of a user](/sdk/workspaces/overview#acting-on-behalf-of-a-user) and [Shapes the server rejects](/sdk/workspaces/overview#shapes-the-server-rejects).
</ParamField>

## Response

Returns the created [WorkspaceInvitation](/data-models/workspace-invitation) object.

## Error Responses

<AccordionGroup>
  <Accordion title="Already a Member — 409">
    ```json theme={null}
    { "error": "That user is already a member. Change their grant via edit-member-access.", "code": "workspace/already-member" }
    ```

    Inviting the workspace's **owner** shares the code with a message of its own:

    ```json theme={null}
    { "error": "That user already owns this workspace.", "code": "workspace/already-member" }
    ```
  </Accordion>

  <Accordion title="No Escalation — 403">
    The offending values are named. Capabilities:

    ```json theme={null}
    { "error": "Cannot invite with capabilities you do not hold: edit-member-access.", "code": "workspace/no-escalation" }
    ```

    …and permissions:

    ```json theme={null}
    { "error": "Cannot invite with permissions you do not hold: deploy.", "code": "workspace/no-escalation" }
    ```
  </Accordion>

  <Accordion title="Insufficient Rank — 403">
    ```json theme={null}
    { "error": "You may only invite at a rank strictly below your own.", "code": "workspace/insufficient-rank" }
    ```

    Checked against the **resolved absolute** rank, so absolute and relative input face the identical floor. A `relativeRank` of `1` or more can never trip it.
  </Accordion>

  <Accordion title="Rank out of range — 400">
    ```json theme={null}
    { "error": "The resolved rank (2147483648) is out of range — ranks are integers from 0 to 2147483647.", "code": "workspace/invalid-body" }
    ```

    Raised **after** the offset is resolved, which is where an overflow is created: `relativeRank: 1` sent by a rank-`2147483647` inviter is two individually-valid numbers whose sum is not storable. Out-of-range `rank` / `relativeRank` **input** is refused earlier by the schema, with the same code.
  </Accordion>

  <Accordion title="Both rank coordinates supplied — 400">
    ```json theme={null}
    { "error": "relativeRank: Provide either rank (absolute) or relativeRank (offset from you), not both", "code": "workspace/invalid-body" }
    ```

    A schema rejection, so the message is prefixed with the field it was reported against. One coordinate system per request. Supplying both is refused rather than resolved by precedence — either reading could grant a rank you did not intend.
  </Accordion>

  <Accordion title="Missing Invite Accept URL — 409">
    ```json theme={null}
    { "error": "This project has no workspaces.inviteAcceptUrl configured...", "code": "workspace/missing-invite-accept-url" }
    ```

    A **project misconfiguration**, not a bad request — the payload is fine and the caller is authorized. Set [`workspaces.inviteAcceptUrl`](/sdk/workspaces/overview#project-settings) in your project settings and retry the identical request.
  </Accordion>

  <Accordion title="Invalid Path Parameter — 400">
    ```json theme={null}
    { "error": "Invalid workspace id: expected a UUID.", "code": "workspace/invalid-params" }
    ```

    Every path id on the workspaces bundle is checked for UUID shape before the route runs, so a malformed one is a plain `400` rather than a `500` from the database.
  </Accordion>

  <Accordion title="Undeclared Field — 400">
    ```json theme={null}
    { "error": "Unrecognized key: \"onBehalfOf\"", "code": "workspace/invalid-body" }
    ```

    Every workspaces endpoint declares its fields exactly, and a top-level field it does not declare is refused rather than ignored — in the request body and in the query string alike, for every caller. Two or more at once are named together: `Unrecognized keys: "onBehalfOf", "impersonate"`. An offender in the query string carries `workspace/invalid-query` instead. Send only the fields documented above, plus `actingUserId` and `projectId`, which every workspaces route accepts. See [Shapes the server rejects](/sdk/workspaces/overview#shapes-the-server-rejects).
  </Accordion>

  <Accordion title="Unparsed Body — 400">
    ```json theme={null}
    {
      "error": "This request carries a body with content-type \"text/plain;charset=UTF-8\", which no parser reads, so any `actingUserId` inside it was discarded and this request names no acting user. Send the body as application/json.",
      "code": "workspace/invalid-body"
    }
    ```

    Returned when a service/master key sends a body with a `Content-Type` other than `application/json` **and** no `actingUserId` was read. Sublay parses only `application/json`, so the actor inside such a body is discarded and the request would fall through to the unbounded path. `fetch()` sends `text/plain;charset=UTF-8` when you pass a stringified body and set no headers — set the header. An empty JSON body and a bodiless request both pass. See [Shapes the server rejects](/sdk/workspaces/overview#shapes-the-server-rejects).
  </Accordion>
</AccordionGroup>

See also: [useCreateWorkspaceInvite](/hooks/workspaces/use-create-workspace-invite) · [createWorkspaceInvite (js-sdk)](/js-sdk/workspaces) · [createWorkspaceInvite (node-sdk)](/node-sdk/workspaces)


# Decline Invite
Source: https://docs.sublay.io/v7/api-reference/workspaces/invitations/decline-invite

POST /v7/:projectId/workspace-invites/:inviteId/decline
Decline an invitation — identity-matched and verification-gated

Declines an invitation. Identity-matched (the caller must be the invite's target) **and** verification-gated — a **verified email is required**, exactly as it is to [accept](/api-reference/workspaces/invitations/accept-invite). Without that gate, someone who signed up with another person's address and never verified it could burn the real target's invite by moving it to the terminal `declined` state. This is **not** a key-bypass gate: a service or master key acting as a named `actingUserId` still requires *that* user to be verified.

Marks the invite `declined` and fires `workspace.invite.declined`.

## Path Parameters

<ParamField type="string">
  The invitation UUID.
</ParamField>

## Body Parameters

<ParamField type="string">
  Service/master keys only — the declining user (must be the invite's target). **Required for a key:** a decline is an act by the invitee, so there is no unbounded path — a key that names nobody is refused with `400 workspace/missing-user-id`.

  A plain user token omits it — the actor is the token's own user. The field is **not** ignored for such a token: sending your *own* user id is a harmless no-op, but sending **anyone else's** is a `403 workspace/unauthorized`. See [Acting on behalf of a user](/sdk/workspaces/overview#acting-on-behalf-of-a-user).
</ParamField>

## Response

```json theme={null}
{ "success": true }
```

## Error Responses

<AccordionGroup>
  <Accordion title="Email Not Verified — 403">
    ```json theme={null}
    { "error": "A verified email is required to decline an invitation.", "code": "workspace/email-not-verified" }
    ```
  </Accordion>

  <Accordion title="Not the Target — 404">
    A caller who is not the invitation's target receives the **same** `404` as a
    non-existent invitation.

    ```json theme={null}
    { "error": "Invitation not found.", "code": "workspace/invite-not-found" }
    ```
  </Accordion>

  <Accordion title="Invite Terminal — 409">
    ```json theme={null}
    { "error": "This invitation is no longer pending.", "code": "workspace/invite-terminal" }
    ```
  </Accordion>

  <Accordion title="Acting User Not Found — 404">
    ```json theme={null}
    { "error": "Acting user not found.", "code": "workspace/invalid-target" }
    ```

    The `actingUserId` a key named does not exist in this project. Naming is not authentication — the id is only looked up here.
  </Accordion>

  <Accordion title="Missing Acting User — 400">
    ```json theme={null}
    { "error": "Missing user ID", "code": "workspace/missing-user-id" }
    ```

    A service/master key called this route without naming an `actingUserId`. A decline is an act by the invitee; there is nobody to attribute it to.
  </Accordion>

  <Accordion title="Acted as Another User — 403">
    ```json theme={null}
    { "error": "Unauthorized", "code": "workspace/unauthorized" }
    ```

    A plain user token sent an `actingUserId` naming a **different** user. Only a service/master key may act as someone else.
  </Accordion>

  <Accordion title="Invalid Path Parameter — 400">
    ```json theme={null}
    { "error": "Invalid invitation id: expected a UUID.", "code": "workspace/invalid-params" }
    ```

    Every path id on the workspaces bundle is checked for UUID shape before the route runs, so a malformed one is a plain `400` rather than a `500` from the database.
  </Accordion>
</AccordionGroup>

See also: [useDeclineWorkspaceInvite](/hooks/workspaces/use-decline-workspace-invite)


# List Workspace Invites
Source: https://docs.sublay.io/v7/api-reference/workspaces/invitations/list-invites

GET /v7/:projectId/workspaces/:id/invites
List a workspace's live pending invites

Returns the workspace's **live** pending invites (`status = 'pending' AND expiresAt > now` — effectively-expired rows are excluded). Requires the `invite` capability (or owner).

## Path Parameters

<ParamField type="string">
  The workspace UUID.
</ParamField>

## Query Parameters

<ParamField type="string">
  Service/master keys only — the user to act as. Enforced: the `invite` capability (or ownership) is required *of the named user*. Omit it to read as the app itself (unbounded). See [Acting on behalf of a user](/sdk/workspaces/overview#acting-on-behalf-of-a-user).
</ParamField>

## Response

```json theme={null}
{ "data": [ /* WorkspaceInvitation[] */ ] }
```

Each item is a [WorkspaceInvitation](/data-models/workspace-invitation) object.

This is a workspace's **outbox**. For the invites addressed **to** a user, see [List My Invites](/api-reference/workspaces/invitations/list-my-invites).

## Error Responses

<AccordionGroup>
  <Accordion title="Invalid Path Parameter — 400">
    ```json theme={null}
    { "error": "Invalid workspace id: expected a UUID.", "code": "workspace/invalid-params" }
    ```

    Every path id on the workspaces bundle is checked for UUID shape before the route runs, so a malformed one is a plain `400` rather than a `500` from the database.
  </Accordion>
</AccordionGroup>

See also: [useFetchWorkspaceInvites](/hooks/workspaces/use-fetch-workspace-invites)


# List My Invites
Source: https://docs.sublay.io/v7/api-reference/workspaces/invitations/list-my-invites

GET /v7/:projectId/me/workspace-invites
The authenticated user's live pending invites

Returns the authenticated user's **live** pending invites (`status = 'pending' AND expiresAt > now`), matched by **`userId`** (no email-string matching at query time — invitations bind to `userId` at invite time or via the signup-attach step).

<Note>
  **Surfacing is NOT verification-gated** — a user sees pending invites right after signup (which nudges them to verify). The verified-email check applies when the user **acts** on an invite — [accept](/api-reference/workspaces/invitations/accept-invite) *and* [decline](/api-reference/workspaces/invitations/decline-invite).
</Note>

## Query Parameters

<ParamField type="string">
  Service/master keys only — the user to act as, whose invites are read. **Required for a key:** this is an *inbox* read, so it has no unbounded path — a key that names nobody is refused with `400 workspace/missing-user-id`.

  A plain user token omits it — the actor is the token's own user. The field is **not** ignored for such a token: sending your *own* user id is a harmless no-op, but sending **anyone else's** is a `403 workspace/unauthorized`. See [Acting on behalf of a user](/sdk/workspaces/overview#acting-on-behalf-of-a-user).
</ParamField>

## Response

```json theme={null}
{ "data": [ /* MyWorkspaceInvitation[] — see below */ ] }
```

Each item is a `MyWorkspaceInvitation`: a [WorkspaceInvitation](/data-models/workspace-invitation) object with one difference from every other invite read — `invitedBy` is a populated `{ id, name, username, avatar, reputation }` object instead of a bare user id, and a sibling `workspace: { id, name }` is included. The invitee has no other reach on the workspace they're invited to or on the inviter, so both are embedded here to make this endpoint self-sufficient for rendering an invite — see the [note on the data model page](/data-models/workspace-invitation#properties) for the full enriched shape.

## Error Responses

<AccordionGroup>
  <Accordion title="Missing Acting User — 400">
    ```json theme={null}
    { "error": "Missing user ID", "code": "workspace/missing-user-id" }
    ```

    A service/master key called this route without naming an `actingUserId`. An inbox belongs to a person; there is no app-level inbox to return.
  </Accordion>

  <Accordion title="Acted as Another User — 403">
    ```json theme={null}
    { "error": "Unauthorized", "code": "workspace/unauthorized" }
    ```

    A plain user token sent an `actingUserId` naming a **different** user. Only a service/master key may act as someone else.
  </Accordion>
</AccordionGroup>

See also: [useFetchMyWorkspaceInvites](/hooks/workspaces/use-fetch-my-workspace-invites)


# Resend Invite
Source: https://docs.sublay.io/v7/api-reference/workspaces/invitations/resend-invite

POST /v7/:projectId/workspaces/:id/invites/:inviteId/resend
Refresh a lapsed pending invitation and resend the email

Refreshes a pending invitation — sets `expiresAt = now + 14 days` and resends the email. **Valid on any `pending` invite, including one past `expiresAt`** (resend = refresh a lapsed invite). A **terminal** invite (`accepted`/`declined`/`revoked`) → `409`. Requires the `invite` capability (or owner).

<Note>
  Resend **emits no webhook** — the status stays `pending`, so there is no lifecycle transition.
</Note>

<Warning>
  **Requires `workspaces.inviteAcceptUrl` on the project**, exactly as [Create Invite](/api-reference/workspaces/invitations/create-invite) does — resending an email that has nowhere to deep-link is equally pointless. Without it this endpoint returns `409 workspace/missing-invite-accept-url` and the invitation's `expiresAt` is left untouched. See [Project settings](/sdk/workspaces/overview#project-settings).
</Warning>

## Path Parameters

<ParamField type="string">
  The workspace UUID.
</ParamField>

<ParamField type="string">
  The invitation UUID.
</ParamField>

## Body Parameters

<ParamField type="string">
  Service/master keys only — the user to act as. Enforced: the `invite` capability (or ownership) is required *of the named user*. Omit it to act as the app itself (unbounded). See [Acting on behalf of a user](/sdk/workspaces/overview#acting-on-behalf-of-a-user).
</ParamField>

## Response

Returns the refreshed [WorkspaceInvitation](/data-models/workspace-invitation) object.

## Error Responses

<AccordionGroup>
  <Accordion title="Invite Not Found — 404">
    ```json theme={null}
    { "error": "Invitation not found.", "code": "workspace/invite-not-found" }
    ```

    Returned when no invitation with that id exists on this workspace — including when the id belongs to a *different* workspace's invitation.
  </Accordion>

  <Accordion title="Missing Invite Accept URL — 409">
    ```json theme={null}
    { "error": "This project has no workspaces.inviteAcceptUrl configured...", "code": "workspace/missing-invite-accept-url" }
    ```

    A **project misconfiguration**, not a bad request. The row is not touched — `expiresAt` is unchanged and no email is sent. Set [`workspaces.inviteAcceptUrl`](/sdk/workspaces/overview#project-settings) and retry.
  </Accordion>

  <Accordion title="Terminal Invite — 409">
    ```json theme={null}
    { "error": "This invitation is no longer pending.", "code": "workspace/invite-terminal" }
    ```

    The invitation is `accepted`, `declined`, or `revoked`. Note an invitation merely past its `expiresAt` is **not** terminal — resending one is the documented purpose of this endpoint.
  </Accordion>

  <Accordion title="Invalid Path Parameter — 400">
    ```json theme={null}
    { "error": "Invalid workspace id: expected a UUID.", "code": "workspace/invalid-params" }
    ```

    Every path id on the workspaces bundle is checked for UUID shape before the route runs, so a malformed one is a plain `400` rather than a `500` from the database.
  </Accordion>

  <Accordion title="Undeclared Field — 400">
    ```json theme={null}
    { "error": "Unrecognized key: \"onBehalfOf\"", "code": "workspace/invalid-body" }
    ```

    Every workspaces endpoint declares its fields exactly, and a top-level field it does not declare is refused rather than ignored — in the request body and in the query string alike, for every caller. Two or more at once are named together: `Unrecognized keys: "onBehalfOf", "impersonate"`. An offender in the query string carries `workspace/invalid-query` instead. Send only the fields documented above, plus `actingUserId` and `projectId`, which every workspaces route accepts. See [Shapes the server rejects](/sdk/workspaces/overview#shapes-the-server-rejects).
  </Accordion>

  <Accordion title="Unparsed Body — 400">
    ```json theme={null}
    {
      "error": "This request carries a body with content-type \"text/plain;charset=UTF-8\", which no parser reads, so any `actingUserId` inside it was discarded and this request names no acting user. Send the body as application/json.",
      "code": "workspace/invalid-body"
    }
    ```

    Returned when a service/master key sends a body with a `Content-Type` other than `application/json` **and** no `actingUserId` was read. Sublay parses only `application/json`, so the actor inside such a body is discarded and the request would fall through to the unbounded path. `fetch()` sends `text/plain;charset=UTF-8` when you pass a stringified body and set no headers — set the header. An empty JSON body and a bodiless request both pass. See [Shapes the server rejects](/sdk/workspaces/overview#shapes-the-server-rejects).
  </Accordion>
</AccordionGroup>

See also: [useResendWorkspaceInvite](/hooks/workspaces/use-resend-workspace-invite) · [Project settings](/sdk/workspaces/overview#project-settings)


# Revoke Invite
Source: https://docs.sublay.io/v7/api-reference/workspaces/invitations/revoke-invite

POST /v7/:projectId/workspaces/:id/invites/:inviteId/revoke
Revoke a pending invitation

Marks a pending invitation `revoked`. Requires the `invite` capability (or owner). Fires `workspace.invite.revoked`.

## Path Parameters

<ParamField type="string">
  The workspace UUID.
</ParamField>

<ParamField type="string">
  The invitation UUID.
</ParamField>

## Body Parameters

<ParamField type="string">
  Service/master keys only — the user to act as. Enforced: the `invite` capability (or ownership) is required *of the named user*. Omit it to act as the app itself (unbounded). See [Acting on behalf of a user](/sdk/workspaces/overview#acting-on-behalf-of-a-user).
</ParamField>

## Response

```json theme={null}
{ "success": true }
```

## Error Responses

<AccordionGroup>
  <Accordion title="Invite Not Found — 404">
    ```json theme={null}
    { "error": "Invitation not found.", "code": "workspace/invite-not-found" }
    ```
  </Accordion>

  <Accordion title="Invalid Path Parameter — 400">
    ```json theme={null}
    { "error": "Invalid workspace id: expected a UUID.", "code": "workspace/invalid-params" }
    ```

    Every path id on the workspaces bundle is checked for UUID shape before the route runs, so a malformed one is a plain `400` rather than a `500` from the database.
  </Accordion>

  <Accordion title="Undeclared Field — 400">
    ```json theme={null}
    { "error": "Unrecognized key: \"onBehalfOf\"", "code": "workspace/invalid-body" }
    ```

    Every workspaces endpoint declares its fields exactly, and a top-level field it does not declare is refused rather than ignored — in the request body and in the query string alike, for every caller. Two or more at once are named together: `Unrecognized keys: "onBehalfOf", "impersonate"`. An offender in the query string carries `workspace/invalid-query` instead. Send only the fields documented above, plus `actingUserId` and `projectId`, which every workspaces route accepts. See [Shapes the server rejects](/sdk/workspaces/overview#shapes-the-server-rejects).
  </Accordion>

  <Accordion title="Unparsed Body — 400">
    ```json theme={null}
    {
      "error": "This request carries a body with content-type \"text/plain;charset=UTF-8\", which no parser reads, so any `actingUserId` inside it was discarded and this request names no acting user. Send the body as application/json.",
      "code": "workspace/invalid-body"
    }
    ```

    Returned when a service/master key sends a body with a `Content-Type` other than `application/json` **and** no `actingUserId` was read. Sublay parses only `application/json`, so the actor inside such a body is discarded and the request would fall through to the unbounded path. `fetch()` sends `text/plain;charset=UTF-8` when you pass a stringified body and set no headers — set the header. An empty JSON body and a bodiless request both pass. See [Shapes the server rejects](/sdk/workspaces/overview#shapes-the-server-rejects).
  </Accordion>
</AccordionGroup>


# Fetch Member Standing
Source: https://docs.sublay.io/v7/api-reference/workspaces/members/fetch-member-standing

GET /v7/:projectId/workspaces/:id/members/:userId
A user's full resolved standing on a workspace, addressed by userId

Returns a single user's full standing on a workspace, addressed by **`userId`** (not a membership-row id, so it works for users with no direct row). Returns the same unified shape as one roster row, computed on demand for **any** relation — direct `member`, this workspace's `owner`, an `ancestor-owner`, or a `reach-holder`. Returns empty/none **only** if the user has no relation at all.

Requires **roster visibility** — any relation to the workspace (owner, ancestor-owner, member, or reach-holder).

`reasons` is an array of **structured entries** — `{ type, viaWorkspaceId? }` — the same object shape a [roster](/api-reference/workspaces/members/list-members) entry's `reasons` carries. `viaWorkspaceId` names the granting ancestor and appears on `ancestor-owner` / `reach-holder` only.

<Warning>
  **The authority-bearing fields are fenced, and the gate is scoped to THIS workspace.** `capabilities`, `permissions`, `rank` and `relativeRank` are **omitted from the response** (absent — not `null`) unless the caller:

  * holds one of the four people-operating capabilities on this workspace — `invite`, `remove-member`, `edit-member-access`, `edit-member-profile`; **or**
  * is this workspace's `owner` or an `ancestor-owner`; **or**
  * is asking about **themselves** (a caller always sees their own access); **or**
  * is a service/master key acting as **itself** (naming no `actingUserId`). A key that **does** name one is fenced exactly as that user is — see [Acting on behalf of a user](/sdk/workspaces/overview#acting-on-behalf-of-a-user).

  The gate is a **per-node** verdict, not a global one: clearing it here says nothing about any other node, and clearing it elsewhere says nothing about here. "On this workspace" means your **resolved** standing on it — including capabilities [reaching](/data-models/workspace#reach-and-the-wall-door-rule) in from an ancestor through an unbroken open inherit chain, and ownership from any ancestor — but not authority that stops at a **sealed** boundary. The [roster read](/api-reference/workspaces/members/list-members) takes the same verdict independently for each `descendant-member` row it returns, so the two reads agree node for node.

  Everything else — `user`, `reasons`, `title`, `metadata` — is visible to any relation. Treat these four fields as optional in your types.

  `relativeRank` is fenced **with** `rank`, not beside it: it is `rank` minus the caller's own anchor, a number the caller already knows, so returning it to a fenced caller would reconstruct the fenced `rank` exactly.
</Warning>

## Path Parameters

<ParamField type="string">
  The workspace UUID.
</ParamField>

<ParamField type="string">
  The target user whose standing to read.
</ParamField>

## Query Parameters

<ParamField type="string">
  Service/master keys only — the user to act as. Enforced: roster visibility **and** the authority-field fence above both evaluate against the named user, so a key acting as a plain member receives the fenced standing (and the full one when asking about that user themselves). Omit it to read as the app itself (unfenced). See [Acting on behalf of a user](/sdk/workspaces/overview#acting-on-behalf-of-a-user).
</ParamField>

## Response

Caller who may see authority fields (a people-operator, an owner, or the user themselves):

```json theme={null}
{
  "user": { "id": "u_pat" },
  "reasons": [
    { "type": "member" },
    { "type": "ancestor-owner", "viaWorkspaceId": "ws_root" }
  ],
  "capabilities": ["view", "invite", "remove-member"],
  "permissions": ["deploy"],
  "rank": 5,
  "relativeRank": 2,
  "title": "Frontend Lead",
  "metadata": {}
}
```

Caller with a plain relation, reading **someone else's** standing — the four authority fields are simply absent:

```json theme={null}
{
  "user": { "id": "u_pat" },
  "reasons": [
    { "type": "member" },
    { "type": "ancestor-owner", "viaWorkspaceId": "ws_root" }
  ],
  "title": "Frontend Lead",
  "metadata": {}
}
```

* `reasons` is always present; `viaWorkspaceId` appears on `ancestor-owner` / `reach-holder` entries only.
* `capabilities` is the **resolved** set (direct + reach + ownership). **`view` is implied by every other capability** — anyone with standing resolves with `view`, including a member whose stored `capabilities` array is empty. A user with no relation at all returns `reasons: []` and an empty capability set.
* `permissions` is **per-node** (the direct membership on this workspace only; may be empty).
* `rank` is the direct-membership rank, or `null` for owners / ancestor-owners / reach-only holders (they sit outside the numbered ladder).
* `relativeRank` is that same position expressed as an **offset from the caller** — `2` above means the target sits two rungs below you; a negative value means they are *senior* to you, and `0` means they are your peer. `null` exactly when `rank` is `null`. The caller's own anchor is their member row on this workspace if they hold one, and apex (one step above rank 0) otherwise — so an owner reads a rank-0 member back as `1`. See [rank semantics](/data-models/workspace-member#two-coordinates-rank-and-relativerank).

## Error Responses

<AccordionGroup>
  <Accordion title="Invalid Path Parameter — 400">
    ```json theme={null}
    { "error": "Invalid workspace id: expected a UUID.", "code": "workspace/invalid-params" }
    ```

    Every path id on the workspaces bundle is checked for UUID shape before the route runs, so a malformed one is a plain `400` rather than a `500` from the database.
  </Accordion>
</AccordionGroup>

See also: [useFetchWorkspaceMemberStanding](/hooks/workspaces/use-fetch-workspace-member-standing) · [List Members](/api-reference/workspaces/members/list-members) · [Read Authority](/api-reference/workspaces/fetch-authority)


# Leave Workspace
Source: https://docs.sublay.io/v7/api-reference/workspaces/members/leave-workspace

DELETE /v7/:projectId/workspaces/:id/members/me
Remove your own membership on this node

Removes the caller's own membership on **this node only** (self-service, no capability). Leaving a parent while still owning a child is fine — ownership is independent of membership. Fires `workspace.member.removed`.

<Note>
  An **owner** has no member row and cannot leave via this path — an owner exits by transferring ownership or deleting the workspace. Sole-owner protection blocks a sole owner from leaving without transferring first. If the caller has **no direct member row here** (only reaches in from an ancestor), leave is a no-op / 404.
</Note>

## Path Parameters

<ParamField type="string">
  The workspace UUID.
</ParamField>

## Body Parameters

<ParamField type="string">
  Service/master keys only — the user to act as, whose membership is removed (sent in the body so the act-as-user path works on `DELETE`). **Required for a key:** leaving is inherently self-service, so there is no unbounded path — a key that names nobody is refused with `400 workspace/missing-user-id`.

  A plain user token omits it — the actor is the token's own user. The field is **not** ignored for such a token: sending your *own* user id is a harmless no-op, but sending **anyone else's** is a `403 workspace/unauthorized`. See [Acting on behalf of a user](/sdk/workspaces/overview#acting-on-behalf-of-a-user).
</ParamField>

## Response

`204 No Content` on success.

## Error Responses

<AccordionGroup>
  <Accordion title="Not a Member — 404">
    ```json theme={null}
    { "error": "You are not a direct member of this workspace.", "code": "workspace/not-found" }
    ```
  </Accordion>

  <Accordion title="Sole Owner — 409">
    ```json theme={null}
    { "error": "The workspace owner cannot leave. Transfer ownership or delete the workspace first.", "code": "workspace/sole-owner" }
    ```
  </Accordion>

  <Accordion title="Missing Acting User — 400">
    ```json theme={null}
    { "error": "Missing user ID", "code": "workspace/missing-user-id" }
    ```

    A service/master key called this route without naming an `actingUserId`. Leaving removes *your own* membership row; there is none for the app itself. To remove somebody else, use [Remove Member](/api-reference/workspaces/members/remove-member).
  </Accordion>

  <Accordion title="Acted as Another User — 403">
    ```json theme={null}
    { "error": "Unauthorized", "code": "workspace/unauthorized" }
    ```

    A plain user token sent an `actingUserId` naming a **different** user. Only a service/master key may act as someone else.
  </Accordion>

  <Accordion title="Invalid Path Parameter — 400">
    ```json theme={null}
    { "error": "Invalid workspace id: expected a UUID.", "code": "workspace/invalid-params" }
    ```

    Every path id on the workspaces bundle is checked for UUID shape before the route runs, so a malformed one is a plain `400` rather than a `500` from the database.
  </Accordion>
</AccordionGroup>


# List Members
Source: https://docs.sublay.io/v7/api-reference/workspaces/members/list-members

GET /v7/:projectId/workspaces/:id/members
The unified roster — one entry per distinct user, each with a reasons array

Returns the roster as a **single unified array, one entry per distinct user**, each carrying a `reasons` array explaining *why* the user appears. Requires **roster visibility** — **any relation** to the workspace (owner, ancestor-owner, member, or reach-holder). A caller with no relation gets a `404`.

**Always returned in full — never paginated.** `include` flags only *add* entries; they never change the shape. `countOnly` is the numbers-only escape hatch.

<Warning>
  **There is no `page` or `limit` on this route, and sending them is a `400`.** This route declares exactly the query parameters listed below, and anything else is refused rather than ignored — `?page=2&limit=10` comes back as `{ "error": "Unrecognized keys: \"page\", \"limit\"", "code": "workspace/invalid-query" }`. A paginating client therefore fails on its first call instead of receiving the **entire** roster every time and mistaking it for page 1.

  The response carries no `pagination` object precisely because there is none. If you need numbers rather than rows — a seat count, a badge — use [`countOnly=true`](#query-parameters), which returns per-reason counts and a distinct-user total **without ever materializing the roster array**. If you need a windowed UI, slice client-side after the single read.
</Warning>

## Path Parameters

<ParamField type="string">
  The workspace UUID.
</ParamField>

## Query Parameters

<ParamField type="string">
  Comma-separated add-on buckets. Default returns `owner` + direct `member`s. Options: `ancestorOwners`, `reachHolders`, `descendants`.
</ParamField>

<ParamField type="boolean">
  When `true`, returns per-reason counts + a distinct-user total instead of the array (never materializes the roster). Honors the same includes.
</ParamField>

<ParamField type="string">
  Service/master keys only — the user to act as. Enforced: roster visibility **and** the authority-field fence below both evaluate against the named user, so a key acting as a plain member receives the fenced view. Omit it to read as the app itself (unfenced) — where "omit" means **absent**: `actingUserId: ""` or `null` is a `400`, not a fall-through to that mode. See [Acting on behalf of a user](/sdk/workspaces/overview#acting-on-behalf-of-a-user) and [Shapes the server rejects](/sdk/workspaces/overview#shapes-the-server-rejects).
</ParamField>

<Note>
  Those three, plus `projectId`, are the whole query vocabulary of this route. Any other parameter is a `400 workspace/invalid-query` — the two exceptions across the bundle are the cache-busters `_` and `_t`, which are dropped before the request is read. An unrecognized *value* inside `include` is a different matter: it is ignored, not rejected.
</Note>

## Reasons

Each entry's `reasons[]` contains `{ type, ...detail }` objects. A user present for several reasons is **one** entry carrying multiple reasons.

| `type`              | Detail                                                                     | Counted as a seat?                      |
| ------------------- | -------------------------------------------------------------------------- | --------------------------------------- |
| `owner`             | —                                                                          | **Yes**                                 |
| `member`            | `rank`, `relativeRank`, `capabilities`, `permissions`, `title`, `metadata` | **Yes**                                 |
| `ancestor-owner`    | `viaWorkspaceId`                                                           | No (informational)                      |
| `reach-holder`      | `viaWorkspaceId`, `capabilities`                                           | No (informational)                      |
| `descendant-member` | `workspaceId`, `rank`, `capabilities` — **no `relativeRank`**              | Counted under the `descendants` include |

<Note>
  **`descendant-member` rows carry `rank` but never `relativeRank`.** Rank is **per-workspace**, so an offset measured against your standing on *this* node against a rank on *another* node would be arithmetic across two different ladders — a number that looks authoritative and is wrong. The field is uniformly absent on descendant rows rather than present only where a per-node anchor happens to have been resolved, so its presence never depends on who is asking. Their absolute `rank` is still there.

  **Presence and fencing follow different rules on these rows, deliberately.** `relativeRank` is *uniformly* absent from every `descendant-member` row for every caller, while the fence below is decided **per node**. Do not read the two as one rule. A field that shows up for some callers and not others is awkward to consume; an authority field that is fenced on some nodes and not others is a hole — so the cosmetic inconsistency is accepted and the security one is not.
</Note>

<Warning>
  **The authority-bearing detail fields are fenced, and the gate is evaluated PER NODE — not once per request.** `capabilities`, `permissions`, `rank` and `relativeRank` are **omitted from a reason** (absent — not `null`) on **other users'** entries unless the caller, judged **on the workspace that reason belongs to**:

  * holds one of the four people-operating capabilities there — `invite`, `remove-member`, `edit-member-access`, `edit-member-profile`; **or**
  * is that workspace's `owner` or an `ancestor-owner`; **or**
  * is a service/master key acting as **itself** (naming no `actingUserId`). A key that **does** name one is fenced exactly as that user is — see [Acting on behalf of a user](/sdk/workspaces/overview#acting-on-behalf-of-a-user).

  For `owner`, `member`, `ancestor-owner` and `reach-holder` reasons, that workspace **is** the one in the path. For a `descendant-member` reason it is the descendant named by the reason's own `workspaceId`, so the verdict is re-taken there. "Judged on that node" means your **resolved** standing there — which includes capabilities [reaching](/data-models/workspace#reach-and-the-wall-door-rule) in through an unbroken open inherit chain, and ownership from any ancestor. What it does *not* include is authority that stops at a **sealed** boundary.

  The caller's **own** entry always carries them in full, on every node, so anyone can discover their own access. Who is on the roster — `user`, the reason `type`s, `title`, `metadata`, `viaWorkspaceId`, `workspaceId` — stays visible to any relation. Treat the four fields as optional in your types.

  `relativeRank` is fenced **with** `rank`, not beside it: it is `rank` minus the caller's own anchor, a number the caller already knows, so returning it to a fenced caller would reconstruct the fenced `rank` exactly.
</Warning>

<Note>
  **Worked example — operating people on the parent is not operating people on the child.** Workspace `P` has a **sealed** child `C` (`inheritsFromParent: false`). Bob holds `invite` on `P`; on `C` he is a plain rank-5 member with no capabilities. Dana is a rank-2 member of `C`.

  Bob calls `GET /workspaces/P/members?include=descendants`:

  * **Dana's `descendant-member` reason (node `C`)** — `workspaceId` only. Bob still learns *that* Dana is on `C`, because he has a relation to `C` and its roster is unsealed to him; but `rank`, `capabilities` and `permissions` are omitted, because on `C` he operates nobody. His `invite` on `P` buys him nothing there — the seal stops it from reaching down.
  * **Bob's own `descendant-member` reason (node `C`)** — full. A caller always sees their own access.
  * Had `C` been **open** instead of sealed, Bob's `invite` would reach into `C`, he would clear the fence there, and Dana's authority fields would be present — correctly.

  Sealing ("may I see this roster at all?") and the fence ("may I see its members' authority?") are two different tiers, and clearing the first does not clear the second. On any given node, `include=descendants` hands you exactly the authority fields that node's own roster read (`GET /workspaces/C/members`) would hand you — never more.
</Note>

## Response (array mode)

```json theme={null}
{
  "data": [
    {
      "user": { "id": "u_pat" },
      "reasons": [
        { "type": "member", "rank": 5, "relativeRank": 2, "capabilities": ["view", "invite"], "permissions": [], "title": "Frontend Lead", "metadata": {} },
        { "type": "ancestor-owner", "viaWorkspaceId": "ws_root" }
      ]
    }
  ],
  "total": 1
}
```

The same roster read by a caller who cannot manage people here — the `member` reason keeps its identity fields but drops the authority-bearing ones:

```json theme={null}
{
  "data": [
    {
      "user": { "id": "u_pat" },
      "reasons": [
        { "type": "member", "title": "Frontend Lead", "metadata": {} },
        { "type": "ancestor-owner", "viaWorkspaceId": "ws_root" }
      ]
    }
  ],
  "total": 1
}
```

## Response (`countOnly=true`)

```json theme={null}
{
  "counts": { "owner": 1, "member": 12, "ancestorOwner": 2, "reachHolder": 3, "descendantMember": 40 },
  "total": 13,
  "distinctUsers": 52
}
```

`total` is the **distinct-user seat number** (owner + direct members), **not** the sum of buckets (buckets overlap). Ancestor-owners and reach-holders are never counted as seats.

## Error Responses

<AccordionGroup>
  <Accordion title="Invalid Path Parameter — 400">
    ```json theme={null}
    { "error": "Invalid workspace id: expected a UUID.", "code": "workspace/invalid-params" }
    ```

    Every path id on the workspaces bundle is checked for UUID shape before the route runs, so a malformed one is a plain `400` rather than a `500` from the database.
  </Accordion>

  <Accordion title="Undeclared Query Parameter — 400">
    ```json theme={null}
    { "error": "Unrecognized key: \"page\"", "code": "workspace/invalid-query" }
    ```

    This route declares `include`, `countOnly`, `actingUserId` and `projectId`, and refuses anything else rather than ignoring it. Two or more at once are named together: `Unrecognized keys: "page", "limit"`. See [Shapes the server rejects](/sdk/workspaces/overview#shapes-the-server-rejects).
  </Accordion>
</AccordionGroup>

See also: [useFetchWorkspaceMembers](/hooks/workspaces/use-fetch-workspace-members) · [Fetch Member Standing](/api-reference/workspaces/members/fetch-member-standing)


# Remove From Subtree
Source: https://docs.sublay.io/v7/api-reference/workspaces/members/remove-from-subtree

POST /v7/:projectId/workspaces/:id/members/:userId/remove-from-subtree
Offboarding convenience — remove a user from this workspace and the descendants you can reach

Removes the target user's **direct** memberships on this workspace and every descendant **you can reach**, in one action. An **owner** (or ancestor owner) reaches the whole subtree via the god-path; a **non-owner** reaches a descendant when they hold `remove-member` there — which they may hold either by reaching in through an unbroken open inherit chain, or by holding a direct member row on that node. So sealing (`inheritsFromParent = false`) stops authority reaching in **from above**; it does not stop authority held **locally**. A non-owner who is a direct member of a sealed child with `remove-member` there does sweep it. **The credential does not widen this** — `actingUserId` is *required* here, so a service/master key always sweeps as the user it names, with that user's reach; act as the owner for a full sweep. Reach-based access auto-revokes with the relevant ancestor membership. Each membership-row deletion fires `workspace.member.removed`. Rank rules apply **per node** — the sweep is refused (`403 workspace/insufficient-rank`) if you are outranked by the target at any node where you both hold a direct member row.

**Owned-descendant handling — block + report.** Because owners have no member row, this sweep does **not** cover descendant workspaces the user *owns*. Instead it **blocks and reports** them (`409 workspace/owns-descendants`) rather than silently orphaning ownership. An admin or any ancestor owner then reassigns each via [transfer-ownership](/api-reference/workspaces/transfer-ownership) or deletes it. **No silent ownership change.**

<Warning>
  **A non-owner's sweep may be partial — check `skipped` before you call someone offboarded.** If the target still holds a membership in a descendant you cannot reach, the `200` reports it in `skippedCount` / `skipped`. `removedCount` alone does **not** mean the user is gone from the subtree: treat any `skippedCount > 0` as "still a member somewhere" and escalate to an owner or ancestor owner of that node. Only an **owner or ancestor owner** is guaranteed `skippedCount: 0`. A service/master key is **not** — it must name an `actingUserId` on this route, and inherits that user's reach, so a key acting as a mid-level admin can absolutely come back with `skippedCount > 0`. See [Acting on behalf of a user](/sdk/workspaces/overview#acting-on-behalf-of-a-user).
</Warning>

## Path Parameters

<ParamField type="string">
  The workspace UUID (subtree root).
</ParamField>

<ParamField type="string">
  The user to offboard.
</ParamField>

## Body Parameters

<ParamField type="string">
  Service/master keys only — the **acting** user (must hold `remove-member`, rank-bounded per node). **Required** for a key: there is no unbounded path on this route, so the sweep's reach is always that user's — a key that names nobody is refused with `400 workspace/missing-user-id`. Name the **owner** for a full-subtree sweep.

  A plain user token omits it — the actor is the token's own user. The field is **not** ignored for such a token: sending your *own* user id is a harmless no-op, but sending **anyone else's** is a `403 workspace/unauthorized`. See [Acting on behalf of a user](/sdk/workspaces/overview#acting-on-behalf-of-a-user).
</ParamField>

## Response

```json theme={null}
{
  "removedCount": 3,
  "removed": [
    { "workspaceId": "ws_a", "userId": "u_pat" },
    { "workspaceId": "ws_b", "userId": "u_pat" },
    { "workspaceId": "ws_c", "userId": "u_pat" }
  ],
  "skippedCount": 2,
  "skipped": [
    { "id": "ws_d", "name": "Finance", "reason": "out-of-reach" },
    { "id": null, "name": null, "reason": "out-of-reach" }
  ]
}
```

<ResponseField name="removedCount" type="number">
  How many membership rows were torn down.
</ResponseField>

<ResponseField name="removed" type="object[]">
  One `{ workspaceId, userId }` entry per removed membership.
</ResponseField>

<ResponseField name="skippedCount" type="number">
  How many memberships the target **retained** because the sweep could not reach them. `0` for an owner or ancestor owner. A service/master key gets whatever its **acting user** gets — the credential grants no extra reach here. Equals `skipped.length`.
</ResponseField>

<ResponseField name="skipped" type="object[]">
  One entry per retained membership — the descendants where the target is *still* a member after this call.

  * `id` / `name` — the workspace, mirroring the `ownedWorkspaces` shape on the 409. **Both are `null` when you have no standing on that workspace**: the sweep tells you a membership survived, but does not disclose the existence or name of a sealed sub-workspace you have no authority over. This is the same sealing fence the [roster read](/api-reference/workspaces/members/list-members) applies to `include=descendants`. Get an owner or ancestor owner of that branch to finish the offboarding.
  * `reason` — currently always `"out-of-reach"`: your authority does not extend to removing members there.

  Only descendants where the target **actually still holds a direct membership** appear. Unreachable descendants the target was never a member of are never listed — the report is scoped to what actually survived the offboarding, not to the shape of the tree.
</ResponseField>

<Note>
  `skipped` covers surviving **memberships** only. Descendants the target *owns* are handled by the separate `409 workspace/owns-descendants` block, and an owned descendant outside a non-owner's reach is neither swept nor reported here — an owner re-running the sweep will surface it as the 409.
</Note>

## Error Responses

<AccordionGroup>
  <Accordion title="Owns Descendants — 409">
    ```json theme={null}
    {
      "error": "The user owns workspaces in this subtree. Transfer or delete them first.",
      "code": "workspace/owns-descendants",
      "ownedWorkspaces": [{ "id": "ws_d", "name": "Client X" }]
    }
    ```
  </Accordion>

  <Accordion title="Insufficient Rank — 403">
    ```json theme={null}
    { "error": "You may only remove members ranked strictly below you.", "code": "workspace/insufficient-rank" }
    ```
  </Accordion>

  <Accordion title="Missing Acting User — 400">
    ```json theme={null}
    { "error": "Missing user ID", "code": "workspace/missing-user-id" }
    ```

    A service/master key called this route without naming an `actingUserId`. The sweep's reach is defined by the acting user's standing per node, so it must be performed *as* somebody.
  </Accordion>

  <Accordion title="Acted as Another User — 403">
    ```json theme={null}
    { "error": "Unauthorized", "code": "workspace/unauthorized" }
    ```

    A plain user token sent an `actingUserId` naming a **different** user. Only a service/master key may act as someone else.
  </Accordion>

  <Accordion title="Invalid Path Parameter — 400">
    ```json theme={null}
    { "error": "Invalid workspace id: expected a UUID.", "code": "workspace/invalid-params" }
    ```

    Every path id on the workspaces bundle is checked for UUID shape before the route runs, so a malformed one is a plain `400` rather than a `500` from the database.
  </Accordion>
</AccordionGroup>


# Remove Member
Source: https://docs.sublay.io/v7/api-reference/workspaces/members/remove-member

DELETE /v7/:projectId/workspaces/:id/members/:userId
Remove a member (rank-bounded; sole-owner protected)

Removes a member from a workspace. Requires the `remove-member` capability and is **rank-bounded** (act only on strictly-lower ranks). Fires `workspace.member.removed`.

<Note>
  Owners have no member row, so removal targets member rows only. **Sole-owner protection:** the owner cannot be removed while sole owner — they must transfer ownership first.
</Note>

## Path Parameters

<ParamField type="string">
  The workspace UUID.
</ParamField>

<ParamField type="string">
  The member to remove.
</ParamField>

## Body Parameters

<ParamField type="string">
  Service/master keys only — the **acting** user (sent in the body so the act-as-user path works on `DELETE`; the path `:userId` is the target). **Required for a key:** this route has no unbounded path, so a key that names nobody is refused with `400 workspace/missing-user-id`. The `remove-member` capability and the rank bound are enforced against the named user — act as the **owner** for an unrestricted removal.

  A plain user token omits it — the actor is the token's own user. The field is **not** ignored for such a token: sending your *own* user id is a harmless no-op, but sending **anyone else's** is a `403 workspace/unauthorized`. See [Acting on behalf of a user](/sdk/workspaces/overview#acting-on-behalf-of-a-user).
</ParamField>

## Response

`204 No Content` on success.

## Error Responses

<AccordionGroup>
  <Accordion title="Insufficient Rank — 403">
    ```json theme={null}
    { "error": "You may only remove members ranked strictly below you.", "code": "workspace/insufficient-rank" }
    ```
  </Accordion>

  <Accordion title="Sole Owner — 409">
    ```json theme={null}
    { "error": "The workspace owner cannot be removed. Transfer ownership first.", "code": "workspace/sole-owner" }
    ```
  </Accordion>

  <Accordion title="Missing Acting User — 400">
    ```json theme={null}
    { "error": "Missing user ID", "code": "workspace/missing-user-id" }
    ```

    A service/master key called this route without naming an `actingUserId`. Removal is rank-bounded against the remover's own standing, so it must be performed *as* somebody — act as the owner for an unrestricted removal.
  </Accordion>

  <Accordion title="Acted as Another User — 403">
    ```json theme={null}
    { "error": "Unauthorized", "code": "workspace/unauthorized" }
    ```

    A plain user token sent an `actingUserId` naming a **different** user. Only a service/master key may act as someone else.
  </Accordion>

  <Accordion title="Invalid Path Parameter — 400">
    ```json theme={null}
    { "error": "Invalid workspace id: expected a UUID.", "code": "workspace/invalid-params" }
    ```

    Every path id on the workspaces bundle is checked for UUID shape before the route runs, so a malformed one is a plain `400` rather than a `500` from the database.
  </Accordion>
</AccordionGroup>


# Update Member
Source: https://docs.sublay.io/v7/api-reference/workspaces/members/update-member

PATCH /v7/:projectId/workspaces/:id/members/:userId
Edit a member's access or profile fields, with two capability tiers

Edits a member, with **two capability tiers by field sensitivity**:

* **Powerful fields** (`capabilities`, `permissions`, and rank — as either `rank` or `relativeRank`) require **`edit-member-access`**, plus the [rank rule](/data-models/workspace-member#rank-semantics) and the [no-escalation](/data-models/workspace-member#no-privilege-escalation) guard.
* **Cosmetic fields** (`title`, `metadata`) require only **`edit-member-profile`**. A member editing **their own `title`** needs no capability.

Rank moves in **either coordinate** — `rank` (absolute) or `relativeRank` (an offset from the actor) — and they are **mutually exclusive**; sending both is a `400`. Omitting **both** means **rank unchanged**: unlike [Create Invite](/api-reference/workspaces/invitations/create-invite), this endpoint has no value default, so editing someone's capabilities never moves them on the ladder. See [choosing a rank](/sdk/workspaces/overview#choosing-a-rank).

**Grant vs strip asymmetry:** you may only *add* a capability/permission you hold on the target node (resolved set, including via reach); *stripping* is governed by **rank alone**. **Cross-node rank is not compared** — the rank guard runs only when actor and target share a member row on the same workspace.

## Path Parameters

<ParamField type="string">
  The workspace UUID.
</ParamField>

<ParamField type="string">
  The target member's user id.
</ParamField>

## Body Parameters

All optional; the controller enforces which tier each touched field belongs to. At least one must be provided.

<ParamField type="string[]">
  New capability set (powerful — `edit-member-access`).
</ParamField>

<ParamField type="string[]">
  New permission set (powerful — `edit-member-access`).
</ParamField>

<ParamField type="number">
  New **absolute** rank, `0` – `2147483647` (powerful — `edit-member-access` + rank rules). Mutually exclusive with `relativeRank`. Omitting both leaves rank unchanged.
</ParamField>

<ParamField type="number">
  New rank expressed as an **offset from the acting user**: `1` = one rung below me. Must be `1` – `2147483647` — `0` (a peer) and negatives are a `400`. The **resolved** value is bounded too, so an in-range offset that overflows once anchored is a `400`, not a `500`. Mutually exclusive with `rank`, and with **no default**: omitting both leaves rank unchanged.

  Anchored on the actor's **own rank if they hold a member row on this workspace**, apex (one step above rank 0) otherwise — the anchor turns on the row, not on what kind of actor they are. Resolved to an absolute number at write time and stored absolute; it is a **snapshot** and does not follow the actor's own rank afterwards.

  Because an in-ladder anchor is `>= 0` and the offset is `>= 1`, a direct-member actor can never reach rank `0` this way — and neither can they by naming absolute `rank: 0`, which the assign rule below refuses for exactly the same reason (nothing is strictly below `0`). There is no separate rank-0 guard: rank `0` is effectively owner-only because the owner skips the rank block, not because a check names them. An actor with **no** member row here — an ancestor owner, or a cross-node reach holder — also skips it.

  A service/master key is **not** on that list. Unlike [Create Invite](/api-reference/workspaces/invitations/create-invite), this route has no unbounded path: `actingUserId` is required, so a key is always *somebody*, and it faces exactly the floors that somebody faces. A key that names nobody does not skip the guard — it gets a `400 workspace/missing-user-id`.
</ParamField>

<ParamField type="string">
  New cosmetic title (`edit-member-profile`, or self for own title). Nullable.
</ParamField>

<ParamField type="object">
  New cosmetic metadata (`edit-member-profile`).
</ParamField>

<ParamField type="string">
  Service/master keys only — the **acting** user (sent in the body; the path `:userId` is the target). **Required for a key:** this route has **no unbounded path**, so a key that names nobody is refused with `400 workspace/missing-user-id`. Every check below — the two capability tiers, the rank guard, the assign rule and no-escalation — runs against the named user. Act as the **owner** for an unrestricted edit.

  A plain user token omits it — the actor is the token's own user. The field is **not** ignored for such a token: sending your *own* user id is a harmless no-op, but sending **anyone else's** is a `403 workspace/unauthorized`. See [Acting on behalf of a user](/sdk/workspaces/overview#acting-on-behalf-of-a-user).
</ParamField>

## Response

Returns the updated [WorkspaceMember](/data-models/workspace-member) object.

## Error Responses

<AccordionGroup>
  <Accordion title="Unauthorized — 403">
    One message per tier, depending on which fields the request touched. Powerful fields (`capabilities`, `permissions`, `rank`, `relativeRank`):

    ```json theme={null}
    { "error": "The 'edit-member-access' capability is required to edit access fields.", "code": "workspace/unauthorized" }
    ```

    Cosmetic fields (`title`, `metadata`) — not raised when a member is editing only their own `title`. Editing your own `metadata` still requires `edit-member-profile`:

    ```json theme={null}
    { "error": "The 'edit-member-profile' capability is required to edit profile fields.", "code": "workspace/unauthorized" }
    ```
  </Accordion>

  <Accordion title="Insufficient Rank — 403">
    Two distinct messages share this code. The **act** rule, on the target:

    ```json theme={null}
    { "error": "You may only manage members ranked strictly below you.", "code": "workspace/insufficient-rank" }
    ```

    …and the **assign** rule, on the rank you asked for — checked against the resolved absolute value, so `rank` and `relativeRank` face it identically. This is also what refuses `rank: 0` to anyone holding a row on this workspace:

    ```json theme={null}
    { "error": "You may only set ranks strictly below your own.", "code": "workspace/insufficient-rank" }
    ```
  </Accordion>

  <Accordion title="Rank out of range — 400">
    ```json theme={null}
    { "error": "The resolved rank (2147483648) is out of range — ranks are integers from 0 to 2147483647.", "code": "workspace/invalid-body" }
    ```

    Checked after the offset is resolved. Out-of-range `rank` / `relativeRank` input is refused earlier by the schema, with the same code.
  </Accordion>

  <Accordion title="Both rank coordinates supplied — 400">
    ```json theme={null}
    { "error": "relativeRank: Provide either rank (absolute) or relativeRank (offset from you), not both", "code": "workspace/invalid-body" }
    ```

    A schema rejection, so the message is prefixed with the field it was reported against.
  </Accordion>

  <Accordion title="No Escalation — 403">
    The offending values are named. Capabilities:

    ```json theme={null}
    { "error": "Cannot grant capabilities you do not hold on this workspace: edit-member-access.", "code": "workspace/no-escalation" }
    ```

    …and permissions:

    ```json theme={null}
    { "error": "Cannot grant permissions you do not hold on this workspace: deploy.", "code": "workspace/no-escalation" }
    ```

    Only **added** values are checked — removing a capability or permission is governed by rank alone.
  </Accordion>

  <Accordion title="Missing Acting User — 400">
    ```json theme={null}
    { "error": "Missing user ID", "code": "workspace/missing-user-id" }
    ```

    A service/master key called this route without naming an `actingUserId`. Every gate on this route is measured against the editor's own standing, so the edit must be performed *as* somebody — act as the owner for an unrestricted edit.
  </Accordion>

  <Accordion title="Acted as Another User — 403">
    ```json theme={null}
    { "error": "Unauthorized", "code": "workspace/unauthorized" }
    ```

    A plain user token sent an `actingUserId` naming a **different** user. Only a service/master key may act as someone else.
  </Accordion>

  <Accordion title="Invalid Path Parameter — 400">
    ```json theme={null}
    { "error": "Invalid workspace id: expected a UUID.", "code": "workspace/invalid-params" }
    ```

    Every path id on the workspaces bundle is checked for UUID shape before the route runs, so a malformed one is a plain `400` rather than a `500` from the database.
  </Accordion>
</AccordionGroup>


# Transfer Ownership
Source: https://docs.sublay.io/v7/api-reference/workspaces/transfer-ownership

POST /v7/:projectId/workspaces/:id/transfer-ownership
Owner-only ownership transfer, keeping ownerId and member rows disjoint

Reassigns a workspace's `ownerId`. Doable by the workspace's **own owner OR any ancestor owner** (owners only — never a capability or reach). Runs in one transaction with a row lock to serialize concurrent transfers.

* The new owner must be a **verified** user (any verified user in the tenant — need not already be a member).
* The new owner's existing member row (if any) is **removed** to keep `ownerId` and member rows disjoint (fires `workspace.member.removed`).
* The previous owner is either **demoted** into a fresh member row (fires `workspace.member.added`) or **removed**. It **defaults to `remove`** whenever the field is omitted — on a voluntary self-transfer as much as on an ancestor-owner reassign. Send `previousOwnerDisposition: "demote"` to keep the outgoing owner on the roster. On demote, rank defaults to **one rung below the acting user** — rank `0` for the usual apex actor, but one below their own row when the acting ancestor owner also sits in this workspace's ladder.

<Note>
  Ancestor-owner transfer is what makes offboarding resolvable — a manager can reassign a fired member's owned sub-workspace without that member's access.
</Note>

## Path Parameters

<ParamField type="string">
  The workspace UUID.
</ParamField>

## Body Parameters

<ParamField type="string">
  The new owner — any **verified** user in the tenant.
</ParamField>

<ParamField type="string">
  `"demote"` or `"remove"`. Defaults to `"remove"` when omitted, on every path — including a voluntary self-transfer.
</ParamField>

<ParamField type="number">
  On demote, the ex-owner's rank. **Absolute only** — there is no relative form here.

  Defaults to **one rung below the acting user's own anchor**: rank `0` when the actor is apex (an owner or ancestor owner with no member row on this workspace, which is the usual case), and `actorRank + 1` when the acting ancestor owner *does* hold a row here — so the default never seats the outgoing owner above the person doing the transfer. An explicit value is honored verbatim and is deliberately unbounded, matching the other ownership carve-outs.
</ParamField>

<ParamField type="string[]">
  On demote, the ex-owner's capabilities.
</ParamField>

<ParamField type="string">
  Service/master keys only — the user to act as. **Enforced:** the owner-only guard runs against the named user, so a key naming a non-owner is refused exactly as that user would be. Omitting it alongside `newOwnerId` is a supported unbounded call — `newOwnerId` is a declared field of this endpoint, so it is accepted on its own terms. Omit it to act as the app itself (unbounded) — but on a call that hands the workspace to a new owner, prefer naming the current owner so the request carries a user id. See [Acting on behalf of a user](/sdk/workspaces/overview#acting-on-behalf-of-a-user).

  The [node SDK](/node-sdk/workspaces) is stricter than this endpoint: it types `actingUserId` as **required** here, so omitting it is only possible by calling the REST route directly.

  Several shapes are refused rather than ignored on this path. `actingUserId: ""` or `null` is a `400` — it reads as an *attempt* to name someone, not as "nobody". So is **every top-level field this endpoint does not declare**, in the body and in the query string alike, for every caller: `onBehalfOf`, `acting_user_id` and `impersonate` all come back as `Unrecognized key: "…"` rather than being quietly dropped. A key that differs from `actingUserId` only in capitalization — `actingUserID`, `actinguserid` — is refused too, but with a "did you mean `actingUserId`?" message instead of the generic one. And when the request names nobody, so is any body whose `Content-Type` is not `application/json` — an unparsed body discards the `actingUserId` inside it just as surely as a misspelling would. See [Shapes the server rejects](/sdk/workspaces/overview#shapes-the-server-rejects).
</ParamField>

## Response

Returns the updated [Workspace](/data-models/workspace) object with the new `ownerId`.

## Error Responses

<AccordionGroup>
  <Accordion title="Unauthorized — 403">
    ```json theme={null}
    { "error": "Owner access required", "code": "workspace/unauthorized" }
    ```
  </Accordion>

  <Accordion title="New Owner Not Verified — 403">
    ```json theme={null}
    { "error": "The new owner must have a verified email.", "code": "workspace/email-not-verified" }
    ```
  </Accordion>

  <Accordion title="Invalid Target — 404">
    ```json theme={null}
    { "error": "Target user not found.", "code": "workspace/invalid-target" }
    ```
  </Accordion>

  <Accordion title="Relative Rank Not Accepted — 400">
    ```json theme={null}
    {
      "error": "previousOwnerRelativeRank: transfer-ownership does not accept a relative rank. Use previousOwnerRank (absolute), or omit it — the default already seats the previous owner one rung below you.",
      "code": "workspace/invalid-body"
    }
    ```

    `previousOwnerRelativeRank` is declared purely so it can be refused with an *explanation*. An undeclared field is already refused, but generically (`Unrecognized key: "…"`); declaring this one buys the message that names what to send instead — and the default this route already applies *is* one rung below the actor.
  </Accordion>

  <Accordion title="Invalid Path Parameter — 400">
    ```json theme={null}
    { "error": "Invalid workspace id: expected a UUID.", "code": "workspace/invalid-params" }
    ```

    Every path id on the workspaces bundle is checked for UUID shape before the route runs, so a malformed one is a plain `400` rather than a `500` from the database.
  </Accordion>

  <Accordion title="Undeclared Field — 400">
    ```json theme={null}
    { "error": "Unrecognized key: \"onBehalfOf\"", "code": "workspace/invalid-body" }
    ```

    Every workspaces endpoint declares its fields exactly, and a top-level field it does not declare is refused rather than ignored — in the request body and in the query string alike, for every caller. Two or more at once are named together: `Unrecognized keys: "onBehalfOf", "impersonate"`. An offender in the query string carries `workspace/invalid-query` instead. Send only the fields documented above, plus `actingUserId` and `projectId`, which every workspaces route accepts. See [Shapes the server rejects](/sdk/workspaces/overview#shapes-the-server-rejects).
  </Accordion>

  <Accordion title="Unparsed Body — 400">
    ```json theme={null}
    {
      "error": "This request carries a body with content-type \"text/plain;charset=UTF-8\", which no parser reads, so any `actingUserId` inside it was discarded and this request names no acting user. Send the body as application/json.",
      "code": "workspace/invalid-body"
    }
    ```

    Returned when a service/master key sends a body with a `Content-Type` other than `application/json` **and** no `actingUserId` was read. Sublay parses only `application/json`, so the actor inside such a body is discarded and the request would fall through to the unbounded path. `fetch()` sends `text/plain;charset=UTF-8` when you pass a stringified body and set no headers — set the header. An empty JSON body and a bodiless request both pass. See [Shapes the server rejects](/sdk/workspaces/overview#shapes-the-server-rejects).
  </Accordion>
</AccordionGroup>


# Flip Inherit Flag
Source: https://docs.sublay.io/v7/api-reference/workspaces/update-inherit-flag

PATCH /v7/:projectId/workspaces/:id/inherit-flag
Owner-only flip of the reach/inherit flag

Flips the workspace's `inheritsFromParent` flag — the switch controlling whether authority from above reaches into this node. See [Reach & the wall/door rule](/data-models/workspace#reach-and-the-wall-door-rule).

* **Owner-only in both directions** (the workspace's own owner or an ancestor owner). **Not a capability.**
* Subject to the **enforced-default lock**: if the project sets [`workspaces.inheritEnforced`](/sdk/workspaces/overview#project-settings), the flip is rejected with `403 workspace/inherit-enforced`.

## Path Parameters

<ParamField type="string">
  The workspace UUID.
</ParamField>

## Body Parameters

<ParamField type="boolean">
  The new flag value (`true` = open/door, `false` = sealed/wall).
</ParamField>

<ParamField type="string">
  Service/master keys only — the user to act as. **Enforced:** the owner-only guard runs against the named user, so a key naming a non-owner is refused exactly as that user would be. Omit it to act as the app itself (unbounded). The `workspace/inherit-enforced` project lock is a separate gate and applies either way. See [Acting on behalf of a user](/sdk/workspaces/overview#acting-on-behalf-of-a-user).

  The [node SDK](/node-sdk/workspaces) is stricter than this endpoint: it types `actingUserId` as **required** here, so omitting it is only possible by calling the REST route directly.

  Several shapes are refused rather than ignored on this path. `actingUserId: ""` or `null` is a `400` — it reads as an *attempt* to name someone, not as "nobody". So is **every top-level field this endpoint does not declare**, in the body and in the query string alike, for every caller: `onBehalfOf`, `acting_user_id` and `impersonate` all come back as `Unrecognized key: "…"` rather than being quietly dropped. A key that differs from `actingUserId` only in capitalization — `actingUserID`, `actinguserid` — is refused too, but with a "did you mean `actingUserId`?" message instead of the generic one. And when the request names nobody, so is any body whose `Content-Type` is not `application/json` — an unparsed body discards the `actingUserId` inside it just as surely as a misspelling would. See [Shapes the server rejects](/sdk/workspaces/overview#shapes-the-server-rejects).
</ParamField>

## Response

Returns the updated [Workspace](/data-models/workspace) object.

## Error Responses

<AccordionGroup>
  <Accordion title="Unauthorized — 403">
    ```json theme={null}
    { "error": "Owner access required", "code": "workspace/unauthorized" }
    ```
  </Accordion>

  <Accordion title="Inherit Enforced — 403">
    ```json theme={null}
    { "error": "The inherit flag is enforced project-wide and cannot be changed.", "code": "workspace/inherit-enforced" }
    ```
  </Accordion>

  <Accordion title="Invalid Path Parameter — 400">
    ```json theme={null}
    { "error": "Invalid workspace id: expected a UUID.", "code": "workspace/invalid-params" }
    ```

    Every path id on the workspaces bundle is checked for UUID shape before the route runs, so a malformed one is a plain `400` rather than a `500` from the database.
  </Accordion>

  <Accordion title="Undeclared Field — 400">
    ```json theme={null}
    { "error": "Unrecognized key: \"onBehalfOf\"", "code": "workspace/invalid-body" }
    ```

    Every workspaces endpoint declares its fields exactly, and a top-level field it does not declare is refused rather than ignored — in the request body and in the query string alike, for every caller. Two or more at once are named together: `Unrecognized keys: "onBehalfOf", "impersonate"`. An offender in the query string carries `workspace/invalid-query` instead. Send only the fields documented above, plus `actingUserId` and `projectId`, which every workspaces route accepts. See [Shapes the server rejects](/sdk/workspaces/overview#shapes-the-server-rejects).
  </Accordion>

  <Accordion title="Unparsed Body — 400">
    ```json theme={null}
    {
      "error": "This request carries a body with content-type \"text/plain;charset=UTF-8\", which no parser reads, so any `actingUserId` inside it was discarded and this request names no acting user. Send the body as application/json.",
      "code": "workspace/invalid-body"
    }
    ```

    Returned when a service/master key sends a body with a `Content-Type` other than `application/json` **and** no `actingUserId` was read. Sublay parses only `application/json`, so the actor inside such a body is discarded and the request would fall through to the unbounded path. `fetch()` sends `text/plain;charset=UTF-8` when you pass a stringified body and set no headers — set the header. An empty JSON body and a bodiless request both pass. See [Shapes the server rejects](/sdk/workspaces/overview#shapes-the-server-rejects).
  </Accordion>
</AccordionGroup>


# Update Workspace
Source: https://docs.sublay.io/v7/api-reference/workspaces/update-workspace

PATCH /v7/:projectId/workspaces/:id
Edit a workspace's name and metadata

Edits a workspace's own `name` and/or `metadata`. Gated by the `edit-workspace` capability (or owner).

<Note>
  This does **not** flip `inheritsFromParent` — that is a separate [owner-only action](/api-reference/workspaces/update-inherit-flag).
</Note>

## Path Parameters

<ParamField type="string">
  The workspace UUID.
</ParamField>

## Body Parameters

<ParamField type="string">
  New display name. 1–100 characters.
</ParamField>

<ParamField type="object">
  New metadata (opaque JSON).
</ParamField>

<ParamField type="string">
  Service/master keys only — the user to act as. **Enforced:** the `edit-workspace` capability (or ownership) is required *of the named user*, so a key naming someone without it is refused exactly as that user would be. Omit it to act as the app itself (unbounded). See [Acting on behalf of a user](/sdk/workspaces/overview#acting-on-behalf-of-a-user).

  The [node SDK](/node-sdk/workspaces) is stricter than this endpoint: it types `actingUserId` as **required** here, so omitting it is only possible by calling the REST route directly.

  Several shapes are refused rather than ignored on this path. `actingUserId: ""` or `null` is a `400` — it reads as an *attempt* to name someone, not as "nobody". So is **every top-level field this endpoint does not declare**, in the body and in the query string alike, for every caller: `onBehalfOf`, `acting_user_id` and `impersonate` all come back as `Unrecognized key: "…"` rather than being quietly dropped. A key that differs from `actingUserId` only in capitalization — `actingUserID`, `actinguserid` — is refused too, but with a "did you mean `actingUserId`?" message instead of the generic one. And when the request names nobody, so is any body whose `Content-Type` is not `application/json` — an unparsed body discards the `actingUserId` inside it just as surely as a misspelling would. See [Shapes the server rejects](/sdk/workspaces/overview#shapes-the-server-rejects).
</ParamField>

## Response

Returns the updated [Workspace](/data-models/workspace) object.

## Error Responses

<AccordionGroup>
  <Accordion title="Unauthorized — 403">
    ```json theme={null}
    { "error": "Capability 'edit-workspace' required", "code": "workspace/unauthorized" }
    ```
  </Accordion>

  <Accordion title="Invalid Path Parameter — 400">
    ```json theme={null}
    { "error": "Invalid workspace id: expected a UUID.", "code": "workspace/invalid-params" }
    ```

    Every path id on the workspaces bundle is checked for UUID shape before the route runs, so a malformed one is a plain `400` rather than a `500` from the database.
  </Accordion>

  <Accordion title="Undeclared Field — 400">
    ```json theme={null}
    { "error": "Unrecognized key: \"onBehalfOf\"", "code": "workspace/invalid-body" }
    ```

    Every workspaces endpoint declares its fields exactly, and a top-level field it does not declare is refused rather than ignored — in the request body and in the query string alike, for every caller. Two or more at once are named together: `Unrecognized keys: "onBehalfOf", "impersonate"`. An offender in the query string carries `workspace/invalid-query` instead. Send only the fields documented above, plus `actingUserId` and `projectId`, which every workspaces route accepts. See [Shapes the server rejects](/sdk/workspaces/overview#shapes-the-server-rejects).
  </Accordion>

  <Accordion title="Unparsed Body — 400">
    ```json theme={null}
    {
      "error": "This request carries a body with content-type \"text/plain;charset=UTF-8\", which no parser reads, so any `actingUserId` inside it was discarded and this request names no acting user. Send the body as application/json.",
      "code": "workspace/invalid-body"
    }
    ```

    Returned when a service/master key sends a body with a `Content-Type` other than `application/json` **and** no `actingUserId` was read. Sublay parses only `application/json`, so the actor inside such a body is discarded and the request would fall through to the unbounded path. `fetch()` sends `text/plain;charset=UTF-8` when you pass a stringified body and set no headers — set the header. An empty JSON body and a bodiless request both pass. See [Shapes the server rejects](/sdk/workspaces/overview#shapes-the-server-rejects).
  </Accordion>
</AccordionGroup>


# ChatMessage
Source: https://docs.sublay.io/v7/data-models/chat-message

The shape of a chat message object returned by the Chat API and SDK

A `ChatMessage` represents a single message in a conversation. Messages support text content, GIF attachments, file attachments, @mentions, emoji reactions, threading (replies to a parent message), and quoting.

## Properties

| Property           | Type                               | Description                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------ | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`               | `string`                           | Unique message identifier (UUID).                                                                                                                                                                                                                                                                                                                                                                              |
| `localId`          | `string \| undefined`              | Locally-generated UUID echoed by the server. Never stored in the database. Used for optimistic deduplication — matching a temporary local entry to the confirmed server response.                                                                                                                                                                                                                              |
| `projectId`        | `string`                           | The project this message belongs to.                                                                                                                                                                                                                                                                                                                                                                           |
| `conversationId`   | `string`                           | ID of the conversation this message is in.                                                                                                                                                                                                                                                                                                                                                                     |
| `userId`           | `string \| null`                   | ID of the user who sent the message. `null` if the sender's account has since been deleted.                                                                                                                                                                                                                                                                                                                    |
| `user`             | `User \| null`                     | The sender's user profile. `null` when `userId` is `null` (account deleted).                                                                                                                                                                                                                                                                                                                                   |
| `content`          | `string \| null`                   | Text content of the message. `null` for GIF-only or file-only messages.                                                                                                                                                                                                                                                                                                                                        |
| `gif`              | `GifData \| null`                  | GIF attachment data. `null` if no GIF was attached.                                                                                                                                                                                                                                                                                                                                                            |
| `mentions`         | `Mention[]`                        | Array of @mentions embedded in the message.                                                                                                                                                                                                                                                                                                                                                                    |
| `files`            | `File[] \| undefined`              | File attachments. Only populated when the hook is called with `includeFiles: true`. Omitted by default to keep payloads small.                                                                                                                                                                                                                                                                                 |
| `metadata`         | `Record<string, any>`              | Custom key-value data. Limited to 10 KB.                                                                                                                                                                                                                                                                                                                                                                       |
| `parentMessageId`  | `string \| null`                   | ID of the parent message if this is a thread reply. Thread replies are excluded from the main conversation stream.                                                                                                                                                                                                                                                                                             |
| `parentMessage`    | `ChatMessage \| null \| undefined` | The parent message for thread replies.                                                                                                                                                                                                                                                                                                                                                                         |
| `quotedMessageId`  | `string \| null`                   | ID of a message being quoted. The message remains in the main stream but renders an inline preview of the quoted content.                                                                                                                                                                                                                                                                                      |
| `quotedMessage`    | `ChatMessage \| null \| undefined` | The quoted message, populated one level deep.                                                                                                                                                                                                                                                                                                                                                                  |
| `threadReplyCount` | `number`                           | Number of replies in this message's thread. Incremented on reply creation; never decremented.                                                                                                                                                                                                                                                                                                                  |
| `reactionCounts`   | `Record<string, number>`           | Emoji reaction counts, keyed by emoji. Computed server-side (e.g. `{ "👍": 3, "❤️": 1 }`).                                                                                                                                                                                                                                                                                                                     |
| `userReactions`    | `string[]`                         | Emojis the requesting user has reacted with on this message.                                                                                                                                                                                                                                                                                                                                                   |
| `editedAt`         | `Date \| null`                     | Timestamp when the message was last edited. `null` if never edited.                                                                                                                                                                                                                                                                                                                                            |
| `userDeletedAt`    | `Date \| null`                     | Timestamp when the sender deleted the message. Deleted messages are soft-deleted — the row is kept as a `[Message deleted]` placeholder with content cleared.                                                                                                                                                                                                                                                  |
| `moderationStatus` | `"approved" \| "removed" \| null`  | Moderation status. `"removed"` messages are excluded from default queries.                                                                                                                                                                                                                                                                                                                                     |
| `moderatedAt`      | `Date \| null`                     | Timestamp when moderation action was taken.                                                                                                                                                                                                                                                                                                                                                                    |
| `moderatedById`    | `string \| null`                   | ID of the moderator (user or client).                                                                                                                                                                                                                                                                                                                                                                          |
| `moderatedByType`  | `"client" \| "user" \| null`       | Whether the moderator was a client (dashboard/API key) or a user.                                                                                                                                                                                                                                                                                                                                              |
| `moderationReason` | `string \| null`                   | Optional reason recorded with the moderation action.                                                                                                                                                                                                                                                                                                                                                           |
| `grants`           | `GrantSummary \| undefined`        | Per-item [reputation-grant](/data-models/reputation-grant) summary — `{ total, count, viewerTotal }` over **positive** grants. Populated when the read asks for grants (`includeGrants: true` on the React message hooks, or a `"grants"` token in the `include` string on the REST and server SDKs). Zero-filled rather than omitted on a project with no grants, so `undefined` always means "nobody asked". |
| `createdAt`        | `Date`                             | Timestamp when the message was sent.                                                                                                                                                                                                                                                                                                                                                                           |
| `updatedAt`        | `Date`                             | Timestamp of the last update to this record.                                                                                                                                                                                                                                                                                                                                                                   |

## Client-only Fields

These fields are never sent by the server. They exist only in the SDK's local state.

| Property     | Type                   | Description                                                                                                                 |
| ------------ | ---------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `sendFailed` | `boolean \| undefined` | Set to `true` by the SDK when a send request fails. Used to render a failed-send indicator on the optimistic message entry. |

## Nested Types

### GifData

The `gif` field uses this shape when a GIF is attached:

| Property        | Type     | Description                                                                      |
| --------------- | -------- | -------------------------------------------------------------------------------- |
| `id`            | `string` | GIF provider ID.                                                                 |
| `url`           | `string` | Landing page URL for the GIF.                                                    |
| `gifUrl`        | `string` | Direct URL to the animated GIF.                                                  |
| `gifPreviewUrl` | `string` | URL to a static preview image.                                                   |
| `altText`       | `string` | Accessibility description. Required.                                             |
| `aspectRatio`   | `string` | Width / height ratio for layout purposes, as a string — e.g. `"1.5"`, not `1.5`. |

All six fields are required when a GIF is attached.

### Mention

Each entry in the `mentions` array is one of:

**UserMention**

| Property    | Type                          | Description                       |
| ----------- | ----------------------------- | --------------------------------- |
| `type`      | `"user"`                      | Discriminant.                     |
| `id`        | `string`                      | Sublay user ID.                   |
| `foreignId` | `string \| null \| undefined` | Your app's user ID, if set.       |
| `username`  | `string`                      | The @username at time of mention. |

**SpaceMention**

| Property | Type      | Description                          |
| -------- | --------- | ------------------------------------ |
| `type`   | `"space"` | Discriminant.                        |
| `id`     | `string`  | Space ID.                            |
| `slug`   | `string`  | The space's slug at time of mention. |

## Soft Deletion

When a user deletes their own message, the row is retained as a placeholder. `userDeletedAt` is set and the content, GIF, mentions, and metadata are cleared by the server. This preserves thread structure — a deleted parent message still anchors its thread replies.

<Note>
  Moderator-removed messages (`moderationStatus: "removed"`) are excluded from all default API responses. They are not returned to clients.
</Note>

## Related

* [Conversation](/data-models/conversation) — the conversation this message belongs to
* [ConversationMember](/data-models/conversation-member) — membership records that track read state
* [File](/data-models/file) — file attachments linked to a message
* [ReputationGrant](/data-models/reputation-grant) — grants that can be attached to a message, and the live `message:grant` broadcast


# Collection
Source: https://docs.sublay.io/v7/data-models/collection

A named folder in a user's personal save library for organizing entities

## Overview

A `Collection` is a user-owned, hierarchical folder used to save and organize entities. Every user has a single root collection created automatically on first access. Users can create any number of sub-collections nested under the root or under other sub-collections.

Collections are private — each collection belongs to one user and is not visible to others.

## Fields

<ResponseField name="id" type="string">
  Unique identifier for the collection (UUID).
</ResponseField>

<ResponseField name="projectId" type="string">
  The project this collection belongs to.
</ResponseField>

<ResponseField name="userId" type="string">
  The user who owns this collection.
</ResponseField>

<ResponseField name="parentId" type="string | null">
  The ID of the parent collection. `null` for the root collection.
</ResponseField>

<ResponseField name="name" type="string">
  Display name of the collection. The root collection is always named `"root"`.
</ResponseField>

<ResponseField name="entityCount" type="number">
  Number of entities directly saved in this collection (not counting sub-collections).
</ResponseField>

<ResponseField name="createdAt" type="string (ISO 8601)">
  Timestamp when the collection was created.
</ResponseField>

<ResponseField name="updatedAt" type="string (ISO 8601)">
  Timestamp when the collection was last modified.
</ResponseField>

## Notes

* The root collection is created lazily on the first call to `GET /v7/:projectId/collections/root`.
* The root collection cannot be renamed or deleted.
* Sub-collections can be nested to any depth.
* Entities are linked to collections via a junction table — the same entity can be saved in multiple collections.


# Comment
Source: https://docs.sublay.io/v7/data-models/comment

The Comment interface shape returned by the API and SDK

A comment represents a user-authored response to an entity. Comments support nested replies, reactions, GIF attachments, user mentions, and moderation.

## Properties

| Property           | Type                              | Description                                                                                                                                                                                                                                                                           |
| ------------------ | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`               | `string`                          | Unique comment identifier (UUID).                                                                                                                                                                                                                                                     |
| `foreignId`        | `string \| null`                  | Your system's ID for this comment, if applicable.                                                                                                                                                                                                                                     |
| `projectId`        | `string`                          | The project this comment belongs to.                                                                                                                                                                                                                                                  |
| `entityId`         | `string`                          | The entity this comment belongs to.                                                                                                                                                                                                                                                   |
| `entity`           | `Entity`                          | Populated when `include` contains `"entity"` or `"space"`.                                                                                                                                                                                                                            |
| `userId`           | `string`                          | The ID of the user who posted this comment.                                                                                                                                                                                                                                           |
| `user`             | `User`                            | The comment author. Populated when `include` contains `"user"`.                                                                                                                                                                                                                       |
| `parentId`         | `string \| null`                  | ID of the parent comment if this is a reply. `null` for top-level comments.                                                                                                                                                                                                           |
| `parentComment`    | `Comment`                         | The parent comment object. Populated when `include` contains `"parent"`.                                                                                                                                                                                                              |
| `content`          | `string \| null`                  | Text content of the comment.                                                                                                                                                                                                                                                          |
| `gif`              | `GifData \| null`                 | Attached GIF, if any.                                                                                                                                                                                                                                                                 |
| `mentions`         | `Mention[]`                       | Array of user mentions embedded in the comment.                                                                                                                                                                                                                                       |
| `upvotes`          | `string[]`                        | Legacy v6 field — array of user IDs that upvoted. Use `reactionCounts` in v7.                                                                                                                                                                                                         |
| `downvotes`        | `string[]`                        | Legacy v6 field — array of user IDs that downvoted. Use `reactionCounts` in v7.                                                                                                                                                                                                       |
| `reactionCounts`   | `ReactionCounts`                  | Counts for all 8 reaction types. See [Reaction](/data-models/reaction).                                                                                                                                                                                                               |
| `userReaction`     | `ReactionType \| null`            | The current user's reaction, populated when authenticated.                                                                                                                                                                                                                            |
| `repliesCount`     | `number`                          | Number of direct replies to this comment.                                                                                                                                                                                                                                             |
| `grants`           | `GrantSummary \| undefined`       | Per-item [reputation-grant](/data-models/reputation-grant) summary — `{ total, count, viewerTotal }` over **positive** grants. Populated when `include` contains `"grants"`. Zero-filled rather than omitted on a project with no grants, so `undefined` always means "nobody asked". |
| `metadata`         | `Record<string, any>`             | Custom key-value data (max 10 KB).                                                                                                                                                                                                                                                    |
| `moderationStatus` | `"approved" \| "removed" \| null` | Space moderation status.                                                                                                                                                                                                                                                              |
| `moderatedAt`      | `Date \| null`                    | When the moderation action was taken.                                                                                                                                                                                                                                                 |
| `moderatedById`    | `string \| null`                  | ID of the moderator.                                                                                                                                                                                                                                                                  |
| `moderatedByType`  | `"client" \| "user" \| null`      | Whether a client (admin) or user performed moderation.                                                                                                                                                                                                                                |
| `moderationReason` | `string \| null`                  | Reason provided for moderation.                                                                                                                                                                                                                                                       |
| `userDeletedAt`    | `Date \| null`                    | Set when a user soft-deletes their own comment. Content is replaced with a placeholder but the comment record remains (Reddit-style behavior).                                                                                                                                        |
| `createdAt`        | `Date`                            | When the comment was created.                                                                                                                                                                                                                                                         |
| `updatedAt`        | `Date`                            | When the comment was last updated.                                                                                                                                                                                                                                                    |
| `deletedAt`        | `Date \| null`                    | Hard-delete timestamp. `null` for active comments.                                                                                                                                                                                                                                    |

## Nested Types

### GifData

| Property        | Type     | Description                                                                 |
| --------------- | -------- | --------------------------------------------------------------------------- |
| `id`            | `string` | GIF provider identifier.                                                    |
| `url`           | `string` | URL to the GIF page or canonical source.                                    |
| `gifUrl`        | `string` | Direct URL to the animated GIF file.                                        |
| `gifPreviewUrl` | `string` | URL to a lower-quality preview of the GIF.                                  |
| `altText`       | `string` | Accessible description of the GIF. Required.                                |
| `aspectRatio`   | `string` | Width-to-height ratio for rendering, as a string — e.g. `"1.5"`, not `1.5`. |

All six fields are required when a GIF is attached.

## Includes

Pass an `include` array to populate optional fields:

| Include value | Populates                                         |
| ------------- | ------------------------------------------------- |
| `"user"`      | `user` — the comment author                       |
| `"entity"`    | `entity` — the parent entity                      |
| `"space"`     | `entity` with its associated space populated      |
| `"parent"`    | `parentComment` — the parent comment, for replies |
| `"grants"`    | `grants` — the reputation-grant summary           |

<Note>
  The two single-comment reads ([Fetch Comment](/api-reference/comments/fetch-comment) and [Fetch Comment by Foreign ID](/api-reference/comments/fetch-comment-by-foreign-id)) nest the record under a `comment` key, so on those the summary is at `comment.grants`. The comment feed returns comments bare.
</Note>

## See Also

* [Reaction](/data-models/reaction)
* [Entity](/data-models/entity)
* [ReputationGrant](/data-models/reputation-grant)
* [Fetch Many Comments](/api-reference/comments/fetch-many-comments)
* [useEntityComments hook](/hooks/comments/use-entity-comments)


# Conversation
Source: https://docs.sublay.io/v7/data-models/conversation

The shape of a conversation object returned by the Chat API and SDK

A `Conversation` represents a messaging thread between two or more participants. Sublay supports three conversation types: **direct** (1:1 DMs), **group** (multi-member chat), and **space** (a single shared chat channel attached to a Space).

## Properties

| Property            | Type                              | Description                                                                                                      |
| ------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `id`                | `string`                          | Unique conversation identifier (UUID).                                                                           |
| `projectId`         | `string`                          | The project this conversation belongs to.                                                                        |
| `type`              | `"direct" \| "group" \| "space"`  | Conversation type.                                                                                               |
| `name`              | `string \| null`                  | Display name. Always `null` for direct conversations.                                                            |
| `description`       | `string \| null`                  | Optional description. Used for group and space conversations.                                                    |
| `spaceId`           | `string \| null`                  | The Space this conversation belongs to. Set only when `type` is `"space"`.                                       |
| `createdById`       | `string \| null`                  | ID of the user who created the conversation. `null` for auto-created space conversations.                        |
| `avatarFileId`      | `string \| null`                  | ID of the uploaded avatar file for this conversation.                                                            |
| `avatarFile`        | `File \| undefined`               | Populated avatar file object, if `avatarFileId` is set.                                                          |
| `lastMessageAt`     | `Date \| null`                    | Timestamp of the most recent message. Used for conversation list sorting. `null` if no messages have been sent.  |
| `postingPermission` | `"members" \| "admins" \| null`   | Who can post in the conversation. Only set for `space` conversations. `null` for direct and group conversations. |
| `metadata`          | `Record<string, any>`             | Custom key-value data. Limited to 1 MB.                                                                          |
| `memberCount`       | `number`                          | Total number of active members.                                                                                  |
| `currentMember`     | `ConversationMember \| undefined` | The requesting user's own membership row. Included in API responses when applicable.                             |
| `createdAt`         | `Date`                            | Timestamp when the conversation was created.                                                                     |
| `updatedAt`         | `Date`                            | Timestamp of the last update.                                                                                    |

## ConversationPreview

When listing conversations (e.g. in an inbox), the API returns `ConversationPreview` objects, which extend `Conversation` with these additional fields:

| Property       | Type                               | Description                                                                                                                                                                                                                                                           |
| -------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `unreadCount`  | `number`                           | Number of messages sent after the current user's `lastReadAt`.                                                                                                                                                                                                        |
| `lastMessage`  | `ChatMessage \| null`              | The most recent message in the conversation, truncated to 100 characters. `null` if no messages have been sent.                                                                                                                                                       |
| `otherMembers` | `{ id, name, username, avatar }[]` | Up to 5 active members other than the current user. Populated for `direct` and `group` conversations (a DM/group has no `name`, so the counterparty supplies the title/avatar); capped at 5 (use `memberCount` for the group total); empty for `space` conversations. |

## Conversation Types

| Type     | Description                                                                                                                            |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `direct` | A private 1:1 DM between two users. Only one direct conversation can exist per user pair per project.                                  |
| `group`  | A multi-member chat created by a user. Members can have `admin` or `member` roles.                                                     |
| `space`  | The shared chat channel for a Space. Exactly one space conversation exists per Space. Created automatically when the Space is created. |

## Related

* [ConversationMember](/data-models/conversation-member) — member rows linked to this conversation
* [ChatMessage](/data-models/chat-message) — messages that belong to this conversation
* [Space](/data-models/space) — the parent Space for `type: "space"` conversations


# ConversationMember
Source: https://docs.sublay.io/v7/data-models/conversation-member

The shape of a conversation membership record returned by the Chat API and SDK

A `ConversationMember` records one user's participation in a conversation. A user has exactly one membership row per conversation. The row persists even after a user leaves — `isActive` tracks whether they are currently a participant.

## Properties

| Property         | Type                          | Description                                                                                                                                                                      |
| ---------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`             | `string`                      | Unique membership identifier (UUID).                                                                                                                                             |
| `projectId`      | `string`                      | The project this membership belongs to.                                                                                                                                          |
| `conversationId` | `string`                      | ID of the conversation.                                                                                                                                                          |
| `userId`         | `string`                      | ID of the member user.                                                                                                                                                           |
| `user`           | `User \| undefined`           | The member's user profile. Included when listing members.                                                                                                                        |
| `role`           | `"admin" \| "member" \| null` | Member role within the conversation. `null` for direct and space conversations — space conversations derive roles from `SpaceMember`. Only `group` conversations use this field. |
| `lastReadAt`     | `Date \| null`                | Timestamp of the user's last read event. Used to compute `unreadCount` on `ConversationPreview`. `null` if the user has never read the conversation.                             |
| `mutedUntil`     | `Date \| null`                | Reserved for future mute functionality. Not used in v7.                                                                                                                          |
| `isActive`       | `boolean`                     | Whether the user is currently an active participant. `false` if they left voluntarily or were removed.                                                                           |
| `leftAt`         | `Date \| null`                | Timestamp when the user left the conversation. `null` if still active.                                                                                                           |
| `createdAt`      | `Date`                        | Timestamp when the membership was created (i.e. when the user joined).                                                                                                           |
| `updatedAt`      | `Date`                        | Timestamp of the last update to this record.                                                                                                                                     |

## Roles

Roles only apply to `group` conversations.

| Role       | Description                                                                        |
| ---------- | ---------------------------------------------------------------------------------- |
| `"admin"`  | Can add/remove members, update the conversation, and delete the conversation.      |
| `"member"` | Can send messages and leave the conversation.                                      |
| `null`     | Used for `direct` and `space` conversation members (role is derived from context). |

<Note>
  For space conversations, posting permissions are controlled by the conversation's `postingPermission` field and the user's `SpaceMember` role — not by `ConversationMember.role`.
</Note>

## Related

* [Conversation](/data-models/conversation) — the conversation this membership belongs to
* [ChatMessage](/data-models/chat-message) — messages in the conversation


# Entity
Source: https://docs.sublay.io/v7/data-models/entity

The Entity interface shape returned by the API and SDK

An entity is the central content unit in Sublay — it can represent a post, article, product listing, video, or any other piece of content in your application. Entities support reactions, comments, votes, file attachments, geo-location, and more.

<Note>
  Entities are provided by the optional **`entities`** bundle. A project without it returns `403 database/tables-not-available` for entity endpoints. See [Bundles](/bundles).
</Note>

## Properties

| Property           | Type                              | Description                                                                                                                                                                                                                                                                           |
| ------------------ | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`               | `string`                          | Unique entity identifier (UUID).                                                                                                                                                                                                                                                      |
| `foreignId`        | `string \| null`                  | Your system's content ID, if this entity maps to existing data. Can also be a static identifier like `"about-page"`.                                                                                                                                                                  |
| `shortId`          | `string`                          | Auto-generated short identifier, useful for sharing links.                                                                                                                                                                                                                            |
| `projectId`        | `string`                          | The project this entity belongs to.                                                                                                                                                                                                                                                   |
| `sourceId`         | `string \| null`                  | Groups entities by content type within a project. Useful when one project hosts multiple distinct categories of content (e.g. `"user-post"` vs `"blog-post"`), allowing you to filter and separate them without creating separate projects.                                           |
| `spaceId`          | `string \| null`                  | The space this entity belongs to, if any.                                                                                                                                                                                                                                             |
| `space`            | `Space \| null`                   | Populated space object when `include` contains `"space"`.                                                                                                                                                                                                                             |
| `userId`           | `string \| null`                  | ID of the user this entity is associated with. `null` if the entity is not associated with any user.                                                                                                                                                                                  |
| `user`             | `User \| null`                    | The author. Populated when `include` contains `"user"`.                                                                                                                                                                                                                               |
| `title`            | `string \| null`                  | Optional title.                                                                                                                                                                                                                                                                       |
| `content`          | `string \| null`                  | Optional text content.                                                                                                                                                                                                                                                                |
| `mentions`         | `Mention[]`                       | Array of user mentions embedded in the content.                                                                                                                                                                                                                                       |
| `attachments`      | `Record<string, any>[]`           | Flexible array of media/attachment metadata objects.                                                                                                                                                                                                                                  |
| `files`            | `File[]`                          | System-managed file associations. Populated when `include` contains `"files"`.                                                                                                                                                                                                        |
| `keywords`         | `string[]`                        | Tags used for filtering and discovery.                                                                                                                                                                                                                                                |
| `upvotes`          | `string[]`                        | Legacy v6 field — array of user IDs that upvoted. Use `reactionCounts` instead.                                                                                                                                                                                                       |
| `downvotes`        | `string[]`                        | Legacy v6 field — array of user IDs that downvoted. Use `reactionCounts` instead.                                                                                                                                                                                                     |
| `reactionCounts`   | `ReactionCounts`                  | Counts for all 8 reaction types. See [Reaction](/data-models/reaction).                                                                                                                                                                                                               |
| `userReaction`     | `ReactionType \| null`            | The current user's reaction. Only present when the user is authenticated and has reacted to this entity.                                                                                                                                                                              |
| `repliesCount`     | `number`                          | Total number of comments and replies on this entity.                                                                                                                                                                                                                                  |
| `views`            | `number`                          | View count. Auto-incremented on every fetch. Can also be incremented manually via the service-key-only `PATCH /entities/:entityId/increment-views` endpoint.                                                                                                                          |
| `score`            | `number`                          | Computed "hotness" score based on engagement activity.                                                                                                                                                                                                                                |
| `scoreUpdatedAt`   | `Date`                            | When the score was last recalculated.                                                                                                                                                                                                                                                 |
| `location`         | `GeoPoint \| null`                | Optional geo-location stored as a GeoJSON point.                                                                                                                                                                                                                                      |
| `metadata`         | `Record<string, any>`             | Custom key-value data (max 10 KB).                                                                                                                                                                                                                                                    |
| `topComment`       | `TopComment \| null`              | The highest-voted comment. Populated when `include` contains `"topComment"`.                                                                                                                                                                                                          |
| `isSaved`          | `boolean`                         | Whether the current user has saved this entity to a collection. Populated when `include` contains `"saved"`.                                                                                                                                                                          |
| `grants`           | `GrantSummary \| undefined`       | Per-item [reputation-grant](/data-models/reputation-grant) summary — `{ total, count, viewerTotal }` over **positive** grants. Populated when `include` contains `"grants"`. Zero-filled rather than omitted on a project with no grants, so `undefined` always means "nobody asked". |
| `isDraft`          | `boolean \| null`                 | Whether this entity is in draft state.                                                                                                                                                                                                                                                |
| `nsfw`             | `boolean`                         | The entity's **own** NSFW flag. `false` by default. Set on create/update by the owner (or a service/master key), or by a space moderator via the [set-NSFW endpoint](/hooks/spaces/use-set-space-entity-nsfw). See [NSFW flagging](#nsfw-flagging).                                   |
| `nsfwEffective`    | `boolean`                         | **Computed live, read-only.** `true` when the entity's own `nsfw` is `true` **or** its space is effectively NSFW: `entity.nsfw OR (space?.nsfwEffective ?? false)`. This is the value the `nsfwFilter` query param keys off. See [NSFW flagging](#nsfw-flagging).                     |
| `moderationStatus` | `"approved" \| "removed" \| null` | Current space moderation status.                                                                                                                                                                                                                                                      |
| `moderatedAt`      | `Date \| null`                    | When the moderation action was taken.                                                                                                                                                                                                                                                 |
| `moderatedById`    | `string \| null`                  | ID of the moderator who took the action.                                                                                                                                                                                                                                              |
| `moderatedByType`  | `"client" \| "user" \| null`      | Whether a client (admin) or user performed moderation.                                                                                                                                                                                                                                |
| `moderationReason` | `string \| null`                  | Reason provided for moderation.                                                                                                                                                                                                                                                       |
| `createdAt`        | `Date`                            | When the entity was created.                                                                                                                                                                                                                                                          |
| `updatedAt`        | `Date`                            | When the entity was last updated.                                                                                                                                                                                                                                                     |
| `deletedAt`        | `Date \| null`                    | Soft-delete timestamp. `null` for active entities.                                                                                                                                                                                                                                    |

## Nested Types

### TopComment

Included when the entity has at least one comment.

| Property       | Type     | Description                        |
| -------------- | -------- | ---------------------------------- |
| `id`           | `string` | Comment identifier.                |
| `user`         | `User`   | The comment author.                |
| `upvotesCount` | `number` | Number of upvotes on this comment. |
| `content`      | `string` | Comment text content.              |
| `createdAt`    | `string` | ISO timestamp string.              |

### GeoPoint

| Property      | Type               | Description                              |
| ------------- | ------------------ | ---------------------------------------- |
| `type`        | `"Point"`          | GeoJSON geometry type. Always `"Point"`. |
| `coordinates` | `[number, number]` | Longitude and latitude, in that order.   |

## NSFW flagging

An entity carries its own `nsfw` boolean and exposes a live-computed `nsfwEffective`:

* **`nsfw`** — the entity's own flag. It defaults to `false` and is what the owner, a service/master key, or a space moderator toggles.
* **`nsfwEffective`** — never stored on the entity. It is computed on **every** read as:

  ```
  nsfwEffective = entity.nsfw OR COALESCE(space.nsfwEffective, false)
  ```

  So an entity reads as effectively NSFW when either its own flag is set **or** the space it lives in is effectively NSFW (which itself folds in the space's whole ancestor chain — see [Space → NSFW flagging](/data-models/space#nsfw-flagging)). A space-less entity (`spaceId` is `null`) falls back to its own flag; on a project without the spaces bundle, the space contribution is simply absent and `nsfwEffective` equals `entity.nsfw`.

The effect is a live OR: clearing an entity's own `nsfw` **cannot** make it read safe while its space chain is still NSFW, and flagging a space instantly cascades to every entity inside it without stamping or backfilling entity rows.

To filter a list by effective NSFW, pass `nsfwFilter` to [Fetch many entities](/hooks/entities/use-fetch-many-entities) (`include-all` default / `exclude` / `only`).

<Note>
  Sublay only **labels** (`nsfw`) and **filters** (`nsfwFilter`) content. It does **not** blur, age-gate, add interstitials, or store a per-viewer "show mature content" preference — how NSFW-flagged content is presented is entirely the consuming app's responsibility.
</Note>

## Includes

Pass an `include` array to populate optional fields:

| Include value  | Populates                                          |
| -------------- | -------------------------------------------------- |
| `"user"`       | `user` — the entity author                         |
| `"space"`      | `space` — the associated space                     |
| `"topComment"` | `topComment` — top-voted comment                   |
| `"saved"`      | `isSaved` — whether current user saved this entity |
| `"files"`      | `files` — managed file records                     |
| `"grants"`     | `grants` — the reputation-grant summary            |

## See Also

* [Reaction](/data-models/reaction)
* [File](/data-models/file)
* [ReputationGrant](/data-models/reputation-grant)
* [Space](/data-models/space)
* [Fetch Entity](/api-reference/entities/fetch-entity)
* [useEntity hook](/hooks/entities/use-entity)
* [Set space entity NSFW hook](/hooks/spaces/use-set-space-entity-nsfw)


# Event
Source: https://docs.sublay.io/v7/data-models/event

The shape of an Event object returned by the Events API and SDKs

An Event is a scheduled happening — online, physical, or hybrid — that users can RSVP to. Events support hosts, capacity limits, invite-only or space-scoped visibility, a guest list, a single cover image, and a multi-image gallery. RSVP counts are denormalized onto the event so every read carries up-to-date `going` / `maybe` / `not_going` totals without an extra query.

Events belong to the `events` bundle. They work standalone, but some behaviors depend on other bundles: space-scoping and `members` visibility require the `spaces` bundle, cover/gallery images require the `files-images` bundle, and invite/update/cancel notifications require the `notifications` bundle. When a dependency is absent, that specific behavior is rejected or skipped — the rest of the events surface keeps working.

## Event

| Property           | Type                                                       | Description                                                                                                                                   |
| ------------------ | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`               | `string`                                                   | Unique event identifier (UUID).                                                                                                               |
| `shortId`          | `string`                                                   | Short, URL-safe identifier generated automatically.                                                                                           |
| `projectId`        | `string`                                                   | The project this event belongs to.                                                                                                            |
| `userId`           | `string \| null`                                           | ID of the event creator. Set to `null` if the creator's account is deleted (the event survives).                                              |
| `user`             | `User \| null`                                             | Populated creator object. Only present when `include` contains `"user"`.                                                                      |
| `title`            | `string`                                                   | Event title (1–300 characters).                                                                                                               |
| `description`      | `string \| null`                                           | Optional description. Empty strings are normalized to `null`.                                                                                 |
| `startTime`        | `string`                                                   | ISO datetime when the event starts. RSVPs close at this moment.                                                                               |
| `endTime`          | `string \| null`                                           | Optional ISO datetime when the event ends. Drives the `ongoing` vs `past` time window.                                                        |
| `timezone`         | `string \| null`                                           | Optional IANA timezone string (e.g. `"America/New_York"`).                                                                                    |
| `type`             | `"online" \| "physical" \| "hybrid"`                       | The event format. Determines which location fields are required.                                                                              |
| `url`              | `string \| null`                                           | Join/stream URL. Required for `online` and `hybrid` events.                                                                                   |
| `venueName`        | `string \| null`                                           | Optional human-readable venue name.                                                                                                           |
| `address`          | `string \| null`                                           | Street address. Required (with or instead of `location`) for `physical` and `hybrid` events.                                                  |
| `location`         | `{ type: "Point"; coordinates: [number, number] } \| null` | GeoJSON point as `[longitude, latitude]` (PostGIS). Set from the `latitude`/`longitude` you pass on create/update. Powers proximity search.   |
| `spaceId`          | `string \| null`                                           | Optional soft reference to a Space. Required when `visibility` is `"members"`. No enforced cross-bundle FK.                                   |
| `space`            | `Space \| null`                                            | Populated space object. Only present when `include` contains `"space"`.                                                                       |
| `visibility`       | `"public" \| "members" \| "invite"`                        | Who can see the event. See [Visibility](#visibility) below. Defaults to `"public"`.                                                           |
| `status`           | `"active" \| "cancelled"`                                  | Lifecycle status. A cancelled event stays fetchable but rejects new RSVPs. Defaults to `"active"`.                                            |
| `allowMaybe`       | `boolean`                                                  | Whether a `"maybe"` RSVP is permitted. Defaults to `true`.                                                                                    |
| `guestListVisible` | `boolean`                                                  | Whether non-hosts can see the named RSVP/guest list (counts are always public). Defaults to `true`.                                           |
| `capacity`         | `number \| null`                                           | Maximum number of `going` RSVPs. `null` means unlimited. Enforced under a row lock so it can't be oversold.                                   |
| `hostIds`          | `string[]`                                                 | UUIDs of the event's hosts. The creator is always included. Always has at least one entry.                                                    |
| `coverImageId`     | `string \| null`                                           | File ID of the single cover image. Requires the `files-images` bundle.                                                                        |
| `files`            | `File[]`                                                   | Cover + gallery file objects. Only present when `include` contains `"files"`.                                                                 |
| `rsvpCounts`       | `{ going: number; maybe: number; not_going: number }`      | Denormalized RSVP totals, always returned.                                                                                                    |
| `userRsvp`         | `"going" \| "maybe" \| "not_going" \| null`                | The requesting user's own RSVP status. Only populated when `include` contains `"userRsvp"` and the caller is authenticated; otherwise `null`. |
| `metadata`         | `Record<string, any>`                                      | Arbitrary key-value data. Up to 1 MB. Use this for ticketing, tags, or any custom fields.                                                     |
| `createdAt`        | `string`                                                   | ISO timestamp when the event was created.                                                                                                     |
| `updatedAt`        | `string`                                                   | ISO timestamp when the event was last updated.                                                                                                |
| `deletedAt`        | `string \| null`                                           | Soft-delete timestamp when `eventDeletion.softDelete` is enabled; otherwise `null`.                                                           |

## Type

The `type` field controls which location fields are required on create and update:

| Type         | Required fields                         |
| ------------ | --------------------------------------- |
| `"online"`   | `url`                                   |
| `"physical"` | `address` or `location` (at least one)  |
| `"hybrid"`   | `url` **and** (`address` or `location`) |

## Visibility

Visibility is enforced **server-side** on every read — an event you can't see returns `404` (its existence is never leaked).

| Value       | Who can see it                                                                         |
| ----------- | -------------------------------------------------------------------------------------- |
| `"public"`  | Anyone, including anonymous callers.                                                   |
| `"members"` | Active members of the event's `spaceId`. Requires a `spaceId` and the `spaces` bundle. |
| `"invite"`  | Users with an `EventInvite` row for the event.                                         |

In every case, a **host** (a user whose ID is in `hostIds`) can always see the event regardless of visibility, and service/master keys bypass visibility entirely.

## Capacity & RSVP rules

* An RSVP can be `going`, `maybe`, or `not_going`. There is one RSVP per user per event.
* RSVPs close at `startTime` and are rejected on `cancelled` events.
* A `"maybe"` RSVP is rejected when `allowMaybe` is `false`.
* A transition into `going` is rejected with `event/full` when `rsvpCounts.going` has reached `capacity`. Capacity is checked under a row-level lock, so concurrent RSVPs can never oversell the event.

## Related

* [EventRsvp data model](/data-models/event-rsvp)
* [EventInvite data model](/data-models/event-invite)
* [File data model](/data-models/file)
* [Create Event API](/api-reference/events/create-event)
* [Fetch Many Events API](/api-reference/events/fetch-many-events)
* [EventProvider & useEvent](/sdk/events/provider-and-hook)


# EventInvite
Source: https://docs.sublay.io/v7/data-models/event-invite

The shape of an EventInvite record returned by the event invitee-list endpoint

An `EventInvite` grants a specific user access to an `invite`-only event. There is at most one invite per user per event (enforced by a unique `(eventId, userId)` constraint), so re-inviting a user is idempotent. Invites are managed by hosts and always reference a Sublay `userId` (never a foreign ID).

Invite records are returned by the host-only invitee-list endpoint ([Fetch Invitees](/api-reference/events/fetch-invitees)).

## EventInvite

| Property    | Type           | Description                                           |
| ----------- | -------------- | ----------------------------------------------------- |
| `id`        | `string`       | Unique invite identifier (UUID).                      |
| `eventId`   | `string`       | The event the user is invited to.                     |
| `userId`    | `string`       | The invited user.                                     |
| `user`      | `User \| null` | Populated user object. Present on invitee-list reads. |
| `invitedAt` | `string`       | ISO timestamp when the invite was created.            |
| `createdAt` | `string`       | ISO timestamp when the record was created.            |
| `updatedAt` | `string`       | ISO timestamp when the record was last updated.       |

## Behavior

* **Add** — `POST /events/:eventId/invites` with a `userId`. Host-only. Idempotent against the unique constraint. When the `notifications` bundle is present, the invitee receives an `event-invite` notification.
* **Remove** — `DELETE /events/:eventId/invites` with a `userId`. Host-only. Removing an invite revokes the user's access to an `invite`-only event **and** deletes their RSVP (decrementing the count).
* **Visibility tie-in** — for an `invite`-visibility event, only users with an invite row (plus hosts) can see or RSVP to the event.

## Related

* [Event data model](/data-models/event)
* [Add Invite API](/api-reference/events/add-invite)
* [Remove Invite API](/api-reference/events/remove-invite)
* [Fetch Invitees API](/api-reference/events/fetch-invitees)


# EventRsvp
Source: https://docs.sublay.io/v7/data-models/event-rsvp

The shape of an EventRsvp record returned by the event guest-list endpoint

An `EventRsvp` records a single user's response to an event. There is at most one RSVP per user per event (enforced by a unique `(eventId, userId)` constraint). Setting, changing, or withdrawing an RSVP keeps the event's denormalized `rsvpCounts` in sync.

Individual RSVP records are returned by the named guest-list endpoint ([Fetch Event RSVPs](/api-reference/events/fetch-event-rsvps)). The aggregate `rsvpCounts` are always available directly on the [Event](/data-models/event), and the caller's own status can be surfaced as `userRsvp` via the `userRsvp` include.

## EventRsvp

| Property    | Type                                | Description                                         |
| ----------- | ----------------------------------- | --------------------------------------------------- |
| `id`        | `string`                            | Unique RSVP identifier (UUID).                      |
| `eventId`   | `string`                            | The event this RSVP belongs to.                     |
| `userId`    | `string`                            | The user who RSVP'd.                                |
| `user`      | `User \| null`                      | Populated user object. Present on guest-list reads. |
| `status`    | `"going" \| "maybe" \| "not_going"` | The RSVP response.                                  |
| `createdAt` | `string`                            | ISO timestamp when the RSVP was first created.      |
| `updatedAt` | `string`                            | ISO timestamp when the RSVP was last changed.       |

## RsvpStatus

The set of valid RSVP values, which also map to the keys of `Event.rsvpCounts`:

| Value         | Description                                                                  |
| ------------- | ---------------------------------------------------------------------------- |
| `"going"`     | The user plans to attend. Counts toward `capacity`.                          |
| `"maybe"`     | The user might attend. Only allowed when the event's `allowMaybe` is `true`. |
| `"not_going"` | The user has declined.                                                       |

## Lifecycle

* **Set / change** — `POST /events/:eventId/rsvp` with a `status`. Creating or switching to `going` is capacity-checked under a row lock.
* **Withdraw** — `DELETE /events/:eventId/rsvp` deletes the RSVP row and decrements the corresponding count.
* **Removed on invite revoke** — if a host removes an invitee from an `invite`-only event, that user's RSVP is deleted and the count decremented.
* **Removed on user deletion** — deleting a user removes all their RSVPs and decrements affected events' counts.

## Related

* [Event data model](/data-models/event)
* [Set RSVP API](/api-reference/events/set-rsvp)
* [Withdraw RSVP API](/api-reference/events/withdraw-rsvp)
* [Fetch Event RSVPs API](/api-reference/events/fetch-event-rsvps)


# Reaction
Source: https://docs.sublay.io/v7/data-models/reaction

ReactionType, ReactionCounts, and the Reaction record interface

Sublay v7 uses an 8-type reaction system that replaces the legacy upvote/downvote arrays. Reactions can be applied to both entities and comments. Each reaction type has a defined effect on the target owner's reputation score.

## ReactionType

The set of valid reaction values:

| Value        | Reputation Effect | Description                 |
| ------------ | ----------------- | --------------------------- |
| `"upvote"`   | +1                | Positive endorsement        |
| `"downvote"` | −1                | Negative endorsement        |
| `"like"`     | +1                | Generic like                |
| `"love"`     | +2                | Strong positive reaction    |
| `"wow"`      | +1                | Surprise or amazement       |
| `"sad"`      | 0                 | Empathetic reaction         |
| `"angry"`    | 0                 | Negative emotional reaction |
| `"funny"`    | +1                | Humor reaction              |

## ReactionCounts

Every entity and comment includes a `reactionCounts` object with the current count for each reaction type:

```ts theme={null}
{
  upvote: number;
  downvote: number;
  like: number;
  love: number;
  wow: number;
  sad: number;
  angry: number;
  funny: number;
}
```

## Reaction Record

When fetching the list of users who reacted to an entity or comment, each item in the result is a `Reaction` record:

| Property       | Type                    | Description                                                   |
| -------------- | ----------------------- | ------------------------------------------------------------- |
| `id`           | `string`                | Unique reaction identifier (UUID).                            |
| `projectId`    | `string`                | The project this reaction belongs to.                         |
| `targetType`   | `"entity" \| "comment"` | Whether the reaction targets an entity or a comment.          |
| `targetId`     | `string`                | The ID of the entity or comment that was reacted to.          |
| `userId`       | `string`                | The ID of the user who reacted.                               |
| `reactionType` | `ReactionType`          | Which of the 8 reaction types was used.                       |
| `createdAt`    | `string`                | ISO timestamp when the reaction was created.                  |
| `updatedAt`    | `string`                | ISO timestamp when the reaction was last updated.             |
| `user`         | `User`                  | The user who reacted. Populated in fetch-reactions responses. |

## See Also

* [Entity](/data-models/entity)
* [Comment](/data-models/comment)
* [useReactionToggle hook](/hooks/reactions/use-reaction-toggle)
* [Fetch Entity Reactions](/api-reference/entities/fetch-reactions)
* [Fetch Comment Reactions](/api-reference/comments/fetch-reactions)


# Reputation
Source: https://docs.sublay.io/v7/data-models/reputation

Per-space reputation buckets, the maintained overall total, and the opt-in read contract for space-scoped reputation

Reputation in Sublay is **space-scoped**. Instead of a single number per user, each user accrues reputation into separate **buckets** — one per space, plus a project-general bucket — and their `reputation` field is the maintained sum of all of them.

Reputation is owned by the optional **`reputation`** bundle. Install it from the **Database** page of your project to turn the feature on. The `reputation` bundle works with or without the `spaces` bundle: without spaces, only the general bucket accrues. See [Bundles](/bundles).

## Buckets

The bundle provisions a per-tenant table of reputation buckets, keyed by `(userId, spaceId)`.

| Bucket          | Key                   | Meaning                                           |
| --------------- | --------------------- | ------------------------------------------------- |
| Project-general | `spaceId IS NULL`     | The user's reputation outside of any space.       |
| Per-space       | `spaceId = <spaceId>` | The user's reputation within that specific space. |

A few rules govern buckets:

* **Lazy creation** — a bucket is created the first time a user's reputation changes for that `(user, space)` pair. A bucket that has never been touched reads as `0`.
* **Negative scores allowed** — there is no floor; a bucket can go below zero.
* **Buckets are not returned directly** — there is no endpoint that lists raw buckets. You read reputation through the `reputation` total and the opt-in `spaceReputation` field described below.

## Where reputation comes from

Reputation accrues two ways:

* **Earned** — the system credits a user for what they do: creating entities and comments, and receiving votes and reactions on them. These changes are not individually recorded.
* **Granted** — reputation is deliberately *given*, either by another user (a transfer that debits their bucket) or by your app (a mint that creates it from nothing, or destroys it). Every grant is persisted as a [ReputationGrant](/data-models/reputation-grant) record, so a user's grant history is readable while their earned history is not.

Grants ship with this bundle — every project that has reputation has them, with no separate opt-in. A transfer never moves reputation between the general bucket and a space bucket: it lands in the recipient's bucket for the same space it left. See [ReputationGrant](/data-models/reputation-grant) and the [Reputation Grants SDK overview](/sdk/reputation/overview).

## The maintained total

Every user object still carries a `reputation` field, and default API responses are unchanged. `reputation` is the **maintained overall total** — the sum of all of that user's buckets (general plus every space). It is always present, whether or not a space is in context.

## Reading space-scoped reputation

Every user-returning endpoint accepts an opt-in **`spaceReputation`** object that adds a `spaceReputation` number to each returned user. The `reputation` total is always included regardless; the per-space `spaceReputation` field is purely additive and only appears when you ask for it.

### The `spaceReputation` object (primary form)

Pass a single object. Its two fields express which bucket to read and whether to sum descendants:

```ts theme={null}
spaceReputation: {
  spaceId: string | "none" | "context"; // "context" only on context endpoints
  includeDescendants?: boolean;
}
```

<ParamField type="object">
  Opt-in. Adds a `spaceReputation` number to each returned user, scoped to a single space.

  <Expandable title="spaceReputation">
    <ParamField name="spaceId" type="string | &#x22;none&#x22; | &#x22;context&#x22;">
      Which bucket to read:

      * a space **`<uuid>`** — that user's reputation in that specific space;
      * **`"none"`** — the project-general (space-less) bucket;
      * **`"context"`** — the space derived from the request context. On lists this is **per-row** (each author scored in the space *that row* belongs to); on single-space surfaces — space members/team, a chat conversation — it's that one space. **Only valid on context endpoints** (see below); user-direct endpoints **reject `"context"` with a 400**.

      A bucket that doesn't exist reads as `0`. The empty string and the legacy `general` / `null` aliases are **rejected (400)** — use `"none"` for the space-less bucket.
    </ParamField>

    <ParamField name="includeDescendants" type="boolean">
      Only honored alongside an explicit space `<uuid>`. When `true`, `spaceReputation` is the **subtree sum** — the named space plus all of its descendant spaces (the root space's own bucket is included). Ignored for `"none"`; not allowed with `"context"`.
    </ParamField>
  </Expandable>
</ParamField>

The object has **two variants** depending on the endpoint class — they differ only in whether `spaceId` accepts `"context"`:

| Variant         | `spaceId` accepts                 | Used by                                                                                                  |
| --------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------- |
| **Context**     | `<uuid>` · `"none"` · `"context"` | Entities, comments, reactions, chat, space members/team, moderated reports, content search & ask         |
| **User-direct** | `<uuid>` · `"none"`               | Fetch user (by ID / foreign ID / username), user suggestions, followers/following/connections by user ID |

### Deprecated flat props

The object **replaces** two flat props that travelled together. They still work — passing the object **wins** if both forms are supplied — but they are deprecated and will be removed in a later major version. Prefer the object.

<ParamField type="string">
  **Deprecated** — use `spaceReputation.spaceId`. Same value set as the object's `spaceId` for the matching endpoint variant (`<uuid>` / `"none"`, plus `"context"` on context endpoints only).
</ParamField>

<ParamField type="boolean">
  **Deprecated** — use `spaceReputation.includeDescendants`. Only honored alongside an explicit `spaceReputationId` `<uuid>`.
</ParamField>

The resulting field appears on each user object as:

<ResponseField name="spaceReputation" type="number">
  The user's reputation in the requested space (or the space-less bucket). Present only when the `spaceReputation` object (or the deprecated `spaceReputationId`) was supplied. Missing buckets read as `0`.
</ResponseField>

### Where the params apply

The `spaceReputation` object is accepted on **every** user-returning endpoint, but the allowed values for `spaceId` depend on whether the endpoint has a space in context.

**Context endpoints** accept `<uuid>`, `none`, **and** `context`:

* Entity feed and single entity
* Comment feed and single comment
* Entity and comment reaction lists
* Chat — list messages, get message, send message, list members, list reactions
* Space members and space team
* Moderated reports
* Content search and AI ask

**User-direct endpoints** accept `<uuid>` and `none` only — `context` is **rejected (400)** because there is no space context to derive:

* Fetch user (by ID, foreign ID, or username) and user suggestions
* Followers / following lists (by user ID)
* Connections list (by user ID)

Project-wide user search (`search-users`) and the self-relative follows/connections lists are **not** enriched and ignore the param.

## Uninstalling is lossy

Removing the `reputation` bundle drops the buckets table and the grants table — destroying all grant history — **and** zeroes the `reputation` column on every user. Reinstalling starts fresh from zero — past scores are not recomputed. Back up anything you need before uninstalling. See [Bundles](/bundles).

## See Also

* [Bundles](/bundles)
* [ReputationGrant data model](/data-models/reputation-grant)
* [User data model](/data-models/user)
* [Space data model](/data-models/space)


# ReputationGrant
Source: https://docs.sublay.io/v7/data-models/reputation-grant

The record of a single deliberate reputation movement — a user transfer or an app mint

A `ReputationGrant` records one deliberate movement of reputation. Where ordinary reputation is *earned* (posting, commenting, receiving reactions), a grant is *given* — by one user to another, or by your app to a user.

Grants are the primitive behind tipping, bounties, contest payouts, staff picks, "best answer" awards, and peer recognition. Sublay stays unopinionated about *why* a grant happens: the reason, the amounts, the eligibility rules, and the UI framing are all your app's logic. Sublay moves the points correctly, keeps the per-space economies honest, records what happened, and notifies the recipient.

Grants belong to the **`reputation`** bundle — every project with reputation has them, with no separate opt-in. See [Reputation](/data-models/reputation) and [Bundles](/bundles).

## The two kinds of grant

| `sourceType` | What it is                                                                           | Who can issue it                                                                    | Debits a sender |
| ------------ | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | --------------- |
| `"user"`     | A **transfer** — reputation leaves one user's bucket and lands in another's.         | The sender (user token), or your backend acting on their behalf with a service key. | Yes             |
| `"app"`      | A **mint** — reputation created from nothing, or (with a negative amount) destroyed. | Service or master key only.                                                         | No              |

`sourceType` is persisted rather than inferred from `senderId`, because `senderId` is also `null` on a transfer whose sender was later deleted.

## Properties

| Property      | Type                                              | Description                                                                                                           |
| ------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `id`          | `string`                                          | Unique grant identifier (UUID).                                                                                       |
| `sourceType`  | `"user" \| "app"`                                 | `"user"` for a debited transfer, `"app"` for a mint.                                                                  |
| `senderId`    | `string \| null`                                  | The user the reputation was debited from. Always `null` for a mint, and set to `null` if the sender is later deleted. |
| `sender`      | `User \| null`                                    | Populated when the list is read with `include=user`.                                                                  |
| `recipientId` | `string`                                          | The user credited.                                                                                                    |
| `recipient`   | `User \| null`                                    | Populated when the list is read with `include=user`.                                                                  |
| `amount`      | `number`                                          | Non-zero integer. Negative only when `sourceType` is `"app"`.                                                         |
| `spaceId`     | `string \| null`                                  | The bucket both legs moved in. `null` = the project-general bucket.                                                   |
| `targetType`  | `"entity" \| "comment" \| "chat-message" \| null` | What the grant was *for*, if anything.                                                                                |
| `targetId`    | `string \| null`                                  | The rewarded record's ID. Both target fields are null, or both are set.                                               |
| `note`        | `string \| null`                                  | Free-text note. Trimmed, up to 2000 characters.                                                                       |
| `metadata`    | `Record<string, any> \| null`                     | Your own key-value data. Up to 1 MB.                                                                                  |
| `createdAt`   | `string`                                          | ISO timestamp when the grant was issued.                                                                              |
| `updatedAt`   | `string`                                          | ISO timestamp. Grants are never updated; this exists for model parity.                                                |

## Which bucket moves

A user's reputation lives in [buckets](/data-models/reputation) — one per space, plus a project-general bucket. A grant always concerns exactly one bucket on each side, and the sender chooses which of *their* buckets pays:

* The reputation lands in the recipient's bucket **for the same space it came from**. Senders never choose where it lands.
* The general bucket is its own lane. Reputation cannot move between the general bucket and a space bucket in either direction.
* Consequently, the total reputation held within a given space is unchanged by a transfer — it only changes hands.

The named space must exist. Both write paths check it before touching a balance — an unknown `spaceId` is rejected with `404 reputation-grant/space-not-found`, and naming a space on a project without the `spaces` bundle with `403 database/tables-not-available`. Without that check a grant could fund a bucket for a space that does not exist: its score would still count toward its owner's profile total while being invisible in every space-scoped view.

A transfer is rejected unless the source bucket holds at least the amount, evaluated at the moment of the transfer. A mint has no source, so it may drive a bucket below zero (buckets have no floor — downvotes can already take one negative).

## The target is an annotation

A grant may point at one entity, comment, or chat message, so your app can render it in place — "this answer earned 120 points from 4 people".

* The target must exist when the grant is issued; a grant naming a missing record is rejected.
* The target does **not** have to be authored by the recipient.
* The target never determines which bucket is used. An app can reward a message living in one space using reputation from a different bucket.
* A target kind is only usable when the project has that capability. A `chat-message` target needs the `chat` bundle; `entity` and `comment` targets need their tables. Grants with no target are always available.
* Deleting the target does **not** reverse the grant. The points stay with the recipient; the attachment simply stops rendering.

## GrantSummary

Reading entities, comments, or chat messages with the `grants` include attaches a per-item summary rather than a full list:

| Property      | Type     | Description                                                                                                                                   |
| ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `total`       | `number` | Sum of positive grant amounts on the item.                                                                                                    |
| `count`       | `number` | Number of positive grants on the item.                                                                                                        |
| `viewerTotal` | `number` | The calling user's own summed positive grants on the item. A user may grant the same item more than once, so this is an amount, not a yes/no. |

The summary covers **positive grants only**. When the token is requested on a project whose schema has no grants table, the server returns a zero-filled summary (`{ total: 0, count: 0, viewerTotal: 0 }`) rather than omitting the key — so `grants` being `undefined` always means "nobody asked", never "this project has no grants".

<Warning>
  **One surface nests the record.** `GET /comments/:id` and `GET /comments/by-foreign-id` return the comment under a `comment` key, so the summary is at **`comment.grants`**. Every other read surface — entity reads, the comment feed, chat messages — returns the record bare, with the summary at `grants`.
</Warning>

The full per-item list of individual grants comes from [Fetch Many Reputation Grants](/api-reference/reputation-grants/fetch-many-reputation-grants), not from the summary.

## Grants on chat messages are private

A grant row carries its `targetType`, `targetId` and the granter's free-text `note`, and a list read can hydrate both parties. On a `chat-message` target those facts describe a private conversation — who is talking to whom, and what one of them said about it — so such a grant is exactly as private as the message it points at:

* **The target shape is gated on membership.** Listing grants by `targetType: "chat-message"` + `targetId` returns rows only to a **member** of that message's conversation. The test is the one [Fetch Message](/api-reference/chat/messages/fetch-message) itself applies — any membership row counts, so a member who has since left the conversation still sees the grants on a message chat still hands them. Everyone else — a user who was never a member, any user on a project without the `chat` bundle — gets a successful empty page with the zero summary, never a `403`, so the response cannot be used to prove the message exists. Service and master keys pass the gate unconditionally: they are the app's own backend, which holds no membership.
* **The user-keyed shapes carry the same test into the query.** Listing by `recipientId` or `senderId` returns a chat-message-targeted grant to a caller who can see the underlying message and withholds it from one who cannot. So a user's own "reputation I received" feed does include the grants made on messages in their own conversations, and reconciles with the reputation on their profile; a caller outside the conversation loses those rows from the page **and** from `totalItems` together, leaving nothing to infer arithmetically. Service and master keys are filtered on neither shape and read every row.
* **A removed message takes its grants with it.** Once moderation removes a message it is invisible on every chat surface, so its grants are invisible on both of these shapes too — to a member of the conversation as much as to a stranger, and to the grant's own sender and recipient. Only service and master keys still read them.

Grants targeting an entity or a comment are unaffected — those items are public — and so are grants with no target at all. The inline summary on the chat reads needs no special rule: those endpoints already refuse a non-member with `403 chat/not-a-member` before they read a message.

## Negative grants are private

A mint may be negative — a moderation clawback, a decay sweep, or a correction. Negative grants are deliberately invisible:

* They never notify the recipient.
* They are never broadcast over the chat socket.
* They are excluded from the public list endpoint **for every caller**, including service and master keys.
* They are excluded from every `GrantSummary`.

The only way to read them is the dashboard history route, [Fetch User Grant History](/api-reference/reputation-grants/fetch-user-grant-history), and the user detail view in the [dashboard](https://dash.sublay.io).

## Immutability

Grant rows are append-only. There is no undo, revoke, cancel window, or editing of the note or metadata. To reverse a grant, issue a compensating negative mint — both records stand.

Grant creation is **not idempotent**. A retried request creates a second grant and moves the points a second time, so clients are responsible for not double-submitting.

## Lifecycle

* **Sender deleted** — the grant record survives with `senderId` set to `null`, so a target's displayed total does not silently shrink.
* **Recipient deleted** — their grants are removed along with their reputation buckets, consistent with how reputation already behaves on user deletion.
* **Target deleted** — the grant stands; only the attachment stops rendering.
* **`reputation` bundle uninstalled** — grant history is destroyed along with the buckets.

## See Also

* [Reputation](/data-models/reputation)
* [Reputation Grants SDK overview](/sdk/reputation/overview)
* [Create Reputation Grant API](/api-reference/reputation-grants/create-reputation-grant)
* [Mint Reputation Grant API](/api-reference/reputation-grants/mint-reputation-grant)
* [Fetch Many Reputation Grants API](/api-reference/reputation-grants/fetch-many-reputation-grants)


# Rule
Source: https://docs.sublay.io/v7/data-models/rule

The Rule interface shape for space community rules

A rule represents a single community guideline for a space. Rules are ordered and displayed to members. They are managed by space admins and moderators.

## Properties

| Property         | Type             | Description                                                       |
| ---------------- | ---------------- | ----------------------------------------------------------------- |
| `id`             | `string`         | Unique rule identifier (UUID).                                    |
| `projectId`      | `string`         | The project this rule belongs to.                                 |
| `spaceId`        | `string`         | The space this rule belongs to.                                   |
| `title`          | `string`         | The rule's short title (e.g. "Be respectful").                    |
| `description`    | `string \| null` | Optional longer explanation of the rule.                          |
| `order`          | `number`         | Display order among the space's rules. Lower values appear first. |
| `lastApprovedBy` | `string \| null` | ID of the user who last reviewed or approved this rule.           |
| `createdAt`      | `Date`           | When the rule was created.                                        |
| `updatedAt`      | `Date`           | When the rule was last updated.                                   |

## See Also

* [List Rules](/api-reference/spaces/rules/list-rules)
* [Create Rule](/api-reference/spaces/rules/create-rule)
* [useFetchManyRules hook](/hooks/spaces/rules/use-fetch-many-rules)


# Space
Source: https://docs.sublay.io/v7/data-models/space

The shape of a Space object returned by the Spaces API and SDK

A Space is a community container — a named area where users can post entities, discuss in threads, and interact under configurable membership and permission rules. Spaces support hierarchical nesting, customizable read/post permissions, and avatar and banner images.

The API returns three space shapes depending on context:

* **`Space`** — the standard shape, returned when fetching a list of spaces.
* **`SpaceDetailed`** — returned when fetching a single space by ID, shortId, or slug. A superset of `Space` with added permission and hierarchy context.
* **`SpacePreview`** — a minimal snapshot, never returned as a standalone response. Only appears embedded inside `SpaceDetailed` as the shape of `parentSpace` and each item in `childSpaces[]`.

## Space

| Property              | Type                                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| --------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                  | `string`                              | Unique space identifier (UUID).                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `shortId`             | `string`                              | Short human-readable ID for the space (URL-safe, generated automatically).                                                                                                                                                                                                                                                                                                                                                                                    |
| `projectId`           | `string`                              | The project this space belongs to.                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `slug`                | `string \| null`                      | Optional URL-friendly slug. Unique per project when set.                                                                                                                                                                                                                                                                                                                                                                                                      |
| `name`                | `string`                              | Display name of the space (3–100 characters).                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `description`         | `string \| null`                      | Optional description (up to 1,000 characters).                                                                                                                                                                                                                                                                                                                                                                                                                |
| `userId`              | `string`                              | ID of the space creator/owner.                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `avatarFileId`        | `string \| null`                      | ID of the space's avatar image file.                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `avatarFile`          | `File \| undefined`                   | Populated avatar file object. Only present when `include: "files"` is requested.                                                                                                                                                                                                                                                                                                                                                                              |
| `bannerFileId`        | `string \| null`                      | ID of the space's banner image file.                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `bannerFile`          | `File \| undefined`                   | Populated banner file object. Only present when `include: "files"` is requested.                                                                                                                                                                                                                                                                                                                                                                              |
| `readingPermission`   | `"anyone" \| "members"`               | Who can read content in the space.                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `postingPermission`   | `"anyone" \| "members" \| "admins"`   | Who can post content in the space.                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `visibility`          | `"public" \| "unlisted" \| "private"` | Controls whether the space is *listed and discoverable* — independent of `readingPermission`, which controls who can read the content. `public` (the default) is listed in discovery and search; `unlisted` is hidden from discovery and search for non-members but still reachable by direct link/slug; `private` currently behaves exactly like `unlisted` (full existence-hiding is planned but not yet implemented). See [Visibility](#visibility) below. |
| `nsfw`                | `boolean`                             | The space's **own** NSFW flag. `false` by default. Set by space admins on [create](/hooks/spaces/use-create-space)/[update](/hooks/spaces/use-update-space) or by a project admin from the dashboard. See [NSFW flagging](#nsfw-flagging).                                                                                                                                                                                                                    |
| `nsfwEffective`       | `boolean`                             | **Denormalized, read-only.** `true` when this space's own `nsfw` is `true` **or** any ancestor space is NSFW. Maintained top-down on write and cascaded to descendants. This is the value the space `nsfwFilter` keys off, and it feeds each entity's live `nsfwEffective`. See [NSFW flagging](#nsfw-flagging).                                                                                                                                              |
| `requireJoinApproval` | `boolean`                             | Whether joining requires moderator/admin approval. When `true`, new joins enter `pending` status.                                                                                                                                                                                                                                                                                                                                                             |
| `parentSpaceId`       | `string \| null`                      | ID of the parent space, if this is a sub-space.                                                                                                                                                                                                                                                                                                                                                                                                               |
| `depth`               | `number`                              | Nesting depth (0 for root spaces, incremented for each sub-level). Maximum depth is 10.                                                                                                                                                                                                                                                                                                                                                                       |
| `metadata`            | `Record<string, any>`                 | Arbitrary key-value data attached to the space. Up to 1 MB.                                                                                                                                                                                                                                                                                                                                                                                                   |
| `isMember`            | `boolean \| undefined`                | Whether the authenticated user is a member of this space. Only present when the user is signed in.                                                                                                                                                                                                                                                                                                                                                            |
| `membersCount`        | `number`                              | Computed count of active members.                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `childSpacesCount`    | `number`                              | Computed count of direct child spaces.                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `createdAt`           | `Date`                                | Timestamp when the space was created.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `updatedAt`           | `Date`                                | Timestamp when the space was last updated.                                                                                                                                                                                                                                                                                                                                                                                                                    |

## SpaceDetailed

Returned when fetching a single space by ID, shortId, or slug. Includes all `Space` fields plus the following:

| Property            | Type                             | Description                                                                                      |
| ------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------ |
| `memberPermissions` | `SpaceMemberPermissions \| null` | The authenticated user's resolved permissions in this space. `null` if the user is not a member. |
| `parentSpace`       | `SpacePreview \| null`           | Preview of the parent space. `null` for root-level spaces.                                       |
| `childSpaces`       | `SpacePreview[]`                 | Preview of up to 10 immediate child spaces.                                                      |

## SpacePreview

A minimal space shape used only as an embedded reference — never returned directly by any endpoint. Appears as `SpaceDetailed.parentSpace` (the space one level up) and inside `SpaceDetailed.childSpaces[]` (spaces one level down).

| Property            | Type                                               | Description                    |
| ------------------- | -------------------------------------------------- | ------------------------------ |
| `id`                | `string`                                           | Space UUID.                    |
| `shortId`           | `string`                                           | Short identifier.              |
| `name`              | `string`                                           | Display name.                  |
| `slug`              | `string \| null`                                   | URL slug.                      |
| `avatarFileId`      | `string \| null`                                   | Avatar file ID.                |
| `readingPermission` | `"anyone" \| "members" \| undefined`               | Reading permission level.      |
| `visibility`        | `"public" \| "unlisted" \| "private" \| undefined` | Listing/discoverability level. |
| `parentSpaceId`     | `string \| null \| undefined`                      | Parent space reference.        |
| `depth`             | `number \| undefined`                              | Nesting depth.                 |

## SpaceMemberPermissions

Included in `SpaceDetailed.memberPermissions` for authenticated users who are members.

| Property      | Type                                        | Description                                       |
| ------------- | ------------------------------------------- | ------------------------------------------------- |
| `isAdmin`     | `boolean`                                   | Whether the user is an admin of this space.       |
| `isModerator` | `boolean`                                   | Whether the user is a moderator of this space.    |
| `isMember`    | `boolean`                                   | Whether the user has an active membership.        |
| `status`      | `"pending" \| "active" \| "banned" \| null` | The user's membership status.                     |
| `canPost`     | `boolean`                                   | Whether the user can post entities in this space. |
| `canModerate` | `boolean`                                   | Whether the user can perform moderation actions.  |
| `canRead`     | `boolean`                                   | Whether the user can read content in this space.  |

## Visibility

`visibility` is a distinct axis from `readingPermission`. **Visibility governs whether the space object is *listed and discoverable*; reading permission governs who can *read the content* inside it.** The two are fully independent — you can have a `public` space that only members can read, or an `unlisted` space that anyone can read once they have the link.

| Value      | Behavior                                                                                                                                                                                                         |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `public`   | **Default.** Listed in discovery and search, and resolvable by anyone. Matches all prior behavior.                                                                                                               |
| `unlisted` | Excluded from discovery lists and from search for non-members, but still reachable by direct link/slug. Joining works exactly as before (governed by the existing join/approval rules).                          |
| `private`  | Reserved for a future stage where the space's existence and metadata are hidden from non-members. **In this release, `private` behaves exactly like `unlisted`** — full existence-hiding is not yet implemented. |

<Note>
  `unlisted` is **not access control.** It only affects discoverability — it does not restrict who can read the content inside the space. To gate content, use `readingPermission`.
</Note>

Visibility can be set on [create](/api-reference/spaces/create-space) and [update](/api-reference/spaces/update-space), and changes take effect immediately and are freely reversible in both directions. A member of a space always continues to see it in surfaces that list their own spaces (e.g. `memberOf=true`, user spaces, mutual spaces) regardless of its visibility.

## NSFW flagging

NSFW is a separate axis from both `visibility` and `moderationStatus` — flagging a space (or entity) NSFW **labels** it, it does not hide or remove it. Every space carries its own `nsfw` boolean plus a denormalized `nsfwEffective`:

* **`nsfw`** — the space's own flag, defaulting to `false`. Toggled by space admins (via [create](/hooks/spaces/use-create-space)/[update](/hooks/spaces/use-update-space)) or by project admins from the dashboard.
* **`nsfwEffective`** — the denormalized rollup:

  ```
  nsfwEffective = own nsfw OR any ancestor space's nsfw
  ```

  It is maintained **on write**: creating a space under an NSFW parent inherits `nsfwEffective = true` even if its own `nsfw` is `false`, and toggling a space's own `nsfw` recomputes `nsfwEffective` top-down across its entire descendant subtree in the same transaction. A root space's `nsfwEffective` equals its own `nsfw`.

Because `nsfwEffective` folds in the whole ancestor chain, it is what an entity's live `nsfwEffective` reads from — flagging a space instantly cascades to every entity within it and its sub-spaces. See [Entity → NSFW flagging](/data-models/entity#nsfw-flagging).

To filter a list by effective NSFW, pass `nsfwFilter` to [Fetch many spaces](/hooks/spaces/use-fetch-many-spaces) (`include-all` default / `exclude` / `only`).

<Note>
  The space `nsfwFilter` keys off each space's own `nsfwEffective`, so `only` can return an NSFW child whose safe parent is omitted — results are **not** guaranteed to form a contiguous tree. Consumers building a tree from the result should not assume completeness.
</Note>

<Note>
  Sublay only **labels** and **filters** NSFW content. It does **not** blur, age-gate, add interstitials, or store a per-viewer "show mature content" preference — presentation is the consuming app's responsibility.
</Note>

## Related

* [Space Member data model](/data-models/space-member)
* [useSpace hook](/hooks/spaces/use-space)
* [Create Space API](/api-reference/spaces/create-space)
* [Fetch Space API](/api-reference/spaces/fetch-space)
* [Set space entity NSFW hook](/hooks/spaces/use-set-space-entity-nsfw)


# Space Member
Source: https://docs.sublay.io/v7/data-models/space-member

The shape of a SpaceMember object returned by the Spaces membership API

A SpaceMember record represents a user's membership in a specific space. It tracks their role (admin, moderator, or member), membership status (pending, active, banned, or rejected), and join timestamp.

## Properties

| Property    | Type                                              | Description                                 |
| ----------- | ------------------------------------------------- | ------------------------------------------- |
| `id`        | `string`                                          | Unique membership record identifier (UUID). |
| `projectId` | `string`                                          | The project this membership belongs to.     |
| `spaceId`   | `string`                                          | ID of the space this membership is for.     |
| `userId`    | `string`                                          | ID of the user who is a member.             |
| `role`      | `"admin" \| "moderator" \| "member"`              | The user's role in the space.               |
| `status`    | `"pending" \| "active" \| "banned" \| "rejected"` | The user's membership status.               |
| `joinedAt`  | `Date`                                            | Timestamp when the membership was created.  |
| `createdAt` | `Date`                                            | Record creation timestamp.                  |

## Membership Statuses

| Status     | Description                                                                                                                |
| ---------- | -------------------------------------------------------------------------------------------------------------------------- |
| `pending`  | Join request submitted but awaiting moderator/admin approval. Only applies when the space has `requireJoinApproval: true`. |
| `active`   | Full membership granted — user can read and post according to space permissions.                                           |
| `banned`   | User has been banned from the space. Banned users cannot access or post.                                                   |
| `rejected` | Join request was declined by a moderator or admin.                                                                         |

## Roles

| Role        | Description                                                                                                               |
| ----------- | ------------------------------------------------------------------------------------------------------------------------- |
| `admin`     | Full control: can update/delete the space, manage all members and roles, create rules, and moderate all content.          |
| `moderator` | Can approve/decline/ban members, moderate content and reports, but cannot change space settings or manage admin accounts. |
| `member`    | Regular participant. Can read and post according to the space's `postingPermission` setting.                              |

## SpaceMemberWithUser

Returned by the list members and list team endpoints. Includes embedded public user details.

| Property           | Type                                              | Description               |
| ------------------ | ------------------------------------------------- | ------------------------- |
| `membershipId`     | `string`                                          | The membership record ID. |
| `role`             | `"admin" \| "moderator" \| "member"`              | Member's role.            |
| `status`           | `"pending" \| "active" \| "banned" \| "rejected"` | Member's status.          |
| `joinedAt`         | `Date`                                            | When the user joined.     |
| `user.id`          | `string`                                          | User UUID.                |
| `user.username`    | `string`                                          | Username.                 |
| `user.displayName` | `string`                                          | Display name.             |
| `user.avatar`      | `string`                                          | Avatar URL.               |
| `user.metadata`    | `object`                                          | Public metadata.          |

<Note>Sensitive user fields (email, password hash, `secureMetadata`) are excluded from `SpaceMemberWithUser` responses.</Note>

## Related

* [Space data model](/data-models/space)
* [List Members API](/api-reference/spaces/membership/list-members)
* [useSpace hook](/hooks/spaces/use-space)


# User
Source: https://docs.sublay.io/v7/data-models/user

The User, AuthUser, and UserFull interface shapes returned by the API and SDK

Sublay exposes two user type variants depending on context: `User` (public profile) and `AuthUser` (the authenticated user's own data). All SDK hooks and API endpoints return one of these two types.

## User

The `User` type is returned when fetching another user's public profile. Sensitive and internal fields are excluded.

| Property          | Type                                  | Description                                                                                                                                                                                                          |
| ----------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`              | `string`                              | Unique user identifier (UUID).                                                                                                                                                                                       |
| `foreignId`       | `string \| null`                      | Your system's user ID if this user was created via external auth.                                                                                                                                                    |
| `projectId`       | `string`                              | The project this user belongs to.                                                                                                                                                                                    |
| `role`            | `"admin" \| "moderator" \| "visitor"` | The user's role within the project.                                                                                                                                                                                  |
| `name`            | `string \| null`                      | Display name.                                                                                                                                                                                                        |
| `username`        | `string \| null`                      | Unique username handle.                                                                                                                                                                                              |
| `avatar`          | `string \| null`                      | Avatar image URL.                                                                                                                                                                                                    |
| `avatarFileId`    | `string \| null`                      | ID of the managed avatar file record.                                                                                                                                                                                |
| `bannerFileId`    | `string \| null`                      | ID of the managed banner file record.                                                                                                                                                                                |
| `avatarFile`      | `File \| null`                        | Populated avatar file object when `include` contains `"files"`.                                                                                                                                                      |
| `bannerFile`      | `File \| null`                        | Populated banner file object when `include` contains `"files"`.                                                                                                                                                      |
| `bio`             | `string \| null`                      | Short biography (max 300 characters).                                                                                                                                                                                |
| `birthdate`       | `Date \| null`                        | User's date of birth.                                                                                                                                                                                                |
| `location`        | `GeoPoint \| null`                    | GeoJSON point representing the user's location.                                                                                                                                                                      |
| `metadata`        | `Record<string, any>`                 | Custom key-value data for your project (max 10 KB).                                                                                                                                                                  |
| `reputation`      | `number`                              | The user's overall reputation total — the sum of all their reputation buckets across every space. Always present. See [Reputation](/data-models/reputation).                                                         |
| `spaceReputation` | `number`                              | Opt-in. The user's reputation in a specific space, added only when an endpoint is called with the `spaceReputation` object (or the deprecated `spaceReputationId` param). See [Reputation](/data-models/reputation). |
| `createdAt`       | `Date`                                | Timestamp when the account was created.                                                                                                                                                                              |

### GeoPoint

| Property      | Type               | Description                              |
| ------------- | ------------------ | ---------------------------------------- |
| `type`        | `"Point"`          | GeoJSON geometry type. Always `"Point"`. |
| `coordinates` | `[number, number]` | Longitude and latitude, in that order.   |

## AuthUser

The `AuthUser` type is returned to the currently authenticated user about themselves. It extends `User` with additional fields not visible to others.

All `User` fields above are included, plus:

| Property      | Type             | Description                                                                          |
| ------------- | ---------------- | ------------------------------------------------------------------------------------ |
| `email`       | `string \| null` | The user's email address.                                                            |
| `isVerified`  | `boolean`        | Whether the user's email address has been verified.                                  |
| `isActive`    | `boolean`        | Whether the account is currently active.                                             |
| `lastActive`  | `Date`           | Timestamp of the user's last activity.                                               |
| `updatedAt`   | `Date`           | Timestamp when the account was last modified.                                        |
| `authMethods` | `string[]`       | Authentication methods linked to this account (e.g. `["password", "google"]`).       |
| `suspensions` | `Suspension[]`   | Array of active or past suspensions. See [Suspensions](/sdk/moderation/suspensions). |

### Suspension

An active suspension is an enforced, platform-wide timeout: it blocks all participation and content writes while leaving reads, sign-in, and account self-management open. Multiple active suspensions can coexist; the "effective" one is the furthest-reaching active row (an indefinite `endDate` of `null` reaches furthest). The [`useUser`](/hooks/user/use-user) hook derives `isSuspended` and `activeSuspension` from this array. See [Suspensions](/sdk/moderation/suspensions) for the full behavior and response contract.

| Property    | Type             | Description                                         |
| ----------- | ---------------- | --------------------------------------------------- |
| `reason`    | `string \| null` | The reason provided for the suspension.             |
| `startDate` | `Date`           | When the suspension began.                          |
| `endDate`   | `Date \| null`   | When the suspension ends, or `null` for indefinite. |

## Includes

Some endpoints accept an `include` parameter that populates additional fields. Pass `"files"` to populate `avatarFile` and `bannerFile` with [File](/data-models/file) objects.

## Reputation

Every user object always carries `reputation` — the maintained sum of the user's reputation across all spaces. When the optional `reputation` bundle is installed, you can additionally read a user's reputation in a specific space via the `spaceReputation` object (deprecating the older `spaceReputationId` param), which adds a `spaceReputation` field to each returned user. See the [Reputation data model](/data-models/reputation) for the full opt-in read contract.

## See Also

* [Reputation data model](/data-models/reputation)
* [Fetch User](/api-reference/users/fetch-user)
* [Update User](/api-reference/users/update-user)
* [useUser hook](/hooks/user/use-user)
* [useFetchUser hook](/hooks/users/use-fetch-user)


# Customization Guide
Source: https://docs.sublay.io/v7/components/components/notifications/customization

Customize notification control appearance and behavior

# Customizing Notification Control

Since you own the source code, you can customize everything: colors, layout, icons, behavior, and more.

***

## Changing Colors

### Styled Variant (Inline Styles)

Open `notification-control.tsx` and find the `colors` object:

```tsx theme={null}
const colors = {
  background: isDarkTheme ? "oklch(0.205 0 0)" : "#ffffff",
  border: isDarkTheme ? "oklch(1 0 0 / 10%)" : "#e5e7eb",
  text: isDarkTheme ? "oklch(0.985 0 0)" : "#0f172a",
  textMuted: isDarkTheme ? "oklch(0.708 0 0)" : "#64748b",
  separator: isDarkTheme ? "oklch(1 0 0 / 10%)" : "#f1f5f9",
};
```

Change to your brand colors:

```tsx theme={null}
const colors = {
  background: isDarkTheme ? "#1a1a2e" : "#f8f9fa",
  border: isDarkTheme ? "#3a3a5c" : "#dee2e6",
  text: isDarkTheme ? "#eaeaea" : "#212529",
  textMuted: isDarkTheme ? "#a0a0c0" : "#6c757d",
  separator: isDarkTheme ? "#2a2a4c" : "#e9ecef",
};
```

### Tailwind Variant

Change classes directly in files:

```tsx theme={null}
// Before
<div className="bg-white dark:bg-gray-900">
// After
<div className="bg-slate-50 dark:bg-slate-950">
```

***

## Modifying Layout

### Change Dropdown Width

In `notification-control.tsx`:

```tsx theme={null}
width: "500px",  // Default is ~400px
```

### Change Max Height

```tsx theme={null}
<div style={{ maxHeight: "600px" }}>  {/* Default is 500px */}
```

### Add Custom Header

```tsx theme={null}
{/* Add above notification list */}
<div style={{ padding: "12px", borderBottom: `1px solid ${colors.separator}` }}>
  <h3>Notifications</h3>
</div>
```

***

## Customizing Notification Items

### Change Avatar Size

In `notification-item.tsx`:

```tsx theme={null}
<div className="w-10 h-10">  {/* Default is w-8 h-8 */}
  <img src={avatar} />
</div>
```

### Remove Unread Indicator

```tsx theme={null}
{/* Delete or comment out: */}
{!notification.isRead && <div className="unread-dot" />}
```

### Add Timestamp

```tsx theme={null}
<span className="text-xs text-gray-500">
  {new Date(notification.createdAt).toLocaleDateString()}
</span>
```

***

## Changing Icons

### Change Icon Colors

In `notification-icon.tsx`, modify `getIconConfig`:

```tsx theme={null}
"comment-reply": {
  Icon: MessageSquare,
  colorClass: "text-purple-600 dark:text-purple-400",  // Changed from blue
  bgClass: "bg-purple-100 dark:bg-purple-500/15",
},
```

### Use Different Icons

Replace lucide-react icons:

```tsx theme={null}
import { CustomIcon } from '@/components/icons';

"comment-reply": {
  Icon: CustomIcon,
  colorClass: "text-blue-600",
  bgClass: "bg-blue-100",
},
```

***

## Customizing Time Format

Open `utils/notification-utils.ts`:

```tsx theme={null}
export function formatRelativeTime(dateInput: string | Date): string {
  const diffInSeconds = Math.floor((Date.now() - new Date(dateInput).getTime()) / 1000);

  // Show exact time for very recent notifications
  if (diffInSeconds < 60) {
    return new Date(dateInput).toLocaleTimeString();  // "2:34 PM"
  }

  if (diffInSeconds < 3600) {
    return `${Math.floor(diffInSeconds / 60)} minutes ago`;
  }

  // ... rest of function
}
```

***

## Adding Features

### Add Sound on New Notification

```tsx theme={null}
useEffect(() => {
  if (unreadCount > previousUnreadCount) {
    const audio = new Audio('/notification-sound.mp3');
    audio.play();
  }
}, [unreadCount]);
```

### Show Count in Page Title

```tsx theme={null}
useEffect(() => {
  document.title = unreadCount > 0 ? `(${unreadCount}) My App` : 'My App';
}, [unreadCount]);
```

***

## Dropdown Positioning

### Force Fixed Position

In `notification-control.tsx`:

```tsx theme={null}
position: "fixed" as const,
top: "60px",   // Below your header
right: "20px",
```

### Align to Left

```tsx theme={null}
left: "0px",
right: "auto",
```

***

## Animation Customization

The component uses framer-motion. Modify animations in `notification-control.tsx`:

```tsx theme={null}
<motion.div
  initial={{ opacity: 0, y: -10 }}
  animate={{ opacity: 1, y: 0 }}
  exit={{ opacity: 0, y: -10 }}
  transition={{ duration: 0.3 }}   // Adjust duration
>
```

Slide in from right instead:

```tsx theme={null}
initial={{ opacity: 0, x: 100 }}
animate={{ opacity: 1, x: 0 }}
exit={{ opacity: 0, x: 100 }}
```

***

## Empty State

Open `notification-list.tsx`:

```tsx theme={null}
{notifications.length === 0 && (
  <div className="empty-state">
    <Bell size={48} />
    <p>You're all caught up! 🎉</p>
  </div>
)}
```

***

## Common Customizations

<AccordionGroup>
  <Accordion title="Change badge color" icon="palette">
    In your trigger component:

    ```tsx theme={null}
    <span className="bg-purple-500">  {/* was bg-red-500 */}
      {unreadCount}
    </span>
    ```
  </Accordion>

  <Accordion title="Add notification categories" icon="folder">
    In `notification-control.tsx`, add tabs or filters:

    ```tsx theme={null}
    const [filter, setFilter] = useState('all');

    <div className="tabs">
      <button onClick={() => setFilter('all')}>All</button>
      <button onClick={() => setFilter('mentions')}>Mentions</button>
    </div>
    ```
  </Accordion>

  <Accordion title="Add confirmation before mark all read" icon="check">
    ```tsx theme={null}
    const handleMarkAllRead = () => {
      if (window.confirm('Mark all as read?')) {
        // existing logic
      }
    };
    ```
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup>
  <Card title="Integration Examples" icon="code" href="/v7/components/components/notifications/integration-examples">
    See real-world examples
  </Card>

  <Card title="Props & API" icon="sliders" href="/v7/components/components/notifications/props-api">
    Component props reference
  </Card>

  <Card title="Installation" icon="download" href="/v7/components/components/notifications/installation">
    Installation guide
  </Card>

  <Card title="Overview" icon="bell" href="/v7/components/components/notifications/overview">
    Back to overview
  </Card>
</CardGroup>


# Installing Notification Control
Source: https://docs.sublay.io/v7/components/components/notifications/installation

Add notification dropdown to your project

# Installing Notification Control

Add a notification dropdown control to your navigation bar with a single command.

***

## Prerequisites

<Steps>
  <Step title="Initialize CLI">
    ```bash theme={null}
    npx @sublay/cli init
    ```

    Creates your `sublay.json`. Select `react` as platform (notifications are web-only).
  </Step>

  <Step title="Install Dependencies">
    ```bash theme={null}
    npm install @sublay/react-js framer-motion lucide-react
    ```
  </Step>
</Steps>

See the [CLI Setup Guide](/v7/components/installation/cli-setup) for details.

***

## Installation Command

```bash theme={null}
npx @sublay/cli add notifications-control
```

***

## What Gets Installed

Only **5 files** — much simpler than comment components:

```
src/components/notifications-control/
├── index.ts                              # Barrel export (entry point)
├── components/
│   ├── notification-control.tsx          # Main dropdown control
│   ├── notification-list.tsx             # List with infinite scroll
│   ├── notification-item.tsx             # Individual notification row
│   └── notification-icon.tsx            # Type-based icon display
└── utils/
    └── notification-utils.ts             # Time formatting, text truncation
```

***

## Basic Usage

```tsx theme={null}
import NotificationControl from './components/notifications-control';
import { Bell } from 'lucide-react';

function Header() {
  const BellTrigger = ({ unreadCount }: { unreadCount: number }) => (
    <button className="relative p-2 hover:bg-gray-100 rounded-full">
      <Bell className="w-6 h-6" />
      {unreadCount > 0 && (
        <span className="absolute -top-1 -right-1 bg-red-500 text-white text-xs rounded-full w-5 h-5 flex items-center justify-center">
          {unreadCount}
        </span>
      )}
    </button>
  );

  return (
    <nav>
      <NotificationControl
        triggerComponent={BellTrigger}
        onNotificationClick={(notification) => {
          console.log('Clicked:', notification);
        }}
      />
    </nav>
  );
}
```

<Info>
  Make sure your app is wrapped with `<SublayProvider>`. See the [Quick Start Guide](/v7/components/installation/quick-start) for details.
</Info>

***

## Complete Example

```tsx theme={null}
import { SublayProvider } from '@sublay/react-js';
import NotificationControl from './components/notifications-control';
import { Bell } from 'lucide-react';
import { useNavigate } from 'react-router-dom';

function App() {
  return (
    <SublayProvider projectId="your-project-id" signedToken={token}>
      <Header />
      <main>{/* Your app */}</main>
    </SublayProvider>
  );
}

function Header() {
  const navigate = useNavigate();

  const BellIcon = ({ unreadCount }: { unreadCount: number }) => (
    <button className="relative p-2 hover:bg-gray-100 rounded-full">
      <Bell className="w-6 h-6" />
      {unreadCount > 0 && (
        <span className="absolute top-0 right-0 bg-red-500 text-white text-xs rounded-full w-5 h-5 flex items-center justify-center">
          {unreadCount}
        </span>
      )}
    </button>
  );

  return (
    <header>
      <nav className="container mx-auto px-4 py-3 flex justify-between items-center">
        <h1>My App</h1>

        <NotificationControl
          triggerComponent={BellIcon}
          onNotificationClick={(notification) => {
            if (notification.type === 'comment-reply') {
              navigate(`/posts/${notification.metadata.entityId}`);
            } else if (notification.type === 'new-follow') {
              navigate(`/users/${notification.metadata.followerId}`);
            }
          }}
          onViewAllNotifications={() => navigate('/notifications')}
        />
      </nav>
    </header>
  );
}
```

***

## Switching Styling Variants

<Steps>
  <Step title="Delete Current Component">
    ```bash theme={null}
    rm -rf src/components/notifications-control
    ```
  </Step>

  <Step title="Update Configuration">
    ```json theme={null}
    { "style": "styled" }
    ```
  </Step>

  <Step title="Re-install">
    ```bash theme={null}
    npx @sublay/cli add notifications-control
    ```
  </Step>
</Steps>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Import errors" icon="file-import">
    ```tsx theme={null}
    // paths.components = "src/components"
    import NotificationControl from './components/notifications-control';
    ```
  </Accordion>

  <Accordion title="Icons not showing" icon="image">
    ```bash theme={null}
    npm install lucide-react
    ```
  </Accordion>

  <Accordion title="Dropdown appears off-screen" icon="location-arrow">
    Check parent container CSS — containers with `overflow: hidden` can clip the dropdown. Set `overflow: visible` on any clipping ancestor.
  </Accordion>

  <Accordion title="Unread count not updating" icon="circle-dot">
    Ensure `<SublayProvider>` wraps the component and `signedToken` is set correctly.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup>
  <Card title="Props & API" icon="sliders" href="/v7/components/components/notifications/props-api">
    Learn about component props
  </Card>

  <Card title="Customization" icon="paintbrush" href="/v7/components/components/notifications/customization">
    Customize colors and layout
  </Card>

  <Card title="Integration Examples" icon="code" href="/v7/components/components/notifications/integration-examples">
    See real-world examples
  </Card>

  <Card title="Overview" icon="bell" href="/v7/components/components/notifications/overview">
    Back to overview
  </Card>
</CardGroup>


# Integration Examples
Source: https://docs.sublay.io/v7/components/components/notifications/integration-examples

Real-world notification control integration examples

# Integration Examples

Real-world examples of integrating `NotificationControl` into different applications.

***

## Next.js App Router

```tsx theme={null}
// app/components/Header.tsx
'use client';

import NotificationControl from '@/components/notifications-control';
import { Bell } from 'lucide-react';
import { useRouter } from 'next/navigation';

export default function Header() {
  const router = useRouter();

  const BellIcon = ({ unreadCount }: { unreadCount: number }) => (
    <button className="relative p-2 hover:bg-gray-100 dark:hover:bg-gray-800 rounded-full">
      <Bell className="w-6 h-6" />
      {unreadCount > 0 && (
        <span className="absolute -top-1 -right-1 bg-red-500 text-white text-xs rounded-full w-5 h-5 flex items-center justify-center">
          {unreadCount}
        </span>
      )}
    </button>
  );

  return (
    <header className="border-b">
      <nav className="container mx-auto px-4 py-3 flex justify-between items-center">
        <h1>My App</h1>

        <NotificationControl
          triggerComponent={BellIcon}
          onNotificationClick={(notif) => router.push(`/notifications/${notif.id}`)}
          onViewAllNotifications={() => router.push('/notifications')}
        />
      </nav>
    </header>
  );
}
```

***

## React Router (SPA)

```tsx theme={null}
import NotificationControl from './components/notifications-control';
import { Bell } from 'lucide-react';
import { useNavigate } from 'react-router-dom';

export default function Navigation() {
  const navigate = useNavigate();

  const handleNotificationClick = (notification: any) => {
    switch (notification.type) {
      case 'comment-reply':
        navigate(`/posts/${notification.metadata.entityId}#comment-${notification.metadata.commentId}`);
        break;
      case 'entity-mention':
        navigate(`/entities/${notification.metadata.entityId}`);
        break;
      case 'new-follow':
        navigate(`/profile/${notification.metadata.followerId}`);
        break;
      default:
        navigate('/notifications');
    }
  };

  const BellIcon = ({ unreadCount }: { unreadCount: number }) => (
    <button className="relative">
      <Bell className="w-6 h-6" />
      {unreadCount > 0 && <span className="badge">{unreadCount}</span>}
    </button>
  );

  return (
    <nav>
      <NotificationControl
        triggerComponent={BellIcon}
        onNotificationClick={handleNotificationClick}
        onViewAllNotifications={() => navigate('/notifications')}
      />
    </nav>
  );
}
```

***

## Social Media App

```tsx theme={null}
function SocialHeader() {
  return (
    <header>
      <NotificationControl
        triggerComponent={BellWithBadge}
        notificationTemplates={{
          'comment-reply': true,
          'comment-mention': true,
          'entity-upvote': true,
          'new-follow': true,
          'connection-accepted': true,
        }}
        onNotificationClick={(notif) => {
          if (notif.type === 'new-follow') {
            navigate(`/profile/${notif.metadata.followerId}`);
          } else if (notif.type === 'comment-reply') {
            navigate(`/post/${notif.metadata.entityId}`);
          }
        }}
      />
    </header>
  );
}
```

***

## SaaS Dashboard (System Notifications Only)

```tsx theme={null}
function DashboardHeader() {
  return (
    <header>
      <NotificationControl
        triggerComponent={SystemBell}
        notificationTemplates={{
          'system': true,
        }}
        onNotificationClick={(notif) => {
          if (notif.metadata.buttonData) {
            window.location.href = notif.metadata.buttonData.url;
          }
        }}
      />
    </header>
  );
}
```

***

## With Theme Toggle

```tsx theme={null}
import { useState, useEffect } from 'react';
import NotificationControl from './components/notifications-control';
import { Bell, Moon, Sun } from 'lucide-react';

function Header() {
  const [isDark, setIsDark] = useState(false);

  useEffect(() => {
    setIsDark(window.matchMedia('(prefers-color-scheme: dark)').matches);
  }, []);

  return (
    <header className={isDark ? 'dark' : ''}>
      <nav>
        <button onClick={() => setIsDark(!isDark)}>
          {isDark ? <Sun /> : <Moon />}
        </button>

        <NotificationControl
          triggerComponent={BellIcon}
          onNotificationClick={handleClick}
          theme={isDark ? 'dark' : 'light'}
        />
      </nav>
    </header>
  );
}
```

***

## With Analytics Tracking

```tsx theme={null}
import { analytics } from '@/lib/analytics';

<NotificationControl
  triggerComponent={BellIcon}
  onNotificationClick={(notif) => {
    analytics.track('Notification Clicked', {
      notificationId: notif.id,
      notificationType: notif.type,
      isRead: notif.isRead,
    });
    handleNavigation(notif);
  }}
/>
```

***

## Accessible Implementation

```tsx theme={null}
const AccessibleBell = ({ unreadCount }: { unreadCount: number }) => (
  <button
    aria-label={`Notifications${unreadCount > 0 ? `, ${unreadCount} unread` : ''}`}
    aria-haspopup="true"
    className="relative"
  >
    <Bell className="w-6 h-6" />
    {unreadCount > 0 && (
      <span aria-label={`${unreadCount} unread notifications`} className="badge">
        {unreadCount}
      </span>
    )}
  </button>
);
```

***

## Complete Working Example

```tsx theme={null}
'use client';

import { useState } from 'react';
import { SublayProvider } from '@sublay/react-js';
import NotificationControl from './components/notifications-control';
import { Bell } from 'lucide-react';

export default function App() {
  const [isDark, setIsDark] = useState(false);

  const BellTrigger = ({ unreadCount }: { unreadCount: number }) => (
    <button className="relative p-2 rounded-full hover:bg-gray-100 dark:hover:bg-gray-800">
      <Bell className="w-6 h-6" />
      {unreadCount > 0 && (
        <span className="absolute -top-1 -right-1 bg-red-500 text-white text-xs w-5 h-5 rounded-full flex items-center justify-center">
          {unreadCount}
        </span>
      )}
    </button>
  );

  return (
    <SublayProvider projectId="your-project-id" signedToken={token}>
      <div className={isDark ? 'dark' : ''}>
        <header className="bg-white dark:bg-gray-900 border-b">
          <nav className="container mx-auto px-4 py-3 flex items-center justify-between">
            <h1>My App</h1>

            <div className="flex items-center gap-4">
              <button onClick={() => setIsDark(!isDark)}>
                {isDark ? '☀️' : '🌙'}
              </button>

              <NotificationControl
                triggerComponent={BellTrigger}
                onNotificationClick={(notification) => {
                  console.log('Notification clicked:', notification);
                }}
                onViewAllNotifications={() => {
                  window.location.href = '/notifications';
                }}
              />
            </div>
          </nav>
        </header>

        <main>{/* Your app content */}</main>
      </div>
    </SublayProvider>
  );
}
```

***

## Next Steps

<CardGroup>
  <Card title="Props & API" icon="sliders" href="/v7/components/components/notifications/props-api">
    Component props reference
  </Card>

  <Card title="Customization" icon="paintbrush" href="/v7/components/components/notifications/customization">
    Customize appearance
  </Card>

  <Card title="Installation" icon="download" href="/v7/components/components/notifications/installation">
    Installation guide
  </Card>

  <Card title="Overview" icon="bell" href="/v7/components/components/notifications/overview">
    Back to overview
  </Card>
</CardGroup>


# Notification Control Overview
Source: https://docs.sublay.io/v7/components/components/notifications/overview

Dropdown notification bell control for real-time app notifications

# Notification Control

A dropdown notification control component for displaying real-time application notifications. Think GitHub, LinkedIn, or Facebook's notification bell — shows an unread count and displays a notification list when clicked.

***

## Key Features

<CardGroup>
  <Card title="Real-Time Updates" icon="bolt">
    Automatic real-time updates when new notifications arrive.
  </Card>

  <Card title="Smart Positioning" icon="location-arrow">
    Dropdown automatically positions itself to stay within viewport bounds. Never overflows screen edges.
  </Card>

  <Card title="Infinite Scroll" icon="arrows-down-to-line">
    Load more notifications on demand. Starts with 10, loads more as needed.
  </Card>

  <Card title="Mark as Read" icon="check">
    Click to mark individual notifications as read, or use "Mark all read" for bulk actions.
  </Card>

  <Card title="Unread Badge" icon="circle-dot">
    Shows unread count on the trigger component. Updates automatically in real-time.
  </Card>

  <Card title="Theme Support" icon="palette">
    Full light/dark/auto mode support with both inline styles and Tailwind variants.
  </Card>
</CardGroup>

***

## What It's NOT

<Warning>
  This is **not** a full-page notifications center or inbox. It's a dropdown control component designed for navigation bars and headers.

  For a full notifications page, use the `useAppNotifications` hook from `@sublay/react-js` to build a custom interface.
</Warning>

***

## Use Cases

**Perfect for:**

* Navigation bar notification bells
* Header dropdown notifications
* Real-time notification alerts
* Social media style notification systems
* SaaS dashboard notifications

**File Complexity:** Only **5 files** — much simpler than comment components.

***

## Notification Types Supported

| Type                  | Icon          | Trigger               |
| --------------------- | ------------- | --------------------- |
| `system`              | Wrench        | System announcements  |
| `entity-comment`      | MessageCircle | New comment on entity |
| `comment-reply`       | MessageSquare | Reply to your comment |
| `entity-mention`      | @             | Mentioned in entity   |
| `comment-mention`     | @             | Mentioned in comment  |
| `entity-upvote`       | Heart         | Upvote on entity      |
| `comment-upvote`      | Heart         | Upvote on comment     |
| `new-follow`          | UserPlus      | New follower          |
| `connection-accepted` | UserPlus      | Connection accepted   |
| `connection-request`  | UserPlus      | Connection request    |

Icons are from **lucide-react**.

***

## Platform Support

| Platform     | Status            |
| ------------ | ----------------- |
| React (Web)  | ✅ Fully supported |
| React Native | ❌ Not available   |
| Expo         | ❌ Not available   |

***

## Required Dependencies

```json theme={null}
{
  "dependencies": {
    "@sublay/react-js": "^7.0.0",
    "framer-motion": "^12.0.0",
    "lucide-react": "^1.0.0"
  }
}
```

The CLI checks for these and offers to install them automatically.

***

## Next Steps

<CardGroup>
  <Card title="Installation" icon="download" href="/v7/components/components/notifications/installation">
    Add notification control to your project
  </Card>

  <Card title="Props & API" icon="sliders" href="/v7/components/components/notifications/props-api">
    Learn about component props
  </Card>

  <Card title="Customization" icon="paintbrush" href="/v7/components/components/notifications/customization">
    Customize colors, layout, and behavior
  </Card>

  <Card title="Integration Examples" icon="code" href="/v7/components/components/notifications/integration-examples">
    See real-world integration examples
  </Card>
</CardGroup>


# Props & API Reference
Source: https://docs.sublay.io/v7/components/components/notifications/props-api

NotificationControl component props and configuration

# Notification Control Props

The `NotificationControl` component has a minimal API focused on flexibility.

***

## Component Import

```tsx theme={null}
import NotificationControl from './components/notifications-control';
```

***

## Props Interface

```tsx theme={null}
interface NotificationControlProps {
  // Required
  triggerComponent: React.ComponentType<{ unreadCount: number }>;
  onNotificationClick: (notification: AppNotification.PotentiallyPopulatedUnifiedAppNotification) => void;

  // Optional
  notificationTemplates?: AppNotification.NotificationTemplates;
  onViewAllNotifications?: () => void;
  theme?: "auto" | "light" | "dark";  // Styled variant only
}
```

***

## Required Props

### `triggerComponent`

**Type:** `React.ComponentType<{ unreadCount: number }>` — **Required**

A React component that triggers the dropdown. Receives `unreadCount` as a prop so you can display a badge.

<Tabs>
  <Tab title="Simple">
    ```tsx theme={null}
    const SimpleBell = ({ unreadCount }: { unreadCount: number }) => (
      <button>
        🔔 {unreadCount > 0 && `(${unreadCount})`}
      </button>
    );
    ```
  </Tab>

  <Tab title="With Badge">
    ```tsx theme={null}
    import { Bell } from 'lucide-react';

    const BellWithBadge = ({ unreadCount }: { unreadCount: number }) => (
      <div className="relative">
        <Bell className="w-6 h-6" />
        {unreadCount > 0 && (
          <span className="absolute -top-1 -right-1 bg-red-500 text-white text-xs rounded-full w-5 h-5 flex items-center justify-center">
            {unreadCount > 9 ? '9+' : unreadCount}
          </span>
        )}
      </div>
    );
    ```
  </Tab>

  <Tab title="With Animation">
    ```tsx theme={null}
    import { motion } from 'framer-motion';
    import { Bell } from 'lucide-react';

    const AnimatedBell = ({ unreadCount }: { unreadCount: number }) => (
      <motion.button whileHover={{ scale: 1.1 }} whileTap={{ scale: 0.95 }}>
        <Bell className="w-6 h-6" />
        {unreadCount > 0 && (
          <motion.span
            initial={{ scale: 0 }}
            animate={{ scale: 1 }}
            className="badge"
          >
            {unreadCount}
          </motion.span>
        )}
      </motion.button>
    );
    ```
  </Tab>
</Tabs>

```tsx theme={null}
<NotificationControl
  triggerComponent={BellWithBadge}
  onNotificationClick={handleClick}
/>
```

***

### `onNotificationClick`

**Type:** `(notification: UnifiedAppNotification) => void` — **Required**

Callback fired when a notification is clicked. The notification is automatically marked as read.

```tsx theme={null}
<NotificationControl
  triggerComponent={BellIcon}
  onNotificationClick={(notification) => {
    switch (notification.type) {
      case 'comment-reply':
        navigate(`/posts/${notification.metadata.entityId}`);
        break;
      case 'new-follow':
        navigate(`/profile/${notification.metadata.followerId}`);
        break;
      default:
        navigate('/notifications');
    }
  }}
/>
```

**Notification object structure:**

```tsx theme={null}
interface UnifiedAppNotification {
  id: string;
  userId: string;
  isRead: boolean;
  createdAt: string;
  type: "system" | "entity-comment" | "comment-reply" | "entity-mention" |
        "comment-mention" | "entity-upvote" | "comment-upvote" | "new-follow" |
        "connection-accepted" | "connection-request";
  title: string;
  content: string | null;
  metadata: {
    entityId?: string;
    commentId?: string;
    initiatorAvatar?: string;
    buttonData?: { text: string; url: string };
  };
}
```

***

## Optional Props

### `notificationTemplates`

**Type:** `AppNotification.NotificationTemplates` — **Default:** all types shown

Filter which notification types to display in the dropdown.

```tsx theme={null}
<NotificationControl
  triggerComponent={BellIcon}
  onNotificationClick={handleClick}
  notificationTemplates={{
    'comment-reply': true,
    'entity-mention': true,
    'new-follow': true,
    'system': false,  // Hide system notifications
  }}
/>
```

***

### `onViewAllNotifications`

**Type:** `() => void` — **Default:** `undefined`

Callback for a "View all notifications" button shown in the dropdown footer. When not provided, the footer button is hidden.

```tsx theme={null}
<NotificationControl
  triggerComponent={BellIcon}
  onNotificationClick={handleClick}
  onViewAllNotifications={() => navigate('/notifications')}
/>
```

***

### `theme`

**Type:** `"auto" | "light" | "dark"` — **Default:** `"auto"`

**Only for the inline styles variant.** Controls the dropdown color theme.

<Tabs>
  <Tab title="auto">
    Uses `prefers-color-scheme` media query to detect system theme.

    ```tsx theme={null}
    <NotificationControl theme="auto" {...props} />
    ```
  </Tab>

  <Tab title="light / dark">
    Forces a specific theme — useful when synced to your app's theme state.

    ```tsx theme={null}
    <NotificationControl
      theme={isDark ? 'dark' : 'light'}
      {...props}
    />
    ```
  </Tab>
</Tabs>

<Note>
  The **Tailwind variant** ignores this prop. Use Tailwind's dark mode system instead (add `dark` class to a parent element).
</Note>

***

## Complete Example

```tsx theme={null}
import NotificationControl from './components/notifications-control';
import { Bell } from 'lucide-react';
import { useNavigate } from 'react-router-dom';
import { useState } from 'react';

function Header() {
  const navigate = useNavigate();
  const [isDark, setIsDark] = useState(false);

  const BellIcon = ({ unreadCount }: { unreadCount: number }) => (
    <button className="relative p-2 hover:bg-gray-100 rounded-full">
      <Bell className="w-6 h-6" />
      {unreadCount > 0 && (
        <span className="absolute -top-1 -right-1 bg-red-500 text-white text-xs rounded-full w-5 h-5 flex items-center justify-center">
          {unreadCount > 9 ? '9+' : unreadCount}
        </span>
      )}
    </button>
  );

  return (
    <nav>
      <NotificationControl
        triggerComponent={BellIcon}
        onNotificationClick={(notification) => {
          if (notification.type === 'comment-reply') {
            navigate(`/posts/${notification.metadata.entityId}`);
          } else if (notification.type === 'new-follow') {
            navigate(`/users/${notification.metadata.followerId}`);
          }
        }}
        notificationTemplates={{
          'comment-reply': true,
          'entity-mention': true,
          'new-follow': true,
          'entity-upvote': true,
        }}
        onViewAllNotifications={() => navigate('/notifications')}
        theme={isDark ? 'dark' : 'light'}
      />
    </nav>
  );
}
```

***

## Utility Functions

```tsx theme={null}
// From utils/notification-utils.ts

formatRelativeTime(date: string | Date): string
// Returns: "Just now", "5m ago", "2h ago", "3d ago"

truncateText(text: string, maxLength?: number): string
// Returns: "Long text here..." (with ellipsis)
```

***

## Next Steps

<CardGroup>
  <Card title="Customization" icon="paintbrush" href="/v7/components/components/notifications/customization">
    Customize colors, layout, and behavior
  </Card>

  <Card title="Integration Examples" icon="code" href="/v7/components/components/notifications/integration-examples">
    See real-world examples
  </Card>

  <Card title="Installation" icon="download" href="/v7/components/components/notifications/installation">
    Installation guide
  </Card>

  <Card title="Overview" icon="bell" href="/v7/components/components/notifications/overview">
    Back to overview
  </Card>
</CardGroup>


# Component Types
Source: https://docs.sublay.io/v7/components/components/overview

Choose the right comment style for your application

# Choosing Your Comment Style

Sublay offers three ready-to-install components, each optimized for different use cases and user experiences.

***

## Available Components

<CardGroup>
  <Card title="Threaded Comments" icon="comments" href="/v7/components/components/threaded/overview">
    **Reddit-style threaded discussions**

    * Unlimited nesting depth
    * Upvote/downvote with scores
    * Visual threading lines
    * Collapsible threads
    * Focus on structured discussions

    **Package:** `comments-threaded`
  </Card>

  <Card title="Social Comments" icon="heart" href="/v7/components/components/social/overview">
    **Instagram-style social comments**

    * Single-level nesting (max 2 levels)
    * Heart/like system (no dislikes)
    * Top/New/Old sorting
    * Clean, minimal design
    * Quick social interactions

    **Package:** `comments-social`
  </Card>

  <Card title="Notification Control" icon="bell" href="/v7/components/components/notifications/overview">
    **Dropdown notification bell**

    * Real-time notification updates
    * Smart viewport positioning
    * Mark as read functionality
    * Infinite scroll
    * Lightweight (5 files)

    **Package:** `notifications-control`
  </Card>
</CardGroup>

***

## Comparison

| Feature          | Threaded Comments                      | Social Comments                  |
| ---------------- | -------------------------------------- | -------------------------------- |
| **Nesting**      | Unlimited depth                        | 2 levels (comments + replies)    |
| **Voting**       | Upvote/downvote with score             | Heart/like only                  |
| **Visual Style** | Threading lines, indentation           | Flat, minimal design             |
| **Sorting**      | Best/Top (by votes)                    | Top/New/Old                      |
| **Collapsing**   | ✅ Collapsible threads                  | ❌ No collapsing                  |
| **Best For**     | Forums, discussions, technical content | Social media, quick interactions |

***

## Platform Support

| Platform         | Threaded Comments | Social Comments | Notification Control |
| ---------------- | :---------------: | :-------------: | :------------------: |
| **React (Web)**  |         ✅         |        ✅        |           ✅          |
| **React Native** |         ✅         |        ✅        |           ❌          |
| **Expo**         |         ✅         |        ✅        |           ❌          |

***

## When to Use Threaded Comments

Choose **Threaded Comments** when you need:

<AccordionGroup>
  <Accordion title="Deep Discussions" icon="messages">
    Forums, technical discussions, and detailed conversations benefit from unlimited nesting. Users can reply to specific points deep in a thread.

    **Example use cases:** Developer forums, blog posts, Q\&A platforms, community discussions
  </Accordion>

  <Accordion title="Vote-Based Ranking" icon="arrow-up">
    Upvotes and downvotes help surface quality content and hide low-quality contributions. Scores provide social proof.

    **Example use cases:** Reddit-style communities, news sites, user-generated content platforms
  </Accordion>

  <Accordion title="Visual Hierarchy" icon="sitemap">
    Threading lines and indentation make it easy to follow complex conversation flows and see which comments are responding to what.

    **Example use cases:** Long discussions, debates, multi-topic threads
  </Accordion>
</AccordionGroup>

***

## When to Use Social Comments

Choose **Social Comments** when you need:

<AccordionGroup>
  <Accordion title="Quick Interactions" icon="bolt">
    Simple, fast commenting without deep nesting. Perfect for social media-style engagement.

    **Example use cases:** Photo/video platforms, social apps, short-form content, mobile-first experiences
  </Accordion>

  <Accordion title="Positive-Only Engagement" icon="heart">
    Hearts/likes promote positive interactions without the negativity of downvotes.

    **Example use cases:** Creator platforms, brand engagement, positive communities
  </Accordion>

  <Accordion title="Clean, Minimal Design" icon="sparkles">
    Flat, uncluttered interface that doesn't distract from content.

    **Example use cases:** Mobile apps, visual content platforms, minimalist designs
  </Accordion>
</AccordionGroup>

***

## Can I Use Both?

Yes. Install both in the same project and use whichever fits each context:

```bash theme={null}
npx @sublay/cli add comments-threaded
npx @sublay/cli add comments-social
```

```tsx theme={null}
// Blog posts — threaded
import { ThreadedCommentSection } from './components/comments-threaded';

function BlogPost({ post }) {
  return (
    <>
      <Article content={post.content} />
      <ThreadedCommentSection entityId={post.id} />
    </>
  );
}

// Photos — social
import { SocialCommentSection } from './components/comments-social';

function PhotoPost({ photo }) {
  return (
    <>
      <Image src={photo.url} />
      <SocialCommentSection entityId={photo.id} />
    </>
  );
}
```

<Info>
  Both components install into separate directories and won't conflict with each other.
</Info>

***

## Next Steps

<CardGroup>
  <Card title="Threaded Comments" icon="comments" href="/v7/components/components/threaded/overview">
    Reddit-style threaded comments
  </Card>

  <Card title="Social Comments" icon="heart" href="/v7/components/components/social/overview">
    Instagram-style social comments
  </Card>

  <Card title="Notification Control" icon="bell" href="/v7/components/components/notifications/overview">
    Dropdown notification bell
  </Card>

  <Card title="Quick Start" icon="rocket" href="/v7/components/installation/quick-start">
    Get started in under 5 minutes
  </Card>
</CardGroup>


# Social Comments Features
Source: https://docs.sublay.io/v7/components/components/social/features

Feature overview for social comments

# Social Comments Features

Instagram-style comment system features.

***

## Core Features

### Single-Level Nesting

Maximum 2 levels: comments and replies. Keeps conversations simple and easy to follow.

```
Comment 1
  └─ Reply to Comment 1
  └─ Another reply

Comment 2
  └─ Reply to Comment 2
```

***

### Heart/Like System

Positive-only engagement with heart icons.

* Heart button with like count display
* One like per user per comment
* Unlike at any time
* No downvotes — positive community focus

***

### Sorting

Built-in Top/New/Old sorting that users can switch on the fly.

* **Top** — Most liked comments first
* **New** — Newest comments first
* **Old** — Oldest comments first

***

### @ Mentions

Tag users with `@username`.

* Autocomplete suggestions as you type
* Clickable mentions link to user profiles (via `otherUserClickCallback`)
* Mentioned users receive notifications (if enabled)
* Works in both comments and replies

***

### Edit & Delete

Comment authors can edit or delete their own comments.

* **Edit:** Inline text editing, shows "edited" indicator
* **Delete:** Confirmation modal, soft delete preserves thread structure

***

### Reporting

Built-in reporting for inappropriate content.

* Click "Report" from the action menu
* Select a reason and submit
* Reports appear in the [Sublay Dashboard](https://dash.sublay.io) for admin review

***

### Loading States

Skeleton loaders while fetching comments — prevents layout shift and provides visual feedback.

***

### Empty States

Friendly placeholder when no comments exist. Customize `no-comments-placeholder.tsx` to change messaging or add illustrations.

***

### Real-Time Updates

Comments automatically update when other users post. No configuration required — powered by `@sublay/react-js` subscriptions.

***

### Dark Mode

Full dark mode support.

**Inline Styles Variant:**

```tsx theme={null}
<SocialCommentSection
  foreignId="photo_123"
  theme={isDark ? 'dark' : 'light'}
/>
```

**Tailwind Variant:**

```tsx theme={null}
<html className={isDark ? 'dark' : ''}>
  <SocialCommentSection foreignId="photo_123" />
</html>
```

***

### GIF Support (Optional)

Enable a GIF picker via the [Sublay Dashboard](https://dash.sublay.io). Add a Giphy API key and GIF search appears in comment forms automatically — no code changes needed.

***

## Feature Matrix

| Feature               | Included |        Customizable        |
| --------------------- | :------: | :------------------------: |
| Single-level nesting  |     ✅    |              ✅             |
| Heart/like system     |     ✅    | ✅ (icon, color, animation) |
| Sorting (Top/New/Old) |     ✅    | ✅ (remove options, rename) |
| @ Mentions            |     ✅    |  ✅ (autocomplete styling)  |
| Edit comments         |     ✅    |              ✅             |
| Delete comments       |     ✅    |     ✅ (confirmation UI)    |
| Reporting             |     ✅    | ✅ (reasons, modal styling) |
| Loading states        |     ✅    |     ✅ (skeleton design)    |
| Empty states          |     ✅    |    ✅ (messaging, design)   |
| Real-time updates     |     ✅    |   ❌ (handled by core SDK)  |
| Dark mode             |     ✅    |              ✅             |
| GIF support           |     ✅    |  ❌ (enabled in dashboard)  |

***

## Next Steps

<CardGroup>
  <Card title="Props & API" icon="sliders" href="/v7/components/components/social/props-api">
    Props reference
  </Card>

  <Card title="Customization" icon="paintbrush" href="/v7/components/customization/overview">
    Customize components
  </Card>

  <Card title="File Structure" icon="folder-tree" href="/v7/components/components/social/file-structure">
    File organization
  </Card>

  <Card title="Installation" icon="download" href="/v7/components/components/social/installation">
    Installation guide
  </Card>
</CardGroup>


# Social Comments File Structure
Source: https://docs.sublay.io/v7/components/components/social/file-structure

File organization for social comments

# Social Comments File Structure

Approximately 23 files organized for simplicity and clarity.

***

## Directory Tree

```
src/components/comments-social/
├── index.ts                              # Barrel export (entry point)
├── components/
│   ├── social-comment-section.tsx        # Main component
│   ├── new-comment-form.tsx              # Comment/reply input
│   ├── reply-banner.tsx                  # Shows who you're replying to
│   ├── mention-suggestions.tsx           # @ mention autocomplete
│   ├── sort-by-button.tsx               # Top/New/Old sort control
│   ├── comments-feed/
│   │   ├── comments-feed.tsx             # Feed container
│   │   ├── loaded-comments.tsx           # Comment list
│   │   ├── fetching-comments-skeletons.tsx
│   │   ├── no-comments-placeholder.tsx
│   │   └── comment/
│   │       ├── comment.tsx              # Individual comment + replies
│   │       ├── heart-button.tsx         # Like button with count
│   │       └── replies.tsx              # Reply list
│   └── modals/
│       ├── report-comment-modal/
│       │   ├── report-comment-modal.tsx
│       │   ├── modal-background.tsx
│       │   └── report-modal-content.tsx
│       └── delete-comment-modal/
│           └── delete-comment-modal.tsx
├── hooks/
│   ├── use-social-comments.tsx           # Main comment logic and callbacks
│   └── use-ui-state.tsx                  # UI state (modals, active reply)
├── utils/
│   └── prop-comparison.ts               # Memoization helpers
└── context/
    └── ui-state-context.tsx             # Provides UI state to components
```

***

## Key Files

### `social-comment-section.tsx` — Main Component

The entry component. Edit this to modify the overall layout, add headers or footers, or change how the component is structured.

***

### `new-comment-form.tsx` — Comment Input

Handles both top-level comment input and reply input (reused for both). Edit to:

* Customize placeholder text
* Change submit button styles
* Add character limits

***

### `heart-button.tsx` — Like Button

The heart icon and like count. Edit to:

* Change the heart icon color or style
* Modify the like count display
* Add animations on like

***

### `sort-by-button.tsx` — Sort Control

The Top/New/Old sort switcher. Edit to:

* Rename sort options
* Remove sort options you don't need
* Change button styles

***

### `use-social-comments.tsx` — Main Hook

Contains all comment logic and the key behavioral callbacks you'll want to customize:

* `loginRequiredCallback` — Called when an unauthenticated user tries to comment
* `usernameRequiredCallback` — Called when a user without a username tries to comment
* `currentUserClickCallback` — Called when a user clicks their own profile
* `otherUserClickCallback(userId, foreignId)` — Called when a user clicks another user's profile

***

## Key Differences from Threaded Comments

| Threaded                      | Social                 |
| ----------------------------- | ---------------------- |
| `vote-buttons.tsx`            | `heart-button.tsx`     |
| Threading lines + indentation | Flat design            |
| Unlimited nesting             | Max 2 levels           |
| No sort button                | `sort-by-button.tsx`   |
| Complex thread collapse       | Simple reply expansion |

***

## Common Customizations

### Change Heart Color

```tsx theme={null}
// Edit: components/social/comments-feed/comment/heart-button.tsx
<span style={{ color: '#EC4899' }}>  {/* Pink heart */}
  ❤️
</span>
```

### Modify Sort Options

```tsx theme={null}
// Edit: components/social/social-comment-section.tsx
const sortOptions = ['top', 'new'];  // Remove 'old' option
```

### Customize Empty State

```tsx theme={null}
// Edit: components/social/comments-feed/no-comments-placeholder.tsx
<p>No comments yet. Be the first! 🎉</p>
```

***

## Next Steps

<CardGroup>
  <Card title="Features" icon="star" href="/v7/components/components/social/features">
    Feature overview
  </Card>

  <Card title="Customization" icon="paintbrush" href="/v7/components/customization/overview">
    Customize colors, layout, and functionality
  </Card>

  <Card title="Props & API" icon="sliders" href="/v7/components/components/social/props-api">
    Props reference
  </Card>

  <Card title="Installation" icon="download" href="/v7/components/components/social/installation">
    Installation guide
  </Card>
</CardGroup>


# Installing Social Comments
Source: https://docs.sublay.io/v7/components/components/social/installation

Add Instagram-style social comments to your project

# Installing Social Comments

Add Instagram-style social comments to your project with a single command.

***

## Prerequisites

<Steps>
  <Step title="Initialize CLI">
    ```bash theme={null}
    npx @sublay/cli init
    ```

    Creates your `sublay.json` configuration file. Select your platform and styling preference.
  </Step>

  <Step title="Install Dependencies">
    **React (Web):**

    ```bash theme={null}
    npm install @sublay/react-js @sublay/ui-core-react-js
    ```

    **React Native:**

    ```bash theme={null}
    npm install @sublay/react-native @sublay/ui-core-react-native
    ```

    **Expo:**

    ```bash theme={null}
    npm install @sublay/expo @sublay/ui-core-react-native
    ```
  </Step>
</Steps>

See the [CLI Setup Guide](/v7/components/installation/cli-setup) for details.

***

## Installation Command

```bash theme={null}
npx @sublay/cli add comments-social
```

***

## What Gets Installed

The CLI copies approximately 23 files into your project:

```
src/components/comments-social/
├── index.ts                              # Barrel export (entry point)
├── components/                           # UI components (~18 files)
│   ├── social-comment-section.tsx        # Main component
│   ├── new-comment-form.tsx              # Comment input form
│   ├── reply-banner.tsx                  # Reply indicator
│   ├── mention-suggestions.tsx           # @ mention autocomplete
│   ├── sort-by-button.tsx               # Top/New/Old sorting
│   ├── comments-feed/
│   │   ├── comments-feed.tsx             # Feed container
│   │   ├── loaded-comments.tsx           # Comment list
│   │   ├── fetching-comments-skeletons.tsx
│   │   ├── no-comments-placeholder.tsx
│   │   └── comment/
│   │       ├── comment.tsx              # Individual comment
│   │       ├── heart-button.tsx         # Like button
│   │       └── replies.tsx
│   └── modals/
│       ├── report-comment-modal/        # Report modal
│       └── delete-comment-modal/        # Delete confirmation
├── hooks/
│   ├── use-social-comments.tsx          # Main comment logic
│   └── use-ui-state.tsx                 # UI state management
├── utils/
│   └── prop-comparison.ts
└── context/
    └── ui-state-context.tsx
```

***

## Using the Component

```tsx theme={null}
import { SocialCommentSection } from './components/comments-social';

function Post({ post }) {
  return (
    <div>
      <img src={post.image} alt={post.caption} />
      <p>{post.caption}</p>
      <SocialCommentSection entityId={post.id} />
    </div>
  );
}
```

<Info>
  Make sure your app is wrapped with `<SublayProvider>`. See the [Quick Start Guide](/v7/components/installation/quick-start) for setup details.
</Info>

***

## Platform Support

| Platform     | Tailwind | Inline Styles |
| ------------ | :------: | :-----------: |
| React (Web)  |     ✅    |       ✅       |
| React Native |     ✅    |       ✅       |
| Expo         |     ✅    |       ✅       |

***

## Switching Styling Variants

<Steps>
  <Step title="Delete Current Components">
    ```bash theme={null}
    rm -rf src/components/comments-social
    ```
  </Step>

  <Step title="Update Configuration">
    Edit `sublay.json`:

    ```json theme={null}
    { "style": "styled" }
    ```
  </Step>

  <Step title="Re-install">
    ```bash theme={null}
    npx @sublay/cli add comments-social
    ```
  </Step>
</Steps>

<Warning>
  This replaces your component files. Back up any customizations first.
</Warning>

***

## Next Steps

<CardGroup>
  <Card title="Props & API" icon="sliders" href="/v7/components/components/social/props-api">
    Learn about available props
  </Card>

  <Card title="Customization" icon="paintbrush" href="/v7/components/customization/overview">
    Customize the component
  </Card>

  <Card title="Features" icon="star" href="/v7/components/components/social/features">
    Explore all features
  </Card>

  <Card title="File Structure" icon="folder-tree" href="/v7/components/components/social/file-structure">
    Understand file organization
  </Card>
</CardGroup>


# Social Comments Overview
Source: https://docs.sublay.io/v7/components/components/social/overview

Instagram-style social comment system

# Social Comments

Instagram-style social comment system with hearts/likes, single-level nesting, and clean minimal design.

***

## Key Features

<CardGroup>
  <Card title="Simple Nesting" icon="layer-group">
    Maximum 2 levels: comments and replies. Clean, easy-to-follow conversations.
  </Card>

  <Card title="Heart/Like System" icon="heart">
    Positive-only engagement. No downvotes — just likes.
  </Card>

  <Card title="Sorting Options" icon="arrow-down-wide-short">
    Top/New/Old sorting built-in. Users can switch on the fly.
  </Card>

  <Card title="Minimal Design" icon="sparkles">
    Clean, uncluttered interface perfect for mobile and visual content.
  </Card>

  <Card title="@ Mentions" icon="at">
    Tag other users with autocomplete suggestions.
  </Card>

  <Card title="Real-Time Updates" icon="bolt">
    Automatic updates when new comments arrive.
  </Card>
</CardGroup>

***

## Use Cases

**Perfect for:**

* Social media platforms
* Photo/video sharing apps
* Content creator platforms
* Mobile-first experiences
* Quick social interactions
* Brand engagement

**Not ideal for:**

* Deep technical discussions (use [Threaded Comments](/v7/components/components/threaded/overview) instead)
* Platforms that need voting/scoring
* Content requiring complex threading

***

## Platform Support

| Platform     | Status            |
| ------------ | ----------------- |
| React (Web)  | ✅ Fully supported |
| React Native | ✅ Fully supported |
| Expo         | ✅ Fully supported |

***

## Styling Variants

<Tabs>
  <Tab title="Tailwind CSS">
    Uses Tailwind utility classes. Requires Tailwind CSS (or NativeWind for React Native) installed.

    Best for projects using Tailwind or design system integration.
  </Tab>

  <Tab title="Inline Styles">
    Uses inline `style={{}}` objects with conditional dark mode logic. No external dependencies.

    Best for projects without Tailwind, or where explicit styling is preferred.
  </Tab>
</Tabs>

Choose your preference during `npx @sublay/cli init`.

***

## Required Dependencies

**React (Web):**

```json theme={null}
{
  "dependencies": {
    "@sublay/react-js": "^7.0.0",
    "@sublay/ui-core-react-js": "^7.0.0"
  }
}
```

**React Native / Expo:**

```json theme={null}
{
  "dependencies": {
    "@sublay/react-native": "^7.0.0",
    "@sublay/ui-core-react-native": "^7.0.0"
  }
}
```

***

## Next Steps

<CardGroup>
  <Card title="Installation" icon="download" href="/v7/components/components/social/installation">
    Add social comments to your project
  </Card>

  <Card title="Props & API" icon="sliders" href="/v7/components/components/social/props-api">
    Learn about available props
  </Card>

  <Card title="File Structure" icon="folder-tree" href="/v7/components/components/social/file-structure">
    Understand file organization
  </Card>

  <Card title="Features" icon="star" href="/v7/components/components/social/features">
    Explore all features
  </Card>
</CardGroup>


# Social Comments Props
Source: https://docs.sublay.io/v7/components/components/social/props-api

SocialCommentSection props and API

# Social Comments Props

The `SocialCommentSection` component follows the same **minimal props philosophy** as all Sublay components. It works with just `entityId` and offers optional props for specific needs.

***

## Component Import

```tsx theme={null}
import { SocialCommentSection } from './components/comments-social';
```

***

## Props Interface

```tsx theme={null}
interface SocialCommentSectionProps {
  // Entity identification (provide ONE of these)
  entity?: Entity | undefined | null;
  entityId?: string | undefined | null;
  foreignId?: string | undefined | null;
  shortId?: string | undefined | null;

  // Optional features
  isVisible?: boolean;
  highlightedCommentId?: string | undefined | null;
  theme?: 'light' | 'dark';   // Only for inline styles variant
  children?: React.ReactNode;
}
```

***

## Entity Identification

**Provide one of these** to identify which entity the comments belong to:

### `entity`

**Type:** `Entity | undefined | null`

A complete Entity object. Use when you already have it from `useFetchEntity` or similar hooks.

### `entityId`

**Type:** `string | undefined | null`

The internal Sublay ID for the entity.

### `foreignId`

**Type:** `string | undefined | null`

Your external/custom ID for the entity. The component finds or creates the Sublay entity automatically. This is the most common option.

### `shortId`

**Type:** `string | undefined | null`

A short, human-readable identifier if you've set one on the entity.

<Note>
  **You only need ONE of these props.** Use whichever fits your data model best.
</Note>

***

## Optional Props

### `isVisible`

**Type:** `boolean` — **Default:** `true`

Controls whether the comment section is visible. Useful when rendering inside a modal, drawer, or bottom sheet.

```tsx theme={null}
<SocialCommentSection
  entityId="photo_123"
  isVisible={showComments}
/>
```

***

### `highlightedCommentId`

**Type:** `string | undefined | null`

ID of a specific comment to highlight on load. The component scrolls to it and applies a highlight that fades after a few seconds.

```tsx theme={null}
<SocialCommentSection
  entityId="photo_123"
  highlightedCommentId="comment_456"
/>
```

***

### `theme`

**Type:** `'light' | 'dark'` — **Default:** `'light'`

**Only for the inline styles variant.** Sets the color theme for the component.

<Tabs>
  <Tab title="Inline Styles Variant">
    ```tsx theme={null}
    <SocialCommentSection
      foreignId="photo_123"
      theme={isDark ? 'dark' : 'light'}
    />
    ```
  </Tab>

  <Tab title="Tailwind Variant">
    Ignores this prop. Use Tailwind's dark mode system instead:

    ```tsx theme={null}
    <html className={isDark ? 'dark' : ''}>
      <SocialCommentSection foreignId="photo_123" />
    </html>
    ```

    Requires `darkMode: 'class'` in `tailwind.config.js`.
  </Tab>
</Tabs>

***

### `children`

**Type:** `React.ReactNode`

Optional content rendered within the comment section.

```tsx theme={null}
<SocialCommentSection entityId="photo_123">
  <div className="text-center text-gray-400 text-sm my-2">
    Share your thoughts!
  </div>
</SocialCommentSection>
```

***

## Usage Examples

### Minimal

```tsx theme={null}
<SocialCommentSection foreignId="photo_123" />
```

***

### With Dark Mode (Inline Styles)

```tsx theme={null}
function PhotoPost({ photo }) {
  const [isDark, setIsDark] = useState(false);

  return (
    <>
      <img src={photo.url} />
      <SocialCommentSection
        foreignId={photo.id}
        theme={isDark ? 'dark' : 'light'}
      />
    </>
  );
}
```

***

### With Highlighted Comment

```tsx theme={null}
import { useSearchParams } from 'react-router-dom';

function PhotoPost({ photo }) {
  const [searchParams] = useSearchParams();

  return (
    <SocialCommentSection
      foreignId={photo.id}
      highlightedCommentId={searchParams.get('commentId')}
    />
  );
}
```

***

### In a React Native Bottom Sheet

```tsx theme={null}
import BottomSheet from '@gorhom/bottom-sheet';

function PhotoScreen({ photo }) {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      <PhotoView photo={photo} onCommentPress={() => setIsOpen(true)} />

      <BottomSheet isOpen={isOpen}>
        <SocialCommentSection
          foreignId={photo.id}
          isVisible={isOpen}
        />
      </BottomSheet>
    </>
  );
}
```

***

## Next Steps

<CardGroup>
  <Card title="File Structure" icon="folder-tree" href="/v7/components/components/social/file-structure">
    Component organization
  </Card>

  <Card title="Features" icon="star" href="/v7/components/components/social/features">
    Feature overview
  </Card>

  <Card title="Customization" icon="paintbrush" href="/v7/components/customization/overview">
    Customize the component
  </Card>

  <Card title="Installation" icon="download" href="/v7/components/components/social/installation">
    Installation guide
  </Card>
</CardGroup>


# Features
Source: https://docs.sublay.io/v7/components/components/threaded/features

Explore all threaded comments features

# Threaded Comments Features

Comprehensive feature overview for Reddit-style threaded comments.

***

## Core Features

### Unlimited Nesting

Comments can be nested infinitely deep. Users can reply to any comment, creating branching conversation threads.

```
Comment 1
  └─ Reply to Comment 1
      └─ Reply to Reply
          └─ Reply to Reply to Reply
              └─ And so on...
```

Visual indicators: indentation, threading lines connecting replies to parents, and clear depth distinction.

***

### Upvote/Downvote System

Reddit-style voting with visible vote scores.

* Upvote (▲) and downvote (▼) buttons
* Net score display (upvotes − downvotes)
* Visual feedback on current vote state
* One vote per user per comment
* Change or remove vote at any time
* Can't vote on your own comments

***

### Visual Threading

Clear visual hierarchy with indentation and connection lines.

* Each reply level indented by 16px (customizable)
* Threading lines show parent-child relationships
* Collapsible threads to hide long chains

Edit `indentation-threading-lines.tsx` to adjust spacing, colors, or line styles.

***

### Collapsible Threads

Users can collapse/expand entire comment chains.

* Click `[-]` to collapse a comment and all its replies
* Click `[+]` to expand
* Collapsed state shows reply count
* Useful for navigating long discussions

***

### @ Mentions

Tag other users with `@username`.

* Autocomplete suggestions as you type
* Clickable mentions link to user profiles (via `otherUserClickCallback`)
* Mentioned users receive notifications (if enabled)
* Works in both comments and replies

***

### Highlighted Comments

Deep-link to specific comments with visual highlighting.

```tsx theme={null}
<ThreadedCommentSection
  foreignId="post_123"
  highlightedCommentId="comment_abc"
/>
```

The component:

1. Scrolls to the highlighted comment
2. Applies a highlight background color
3. Fades the highlight after a few seconds

**Use cases:** Notification links, URL params like `?commentId=abc123`.

***

### Edit & Delete

Comment authors can edit or delete their own comments.

**Edit:** Click "Edit" from the action menu, modify text inline, save or cancel. An "edited" indicator is shown.

**Delete:** Click "Delete" from the action menu, confirm. Soft delete — the comment shows `[deleted]` to preserve thread structure.

***

### Reporting & Moderation

Built-in reporting for inappropriate content.

**Users:** Click "Report" → select reason → submit.

**Admins:** Reports appear in the [Sublay Dashboard](https://dash.sublay.io) for review. Full moderation toolkit including comment deletion and user banning.

***

### Loading States

Skeleton loaders while fetching comments. Realistic skeleton UI mimics comment structure and prevents layout shift.

**File:** `fetching-comments-skeletons.tsx`

***

### Empty States

Friendly placeholder when no comments exist yet.

**Default message:** "No comments yet. Be the first to comment!"

Customize `no-comments-placeholder.tsx` to change messaging or add illustrations.

***

### Real-Time Updates

Comments automatically update when other users post. No configuration needed — powered by `@sublay/react-js` subscriptions.

***

### Dark Mode Support

**Inline Styles Variant:**

```tsx theme={null}
<ThreadedCommentSection
  foreignId="post_123"
  theme={isDark ? 'dark' : 'light'}
/>
```

**Tailwind Variant:**

```tsx theme={null}
<html className={isDark ? 'dark' : ''}>
  <ThreadedCommentSection foreignId="post_123" />
</html>
```

All colors adapt automatically.

***

### GIF Support (Optional)

Enable a GIF picker in comment forms via the [Sublay Dashboard](https://dash.sublay.io). Add a Giphy API key and GIF search appears automatically — no code changes needed.

***

## Feature Matrix

| Feature              | Included |            Customizable           |
| -------------------- | :------: | :-------------------------------: |
| Unlimited nesting    |     ✅    |    ✅ (max depth can be limited)   |
| Upvote/downvote      |     ✅    |    ✅ (can remove, change icons)   |
| Threading lines      |     ✅    |        ✅ (colors, spacing)        |
| Collapsible threads  |     ✅    |        ✅ (behavior, icons)        |
| @ Mentions           |     ✅    |      ✅ (autocomplete styling)     |
| Highlighted comments |     ✅    |   ✅ (highlight color, duration)   |
| Edit comments        |     ✅    | ✅ (can disable, add confirmation) |
| Delete comments      |     ✅    |  ✅ (can add confirmation dialog)  |
| Reporting            |     ✅    | ✅ (report reasons, modal styling) |
| Loading states       |     ✅    |        ✅ (skeleton design)        |
| Empty states         |     ✅    |       ✅ (messaging, design)       |
| Real-time updates    |     ✅    |      ❌ (handled by core SDK)      |
| Dark mode            |     ✅    |    ✅ (all colors customizable)    |
| GIF support          |     ✅    |      ❌ (enabled in dashboard)     |

***

## Next Steps

<CardGroup>
  <Card title="Customization" icon="paintbrush" href="/v7/components/customization/overview">
    Learn how to customize features
  </Card>

  <Card title="Props & API" icon="sliders" href="/v7/components/components/threaded/props-api">
    Component props reference
  </Card>

  <Card title="File Structure" icon="folder-tree" href="/v7/components/components/threaded/file-structure">
    Understand file organization
  </Card>

  <Card title="Installation" icon="download" href="/v7/components/components/threaded/installation">
    Installation guide
  </Card>
</CardGroup>


# File Structure
Source: https://docs.sublay.io/v7/components/components/threaded/file-structure

Understanding the threaded comments file organization

# File Structure

When you install threaded comments, approximately 25 TypeScript/TSX files are copied into your project in a clear, navigable structure.

***

## Directory Tree

```
src/components/comments-threaded/
├── index.ts                              # Barrel export (entry point)
├── components/                           # UI components (~20 files)
│   ├── threaded-comment-section.tsx     # Main component
│   ├── new-comment-form.tsx             # Top-level comment form
│   ├── mention-suggestions.tsx          # @ mention autocomplete
│   ├── comments-feed/
│   │   ├── comments-feed.tsx            # Feed container
│   │   ├── loaded-comments.tsx          # Renders comment list
│   │   ├── fetching-comments-skeletons.tsx
│   │   ├── no-comments-placeholder.tsx
│   │   └── comment-thread/
│   │       ├── comment-thread.tsx       # Thread with replies
│   │       ├── comment-replies.tsx      # Reply list
│   │       ├── action-menu.tsx          # Edit/delete/report menu
│   │       ├── new-reply-form.tsx       # Reply form
│   │       └── single-comment/
│   │           ├── single-comment.tsx   # Individual comment
│   │           ├── vote-buttons.tsx     # Upvote/downvote
│   │           ├── reply-button-and-info.tsx
│   │           ├── toggle-replies-visibility.tsx
│   │           └── indentation-threading-lines.tsx
│   └── modals/
│       ├── comment-menu-modal/          # Report modal (3 files)
│       │   ├── comment-menu-modal.tsx
│       │   ├── modal-background.tsx
│       │   └── report-modal-content.tsx
│       └── comment-menu-modal-owner/    # Owner actions
│           └── comment-menu-modal-owner.tsx
├── hooks/
│   ├── use-threaded-comments.tsx        # Main comment logic
│   └── use-ui-state.tsx                 # UI state management
├── utils/
│   └── prop-comparison.ts               # Memoization helpers
└── context/
    └── ui-state-context.tsx             # Modal & theme context
```

***

## Key Files

### `index.ts` — Entry Point

Barrel export for clean imports:

```tsx theme={null}
export { default as ThreadedCommentSection } from './components/threaded-comment-section';
```

This lets you write:

```tsx theme={null}
import { ThreadedCommentSection } from './components/comments-threaded';
```

***

### `threaded-comment-section.tsx` — Main Component

The entry component that orchestrates everything. Edit this to:

* Add custom headers or footers
* Modify the overall layout
* Change the component structure

***

### `new-comment-form.tsx` — Comment Input

The textarea and submit button for top-level comments. Edit this to:

* Customize placeholder text
* Change button styles
* Add character counters

***

### `single-comment.tsx` — Individual Comment

The core comment display component. Edit this to:

* Change author name styling
* Modify comment body layout
* Add custom badges or labels

***

### `vote-buttons.tsx` — Voting UI

Upvote and downvote buttons with score display. Edit this to:

* Change button colors
* Modify vote count formatting
* Change icon styles

***

### `use-threaded-comments.tsx` — Main Hook

Contains all comment data logic and callbacks. This is where you customize behavior like:

* `loginRequiredCallback` — Called when an unauthenticated user tries to comment
* `usernameRequiredCallback` — Called when a user without a username tries to comment
* `otherUserClickCallback` — Called when a user clicks on another user's name/avatar

***

## Common Customizations

### Change Colors

**Inline Styles Variant:** Look for the color palette guide at the top of component files:

```tsx theme={null}
/**
 * COLOR PALETTE
 * - #3B82F6 → Primary blue (votes, links)
 * - #EF4444 → Red (downvotes, delete)
 * - #111827 → #F9FAFB (text)
 * - #FFFFFF → #1F2937 (backgrounds)
 */
```

Find and replace hex codes throughout the file.

**Tailwind Variant:** Change utility classes directly:

```tsx theme={null}
// Before
<button className="bg-blue-600 hover:bg-blue-700">
// After
<button className="bg-purple-600 hover:bg-purple-700">
```

***

### Modify Layout

Open `threaded-comment-section.tsx` and rearrange JSX:

```tsx theme={null}
return (
  <div>
    <h2>Discussion ({totalComments} comments)</h2>
    <NewCommentForm />
    <CommentsFeed />
  </div>
);
```

***

### Remove Features

Don't want vote buttons? Remove them from `single-comment.tsx`:

```tsx theme={null}
return (
  <div>
    <AuthorInfo />
    <CommentBody />
    {/* <VoteButtons /> */}
    <ReplyButton />
  </div>
);
```

***

## File Responsibilities

| Directory      | Purpose                         |
| -------------- | ------------------------------- |
| `/components/` | All UI/JSX components           |
| `/hooks/`      | React hooks for state and logic |
| `/utils/`      | Helper functions                |
| `/context/`    | React context providers         |
| `/modals/`     | Modal dialogs (report, actions) |

***

## Next Steps

<CardGroup>
  <Card title="Props & API" icon="sliders" href="/v7/components/components/threaded/props-api">
    Component props reference
  </Card>

  <Card title="Customization" icon="paintbrush" href="/v7/components/customization/overview">
    Customize colors, layout, functionality
  </Card>

  <Card title="Features" icon="star" href="/v7/components/components/threaded/features">
    Explore all features
  </Card>

  <Card title="Installation" icon="download" href="/v7/components/components/threaded/installation">
    Installation guide
  </Card>
</CardGroup>


# Installing Threaded Comments
Source: https://docs.sublay.io/v7/components/components/threaded/installation

Add Reddit-style threaded comments to your project

# Installing Threaded Comments

Add Reddit-style threaded comments to your project with a single command.

***

## Prerequisites

<Steps>
  <Step title="Initialize CLI">
    ```bash theme={null}
    npx @sublay/cli init
    ```

    Creates your `sublay.json` configuration file.
  </Step>

  <Step title="Install Dependencies">
    **React (Web):**

    ```bash theme={null}
    npm install @sublay/react-js @sublay/ui-core-react-js
    ```

    **React Native:**

    ```bash theme={null}
    npm install @sublay/react-native @sublay/ui-core-react-native
    ```

    **Expo:**

    ```bash theme={null}
    npm install @sublay/expo @sublay/ui-core-react-native
    ```
  </Step>
</Steps>

See the [CLI Setup Guide](/v7/components/installation/cli-setup) for details.

***

## Installation Command

```bash theme={null}
npx @sublay/cli add comments-threaded
```

***

## What Gets Installed

The CLI will:

1. **Fetch the component** from the registry based on your `sublay.json` platform and style settings
2. **Copy \~25 files** into your project at `{componentsPath}/comments-threaded/`
3. **Transform imports** to work with your project structure
4. **Create `index.ts`** barrel export for clean imports
5. **Display usage examples** and required dependencies

### File Structure Created

```
src/components/comments-threaded/
├── index.ts                                # Barrel export (entry point)
├── components/                             # All UI components (~20 files)
│   ├── threaded-comment-section.tsx        # Main component
│   ├── new-comment-form.tsx                # Top-level comment form
│   ├── mention-suggestions.tsx             # @ mention autocomplete
│   ├── comments-feed/
│   │   ├── comments-feed.tsx               # Feed container
│   │   ├── loaded-comments.tsx             # Renders comment list
│   │   ├── fetching-comments-skeletons.tsx # Loading states
│   │   ├── no-comments-placeholder.tsx     # Empty state
│   │   └── comment-thread/
│   │       ├── comment-thread.tsx          # Thread with replies
│   │       ├── comment-replies.tsx         # Reply list
│   │       ├── action-menu.tsx             # Edit/delete/report menu
│   │       ├── new-reply-form.tsx          # Reply form
│   │       └── single-comment/
│   │           ├── single-comment.tsx      # Individual comment
│   │           ├── vote-buttons.tsx        # Upvote/downvote
│   │           ├── reply-button-and-info.tsx
│   │           ├── toggle-replies-visibility.tsx
│   │           └── indentation-threading-lines.tsx
│   └── modals/
│       ├── comment-menu-modal/             # Report modal (3 files)
│       └── comment-menu-modal-owner/       # Owner actions (1 file)
├── hooks/
│   ├── use-threaded-comments.tsx           # Main comment logic hook
│   └── use-ui-state.tsx                    # UI state management
├── utils/
│   └── prop-comparison.ts                  # Memoization helpers
└── context/
    └── ui-state-context.tsx               # Modal & theme context
```

***

## Using the Component

After installation, import and use the component:

```tsx theme={null}
import { ThreadedCommentSection } from './components/comments-threaded';

function BlogPost({ post }) {
  return (
    <div>
      <h1>{post.title}</h1>
      <article>{post.content}</article>
      <ThreadedCommentSection entityId={post.id} />
    </div>
  );
}
```

<Info>
  Make sure your app is wrapped with `<SublayProvider>`. See the [Quick Start Guide](/v7/components/installation/quick-start) for setup details.
</Info>

***

## Switching Styling Variants

To switch between Tailwind and Inline Styles after installation:

<Steps>
  <Step title="Delete Current Components">
    ```bash theme={null}
    rm -rf src/components/comments-threaded
    ```
  </Step>

  <Step title="Update Configuration">
    Edit `sublay.json`:

    ```json theme={null}
    {
      "style": "styled"
    }
    ```
  </Step>

  <Step title="Re-install">
    ```bash theme={null}
    npx @sublay/cli add comments-threaded
    ```
  </Step>
</Steps>

<Warning>
  This replaces your component files. Back up any customizations first.
</Warning>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Import errors" icon="file-import">
    Make sure your import path matches your `paths.components` in `sublay.json`:

    ```tsx theme={null}
    // paths.components = "src/components"
    import { ThreadedCommentSection } from './components/comments-threaded';
    ```
  </Accordion>

  <Accordion title="TypeScript errors" icon="code">
    Ensure your `tsconfig.json` includes the components directory:

    ```json theme={null}
    { "include": ["src/**/*"] }
    ```
  </Accordion>

  <Accordion title="Component already exists" icon="copy">
    Re-running `add` overwrites the existing installation. The CLI prints a
    warning first, then proceeds:

    ```
    ⚠️  Overwriting existing component: comments-threaded
    ```

    Because these files are yours to edit, any customizations you made are
    replaced. Commit (or back up) your changes before re-adding a component:

    ```bash theme={null}
    git status src/components/comments-threaded
    npx @sublay/cli add comments-threaded
    ```
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup>
  <Card title="Props & API" icon="sliders" href="/v7/components/components/threaded/props-api">
    Learn about available props
  </Card>

  <Card title="File Structure" icon="folder-tree" href="/v7/components/components/threaded/file-structure">
    Understand the component organization
  </Card>

  <Card title="Customization" icon="paintbrush" href="/v7/components/customization/overview">
    Customize colors, layout, and functionality
  </Card>

  <Card title="Features" icon="star" href="/v7/components/components/threaded/features">
    Explore all features
  </Card>
</CardGroup>


# Threaded Comments Overview
Source: https://docs.sublay.io/v7/components/components/threaded/overview

Reddit-style threaded comment system with unlimited nesting

# Threaded Comments

Reddit-style threaded comment system with unlimited nesting depth, upvote/downvote functionality, and visual threading lines.

***

## Overview

Threaded comments are perfect for forums, technical discussions, and any platform where users need deep, structured conversations with clear visual hierarchy.

***

## Key Features

<CardGroup>
  <Card title="Unlimited Nesting" icon="sitemap">
    Comments can be nested infinitely deep. Users can reply to any comment, creating branching conversation threads.
  </Card>

  <Card title="Upvote/Downvote System" icon="arrow-up-arrow-down">
    Reddit-style voting with visible scores. Helps surface quality content and provides social proof.
  </Card>

  <Card title="Visual Threading" icon="diagram-project">
    Clear indentation and connection lines show comment hierarchy. Easy to follow complex conversations.
  </Card>

  <Card title="Collapsible Threads" icon="compress">
    Users can collapse entire comment chains to navigate long discussions more easily.
  </Card>

  <Card title="@ Mentions" icon="at">
    Tag other users with `@username`. Clickable mentions with autocomplete suggestions.
  </Card>

  <Card title="Highlighted Comments" icon="highlighter">
    Deep-link to specific comments. Useful when directing users from notifications.
  </Card>

  <Card title="Edit & Delete" icon="pen-to-square">
    Comment authors can edit or delete their own comments. Full moderation support.
  </Card>

  <Card title="Reporting & Moderation" icon="flag">
    Built-in reporting system. Admin dashboard for managing reports and banning users.
  </Card>
</CardGroup>

***

## Use Cases

**Perfect for:**

* Developer forums and Q\&A sites
* Technical blog posts
* News sites with discussion sections
* Community forums
* Reddit-style platforms
* Long-form content with detailed discussions

**Not ideal for:**

* Quick social media interactions (use [Social Comments](/v7/components/components/social/overview) instead)
* Mobile-first, minimal designs
* Platforms that want positive-only engagement (no downvotes)

***

## Platform Support

| Platform     | Status            |
| ------------ | ----------------- |
| React (Web)  | ✅ Fully supported |
| React Native | ✅ Fully supported |
| Expo         | ✅ Fully supported |

***

## Styling Variants

<Tabs>
  <Tab title="Tailwind CSS">
    Uses Tailwind utility classes. Requires Tailwind CSS installed.

    ```tsx theme={null}
    <div className="bg-white dark:bg-gray-800 p-4 rounded-lg border border-gray-200 dark:border-gray-600">
    ```

    Best for projects using Tailwind or NativeWind.
  </Tab>

  <Tab title="Inline Styles">
    Uses inline `style={{}}` objects with conditional dark mode logic.

    ```tsx theme={null}
    <div style={{
      backgroundColor: theme === 'dark' ? '#1F2937' : '#FFFFFF',
      padding: '16px',
      borderRadius: '8px'
    }}>
    ```

    Best for projects without Tailwind, or where explicit styling is preferred.
  </Tab>
</Tabs>

Choose your preference during `npx @sublay/cli init`.

***

## Required Dependencies

**React (Web):**

```json theme={null}
{
  "dependencies": {
    "@sublay/react-js": "^7.0.0",
    "@sublay/ui-core-react-js": "^7.0.0"
  }
}
```

**React Native / Expo:**

```json theme={null}
{
  "dependencies": {
    "@sublay/react-native": "^7.0.0",
    "@sublay/ui-core-react-native": "^7.0.0"
  }
}
```

The CLI checks for these and prompts to install them if missing.

***

## Next Steps

<CardGroup>
  <Card title="Installation" icon="download" href="/v7/components/components/threaded/installation">
    Add threaded comments to your project
  </Card>

  <Card title="Props & API" icon="sliders" href="/v7/components/components/threaded/props-api">
    Learn about available props and options
  </Card>

  <Card title="File Structure" icon="folder-tree" href="/v7/components/components/threaded/file-structure">
    Understand the component file organization
  </Card>

  <Card title="Features" icon="star" href="/v7/components/components/threaded/features">
    Explore all features in detail
  </Card>
</CardGroup>


# Props & API
Source: https://docs.sublay.io/v7/components/components/threaded/props-api

ThreadedCommentSection component props and configuration

# Threaded Comments Props

The `ThreadedCommentSection` component follows a **minimal props philosophy**. It works with just `entityId` and offers optional props for specific needs.

***

## Component Import

```tsx theme={null}
import { ThreadedCommentSection } from './components/comments-threaded';
```

***

## Props Interface

```tsx theme={null}
interface ThreadedCommentSectionProps {
  // Entity identification (provide ONE of these)
  entity?: Entity | undefined | null;
  entityId?: string | undefined | null;
  foreignId?: string | undefined | null;
  shortId?: string | undefined | null;

  // Optional features
  isVisible?: boolean;
  highlightedCommentId?: string | undefined | null;
  theme?: 'light' | 'dark';   // Only for inline styles variant
  children?: React.ReactNode;
}
```

***

## Entity Identification

**Provide one of these** to identify which entity the comments belong to:

### `entity`

**Type:** `Entity | undefined | null`

A complete Entity object.

```tsx theme={null}
<ThreadedCommentSection
  entity={{
    id: "entity_123",
    projectId: "proj_456",
    foreignId: "post-789",
    // ... other entity fields
  }}
/>
```

**Use when:** You already have the full entity object from `useFetchEntity` or similar hooks.

***

### `entityId`

**Type:** `string | undefined | null`

The internal Sublay ID for the entity.

```tsx theme={null}
<ThreadedCommentSection entityId="entity_123" />
```

***

### `foreignId`

**Type:** `string | undefined | null`

Your external/custom ID for the entity. The component will find or create the Sublay entity automatically.

```tsx theme={null}
<ThreadedCommentSection foreignId="blog-post-789" />
```

**Use when:** You're using your own IDs and haven't fetched the Sublay entity yet. This is the most common option.

***

### `shortId`

**Type:** `string | undefined | null`

A short, human-readable identifier (if you've set one on the entity).

```tsx theme={null}
<ThreadedCommentSection shortId="my-first-post" />
```

<Note>
  **You only need ONE of these props.** Use whichever fits your data model best.
</Note>

***

## Optional Props

### `isVisible`

**Type:** `boolean` — **Default:** `true`

Controls whether the comment section is visible. Useful when rendering inside a drawer, modal, or conditional layout.

```tsx theme={null}
const [showComments, setShowComments] = useState(false);

<ThreadedCommentSection
  entityId="post_123"
  isVisible={showComments}
/>
```

Ensures event listeners are only active when the component is visible, improving performance.

***

### `highlightedCommentId`

**Type:** `string | undefined | null`

ID of a specific comment to highlight when the section loads. The component scrolls to it and applies a highlight that fades after a few seconds.

```tsx theme={null}
<ThreadedCommentSection
  entityId="post_123"
  highlightedCommentId="comment_456"
/>
```

**Use cases:** Deep-linking from notifications, jumping to a comment via URL param.

***

### `theme`

**Type:** `'light' | 'dark'` — **Default:** `'light'`

**Only for the inline styles variant.** Sets the color theme for the entire comment section.

```tsx theme={null}
<ThreadedCommentSection
  entityId="post_123"
  theme={isDark ? 'dark' : 'light'}
/>
```

<Tabs>
  <Tab title="Inline Styles Variant">
    Uses the `theme` prop to conditionally render dark or light colors:

    ```tsx theme={null}
    style={{ backgroundColor: theme === 'dark' ? '#1F2937' : '#FFFFFF' }}
    ```
  </Tab>

  <Tab title="Tailwind Variant">
    Ignores this prop. Uses Tailwind's dark mode system instead — add a `dark` class to a parent element:

    ```tsx theme={null}
    <html className={isDark ? 'dark' : ''}>
      <ThreadedCommentSection entityId="post_123" />
    </html>
    ```

    Requires `darkMode: 'class'` in `tailwind.config.js`.
  </Tab>
</Tabs>

***

### `children`

**Type:** `React.ReactNode`

Optional content rendered within the comment feed area.

```tsx theme={null}
<ThreadedCommentSection entityId="post_123">
  <div className="text-center text-gray-500 my-4">
    Join the discussion!
  </div>
</ThreadedCommentSection>
```

***

## Complete Examples

### Minimal Usage

```tsx theme={null}
<ThreadedCommentSection foreignId="blog-post-123" />
```

***

### With Dark Mode (Inline Styles)

```tsx theme={null}
function BlogPost({ post }) {
  const [isDark, setIsDark] = useState(false);

  return (
    <>
      <button onClick={() => setIsDark(!isDark)}>Toggle Theme</button>
      <ThreadedCommentSection
        foreignId={post.id}
        theme={isDark ? 'dark' : 'light'}
      />
    </>
  );
}
```

***

### With Highlighted Comment

```tsx theme={null}
import { useSearchParams } from 'react-router-dom';

function BlogPost({ post }) {
  const [searchParams] = useSearchParams();

  return (
    <ThreadedCommentSection
      foreignId={post.id}
      highlightedCommentId={searchParams.get('commentId')}
    />
  );
}

// URL: /blog/my-post?commentId=comment_abc123
// → highlights comment_abc123 on load
```

***

### Full Example

```tsx theme={null}
function BlogPost({ postId }) {
  const [searchParams] = useSearchParams();
  const [showComments, setShowComments] = useState(true);
  const [isDark, setIsDark] = useState(false);
  const { data: entity } = useFetchEntity({ foreignId: postId });

  return (
    <>
      <button onClick={() => setShowComments(!showComments)}>
        {showComments ? 'Hide' : 'Show'} Comments
      </button>

      <ThreadedCommentSection
        entity={entity}
        isVisible={showComments}
        highlightedCommentId={searchParams.get('commentId')}
        theme={isDark ? 'dark' : 'light'}
      >
        <div className="text-center text-sm text-gray-500 my-2">
          Be respectful in the discussion
        </div>
      </ThreadedCommentSection>
    </>
  );
}
```

***

## Next Steps

<CardGroup>
  <Card title="File Structure" icon="folder-tree" href="/v7/components/components/threaded/file-structure">
    Understand component organization
  </Card>

  <Card title="Features" icon="star" href="/v7/components/components/threaded/features">
    Explore all features
  </Card>

  <Card title="Customization" icon="paintbrush" href="/v7/components/customization/overview">
    Customize the component
  </Card>

  <Card title="Installation" icon="download" href="/v7/components/components/threaded/installation">
    Installation guide
  </Card>
</CardGroup>


# Adding Features
Source: https://docs.sublay.io/v7/components/customization/adding-features

Add custom functionality to components

# Adding Features

Extend components with custom behavior — confirmations, analytics, integrations, and more.

***

## Add Confirmation Before Delete

```tsx theme={null}
// File: comment-menu-modal-owner.tsx

const handleDelete = () => {
  if (window.confirm('Are you sure you want to delete this comment?')) {
    // existing delete logic
    deleteComment(comment.id);
  }
};
```

Or use a custom modal by replacing the `window.confirm` with your modal component.

***

## Add Character Counter to Comment Form

```tsx theme={null}
// File: new-comment-form.tsx

const [text, setText] = useState('');
const MAX_LENGTH = 500;

return (
  <div>
    <textarea
      value={text}
      onChange={(e) => setText(e.target.value)}
      maxLength={MAX_LENGTH}
      placeholder="Leave a comment..."
    />
    <div className="text-sm text-gray-400 text-right">
      {text.length} / {MAX_LENGTH}
    </div>
    <button type="submit">Comment</button>
  </div>
);
```

***

## Add Analytics Tracking

```tsx theme={null}
// File: vote-buttons.tsx

const handleUpvote = () => {
  analytics.track('Comment Upvoted', {
    commentId: comment.id,
    entityId: entity.id,
  });
  // existing upvote logic
};
```

```tsx theme={null}
// File: new-comment-form.tsx

const handleSubmit = async () => {
  await submitComment(text);
  analytics.track('Comment Posted', { entityId: entity.id });
};
```

***

## Add Custom User Badges

```tsx theme={null}
// File: single-comment.tsx

<div className="flex items-center gap-2">
  <span className="font-semibold">{author.name}</span>
  {author.isPro && (
    <span className="px-2 py-0.5 bg-amber-500 text-white text-xs rounded-full">
      PRO
    </span>
  )}
  {author.isAdmin && (
    <span className="px-2 py-0.5 bg-purple-600 text-white text-xs rounded-full">
      Admin
    </span>
  )}
</div>
```

***

## Auto-Collapse Old Threads

```tsx theme={null}
// File: comment-thread.tsx

const [isCollapsed, setIsCollapsed] = useState(() => {
  const sevenDaysAgo = Date.now() - 7 * 24 * 60 * 60 * 1000;
  return new Date(comment.createdAt).getTime() < sevenDaysAgo;
});
```

***

## Navigate on User Click

The hooks expose callback props for user interactions. Wire them to your router:

```tsx theme={null}
// File: hooks/use-threaded-comments.tsx

const otherUserClickCallback = (userId: string, foreignId?: string) => {
  // Navigate to user profile
  router.push(`/users/${foreignId || userId}`);
};

const loginRequiredCallback = () => {
  // Redirect to login
  router.push('/login?returnTo=' + window.location.pathname);
};
```

***

## Add Pinned Comment

Show a pinned comment above the feed:

```tsx theme={null}
// File: threaded-comment-section.tsx

return (
  <div>
    <NewCommentForm />

    {pinnedComment && (
      <div className="border-l-4 border-blue-500 pl-4 mb-4 bg-blue-50 dark:bg-blue-950 rounded-r-lg py-2">
        <span className="text-xs font-semibold text-blue-600 uppercase tracking-wide">Pinned</span>
        <SingleComment comment={pinnedComment} />
      </div>
    )}

    <CommentsFeed />
  </div>
);
```

***

## Add "Load More" Button Instead of Infinite Scroll

In `comments-feed.tsx`, replace the infinite scroll observer with an explicit button:

```tsx theme={null}
{hasNextPage && (
  <button
    onClick={() => fetchNextPage()}
    disabled={isFetchingNextPage}
    className="w-full py-2 text-blue-600 hover:underline text-sm"
  >
    {isFetchingNextPage ? 'Loading...' : 'Load more comments'}
  </button>
)}
```

***

## Integrate with Error Tracking

```tsx theme={null}
// File: use-threaded-comments.tsx

const submitComment = async (text: string) => {
  try {
    await createComment({ content: text });
  } catch (error) {
    Sentry.captureException(error, {
      tags: { feature: 'comments', entityId: entity.id }
    });
    throw error;
  }
};
```

***

## Next Steps

<CardGroup>
  <Card title="Advanced" icon="star" href="/v7/components/customization/advanced">
    Advanced customization techniques
  </Card>

  <Card title="Colors & Theming" icon="palette" href="/v7/components/customization/colors-theming">
    Customize colors and dark mode
  </Card>

  <Card title="Layout & Structure" icon="table-columns" href="/v7/components/customization/layout-structure">
    Modify layout
  </Card>

  <Card title="File Structure" icon="folder-tree" href="/v7/components/components/threaded/file-structure">
    Threaded comments file organization
  </Card>
</CardGroup>


# Advanced Customization
Source: https://docs.sublay.io/v7/components/customization/advanced

Advanced techniques for customizing Sublay components

# Advanced Customization

Deeper customizations involving hooks, context, utilities, and integration with your own systems.

***

## Modifying Hooks

The `/hooks/` directory contains the core logic for each component. This is where you customize behavior at a deeper level than editing JSX.

### Change Default Sort Order

```tsx theme={null}
// File: hooks/use-threaded-comments.tsx

const [sortBy, setSortBy] = useState<'top' | 'new' | 'old'>('new');  // Changed from 'top'
```

### Change Comments Per Page

```tsx theme={null}
const { data } = useComments({
  entityId,
  pageSize: 20,  // Default is 10
});
```

### Customize Reply Depth Limit

```tsx theme={null}
// File: comment-thread.tsx

const MAX_DEPTH = 3;  // Only allow 3 levels of nesting

{depth < MAX_DEPTH && (
  <NewReplyForm parentId={comment.id} />
)}
```

***

## User Interaction Callbacks

Both comment hooks expose behavioral callbacks you can customize in the hook file:

```tsx theme={null}
// File: hooks/use-threaded-comments.tsx (or use-social-comments.tsx)

// Called when unauthenticated user tries to comment
const loginRequiredCallback = () => {
  router.push('/login?returnTo=' + window.location.pathname);
};

// Called when user without a username tries to comment
const usernameRequiredCallback = () => {
  router.push('/settings/profile?setup=username');
};

// Called when clicking your own profile
const currentUserClickCallback = () => {
  router.push('/profile');
};

// Called when clicking another user's name/avatar
const otherUserClickCallback = (userId: string, foreignId?: string) => {
  router.push(`/users/${foreignId || userId}`);
};
```

***

## Customizing Context

The `ui-state-context.tsx` provides shared state across all sub-components. Add custom state here to make it accessible throughout the component tree:

```tsx theme={null}
// File: context/ui-state-context.tsx

interface UIState {
  // Existing state
  activeReplyId: string | null;
  reportModalOpen: boolean;

  // Add your custom state
  highlightedUserId: string | null;
  isCompact: boolean;
}

const UIStateContext = createContext<UIState>({
  activeReplyId: null,
  reportModalOpen: false,
  highlightedUserId: null,
  isCompact: false,
});
```

***

## Adding Utility Functions

Create new files in the `/utils/` directory for shared logic:

```tsx theme={null}
// File: utils/analytics.ts

export const trackCommentEvent = (event: string, data: Record<string, unknown>) => {
  window.analytics?.track(event, {
    ...data,
    source: 'comments-component',
    timestamp: new Date().toISOString(),
  });
};
```

Then import and use it in any component:

```tsx theme={null}
import { trackCommentEvent } from '../utils/analytics';

const handleVote = () => {
  trackCommentEvent('Comment Voted', { commentId, direction: 'up' });
  // existing vote logic
};
```

***

## Replacing Sub-Components

For major UI changes, replace a sub-component with your own implementation:

```tsx theme={null}
// File: comment-thread.tsx

// Instead of the built-in VoteButtons:
// import VoteButtons from './single-comment/vote-buttons';

// Use your own:
import CustomVoteButtons from '@/components/ui/vote-buttons';

return (
  <div>
    <AuthorInfo />
    <CommentBody />
    <CustomVoteButtons
      commentId={comment.id}
      upvotes={comment.upvotes}
      downvotes={comment.downvotes}
    />
  </div>
);
```

***

## Integrating with External Systems

### Connecting to Your Auth System

```tsx theme={null}
// File: hooks/use-threaded-comments.tsx

import { useAuth } from '@/context/auth-context';

const { user, isAuthenticated } = useAuth();

const loginRequiredCallback = () => {
  openLoginModal();  // Your app's modal
};
```

### Connecting to Your User System

```tsx theme={null}
const otherUserClickCallback = (userId: string, foreignId?: string) => {
  // foreignId is your system's user ID if set during auth
  const profileUrl = foreignId
    ? `/users/${foreignId}`
    : `/users/sublay/${userId}`;

  router.push(profileUrl);
};
```

### Connecting to Your Notification System

Wire the `highlightedCommentId` prop to deep-link from your notifications:

```tsx theme={null}
// In your notification handler
const handleNotificationClick = (notification) => {
  if (notification.type === 'comment-reply') {
    router.push(`/posts/${notification.metadata.entityId}?commentId=${notification.metadata.commentId}`);
  }
};

// In your post page
const [searchParams] = useSearchParams();

<ThreadedCommentSection
  foreignId={post.id}
  highlightedCommentId={searchParams.get('commentId')}
/>
```

***

## Performance Optimization

### Memoize the Component

Wrap the component if its parent re-renders frequently:

```tsx theme={null}
import { memo } from 'react';
import { ThreadedCommentSection } from './components/comments-threaded';

const MemoizedComments = memo(ThreadedCommentSection);
```

The installed `utils/prop-comparison.ts` already handles deep equality checks for entity props to prevent unnecessary re-renders.

### Lazy Load on Scroll

```tsx theme={null}
import { useInView } from 'react-intersection-observer';

function BlogPost({ post }) {
  const { ref, inView } = useInView({ triggerOnce: true });

  return (
    <div>
      <article>{post.content}</article>
      <div ref={ref}>
        {inView && <ThreadedCommentSection foreignId={post.id} />}
      </div>
    </div>
  );
}
```

***

## Next Steps

<CardGroup>
  <Card title="Customization Overview" icon="paintbrush" href="/v7/components/customization/overview">
    Customization introduction
  </Card>

  <Card title="Colors & Theming" icon="palette" href="/v7/components/customization/colors-theming">
    Customize colors and dark mode
  </Card>

  <Card title="Adding Features" icon="plus" href="/v7/components/customization/adding-features">
    Common feature additions
  </Card>

  <Card title="File Structure" icon="folder-tree" href="/v7/components/components/threaded/file-structure">
    Understand component organization
  </Card>
</CardGroup>


# Colors & Theming
Source: https://docs.sublay.io/v7/components/customization/colors-theming

Customize colors and implement dark mode

# Colors & Theming

Change colors to match your brand and implement dark mode.

***

## Inline Styles Variant

### Color Palette Guides

Component files have color palette documentation in their headers:

```tsx theme={null}
/**
 * ====================
 * THEME COLOR PALETTE
 * ====================
 *
 * BACKGROUNDS:
 * - #FFFFFF → #1F2937 (main background)
 * - #F3F4F6 → #374151 (secondary background, hover)
 *
 * TEXT:
 * - #111827 → #F9FAFB (primary text)
 * - #6B7280 → #9CA3AF (secondary text)
 *
 * BLUES (links, actions, upvotes):
 * - #3B82F6 → #60A5FA (primary blue)
 *
 * REDS (downvotes, delete):
 * - #EF4444 → #F87171 (primary red)
 */
```

Format: `Light Color → Dark Color`

### Changing Colors

1. Find the hex code in your editor's search
2. Replace with your brand color

```tsx theme={null}
// Before
<button style={{ backgroundColor: '#3B82F6' }}>

// After
<button style={{ backgroundColor: '#9333EA' }}>  // Purple
```

### Dark Mode (Inline Styles)

Use the `theme` prop on comment components:

```tsx theme={null}
<ThreadedCommentSection
  entityId="post_123"
  theme={isDarkMode ? 'dark' : 'light'}
/>
```

Components check the theme and apply colors conditionally:

```tsx theme={null}
<div style={{
  backgroundColor: theme === 'dark' ? '#1F2937' : '#FFFFFF',
  color: theme === 'dark' ? '#F9FAFB' : '#111827'
}}>
```

***

## Tailwind CSS Variant

### Changing Colors

**Option 1: Change classes directly**

```tsx theme={null}
// Before
<button className="bg-blue-600 hover:bg-blue-700">

// After
<button className="bg-purple-600 hover:bg-purple-700">
```

**Option 2: Extend Tailwind config**

```js theme={null}
// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: '#9333EA',
      }
    }
  }
}
```

Then use `bg-primary`, `text-primary`, etc.

### Dark Mode (Tailwind)

Components use `dark:` prefix for dark mode:

```tsx theme={null}
<div className="bg-white dark:bg-gray-800 text-gray-900 dark:text-gray-50">
```

**Setup:**

1. Configure Tailwind for class-based dark mode:

```js theme={null}
// tailwind.config.js
module.exports = {
  darkMode: 'class',
}
```

2. Add `dark` class to parent element:

```tsx theme={null}
<html className={isDarkMode ? 'dark' : ''}>
  <App />
</html>
```

All components automatically switch to dark colors.

***

## Common Customizations

### Change Primary Brand Color

**Inline Styles — find & replace across the component directory:**

```
Find:    #3B82F6
Replace: #9333EA
Scope:   src/components/comments-threaded/
```

**Tailwind:**

```
Find:    blue-600
Replace: purple-600

Find:    blue-700
Replace: purple-700
```

### Customize Dark Mode Colors

```tsx theme={null}
// Make dark mode deeper
backgroundColor: theme === 'dark' ? '#0F172A' : '#FFFFFF'  // Slate-900 instead of gray-800
```

***

## Next Steps

<CardGroup>
  <Card title="Layout & Structure" icon="table-columns" href="/v7/components/customization/layout-structure">
    Modify component layout
  </Card>

  <Card title="Styling Variants" icon="wand-magic-sparkles" href="/v7/components/customization/styling-variants">
    Inline styles vs Tailwind
  </Card>

  <Card title="Adding Features" icon="plus" href="/v7/components/customization/adding-features">
    Add custom functionality
  </Card>

  <Card title="Advanced" icon="star" href="/v7/components/customization/advanced">
    Advanced customization techniques
  </Card>
</CardGroup>


# Layout & Structure
Source: https://docs.sublay.io/v7/components/customization/layout-structure

Modify component layout and structure

# Layout & Structure

Rearrange, add, or remove UI elements directly in the source files.

***

## Adding Elements

### Add Custom Header

```tsx theme={null}
// File: threaded-comment-section.tsx

return (
  <div>
    {/* Custom header */}
    <div className="flex justify-between items-center mb-4">
      <h2>Discussion ({totalComments} comments)</h2>
      <button onClick={sortBy}>Sort</button>
    </div>

    <NewCommentForm />
    <CommentsFeed />
  </div>
);
```

### Add Custom Footer

```tsx theme={null}
return (
  <div>
    <NewCommentForm />
    <CommentsFeed />

    {/* Custom footer */}
    <footer className="text-center text-gray-500 mt-4 text-sm">
      Powered by Sublay
    </footer>
  </div>
);
```

### Add a Banner Between Form and Feed

```tsx theme={null}
return (
  <div>
    <NewCommentForm />

    {/* Custom banner */}
    <div className="bg-blue-50 dark:bg-blue-950 rounded p-3 my-3 text-sm text-blue-700 dark:text-blue-300">
      Be respectful. See our community guidelines.
    </div>

    <CommentsFeed />
  </div>
);
```

***

## Removing Elements

### Remove Vote Buttons

```tsx theme={null}
// File: single-comment.tsx

return (
  <div>
    <AuthorInfo />
    <CommentBody />
    {/* <VoteButtons /> */}
    <ReplyButton />
  </div>
);
```

### Remove Reply Functionality

```tsx theme={null}
return (
  <div>
    <AuthorInfo />
    <CommentBody />
    <VoteButtons />
    {/* <ReplyButton /> */}
  </div>
);
```

### Remove Moderation Options

Delete or comment out the action menu trigger in `single-comment.tsx`:

```tsx theme={null}
{/* <ActionMenu comment={comment} /> */}
```

***

## Rearranging Elements

### Move Vote Buttons Above Comment Body

```tsx theme={null}
// Before
<AuthorInfo />
<CommentBody />
<VoteButtons />

// After
<AuthorInfo />
<VoteButtons />  {/* Moved up */}
<CommentBody />
```

### Move Sort Controls

Move `<SortByButton />` to the top of the section instead of inline with the feed.

***

## Modifying Spacing

**Inline Styles:**

```tsx theme={null}
<div style={{ padding: '24px', gap: '16px' }}>  {/* Increased from 12px */}
```

**Tailwind:**

```tsx theme={null}
<div className="p-6 gap-4">  {/* p-4 → p-6 */}
```

***

## Component Hierarchy

Understanding the component tree helps you know which file to edit:

**Threaded Comments:**

```
ThreadedCommentSection        ← threaded-comment-section.tsx
  ├── NewCommentForm           ← new-comment-form.tsx
  └── CommentsFeed             ← comments-feed.tsx
        └── CommentThread      ← comment-thread.tsx
              └── SingleComment ← single-comment.tsx
                    ├── AuthorInfo
                    ├── CommentBody
                    ├── VoteButtons   ← vote-buttons.tsx
                    └── ReplyButton
```

**Social Comments:**

```
SocialCommentSection          ← social-comment-section.tsx
  ├── SortByButton             ← sort-by-button.tsx
  ├── NewCommentForm           ← new-comment-form.tsx
  └── CommentsFeed             ← comments-feed.tsx
        └── Comment            ← comment.tsx
              ├── HeartButton  ← heart-button.tsx
              └── Replies      ← replies.tsx
```

***

## Next Steps

<CardGroup>
  <Card title="Adding Features" icon="plus" href="/v7/components/customization/adding-features">
    Add custom functionality
  </Card>

  <Card title="Colors & Theming" icon="palette" href="/v7/components/customization/colors-theming">
    Customize colors
  </Card>

  <Card title="Advanced" icon="star" href="/v7/components/customization/advanced">
    Advanced customization techniques
  </Card>

  <Card title="File Structure" icon="folder-tree" href="/v7/components/components/threaded/file-structure">
    Threaded comments file organization
  </Card>
</CardGroup>


# Customization Overview
Source: https://docs.sublay.io/v7/components/customization/overview

Customize components to match your brand

# Customization

Since you own the source code, you can customize **everything**: colors, layout, typography, functionality, and more.

***

## Philosophy

The CLI approach enables true customization:

<CardGroup>
  <Card title="Edit, Don't Configure" icon="code">
    Customize by editing source files, not passing complex config objects.
  </Card>

  <Card title="Full Ownership" icon="key">
    The code lives in your project. Change anything you want.
  </Card>

  <Card title="No Limitations" icon="unlock">
    Not restricted to what props expose. Modify layout, logic, features.
  </Card>

  <Card title="Self-Documenting" icon="book">
    Clear file names, inline comments, and color palettes documented in headers.
  </Card>
</CardGroup>

***

## What You Can Customize

<AccordionGroup>
  <Accordion title="Colors & Theming" icon="palette">
    Change any color: backgrounds, text, buttons, icons, borders.

    * Inline styles: Find and replace hex codes
    * Tailwind: Change utility classes or extend config

    See [Colors & Theming](/v7/components/customization/colors-theming)
  </Accordion>

  <Accordion title="Layout & Structure" icon="table-columns">
    Rearrange, add, or remove UI elements.

    * Add custom headers/footers
    * Remove features you don't need
    * Change component ordering
    * Modify spacing and sizing

    See [Layout & Structure](/v7/components/customization/layout-structure)
  </Accordion>

  <Accordion title="Styling Variants" icon="wand-magic-sparkles">
    Switch between inline styles and Tailwind CSS.

    See [Styling Variants](/v7/components/customization/styling-variants)
  </Accordion>

  <Accordion title="Functionality" icon="gears">
    Modify behavior and add features.

    * Add confirmation dialogs
    * Change interaction logic
    * Integrate with your analytics
    * Wire to your auth system

    See [Adding Features](/v7/components/customization/adding-features)
  </Accordion>

  <Accordion title="Typography" icon="font">
    Change fonts, sizes, weights, and line heights throughout any component file.
  </Accordion>

  <Accordion title="Icons & Assets" icon="image">
    Replace icons with your own or use an icon library (Font Awesome, Heroicons, etc.).
  </Accordion>
</AccordionGroup>

***

## Quick Examples

### Change Primary Color (Inline Styles)

```tsx theme={null}
// File: components/comments-threaded/components/single-comment/vote-buttons.tsx

// Find:
<button style={{ color: '#3B82F6' }}>

// Replace with:
<button style={{ color: '#9333EA' }}>  // Purple
```

### Change Primary Color (Tailwind)

```tsx theme={null}
// File: components/comments-threaded/components/single-comment/vote-buttons.tsx

// Find:
<button className="text-blue-600 hover:text-blue-700">

// Replace with:
<button className="text-purple-600 hover:text-purple-700">
```

### Add Custom Header

```tsx theme={null}
// File: components/comments-threaded/components/threaded-comment-section.tsx

return (
  <div>
    <div className="flex justify-between items-center mb-4">
      <h2 className="text-2xl font-bold">Discussion</h2>
      <span className="text-gray-500">{totalComments} comments</span>
    </div>

    <NewCommentForm />
    <CommentsFeed />
  </div>
);
```

### Remove a Feature

```tsx theme={null}
// File: components/comments-threaded/components/single-comment/single-comment.tsx

return (
  <div>
    <AuthorInfo />
    <CommentBody />
    {/* <VoteButtons /> */}  {/* Removed voting */}
    <ReplyButton />
  </div>
);
```

***

## Where to Make Changes

| What to Change | Where to Look                                                          |
| -------------- | ---------------------------------------------------------------------- |
| Colors         | Search for hex codes (`#3B82F6`) or Tailwind classes (`text-blue-600`) |
| Layout         | Main component file (`threaded-comment-section.tsx`, etc.)             |
| Typography     | Any component file — search `fontSize` or `text-` classes              |
| Behavior       | Component files and the `hooks/` directory                             |
| Icons          | Search for Unicode symbols or icon component names                     |

***

## Tips

<Steps>
  <Step title="Read Color Palette Guides">
    Many component files have color palette documentation in their headers:

    ```tsx theme={null}
    /**
     * COLOR PALETTE
     * - #3B82F6 → Primary blue (upvotes, links)
     * - #EF4444 → Red (downvotes, delete)
     */
    ```
  </Step>

  <Step title="Use Find & Replace">
    To change a color globally across the component:

    * Find: `#3B82F6`
    * Replace: `#9333EA`
    * Scope: `components/comments-threaded/`
  </Step>

  <Step title="Test Incrementally">
    Make one change at a time. Easier to debug if something breaks.
  </Step>

  <Step title="Version Control">
    Commit changes frequently so you can revert if needed.

    ```bash theme={null}
    git add src/components/comments-threaded/
    git commit -m "Change primary color to purple"
    ```
  </Step>
</Steps>

***

## Next Steps

<CardGroup>
  <Card title="Colors & Theming" icon="palette" href="/v7/components/customization/colors-theming">
    Customize colors and dark mode
  </Card>

  <Card title="Layout & Structure" icon="table-columns" href="/v7/components/customization/layout-structure">
    Modify layout and add/remove elements
  </Card>

  <Card title="Styling Variants" icon="wand-magic-sparkles" href="/v7/components/customization/styling-variants">
    Inline styles vs Tailwind CSS
  </Card>

  <Card title="Adding Features" icon="plus" href="/v7/components/customization/adding-features">
    Add custom functionality
  </Card>
</CardGroup>


# Styling Variants
Source: https://docs.sublay.io/v7/components/customization/styling-variants

Inline styles vs Tailwind CSS

# Styling Variants

Understanding inline styles vs Tailwind CSS variants and when to use each.

***

## Comparison

| Aspect             |   Inline Styles  |        Tailwind CSS       |
| ------------------ | :--------------: | :-----------------------: |
| **Dependencies**   |       None       |   Requires Tailwind CSS   |
| **Dark Mode**      |   `theme` prop   |       `dark:` prefix      |
| **Customization**  | Change hex codes |  Change classes or config |
| **Code verbosity** |   More verbose   |          Concise          |
| **Learning curve** |      Easier      | Tailwind knowledge needed |
| **React Native**   |    ✅ Supported   |       ✅ (NativeWind)      |

***

## Inline Styles

```tsx theme={null}
<div style={{
  backgroundColor: theme === 'dark' ? '#1F2937' : '#FFFFFF',
  padding: '16px',
  borderRadius: '8px',
  border: `1px solid ${theme === 'dark' ? '#374151' : '#E5E7EB'}`
}}>
  <span style={{
    color: theme === 'dark' ? '#F9FAFB' : '#111827',
    fontWeight: 600,
  }}>
    Username
  </span>
</div>
```

**Pros:**

* No additional dependencies
* Works everywhere (web and React Native)
* Explicit, self-contained styling
* Direct control over every value

**Cons:**

* More verbose code
* Manual dark mode logic in every component
* Repeated color values across files

**Best for:**

* Projects without Tailwind
* React Native / Expo apps
* Developers who prefer explicit styles

***

## Tailwind CSS

```tsx theme={null}
<div className="bg-white dark:bg-gray-800 p-4 rounded-lg border border-gray-200 dark:border-gray-600">
  <span className="text-gray-900 dark:text-gray-50 font-semibold">
    Username
  </span>
</div>
```

**Pros:**

* Concise, readable code
* Automatic dark mode with `dark:` prefix
* Integrates with design systems
* Smaller bundle with purging

**Cons:**

* Requires Tailwind CSS installed
* Learning curve if unfamiliar
* Less explicit (need to know what classes do)

**Best for:**

* Projects already using Tailwind
* Web-only React apps
* Developers who prefer utility-first CSS

***

## Choosing a Variant

Choose during `npx @sublay/cli init`:

```
? Which styling approach do you prefer?
❯ Tailwind CSS
  Inline Styles
```

**If you're unsure:** choose Inline Styles. It works everywhere with no setup.

***

## Switching Variants

To switch after installation, delete the component and reinstall with the new style:

```bash theme={null}
# 1. Delete installed component
rm -rf src/components/comments-threaded

# 2. Update sublay.json
# Change "style": "tailwind" to "style": "styled" (or vice versa)

# 3. Re-install
npx @sublay/cli add comments-threaded
```

<Warning>
  This replaces your component files. Back up any customizations before switching.
</Warning>

***

## React Native Styling

For React Native and Expo:

* **Inline Styles** → Standard React Native `StyleSheet` / `style` prop approach
* **Tailwind** → Uses [NativeWind](https://www.nativewind.dev/) (`className` prop)

NativeWind must be installed and configured for the Tailwind variant to work on React Native.

***

## Next Steps

<CardGroup>
  <Card title="Colors & Theming" icon="palette" href="/v7/components/customization/colors-theming">
    Customize colors
  </Card>

  <Card title="Layout & Structure" icon="table-columns" href="/v7/components/customization/layout-structure">
    Modify layout
  </Card>

  <Card title="Adding Features" icon="plus" href="/v7/components/customization/adding-features">
    Add custom functionality
  </Card>

  <Card title="Advanced" icon="star" href="/v7/components/customization/advanced">
    Advanced techniques
  </Card>
</CardGroup>


# CLI Setup
Source: https://docs.sublay.io/v7/components/installation/cli-setup

Install and configure the Sublay CLI

# Installing the Sublay CLI

The Sublay CLI copies fully customizable comment components directly into your project as editable source code. You can use it with `npx` (no installation required) or install it globally.

***

## Prerequisites

<Steps>
  <Step title="Node.js 20.5+">
    ```bash theme={null}
    node --version
    # Should output v20.5.0 or higher
    ```
  </Step>

  <Step title="A React, React Native, or Expo project">
    Supported platforms:

    * React (Web) ✅
    * React Native ✅
    * Expo ✅
  </Step>

  <Step title="A Sublay project">
    Create a project in the [Sublay Dashboard](https://dash.sublay.io) if you haven't already.
  </Step>
</Steps>

***

## Using npx (Recommended)

No installation required — `npx` always uses the latest version:

```bash theme={null}
npx @sublay/cli init
```

***

## Global Installation (Optional)

```bash theme={null}
npm install -g @sublay/cli
```

Then use without `npx`:

```bash theme={null}
sublay init
sublay add comments-threaded
```

<Note>
  The rest of this documentation uses `npx @sublay/cli` to stay version-agnostic, but `sublay` works identically when installed globally.
</Note>

***

## Initializing Your Project

Run the init command from your project root:

```bash theme={null}
cd your-react-app
npx @sublay/cli init
```

### Interactive Prompts

<AccordionGroup>
  <Accordion title="Platform Selection" icon="layer-group">
    **Question:** "Which platform are you using?"

    **Options:** React (Web) · React Native · Expo

    Determines which component variants and dependencies are used.
  </Accordion>

  <Accordion title="Styling Preference" icon="palette">
    **Question:** "Which styling approach do you prefer?"

    **Options:**

    * **Tailwind CSS** — Uses utility classes (`bg-white dark:bg-gray-800`)
    * **Inline Styles** — Uses style objects (`style={{ backgroundColor: '...' }}`)

    Choose **Tailwind** if your project already uses Tailwind CSS. Otherwise choose **Inline Styles**.
  </Accordion>

  <Accordion title="Component Path" icon="folder">
    **Question:** "Where should components be installed?"

    **Default:** `src/components`

    The directory where CLI components will be copied. You can use any path.
  </Accordion>
</AccordionGroup>

***

## What Happens During Init

1. **Detects your project type** from `package.json`
2. **Creates `sublay.json`** in your project root
3. **Checks for required peer dependencies** and offers to install missing ones

***

## The sublay.json File

After initialization, a `sublay.json` file is created in your project root:

```json theme={null}
{
  "platform": "react",
  "style": "tailwind",
  "typescript": true,
  "paths": {
    "components": "src/components"
  },
  "aliases": {
    "@/components": "./src/components"
  }
}
```

See [Configuration](/v7/components/installation/configuration) for a full reference.

***

## Installing Dependencies

The CLI checks for required peer dependencies and prompts to install them if missing.

**React (Web):**

```bash theme={null}
npm install @sublay/react-js
```

**React Native:**

```bash theme={null}
npm install @sublay/react-native
```

**Expo:**

```bash theme={null}
npm install @sublay/expo
```

<Warning>
  These packages are **required**. Components use them for data fetching, authentication, real-time updates, and core functionality.
</Warning>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Warning: No package.json found" icon="folder-xmark">
    ```
    ⚠️  No package.json found
    ```

    After installing a component's files, `add` reads your `package.json` to
    check which of the component's dependencies you already have. If there is
    no `package.json` in the current directory it prints this warning and skips
    that check — the component itself is still installed, and the command still
    succeeds.

    Run `add` from your project root (where `package.json` lives) to get the
    dependency check.
  </Accordion>

  <Accordion title="CLI hangs or doesn't respond" icon="hourglass">
    1. Press `Ctrl+C` to cancel
    2. Clear npx cache: `npx clear-npx-cache`
    3. Try again: `npx @sublay/cli init`
  </Accordion>

  <Accordion title="Want to change configuration" icon="gear">
    Delete `sublay.json` and run `npx @sublay/cli init` again, or manually edit the file and re-run `add` commands.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup>
  <Card title="Quick Start" icon="rocket" href="/v7/components/installation/quick-start">
    Add your first component in under 5 minutes
  </Card>

  <Card title="Configuration Reference" icon="file-code" href="/v7/components/installation/configuration">
    Understand every option in sublay.json
  </Card>

  <Card title="Threaded Comments" icon="comments" href="/v7/components/components/threaded/installation">
    Add Reddit-style threaded comments
  </Card>

  <Card title="Social Comments" icon="heart" href="/v7/components/components/social/installation">
    Add Instagram-style social comments
  </Card>
</CardGroup>


# Configuration
Source: https://docs.sublay.io/v7/components/installation/configuration

Understanding the sublay.json configuration file

# Configuration File

The `sublay.json` file is created in your project root during initialization. It stores your preferences and is used by the CLI when adding components.

***

## File Location

```
your-project/
├── package.json
├── sublay.json          ← Configuration file
├── src/
│   └── components/
└── ...
```

***

## Configuration Schema

```json theme={null}
{
  "platform": "react" | "react-native" | "expo",
  "style": "tailwind" | "styled",
  "typescript": true | false,
  "paths": {
    "components": "src/components"
  },
  "aliases": {
    "@/components": "./src/components"
  }
}
```

***

## Configuration Options

### `platform`

**Type:** `"react"` | `"react-native"` | `"expo"`

Specifies your application platform. This determines which component variants are available, which peer dependencies are required, and platform-specific imports.

```json theme={null}
{ "platform": "react" }        // React web applications
{ "platform": "react-native" } // React Native mobile applications
{ "platform": "expo" }         // Expo-managed projects
```

***

### `style`

**Type:** `"tailwind"` | `"styled"`

Determines which styling approach to use for components.

<Tabs>
  <Tab title="tailwind">
    Components use Tailwind CSS utility classes.

    ```json theme={null}
    { "style": "tailwind" }
    ```

    **Requires:** Tailwind CSS installed in your project

    ```tsx theme={null}
    <div className="bg-white dark:bg-gray-800 p-4 rounded-lg">
      <span className="text-blue-600 font-bold">Username</span>
    </div>
    ```

    **Best for:** Projects already using Tailwind, design systems, developers who prefer utility-first CSS
  </Tab>

  <Tab title="styled (Inline Styles)">
    Components use inline `style={{}}` objects.

    ```json theme={null}
    { "style": "styled" }
    ```

    **Requires:** Nothing additional

    ```tsx theme={null}
    <div style={{
      backgroundColor: theme === 'dark' ? '#1F2937' : '#FFFFFF',
      padding: '16px',
      borderRadius: '8px'
    }}>
      <span style={{ color: '#2563EB', fontWeight: 'bold' }}>Username</span>
    </div>
    ```

    **Best for:** Projects without Tailwind, explicit self-contained styling
  </Tab>
</Tabs>

<Warning>
  Once you've added components with a specific style variant, switching requires re-installing them. Change `style` in `sublay.json`, delete the installed component directory, then re-run `add`.
</Warning>

***

### `typescript`

**Type:** `boolean` — Default: `true` (auto-detected)

Indicates whether your project uses TypeScript. Automatically detected from `tsconfig.json` or file extensions. You rarely need to change this manually.

```json theme={null}
{ "typescript": true }   // .tsx files
{ "typescript": false }  // .jsx files (types are stripped during installation)
```

***

### `paths`

**Type:** `object`

Configures where components are installed.

```json theme={null}
{
  "paths": {
    "components": "src/components"
  }
}
```

Components install at:

* `src/components/comments-threaded/`
* `src/components/comments-social/`

Use any path relative to your project root. The CLI creates the directory if it doesn't exist.

***

### `aliases`

**Type:** `object`

Path aliases used in component imports. These should match your `tsconfig.json` paths or bundler alias configuration.

```json theme={null}
{
  "aliases": {
    "@/components": "./src/components"
  }
}
```

Components will use imports like:

```tsx theme={null}
import { SomeUtil } from '@/components/utils';
```

<Warning>
  Aliases must match your `tsconfig.json` or bundler config. Mismatched aliases cause import errors.
</Warning>

***

## Complete Example

A typical `sublay.json` for a React web app with Tailwind CSS:

```json theme={null}
{
  "platform": "react",
  "style": "tailwind",
  "typescript": true,
  "paths": {
    "components": "src/components"
  },
  "aliases": {
    "@/components": "./src/components"
  }
}
```

***

## Platform-Specific Notes

### React (Web)

```json theme={null}
{ "platform": "react" }
```

Required dependency: `@sublay/react-js@^7.0.0`

Available components: Threaded comments ✅, Social comments ✅, Notification control ✅

***

### React Native

```json theme={null}
{ "platform": "react-native" }
```

Required dependency: `@sublay/react-native@^7.0.0`

Available components: Threaded comments ✅, Social comments ✅

***

### Expo

```json theme={null}
{ "platform": "expo" }
```

Required dependency: `@sublay/expo@^7.0.0`

Available components: Threaded comments ✅, Social comments ✅

***

## Changing Configuration

**Option 1 — Edit manually:** Update `sublay.json` directly, then delete and re-add any installed components.

```bash theme={null}
rm -rf src/components/comments-threaded
npx @sublay/cli add comments-threaded
```

**Option 2 — Re-initialize:** Delete `sublay.json` and run `init` again.

```bash theme={null}
rm sublay.json
npx @sublay/cli init
```

***

## FAQ

<AccordionGroup>
  <Accordion title="Can I use both styling variants in the same project?" icon="question">
    No, the configuration applies globally. Pick one approach for consistency.
  </Accordion>

  <Accordion title="What if I delete sublay.json?" icon="trash">
    The CLI will error when you try to `add` components. Run `npx @sublay/cli init` to recreate it.
  </Accordion>

  <Accordion title="Does this file affect my application at runtime?" icon="play">
    No. `sublay.json` is only used by the CLI during component installation. Your application never reads this file.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup>
  <Card title="Quick Start Guide" icon="rocket" href="/v7/components/installation/quick-start">
    Add your first component
  </Card>

  <Card title="Threaded Comments" icon="comments" href="/v7/components/components/threaded/installation">
    Install Reddit-style threaded comments
  </Card>

  <Card title="Social Comments" icon="heart" href="/v7/components/components/social/installation">
    Install Instagram-style social comments
  </Card>

  <Card title="Customization Guide" icon="paintbrush" href="/v7/components/customization/overview">
    Learn how to customize components
  </Card>
</CardGroup>


# Quick Start
Source: https://docs.sublay.io/v7/components/installation/quick-start

Get comment components running in under 5 minutes

# Quick Start Guide

This guide will have you up and running with Sublay comment components in under 5 minutes.

***

## Before You Begin

* ✅ Node.js 20.5+ installed
* ✅ A React, React Native, or Expo project
* ✅ A [Sublay project](https://dash.sublay.io) created

***

## Step 1: Initialize the CLI

Run the init command in your project directory:

```bash theme={null}
cd your-project
npx @sublay/cli init
```

### Answer the prompts:

<Steps>
  <Step title="Select Platform">
    ```
    ? Which platform are you using?
    ❯ React (Web)
      React Native
      Expo
    ```
  </Step>

  <Step title="Choose Styling">
    ```
    ? Which styling approach do you prefer?
    ❯ Tailwind CSS
      Inline Styles
    ```

    * Select **Tailwind CSS** if you use Tailwind
    * Select **Inline Styles** otherwise
  </Step>

  <Step title="Set Component Path">
    ```
    ? Where should components be installed? (src/components)
    ```

    Press Enter to use the default, or type a custom path.
  </Step>
</Steps>

The CLI creates a `sublay.json` configuration file and checks for required dependencies.

***

## Step 2: Install Dependencies (if needed)

<Tabs>
  <Tab title="React (Web)">
    ```bash theme={null}
    npm install @sublay/react-js
    ```
  </Tab>

  <Tab title="React Native">
    ```bash theme={null}
    npm install @sublay/react-native
    ```
  </Tab>

  <Tab title="Expo">
    ```bash theme={null}
    npm install @sublay/expo
    ```
  </Tab>
</Tabs>

<Info>
  The CLI will prompt you to install these automatically if they're missing.
</Info>

***

## Step 3: Add a Component

<Tabs>
  <Tab title="Threaded Comments">
    ```bash theme={null}
    npx @sublay/cli add comments-threaded
    ```

    Reddit-style discussions with unlimited nesting, upvote/downvote, threading lines, and collapsible threads.
  </Tab>

  <Tab title="Social Comments">
    ```bash theme={null}
    npx @sublay/cli add comments-social
    ```

    Instagram-style comments with single-level nesting, heart/like system, and Top/New/Old sorting.
  </Tab>
</Tabs>

The CLI copies \~25 source files into your project and shows a usage example.

***

## Step 4: Set Up SublayProvider

Wrap your app (or the relevant section) with `SublayProvider`:

<Tabs>
  <Tab title="React (Web)">
    ```tsx theme={null}
    // App.tsx
    import { SublayProvider } from '@sublay/react-js';

    function App() {
      return (
        <SublayProvider
          projectId="your-project-id"
          signedToken={yourAuthToken}
        >
          {/* Your app content */}
        </SublayProvider>
      );
    }
    ```
  </Tab>

  <Tab title="React Native / Expo">
    ```tsx theme={null}
    // App.tsx
    import { SublayProvider } from '@sublay/react-native'; // or '@sublay/expo'

    function App() {
      return (
        <SublayProvider
          projectId="your-project-id"
          signedToken={yourAuthToken}
        >
          {/* Your app content */}
        </SublayProvider>
      );
    }
    ```
  </Tab>
</Tabs>

<Note>
  For authentication setup and obtaining `signedToken`, see the [Authentication](/v7/authentication) guide.
</Note>

***

## Step 5: Use the Component

<Tabs>
  <Tab title="Threaded Comments">
    ```tsx theme={null}
    // BlogPost.tsx
    import { ThreadedCommentSection } from './components/comments-threaded';

    function BlogPost({ post }) {
      return (
        <div>
          <h1>{post.title}</h1>
          <p>{post.content}</p>
          <ThreadedCommentSection entityId={post.id} />
        </div>
      );
    }
    ```
  </Tab>

  <Tab title="Social Comments">
    ```tsx theme={null}
    // Post.tsx
    import { SocialCommentSection } from './components/comments-social';

    function Post({ post }) {
      return (
        <div>
          <img src={post.image} />
          <p>{post.caption}</p>
          <SocialCommentSection entityId={post.id} />
        </div>
      );
    }
    ```
  </Tab>
</Tabs>

That's it! You now have a fully functional comment system.

***

## Complete Example

<Tabs>
  <Tab title="Threaded Comments">
    ```tsx theme={null}
    import { useEffect, useState } from 'react';
    import { SublayProvider, useSignTestingJwt } from '@sublay/react-js';
    import { ThreadedCommentSection } from './components/comments-threaded';

    const PROJECT_ID = import.meta.env.VITE_PUBLIC_SUBLAY_PROJECT_ID;
    const PRIVATE_KEY = import.meta.env.VITE_PUBLIC_SUBLAY_SECRET_KEY;

    const DUMMY_USER = { id: 'user1', username: 'tech_developer' };

    function App() {
      const signTestingJwt = useSignTestingJwt();
      const [signedToken, setSignedToken] = useState<string>();

      useEffect(() => {
        const handleSignJwt = async () => {
          const token = await signTestingJwt({
            projectId: PROJECT_ID,
            privateKey: PRIVATE_KEY,
            payload: DUMMY_USER,
          });
          setSignedToken(token);
        };
        handleSignJwt();
      }, []);

      return (
        <SublayProvider projectId={PROJECT_ID} signedToken={signedToken}>
          <div className="max-w-4xl mx-auto p-8">
            <h1>My Blog Post</h1>
            <p>This is my awesome blog post content...</p>
            <ThreadedCommentSection entityId="blog-post-123" />
          </div>
        </SublayProvider>
      );
    }

    export default App;
    ```
  </Tab>

  <Tab title="Social Comments">
    ```tsx theme={null}
    import { useEffect, useState } from 'react';
    import { SublayProvider, useSignTestingJwt } from '@sublay/react-js';
    import { SocialCommentSection } from './components/comments-social';

    const PROJECT_ID = import.meta.env.VITE_PUBLIC_SUBLAY_PROJECT_ID;
    const PRIVATE_KEY = import.meta.env.VITE_PUBLIC_SUBLAY_SECRET_KEY;

    const DUMMY_USER = { id: 'user1', username: 'social_user' };

    function App() {
      const signTestingJwt = useSignTestingJwt();
      const [signedToken, setSignedToken] = useState<string>();

      useEffect(() => {
        const handleSignJwt = async () => {
          const token = await signTestingJwt({
            projectId: PROJECT_ID,
            privateKey: PRIVATE_KEY,
            payload: DUMMY_USER,
          });
          setSignedToken(token);
        };
        handleSignJwt();
      }, []);

      return (
        <SublayProvider projectId={PROJECT_ID} signedToken={signedToken}>
          <div className="max-w-2xl mx-auto p-8">
            <img src="post.jpg" className="w-full rounded-lg" />
            <p className="mt-4">Check out this amazing photo!</p>
            <SocialCommentSection entityId="post-456" />
          </div>
        </SublayProvider>
      );
    }

    export default App;
    ```
  </Tab>
</Tabs>

***

## What Gets Installed

```
src/components/comments-threaded/
├── index.ts
├── components/          # ~20 UI component files
│   ├── threaded-comment-section.tsx
│   ├── new-comment-form.tsx
│   ├── comments-feed/
│   └── modals/
├── hooks/
├── utils/
└── context/
```

All files are editable TypeScript/TSX, documented with inline comments, and committed to your repo.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Import errors after adding component" icon="triangle-exclamation">
    Make sure the import path matches your `paths.components` in `sublay.json`:

    ```tsx theme={null}
    // paths.components = "src/components"
    import { ThreadedCommentSection } from './components/comments-threaded';

    // paths.components = "app/ui"
    import { ThreadedCommentSection } from './ui/comments-threaded';
    ```
  </Accordion>

  <Accordion title="Components not rendering" icon="eye-slash">
    1. Check that `<SublayProvider>` wraps the component
    2. Verify `projectId` and `signedToken` are correctly set
    3. Check the browser console for errors
  </Accordion>

  <Accordion title="TypeScript errors" icon="code">
    Ensure your `tsconfig.json` includes the components directory:

    ```json theme={null}
    { "include": ["src/**/*"] }
    ```
  </Accordion>

  <Accordion title="Dark mode not working (Tailwind)" icon="moon">
    Set `darkMode: 'class'` in `tailwind.config.js` and add a `dark` class to a parent element:

    ```tsx theme={null}
    <html className={isDark ? 'dark' : ''}>
    ```
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup>
  <Card title="Props API" icon="sliders" href="/v7/components/components/threaded/props-api">
    Learn about available props and options
  </Card>

  <Card title="File Structure" icon="folder-tree" href="/v7/components/components/threaded/file-structure">
    Understand the installed file organization
  </Card>

  <Card title="Customization" icon="paintbrush" href="/v7/components/customization/overview">
    Customize colors, layout, and functionality
  </Card>

  <Card title="Styling Variants" icon="palette" href="/v7/components/customization/styling-variants">
    Inline styles vs Tailwind CSS
  </Card>
</CardGroup>


# Components Overview
Source: https://docs.sublay.io/v7/components/overview

Own your components with Sublay's CLI-based distribution system

# Sublay Components

Sublay provides a **CLI-based component distribution** system inspired by shadcn/ui. Instead of hiding UI components in `node_modules`, Sublay copies the full source code directly into your project so you own and control every line.

<Info>
  **The philosophy:** Copy, paste, customize. Not install and configure.

  You get **source code**, not packages. You **own** your components and can modify anything.
</Info>

***

## How It Works

<Steps>
  <Step title="Initialize Sublay">
    ```bash theme={null}
    npx @sublay/cli init
    ```

    Configure your platform (React/React Native/Expo), styling preference (Tailwind/Inline styles), and component installation path.
  </Step>

  <Step title="Add Components">
    ```bash theme={null}
    npx @sublay/cli add comments-threaded
    # or
    npx @sublay/cli add comments-social
    ```

    Components are copied directly into your `src/components/` directory as editable source files.
  </Step>

  <Step title="Use & Customize">
    ```tsx theme={null}
    import { ThreadedCommentSection } from './components/comments-threaded';

    <ThreadedCommentSection entityId="my-post-123" />
    ```

    The component works out of the box. Want to customize? Edit the source files directly.
  </Step>
</Steps>

***

## Available Components

<CardGroup>
  <Card title="Threaded Comments" icon="comments" href="/v7/components/components/threaded/overview">
    Reddit-style threaded discussions with:

    * Unlimited nesting depth
    * Upvote/downvote system
    * Visual threading lines
    * Collapsible threads

    **Best for:** Forums, technical discussions, detailed conversations
  </Card>

  <Card title="Social Comments" icon="heart" href="/v7/components/components/social/overview">
    Instagram-style social comments with:

    * Single-level nesting
    * Heart/like system
    * Clean, minimal design
    * Top/New/Old sorting

    **Best for:** Social platforms, media content, quick interactions
  </Card>

  <Card title="Notification Control" icon="bell" href="/v7/components/components/notifications/overview">
    Dropdown notification bell control with:

    * Real-time notification updates
    * Smart viewport positioning
    * Mark as read functionality
    * Infinite scroll

    **Best for:** Navigation bars, headers, notification systems
  </Card>
</CardGroup>

***

## Styling Options

Each component comes in two styling variants:

### Inline Styles

* All styles as `style={{}}` objects in JSX
* No external dependencies
* Works everywhere
* Easy to find and change colors
* Theme support via conditional logic

### Tailwind CSS

* Utility classes for styling
* Requires Tailwind CSS installed
* Dark mode via `dark:` prefix
* More concise code
* Easy to integrate with design systems

Choose your variant during `init` — you can switch by re-running `add` commands.

***

## What Gets Installed

When you add a component, approximately **25 TypeScript/TSX files** are copied into your project:

```
src/components/comments-threaded/
├── index.ts                    # Entry point
├── components/                 # All UI components (~20 files)
│   ├── threaded-comment-section.tsx
│   ├── new-comment-form.tsx
│   ├── comments-feed/
│   └── modals/
├── hooks/                      # React hooks
├── utils/                      # Utilities
└── context/                    # React context
```

Every file is:

* ✅ Visible in your project
* ✅ Editable
* ✅ TypeScript with full type annotations
* ✅ Self-documenting with inline comments

***

## Required Dependencies

Components depend on Sublay's core libraries for data fetching, real-time updates, authentication, and more.

**For React (Web):**

```json theme={null}
{
  "dependencies": {
    "@sublay/react-js": "^7.0.0",
    "@sublay/ui-core-react-js": "^7.0.0"
  }
}
```

**For React Native / Expo:**

```json theme={null}
{
  "dependencies": {
    "@sublay/react-native": "^7.0.0",
    "@sublay/ui-core-react-native": "^7.0.0"
  }
}
```

The CLI checks for these and offers to install them automatically.

***

## Getting Started

<CardGroup>
  <Card title="CLI Setup" icon="terminal" href="/v7/components/installation/cli-setup">
    Install the CLI and configure your project
  </Card>

  <Card title="Quick Start" icon="bolt" href="/v7/components/installation/quick-start">
    Get comments working in under 5 minutes
  </Card>

  <Card title="Customization" icon="paintbrush" href="/v7/components/customization/overview">
    Learn how to customize colors, layout, and functionality
  </Card>

  <Card title="Component Types" icon="layer-group" href="/v7/components/components/overview">
    Compare available components and choose the right one
  </Card>
</CardGroup>

***

## Philosophy

The Sublay CLI follows these principles:

1. **Minimal Props** — Components work with just `entityId`. No complex configuration required.
2. **Sensible Defaults** — Beautiful, accessible styling out of the box.
3. **Edit, Don't Configure** — Customize by editing source code, not passing config objects.
4. **Progressive Disclosure** — Ignore implementation details until you need to customize.
5. **Self-Documenting Code** — Clear file names, thorough comments, and color palettes documented in headers.

***

## Open Source

All components are **open source** under the Apache 2.0 license. You can fork, modify, contribute, and use them in commercial projects freely.


# App Notification
Source: https://docs.sublay.io/v7/data-models/app-notification

The AppNotification interface shape including all notification types and their metadata

App notifications are in-app alerts sent to users when relevant activity occurs. Every notification shares a common base shape, and each notification type carries type-specific data in its `metadata` field.

## Base Fields

All notification types include these fields:

| Property    | Type                  | Description                                                                                                                                                  |
| ----------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`        | `string`              | Unique notification identifier (UUID).                                                                                                                       |
| `userId`    | `string`              | The recipient's user ID.                                                                                                                                     |
| `type`      | `AppNotificationType` | The notification type. See types listed below.                                                                                                               |
| `action`    | `string`              | Suggested action for the client when the notification is tapped (e.g. `"open-comment"`, `"open-entity"`, `"open-profile"`).                                  |
| `isRead`    | `boolean`             | Whether the user has read this notification.                                                                                                                 |
| `metadata`  | `Record<string, any>` | Type-specific data. See per-type metadata below.                                                                                                             |
| `title`     | `string \| undefined` | Display title derived from the notification template. Only present when the notification has been populated — not guaranteed on every notification object.   |
| `content`   | `string \| undefined` | Display content derived from the notification template. Only present when the notification has been populated — not guaranteed on every notification object. |
| `createdAt` | `string`              | ISO timestamp when the notification was created.                                                                                                             |

## Notification Types

### `entity-comment`

Triggered when someone comments on the user's entity.

**Action**: `"open-comment"`

| Metadata Field      | Type             | Description                    |
| ------------------- | ---------------- | ------------------------------ |
| `entityId`          | `string`         | ID of the entity.              |
| `entityShortId`     | `string`         | Short ID for sharing links.    |
| `entityTitle`       | `string \| null` | Entity title.                  |
| `entityContent`     | `string \| null` | Entity content preview.        |
| `commentId`         | `string`         | ID of the new comment.         |
| `commentContent`    | `string \| null` | Comment content preview.       |
| `initiatorId`       | `string`         | ID of the user who commented.  |
| `initiatorName`     | `string \| null` | Display name of the commenter. |
| `initiatorUsername` | `string \| null` | Username of the commenter.     |
| `initiatorAvatar`   | `string \| null` | Avatar URL of the commenter.   |

### `comment-reply`

Triggered when someone replies to the user's comment.

**Action**: `"open-comment"`

Same metadata as `entity-comment`, plus:

| Metadata Field | Type             | Description            |
| -------------- | ---------------- | ---------------------- |
| `replyId`      | `string`         | ID of the reply.       |
| `replyContent` | `string \| null` | Reply content preview. |

### `entity-mention`

Triggered when a user is mentioned in an entity.

**Action**: `"open-entity"`

| Metadata Field      | Type             | Description                              |
| ------------------- | ---------------- | ---------------------------------------- |
| `entityId`          | `string`         | ID of the entity containing the mention. |
| `entityShortId`     | `string`         | Short ID for sharing links.              |
| `entityTitle`       | `string \| null` | Entity title.                            |
| `entityContent`     | `string \| null` | Entity content preview.                  |
| `initiatorId`       | `string`         | ID of the user who made the mention.     |
| `initiatorName`     | `string \| null` | Display name.                            |
| `initiatorUsername` | `string \| null` | Username.                                |
| `initiatorAvatar`   | `string \| null` | Avatar URL.                              |

### `comment-mention`

Triggered when a user is mentioned in a comment.

**Action**: `"open-comment"`

Same as `entity-mention` metadata, plus:

| Metadata Field   | Type             | Description                               |
| ---------------- | ---------------- | ----------------------------------------- |
| `commentId`      | `string`         | ID of the comment containing the mention. |
| `commentContent` | `string \| null` | Comment content preview.                  |

### `entity-upvote`

Triggered when someone upvotes the user's entity.

**Action**: `"open-entity"`

Same as `entity-mention` metadata.

### `comment-upvote`

Triggered when someone upvotes the user's comment.

**Action**: `"open-comment"`

Same as `comment-mention` metadata.

### `entity-reaction`

Triggered when someone reacts to the user's entity.

**Action**: `"open-entity"`

Same as `entity-mention` metadata, plus:

| Metadata Field | Type     | Description                         |
| -------------- | -------- | ----------------------------------- |
| `reactionType` | `string` | The reaction type that was applied. |

### `comment-reaction`

Triggered when someone reacts to the user's comment.

**Action**: `"open-comment"`

Same as `comment-mention` metadata, plus `reactionType`.

### `entity-reaction-milestone-specific`

Triggered when an entity reaches a milestone count for a specific reaction type.

**Action**: `"open-entity"`

| Metadata Field   | Type              | Description                               |
| ---------------- | ----------------- | ----------------------------------------- |
| `entityId`       | `string`          | ID of the entity.                         |
| `entityShortId`  | `string`          | Short ID.                                 |
| `entityTitle`    | `string \| null`  | Entity title.                             |
| `entityContent`  | `string \| null`  | Content preview.                          |
| `reactionType`   | `string`          | The reaction type that hit the milestone. |
| `milestoneCount` | `number`          | The milestone count reached.              |
| `lastThreeUsers` | `MilestoneUser[]` | The three most recent reactors.           |

### `entity-reaction-milestone-total`

Triggered when an entity reaches a milestone for total reactions across all types.

**Action**: `"open-entity"`

| Metadata Field   | Type                     | Description                           |
| ---------------- | ------------------------ | ------------------------------------- |
| `entityId`       | `string`                 | ID of the entity.                     |
| `entityShortId`  | `string`                 | Short ID.                             |
| `entityTitle`    | `string \| null`         | Entity title.                         |
| `entityContent`  | `string \| null`         | Content preview.                      |
| `milestoneCount` | `number`                 | The total reaction milestone reached. |
| `reactionCounts` | `Record<string, number>` | Breakdown of counts by reaction type. |
| `lastThreeUsers` | `MilestoneUser[]`        | The three most recent reactors.       |

### `comment-reaction-milestone-specific`

Triggered when a comment reaches a milestone count for a specific reaction type.

**Action**: `"open-comment"`

| Metadata Field   | Type              | Description                               |
| ---------------- | ----------------- | ----------------------------------------- |
| `entityId`       | `string`          | ID of the entity the comment belongs to.  |
| `entityShortId`  | `string`          | Short ID.                                 |
| `entityTitle`    | `string \| null`  | Entity title.                             |
| `entityContent`  | `string \| null`  | Entity content preview.                   |
| `commentId`      | `string`          | ID of the comment.                        |
| `commentContent` | `string \| null`  | Comment content preview.                  |
| `reactionType`   | `string`          | The reaction type that hit the milestone. |
| `milestoneCount` | `number`          | The milestone count reached.              |
| `lastThreeUsers` | `MilestoneUser[]` | The three most recent reactors.           |

### `comment-reaction-milestone-total`

Triggered when a comment reaches a milestone for total reactions across all types.

**Action**: `"open-comment"`

| Metadata Field   | Type                     | Description                              |
| ---------------- | ------------------------ | ---------------------------------------- |
| `entityId`       | `string`                 | ID of the entity the comment belongs to. |
| `entityShortId`  | `string`                 | Short ID.                                |
| `entityTitle`    | `string \| null`         | Entity title.                            |
| `entityContent`  | `string \| null`         | Entity content preview.                  |
| `commentId`      | `string`                 | ID of the comment.                       |
| `commentContent` | `string \| null`         | Comment content preview.                 |
| `milestoneCount` | `number`                 | The total reaction milestone reached.    |
| `reactionCounts` | `Record<string, number>` | Breakdown of counts by reaction type.    |
| `lastThreeUsers` | `MilestoneUser[]`        | The three most recent reactors.          |

### `new-follow`

Triggered when someone follows the user.

**Action**: `"open-profile"`

| Metadata Field      | Type             | Description             |
| ------------------- | ---------------- | ----------------------- |
| `initiatorId`       | `string`         | ID of the new follower. |
| `initiatorName`     | `string \| null` | Display name.           |
| `initiatorUsername` | `string \| null` | Username.               |
| `initiatorAvatar`   | `string \| null` | Avatar URL.             |

### `connection-request`

Triggered when someone sends the user a connection request.

**Action**: `"open-profile"`

| Metadata Field      | Type             | Description                  |
| ------------------- | ---------------- | ---------------------------- |
| `connectionId`      | `string`         | ID of the connection record. |
| `initiatorId`       | `string`         | ID of the requester.         |
| `initiatorName`     | `string \| null` | Display name.                |
| `initiatorUsername` | `string \| null` | Username.                    |
| `initiatorAvatar`   | `string \| null` | Avatar URL.                  |

### `connection-accepted`

Triggered when someone accepts the user's connection request.

**Action**: `"open-profile"`

Same metadata fields as `connection-request`.

### `space-membership-approved`

Triggered when a space moderator approves the user's pending membership request.

**Action**: `"open-space"`

| Metadata Field | Type                          | Description                 |
| -------------- | ----------------------------- | --------------------------- |
| `spaceId`      | `string`                      | ID of the space.            |
| `spaceName`    | `string`                      | Name of the space.          |
| `spaceShortId` | `string`                      | Short ID for sharing links. |
| `spaceSlug`    | `string \| null \| undefined` | URL slug of the space.      |
| `spaceAvatar`  | `string \| null \| undefined` | Avatar URL of the space.    |

### `reputation-grant`

Triggered when a user is granted reputation — by another user, or by the app. **Only positive grants notify**; a negative grant (an app deduction) is silent.

**Action**: computed per grant. With a target it is that target's action (`"open-entity"`, `"open-comment"`, or `"open-chat-message"`). With no target it is `"open-profile"` for a user grant (opening the granter) and `"do-nothing"` for an app mint, which has no granter to open.

| Metadata Field                                 | Type                                                           | Description                                                                                                                   |
| ---------------------------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `grantId`                                      | `string`                                                       | ID of the [ReputationGrant](/data-models/reputation-grant).                                                                   |
| `amount`                                       | `number`                                                       | The amount granted. Always positive here.                                                                                     |
| `sourceType`                                   | `"user" \| "app"`                                              | `"user"` = a debited transfer, `"app"` = a mint.                                                                              |
| `note`                                         | `string \| null \| undefined`                                  | The granter's note, if any.                                                                                                   |
| `granterId`                                    | `string \| null \| undefined`                                  | The sender. Absent for a mint — the app has no user identity.                                                                 |
| `granterName`                                  | `string \| null \| undefined`                                  | Display name of the granter.                                                                                                  |
| `granterUsername`                              | `string \| null \| undefined`                                  | Username of the granter.                                                                                                      |
| `granterForeignId`                             | `string \| null \| undefined`                                  | Your system's ID for the granter.                                                                                             |
| `granterAvatar`                                | `string \| null \| undefined`                                  | Avatar URL of the granter.                                                                                                    |
| `spaceId`                                      | `string \| null \| undefined`                                  | The bucket the grant moved in. Absent/null = the project-general bucket.                                                      |
| `spaceShortId`                                 | `string \| null \| undefined`                                  | Short ID of that space.                                                                                                       |
| `spaceSlug`                                    | `string \| null \| undefined`                                  | URL slug of that space.                                                                                                       |
| `targetType`                                   | `"entity" \| "comment" \| "chat-message" \| null \| undefined` | What the grant was for, if anything.                                                                                          |
| `targetId`                                     | `string \| null \| undefined`                                  | ID of the rewarded record.                                                                                                    |
| `entityId`, `entityShortId`, `entityForeignId` | `string \| null \| undefined`                                  | Id forms of an entity target.                                                                                                 |
| `commentId`, `commentForeignId`                | `string \| null \| undefined`                                  | Id forms of a comment target. A comment target also carries `entityId`, since a comment can only be opened inside its entity. |
| `messageId`, `conversationId`                  | `string \| null \| undefined`                                  | Id forms of a chat-message target. Both are needed to place a message.                                                        |

<Note>
  The granter is carried under `granter*` keys, **never** `initiatorId`. A notification whose `metadata.initiatorId` is blocked by the recipient is suppressed entirely — and an app-mediated transfer between two users who blocked each other is required to succeed *and* to notify.
</Note>

### `system`

A manually triggered notification from the project dashboard.

**Action**: Configurable.

| Metadata Field | Type                                    | Description                          |
| -------------- | --------------------------------------- | ------------------------------------ |
| `title`        | `string \| undefined`                   | Optional notification title.         |
| `content`      | `string \| undefined`                   | Optional notification body.          |
| `buttonData`   | `{ text: string; url: string } \| null` | Optional call-to-action button data. |

## Nested Types

### MilestoneUser

| Property   | Type                          | Description   |
| ---------- | ----------------------------- | ------------- |
| `id`       | `string`                      | User ID.      |
| `name`     | `string \| null \| undefined` | Display name. |
| `username` | `string \| null \| undefined` | Username.     |
| `avatar`   | `string \| null \| undefined` | Avatar URL.   |

## See Also

* [ReputationGrant](/data-models/reputation-grant)
* [useAppNotifications hook](/hooks/app-notifications/use-app-notifications)
* [Fetch Notifications](/api-reference/app-notifications/fetch-notifications)
* [Notification Templates](/sdk/app-notifications/notification-templates)


# Block
Source: https://docs.sublay.io/v7/data-models/block

The Block interface shape representing one user blocking another

A block record represents a directed edge where one user (the blocker) has blocked another (the blocked). A block simply exists or doesn't — there is no status column. Blocks are part of the trust & safety [moderation bundle](/sdk/moderation/overview#blocking); the table is provisioned only in projects that have that bundle installed.

Blocks are **private to the blocker** — only the blocker can read their own block list, and the block-status read is outbound-only, so the block is never disclosed to the blocked user.

## Properties

| Property    | Type     | Description                               |
| ----------- | -------- | ----------------------------------------- |
| `id`        | `string` | Unique block identifier (UUID).           |
| `blockerId` | `string` | The ID of the user who created the block. |
| `blockedId` | `string` | The ID of the user being blocked.         |
| `createdAt` | `Date`   | When the block was created.               |

<Note>
  The pair `(blockerId, blockedId)` is unique. Blocking someone already blocked is an idempotent no-op. Deleting either user removes their block edges in both directions.
</Note>

## See Also

* [Moderation — Blocking](/sdk/moderation/overview#blocking) — enforcement behavior
* [useBlockManager hook](/hooks/blocks/use-block-manager)
* [Block User](/api-reference/users/blocks/block-user)
* [Fetch Blocked Users](/api-reference/blocks/fetch-blocks)


# Connection
Source: https://docs.sublay.io/v7/data-models/connection

Connection interface shapes for bidirectional user relationships

A connection is a bidirectional relationship between two users that requires mutual acceptance. The connection lifecycle goes through request → accept/decline. Multiple response shapes exist depending on the context in which connections are retrieved.

## EstablishedConnection

Returned in lists of confirmed connections.

| Property        | Type     | Description                                     |
| --------------- | -------- | ----------------------------------------------- |
| `id`            | `string` | Unique connection identifier.                   |
| `connectedUser` | `User`   | The other user in this connection.              |
| `connectedAt`   | `string` | ISO timestamp when the connection was accepted. |

## PendingConnection

Returned for requests that have not yet been accepted or declined.

| Property    | Type                   | Description                                             |
| ----------- | ---------------------- | ------------------------------------------------------- |
| `id`        | `string`               | Unique connection identifier.                           |
| `user`      | `User`                 | The other user involved in this pending request.        |
| `type`      | `"received" \| "sent"` | Whether the current user received or sent this request. |
| `message`   | `string`               | Optional message included with the request.             |
| `createdAt` | `string`               | ISO timestamp when the request was sent.                |

## ConnectionStatusResponse

Returned by the connection status endpoint. The shape varies by status:

### Status: none

```ts theme={null}
{ status: "none" }
```

### Status: pending

| Property       | Type                   | Description                                            |
| -------------- | ---------------------- | ------------------------------------------------------ |
| `status`       | `"pending"`            |                                                        |
| `type`         | `"sent" \| "received"` | Whether the current user sent or received the request. |
| `connectionId` | `string`               | The connection record's ID.                            |
| `createdAt`    | `string`               | When the request was sent.                             |

### Status: connected

| Property       | Type          | Description                           |
| -------------- | ------------- | ------------------------------------- |
| `status`       | `"connected"` |                                       |
| `connectionId` | `string`      | The connection record's ID.           |
| `connectedAt`  | `string`      | When the connection was accepted.     |
| `requestedAt`  | `string`      | When the request was originally sent. |

### Status: declined

| Property       | Type                   | Description                                                     |
| -------------- | ---------------------- | --------------------------------------------------------------- |
| `status`       | `"declined"`           |                                                                 |
| `type`         | `"sent" \| "received"` | Whether the current user sent or received the declined request. |
| `connectionId` | `string`               | The connection record's ID.                                     |
| `respondedAt`  | `string`               | When the decline occurred.                                      |

## Pagination

Connection list responses include a `pagination` object:

| Property          | Type      | Description                              |
| ----------------- | --------- | ---------------------------------------- |
| `currentPage`     | `number`  | The current page number.                 |
| `totalPages`      | `number`  | Total number of pages.                   |
| `totalCount`      | `number`  | Total number of connections.             |
| `hasNextPage`     | `boolean` | Whether more pages exist after this one. |
| `hasPreviousPage` | `boolean` | Whether pages exist before this one.     |
| `limit`           | `number`  | The page size used for this response.    |

## See Also

* [useConnectionManager hook](/hooks/connections/use-connection-manager)
* [useRequestConnection hook](/hooks/connections/use-request-connection)
* [Fetch Connections](/api-reference/connections/fetch-connections)
* [Fetch Connection Status](/api-reference/users/connections/get-connection-status)


# File
Source: https://docs.sublay.io/v7/data-models/file

The File and FileImage interface shapes for uploaded media

A `File` record represents a file uploaded to Sublay's storage system. Files can be attached to users (avatars, banners), entities, comments, chat messages, or spaces. Image files include an additional `image` extension with processed variants at multiple sizes.

## File

| Property           | Type                                          | Description                                                               |
| ------------------ | --------------------------------------------- | ------------------------------------------------------------------------- |
| `id`               | `string`                                      | Unique file identifier (UUID).                                            |
| `projectId`        | `string`                                      | The project this file belongs to.                                         |
| `userId`           | `string \| null`                              | The user this file is associated with (for avatars/banners).              |
| `entityId`         | `string \| null`                              | The entity this file is attached to.                                      |
| `commentId`        | `string \| null`                              | The comment this file is attached to.                                     |
| `chatMessageId`    | `string \| null`                              | The chat message this file is attached to.                                |
| `spaceId`          | `string \| null`                              | The space this file is associated with.                                   |
| `type`             | `"image" \| "video" \| "document" \| "other"` | The file category.                                                        |
| `originalPath`     | `string`                                      | Proxied URL to the original uploaded file.                                |
| `originalSize`     | `number`                                      | Size of the original file in bytes.                                       |
| `originalMimeType` | `string`                                      | MIME type of the original file (e.g. `"image/jpeg"`).                     |
| `position`         | `number`                                      | Display order when multiple files are attached to the same record.        |
| `metadata`         | `Record<string, any>`                         | Custom key-value data for this file.                                      |
| `image`            | `FileImage`                                   | Present only when `type` is `"image"`. Contains processed image variants. |
| `createdAt`        | `Date`                                        | When the file was uploaded.                                               |
| `updatedAt`        | `Date`                                        | When the file record was last updated.                                    |

## FileImage

For image files, the `image` field contains processing results and variant URLs.

| Property           | Type                               | Description                                                                           |
| ------------------ | ---------------------------------- | ------------------------------------------------------------------------------------- |
| `fileId`           | `string`                           | The parent file's ID.                                                                 |
| `originalWidth`    | `number`                           | Width of the original image in pixels.                                                |
| `originalHeight`   | `number`                           | Height of the original image in pixels.                                               |
| `variants`         | `Record<string, FileImageVariant>` | Processed variants keyed by size name (e.g. `thumbnail`, `small`, `medium`, `large`). |
| `processingStatus` | `"completed" \| "failed"`          | Whether image processing succeeded.                                                   |
| `processingError`  | `string \| null`                   | Error message if processing failed.                                                   |
| `format`           | `string`                           | The output format requested by the uploader (e.g. `"webp"`).                          |
| `quality`          | `number`                           | The output quality requested (1–100).                                                 |
| `exifStripped`     | `boolean`                          | Whether EXIF metadata was removed from the output.                                    |
| `createdAt`        | `Date`                             | When the image record was created.                                                    |
| `updatedAt`        | `Date`                             | When the image record was last updated.                                               |

## FileImageVariant

Each entry in `FileImage.variants` has this shape:

| Property     | Type     | Description                                       |
| ------------ | -------- | ------------------------------------------------- |
| `path`       | `string` | Relative storage path for this variant.           |
| `publicPath` | `string` | Proxied public URL for this variant.              |
| `width`      | `number` | Width of this variant in pixels.                  |
| `height`     | `number` | Height of this variant in pixels.                 |
| `size`       | `number` | File size of this variant in bytes.               |
| `format`     | `string` | Format of this variant (e.g. `"webp"`, `"jpeg"`). |

## See Also

* [Upload Image](/api-reference/storage/upload-image)
* [Upload File](/api-reference/storage/upload-file)
* [useUploadImage hook](/hooks/storage/use-upload-image)
* [useUploadFile hook](/hooks/storage/use-upload-file)
* [User](/data-models/user)


# Follow
Source: https://docs.sublay.io/v7/data-models/follow

The Follow interface shape representing a user following another user

A follow record represents a directional relationship where one user follows another. Follows are one-way — unlike connections, following someone does not require the other person to accept.

## Properties

| Property     | Type     | Description                                      |
| ------------ | -------- | ------------------------------------------------ |
| `id`         | `string` | Unique follow identifier (UUID).                 |
| `projectId`  | `string` | The project this follow relationship belongs to. |
| `followerId` | `string` | The ID of the user who is doing the following.   |
| `followedId` | `string` | The ID of the user being followed.               |
| `createdAt`  | `Date`   | When the follow was created.                     |

## See Also

* [useFollowManager hook](/hooks/follows/use-follow-manager)
* [useFollowUser hook](/hooks/follows/use-follow-user)
* [Fetch Follow Status](/api-reference/users/follows/get-follow-status)
* [Fetch Followers](/api-reference/users/follows/get-followers)
* [Fetch Following](/api-reference/users/follows/get-following)


# Workspace
Source: https://docs.sublay.io/v7/data-models/workspace

The shape of a Workspace object returned by the Workspaces API and SDK

A **Workspace** is a self-nesting grouping primitive — an account/team/org that people are invited into and given authority over. Unlike a [Space](/data-models/space) (a community/subreddit shape with join-requests, posting, and moderation), a Workspace is the **B2B/SaaS collaboration shape**: invite-only, with a granular per-member authority model and an owner apex.

A workspace can optionally contain copies of itself:

* **Don't nest** → a flat team (one level).
* **Nest one level** → the classic SaaS shape: a workspace containing "projects."
* **Nest deeper** → agency-style org → client → project.

<Note>
  **Requires the `workspaces` bundle.** Workspaces are only available when the `workspaces` bundle is installed on your project. See [Bundles](/bundles) to add it. The bundle is purely additive — it touches no other bundle's data.
</Note>

## Workspace

| Property             | Type                  | Description                                                                                                                                                                                                                                      |
| -------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`                 | `string`              | Unique workspace identifier (UUID).                                                                                                                                                                                                              |
| `name`               | `string`              | Display name (1–100 characters).                                                                                                                                                                                                                 |
| `metadata`           | `Record<string, any>` | Arbitrary developer-defined data (opaque JSON, size-capped).                                                                                                                                                                                     |
| `ownerId`            | `string`              | The apex user id — the workspace's owner. The creator of a workspace becomes its owner. See [Ownership](#ownership).                                                                                                                             |
| `parentWorkspaceId`  | `string \| null`      | The parent workspace id, or `null` for a root workspace. **Immutable** — set at creation; there is no re-parenting in v1.                                                                                                                        |
| `depth`              | `number`              | Denormalized nesting depth (0 for a root workspace, `parent.depth + 1` for a child). Maximum depth is 10.                                                                                                                                        |
| `inheritsFromParent` | `boolean`             | Whether capabilities held on an ancestor **reach** into this node. **Off by default (strict).** Server-set at creation from the project default; owner-only to flip afterwards. See [Reach & the wall/door rule](#reach-and-the-wall-door-rule). |
| `createdAt`          | `string`              | ISO timestamp when the workspace was created.                                                                                                                                                                                                    |
| `updatedAt`          | `string`              | ISO timestamp when the workspace was last updated.                                                                                                                                                                                               |
| `memberCount`        | `number \| undefined` | The workspace's **direct** member count — descendants and reach-holders excluded. Present only when `include=memberCount` is requested, on the single-workspace read or the list alike; absent otherwise, not `null` or `0`.                     |

## Ownership

`ownerId` is a per-workspace **super-user apex**, stored on the workspace itself (mirroring how a [Space](/data-models/space) stores its owner) — not a role and not a capability.

* The owner implicitly holds **all** authority over the workspace **and its entire subtree**, and this can never be revoked.
* The owner **never has a `WorkspaceMember` row** — owner and member rows are **disjoint** for a given user + workspace. On becoming owner (creation or transfer), any existing member row for that user is removed.
* The owner still appears in the roster and **counts as a seat**, synthesized from `ownerId` with reason `owner`.
* Ownership **stacks down the tree**: an ancestor's owner is an owner over all descendants (the "god path"). So the account owner at the root is god over everything, while day-to-day authority is distributed to whoever runs each sub-workspace.

**Owner-only actions (never capabilities):** deleting a workspace, transferring ownership, and flipping the inherit flag — doable by the workspace's own owner **or any ancestor owner**, never via a capability or reach.

## Reach and the wall-door rule

Authority is **strict per-node by default**: a capability applies only to the workspace it is held on. Downward "reach" is opt-in via the child-owned `inheritsFromParent` flag.

* **Default (strict):** holding `invite` on workspace A lets you invite into A — not into A's children.
* **Opt-in reach — the flag:** each workspace carries `inheritsFromParent` (default **off**), meaning *"I accept authority reaching into me from my parent."* It is **child-owned**, so a confidential sub-workspace can seal itself even under an open parent.
* **The unbroken-chain rule (wall / door):** a capability held at an ancestor A reaches a descendant T **only if every node from A's child down to T has the flag on.** A single **off** is a *wall* sealing that node and its whole subtree from authority above; a deeper "on" cannot punch back through a sealed ancestor.
* **Ownership is the god path and ignores the flag:** the owner — and every ancestor owner — reaches the entire subtree regardless of any flag. **Capabilities respect the seal; ownership overrides it.**

Because a sealed node is capability-unreachable, only an owner can un-seal it — which is why flipping the flag is owner-only in both directions. The ownership god-path is also the recovery guarantee: a misconfigured/sealed node is never permanently locked out.

## Related

* [Workspace Member data model](/data-models/workspace-member)
* [Workspace Invitation data model](/data-models/workspace-invitation)
* [Create Workspace API](/api-reference/workspaces/create-workspace)
* [Authority read API](/api-reference/workspaces/fetch-authority)


# Workspace Invitation
Source: https://docs.sublay.io/v7/data-models/workspace-invitation

The shape of a WorkspaceInvitation object, plus the identity-matched, no-token acceptance model

A **WorkspaceInvitation** is a persistent record inviting a person into a [workspace](/data-models/workspace) with a pre-chosen grant (capabilities, permissions, rank, title) applied atomically on accept. Every invite **always sends an email** (there is no developer toggle).

Acceptance is **identity-matched + verified-email, with no token** — see [Acceptance model](#acceptance-model).

## Properties

| Property       | Type                                                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                 |
| -------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`           | `string`                                             | Unique invitation identifier (UUID). **Non-secret** — knowing it does not let a non-target accept.                                                                                                                                                                                                                                                                                                                          |
| `workspaceId`  | `string`                                             | The target workspace.                                                                                                                                                                                                                                                                                                                                                                                                       |
| `invitedBy`    | `string`                                             | User id of the inviter.                                                                                                                                                                                                                                                                                                                                                                                                     |
| `userId`       | `string \| null`                                     | The resolved invitee's user id. Set at invite time when the email/username matches an existing user, and bound at signup for email-only invites. `null` only while no account exists for the address.                                                                                                                                                                                                                       |
| `email`        | `string \| null`                                     | The invitee email, stored **normalized** (lowercase + trim). `null` for `userId`/`username`-addressed invites.                                                                                                                                                                                                                                                                                                              |
| `capabilities` | `string[]`                                           | The [capabilities](/data-models/workspace-member#capabilities-the-closed-vocabulary) to apply on accept.                                                                                                                                                                                                                                                                                                                    |
| `permissions`  | `string[]`                                           | The opaque [permissions](/data-models/workspace-member#permissions-opaque) to apply on accept.                                                                                                                                                                                                                                                                                                                              |
| `rank`         | `number`                                             | The initial [rank](/data-models/workspace-member#rank-semantics) to apply on accept — always **absolute**, whichever coordinate the inviter used. A [`relativeRank`](/data-models/workspace-member#two-coordinates-rank-and-relativerank) offset (or the default, one rung below the inviter) is resolved to a number when the invitation is created and **frozen** here; it does not follow the inviter's rank afterwards. |
| `title`        | `string \| null`                                     | Optional initial cosmetic title.                                                                                                                                                                                                                                                                                                                                                                                            |
| `status`       | `"pending" \| "accepted" \| "declined" \| "revoked"` | Invitation status. **There is no `expired` status** — expiry is lazy (see below).                                                                                                                                                                                                                                                                                                                                           |
| `expiresAt`    | `string`                                             | Absolute expiry timestamp (ISO). Set to now + **14 days**.                                                                                                                                                                                                                                                                                                                                                                  |
| `createdAt`    | `string`                                             | Creation timestamp.                                                                                                                                                                                                                                                                                                                                                                                                         |
| `updatedAt`    | `string`                                             | Last-update timestamp.                                                                                                                                                                                                                                                                                                                                                                                                      |

<Note>
  **[`GET /me/workspace-invites`](/api-reference/workspaces/invitations/list-my-invites) returns an enriched variant of this shape.** Every other read of a `WorkspaceInvitation` (listing what a workspace has issued, creating one, resending one) is by a capability-holder who already has full reach on the workspace, so `workspaceId`/`invitedBy` as bare ids are enough. The my-invites read is different: it's addressed to the *invitee*, who otherwise has no reach on the workspace at all (a direct workspace read 404s for a non-member) or the inviter. So that one endpoint replaces `invitedBy` with a populated object and adds a sibling `workspace` field, so the invite can be rendered ("X invited you to *Y*") without a follow-up read per invitation:

  | Property    | Type                                                                                                         | Description                                                                  |
  | ----------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
  | `workspace` | `{ id: string, name: string }`                                                                               | The target workspace, embedded. `workspaceId` is still present alongside it. |
  | `invitedBy` | `{ id: string, name: string \| null, username: string \| null, avatar: string \| null, reputation: number }` | The inviter, embedded in place of the bare id.                               |
</Note>

## Lazy expiry

Expiry is **lazy** — there is no background sweep and no `expired` status or webhook. A `pending` invite past `expiresAt` is **effectively expired**: it won't accept, and "live" reads filter on `status = 'pending' AND expiresAt > now`. A capability-holder can **resend** to refresh a lapsed invite (resets a fresh 14-day expiry).

## Acceptance model

Acceptance is an authenticated, in-app action gated by **identity**, not a token:

* **No secret token** is minted or emailed. The email link is a non-secret pointer to your app (a per-project accept URL) with a `?workspaceInviteId=<id>` appended for deep-linking.
* On accept **and on decline**, Sublay verifies the caller **is** the invite's target (by `userId` or normalized `email`) **and has a verified email**.
* **A verified email is required to accept *any* invite** — userId- or email-addressed. An unverified accept returns the distinct `workspace/email-not-verified` code so your app can prompt verification specifically. A squatter who signed up with someone else's address can never accept (they can't verify it) — and **decline is gated the same way**, so they cannot burn the real target's invite by moving it to the terminal `declined` state either. (Squatters can still *see* the invite: surfacing is deliberately not verification-gated.)

Combined with the verified-email gate on root-workspace creation — which **service and master keys do not bypass** either — **every workspace participant (member or owner) has a confirmed email.**

<Note>
  **Delivery requires one project setting.** Invitation emails deep-link to your app via [`workspaces.inviteAcceptUrl`](/sdk/workspaces/overview#project-settings), which has **no default**. Until it is set, creating or resending an invitation is refused with `409 workspace/missing-invite-accept-url` — including for invitees who already have an account. The link itself carries nothing secret; acceptance is identity-matched.
</Note>

### Binding to `userId`

Invitations **bind to a `userId`**: at invite time if the user already exists, and via a **signup-attach step** for new users (on signup, pending invites matching the new user's normalized email get their `userId`). So surfacing and matching are always by `userId`, and a deleted user never leaves an orphaned email-invite.

### v1 external-auth limitation

External / developer-managed-auth users have **no verified-email signal** in v1. Consequently, on a purely external-auth project:

* They **cannot act on any invite** — email- *or* `userId`-addressed — because both acceptance and decline are hard-gated on a verified email, which they lack. Inviting by `userId` lets the invite bind to the user and surface in their pending list, but they cannot accept or decline it in v1 until a verified-email signal exists.
* They **cannot create a root workspace at all** (root creation is hard-gated on a verified email, with no `userId` workaround), so **root-creation is effectively unavailable on a purely external-auth project in v1.**

This is a documented v1 limitation. A future dev-flippable project flag (treat the project's asserted emails as verified) would lift both restrictions.

## Related

* [Workspace data model](/data-models/workspace)
* [Create Invite API](/api-reference/workspaces/invitations/create-invite)
* [Accept Invite API](/api-reference/workspaces/invitations/accept-invite)


# Workspace Member
Source: https://docs.sublay.io/v7/data-models/workspace-member

The shape of a WorkspaceMember object, plus the capability vocabulary, permissions, and rank semantics

A **WorkspaceMember** record represents a user's membership in a specific [workspace](/data-models/workspace). One row exists per user per workspace, and it exists **only once an invite is accepted** — there is **no `status` column** (the "pending" state lives entirely on the [invitation](/data-models/workspace-invitation)). A member row always means "this user actually works here."

The workspace's **owner never has a member row** — owner and member rows are disjoint (see [Workspace → Ownership](/data-models/workspace#ownership)).

## Properties

| Property       | Type                  | Description                                                                                                                                                 |
| -------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`           | `string`              | Unique membership record identifier (UUID).                                                                                                                 |
| `workspaceId`  | `string`              | ID of the workspace this membership is for.                                                                                                                 |
| `userId`       | `string`              | ID of the member user.                                                                                                                                      |
| `capabilities` | `string[]`            | The member's [capabilities](#capabilities-the-closed-vocabulary) — a **closed, Sublay-enforced vocabulary** governing workspace plumbing.                   |
| `permissions`  | `string[]`            | The member's [permissions](#permissions-opaque) — **free-form, developer-defined, opaque** strings. Sublay stores and returns them but never consumes them. |
| `rank`         | `number`              | The member's management [rank](#rank-semantics) (smaller = more senior).                                                                                    |
| `title`        | `string \| null`      | Optional cosmetic label (e.g. "Frontend Team Leader"). **No authority.**                                                                                    |
| `metadata`     | `Record<string, any>` | Arbitrary developer-defined data (opaque JSON).                                                                                                             |
| `joinedAt`     | `string`              | ISO timestamp when the membership was created.                                                                                                              |
| `createdAt`    | `string`              | Record creation timestamp.                                                                                                                                  |

## The two arrays: `capabilities` vs `permissions`

The single most important sentence for developers:

> **Sublay understands and enforces `capabilities`; Sublay is blind to `permissions`.**

They never mix. `capabilities` is a fixed set Sublay uses to gate its own workspace plumbing (who can invite, who can remove members, etc.). `permissions` is whatever *your* app means by "can deploy," "can edit," etc. — Sublay stores, grants, revokes, and returns them, but never validates or interprets which strings you use.

### `capabilities` (the closed vocabulary)

There are exactly **7** capabilities. Sublay ships **no** built-in `owner`/`admin`/`member` role presets — you compose your own role concepts from these keys (the "keyring" model).

| Capability             | Grants                                                                                                                                                                                                                                                                                                                                                 |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `view`                 | See the workspace's existence + name/metadata. The auditor floor — **implied by every other capability** (you cannot manage what you cannot see), and by standing itself: the resolver adds `view` to anyone with any relation to the workspace, including a member whose stored `capabilities` array is empty. You never need to grant it explicitly. |
| `invite`               | The **whole** invitation lifecycle on this workspace: send, revoke, resend, and list pending invites.                                                                                                                                                                                                                                                  |
| `remove-member`        | Remove an existing member (subject to the [rank rule](#rank-semantics)).                                                                                                                                                                                                                                                                               |
| `edit-member-access`   | Edit a member's **powerful** fields: `capabilities`, `permissions`, and rank — in either coordinate, `rank` or `relativeRank` (fenced by no-escalation + rank).                                                                                                                                                                                        |
| `edit-member-profile`  | Edit a member's **cosmetic** fields: `title` and `metadata`. Carries no authority.                                                                                                                                                                                                                                                                     |
| `create-sub-workspace` | Create a child workspace (the creator becomes its owner).                                                                                                                                                                                                                                                                                              |
| `edit-workspace`       | Edit this workspace's own name and metadata. Does **not** include the inherit flag.                                                                                                                                                                                                                                                                    |

The four **people-operating** capabilities (`invite`, `remove-member`, `edit-member-access`, `edit-member-profile`) additionally grant visibility of **other members' authority**.

<Note>
  **Two tiers, not one.** Reading the roster at all — [`GET /workspaces/:id/members`](/api-reference/workspaces/members/list-members) and [`GET /workspaces/:id/members/:userId`](/api-reference/workspaces/members/fetch-member-standing) — needs only **some relation** to the workspace (owner, ancestor-owner, member, or reach-holder); that tier shows *who* is there, plus each member's `title` and `metadata`.

  The authority-bearing fields — **`capabilities`, `permissions`, `rank`, `relativeRank`** — are **omitted** from other users' entries unless the caller holds one of the four people-operating capabilities above, or is the `owner` / an `ancestor-owner` (a service/master key acting as **itself** is never fenced; one naming an [`actingUserId`](/sdk/workspaces/overview#acting-on-behalf-of-a-user) is fenced exactly as that user is). A caller always sees their **own** — their own roster row, their own standing, and the [authority read](/api-reference/workspaces/fetch-authority) — so no one is ever blind to their own access.

  **That gate is per node, not per request.** It is answered separately for every workspace whose members a response describes, against your **resolved** standing on *that* workspace — which includes capabilities [reaching](/data-models/workspace#reach-and-the-wall-door-rule) in through an unbroken open inherit chain and ownership from any ancestor, but not authority that stops at a **sealed** boundary. So on [`GET /workspaces/:id/members?include=descendants`](/api-reference/workspaces/members/list-members), each `descendant-member` row is judged on the descendant it belongs to: operating people on the parent does not unfence a sealed child, and the roster never shows you more of a node than that node's own roster read would.

  `relativeRank` is fenced *with* `rank` rather than beside it, because it is `rank` minus a number the caller already knows — handing it to a fenced caller would hand them `rank` itself. Note that fencing and *presence* are different questions on descendant rows: `relativeRank` is uniformly absent there for everyone (ranks from two ladders cannot be subtracted), while the fence above is decided node by node.
</Note>

**Owner-only, deliberately NOT capabilities:** deleting a workspace, transferring ownership, and flipping the inherit flag. **Self-service, no capability needed:** accepting/declining your own invite, leaving, and editing your own `title`.

Capabilities are **resolved across the tree** — a member's effective set includes their direct capabilities, plus any reaching in from ancestors via an open inherit-chain, plus the full vocabulary if they are an owner/ancestor-owner. See [reach](/data-models/workspace#reach-and-the-wall-door-rule) and the [authority read](/api-reference/workspaces/fetch-authority).

### `permissions` (opaque)

A free-form array of developer-defined strings, opaque to Sublay. Unlike capabilities, **permissions do NOT cascade** down the tree — they are strictly per-node. A read of a user's standing returns the `permissions` stored on their **direct** membership on the target workspace only; an ancestor membership's permissions never appear. If you want a parent permission to imply a child one, that is your app logic to add.

## Rank semantics

`rank` is a **per-workspace integer where a smaller number = more senior.** The **owner is the apex, above rank 0** (not a numbered rank).

* The owner mints rank **0** (only an owner can mint rank 0); each level appointed below gets the next number up (1, 2, 3, …). The top is anchored at 0 and the ladder extends downward without a ceiling.
* **Act rule:** a member may only strip capabilities from, remove, or re-rank members who are **strictly less senior** (a strictly larger rank number). Equals cannot act on equals.
* **Assign rule:** you may only set another member's rank to a number **strictly larger than your own**.
* **Initial rank** is chosen on the [invitation](/data-models/workspace-invitation).

**Cross-node rank is not compared.** When authority reaches into a *descendant* via an open chain, the actor and target sit in different, non-comparable rosters — so cross-node actions are **not** rank-checked; they are authorized by capability + open chain + ownership. The rank guard runs **only** when actor and target share a member row on the **same** workspace. A cross-node reacher may therefore set any rank in the descendant. The owner (god path) is always the backstop able to re-rank or remove any member.

### Two coordinates: `rank` and `relativeRank`

Both governance rules above are **relative** — act only on someone strictly below you, assign only strictly below yourself — so the API lets you name a rank in either coordinate:

| Field          | Means                                                                   | Domain                                                   |
| -------------- | ----------------------------------------------------------------------- | -------------------------------------------------------- |
| `rank`         | An **absolute** position on this workspace's ladder.                    | `0` – `2147483647` on a write                            |
| `relativeRank` | An **offset from you**. `1` = one rung below me, `2` = two rungs below. | `1` – `2147483647` on a write, **any integer** on a read |

The ceiling is the ladder's storage type (`int4`). Both the value you send **and** the resolved sum are bounded, so an offset that is legal on its own but overflows once anchored — `relativeRank: 1` from a rank-`2147483647` actor — is a `400 workspace/invalid-body` at the edge rather than a `500` from the database.

They are **mutually exclusive** — sending both on the same write is a `400`. Storage is always absolute: a relative offset is resolved to an absolute number at write time and that is what the member row holds.

On reads, the same field runs the other way: the roster and member-standing reads return `relativeRank` alongside `rank`, expressing that member's position **as an offset from you**. (The [authority read](/api-reference/workspaces/fetch-authority) carries `rank` only — its subject is *you*, so an offset from yourself could only ever be `0`.) The read domain is wider than the write domain — `-3` means "three rungs *above* you", `0` means "your peer". That asymmetry is one validation rule, not two concepts.

#### The anchor: your member row, not what kind of actor you are

A relative offset is measured from the caller's **own row on this workspace** if they hold one, and from **apex** (one step above rank 0) if they do not.

<Warning>
  **Phrase this on the row, not on the actor.** It is tempting to say "owners, ancestor owners, reach holders and service keys anchor at apex" — that is usually true and it is *wrong in general*. An ancestor owner may **also** hold a member row on the node they are acting on, and then they measure from that row.

  Alice owns `root` and is **rank 3** on `child`. On `child`:

  * her `relativeRank: 1` resolves to rank **4** — not 0;
  * she reads `child`'s rank-0 member back as `relativeRank: -3`.

  Write and read stay mutually consistent, and this is the correct behavior: on `child` she stands *in* the ladder, so she measures from where she stands.
</Warning>

This makes "only the owner mints rank 0" fall out of the rules instead of being a separate guard — there is no rank-0 check anywhere in the bundle. Through the **relative** form the arithmetic settles it: an in-ladder anchor is `>= 0` and a write offset is `>= 1`, so **a direct member can never produce rank 0**. Through the **absolute** form the assign rule settles it: `0` is not strictly larger than any rank `>= 0`, so an actor with a row here is refused (`403 workspace/insufficient-rank`). Rank 0 is therefore reachable by the owner — who skips the rank rules entirely — and by any other actor with **no row on this node**, who skips them too and anchors at apex.

#### A relative offset is a snapshot, not a live link

<Warning>
  **`relativeRank` is resolved once, at write time, and frozen.** It does not track the actor's later rank changes.

  Invite someone at `relativeRank: 1` while you are rank 1 and they land on rank **2**. If you are later promoted to rank 0, they stay at 2 — now two rungs below you, not one. Nothing re-derives.

  If your product wants a relationship that survives re-ranking, model it in your own data; the ladder stores plain numbers.
</Warning>

`relativeRank` on a **read** is the opposite: computed fresh on every request against whoever is asking, so two callers reading the same roster see different `relativeRank` values for the same member. Only `rank` is stable across callers.

## No privilege escalation

* **Granting** a capability or permission string requires the actor to already hold it **on the target node** (their resolved set there, including via reach).
* **Stripping/removing** a capability or permission is governed by **rank alone** (strip anything from a lower-ranked member; you need not hold it yourself).

## Related

* [Workspace data model](/data-models/workspace)
* [Workspace Invitation data model](/data-models/workspace-invitation)
* [Update Member API](/api-reference/workspaces/members/update-member)
* [List Members API](/api-reference/workspaces/members/list-members)


# App Notifications
Source: https://docs.sublay.io/v7/js-sdk/app-notifications

Read and mark the authenticated user's in-app notifications

The `appNotifications` module exposes the in-app notification feed for the authenticated user — read notifications, count unread ones, and mark them as read.

***

### fetchNotifications

Fetches a paginated list of the user's notifications.

```typescript theme={null}
const { data, pagination } = await sublay.appNotifications.fetchNotifications({
  page: 1,
  limit: 20,
});
```

The whole argument is optional.

<ParamField type="number">
  The page of results to fetch.
</ParamField>

<ParamField type="number">
  The number of notifications to return per page.
</ParamField>

**Returns** — `Promise<PaginatedResponse<UnifiedAppNotification>>`

<Note>
  A notification is a discriminated union on a `type` field, spanning system, entity/comment comments and replies, mentions, upvotes, reactions, reaction milestones, new-follow, connection-request, connection-accepted, and space-membership-approved. Each notification has `id`, `type`, `isRead`, `metadata`, and `createdAt`.
</Note>

***

### countUnreadNotifications

Returns the number of unread notifications.

```typescript theme={null}
const count = await sublay.appNotifications.countUnreadNotifications();
```

**Returns** — `Promise<number>`

***

### markNotificationAsRead

Marks a single notification as read.

```typescript theme={null}
await sublay.appNotifications.markNotificationAsRead({
  notificationId: "ntf_abc123",
});
```

<ParamField type="string">
  The ID of the notification to mark as read.
</ParamField>

**Returns** — `Promise<void>`

***

### markAllNotificationsAsRead

Marks all the user's notifications as read.

```typescript theme={null}
const { markedAsRead } = await sublay.appNotifications.markAllNotificationsAsRead();
```

**Returns** — `Promise<{ markedAsRead: number }>`


# Auth
Source: https://docs.sublay.io/v7/js-sdk/auth

Sign up, sign in, manage tokens, and handle password and email-verification flows for the end user

The `auth` module handles authentication for the current end user. Use it to register and log in users, rotate tokens, and run password and email-verification flows.

<Note>
  These functions run as the end user — there is no API key and no actor user ID. `signIn`, `signUp`, and `verifyExternalUser` automatically store the returned tokens, and `signOut` clears them (see the auth section of the SDK overview).
</Note>

***

### signUp

Registers a new user and stores the returned tokens.

```typescript theme={null}
const { user, accessToken, refreshToken } = await sublay.auth.signUp({
  email: "user@example.com",
  password: "s3cur3P@ss",
  name: "Alice",
  username: "alice",
});
```

<ParamField type="string">
  The user's email address.
</ParamField>

<ParamField type="string">
  The user's plain-text password (hashed server-side).
</ParamField>

<ParamField type="string">
  Display name for the user.
</ParamField>

<ParamField type="string">
  Unique username for the user.
</ParamField>

<ParamField type="string">
  URL of the user's avatar image.
</ParamField>

<ParamField type="string">
  Short biography for the user.
</ParamField>

<ParamField type="{ latitude: number; longitude: number }">
  The user's geographic location.
</ParamField>

<ParamField type="string">
  The user's birthdate as an ISO 8601 string.
</ParamField>

<ParamField type="Record<string, any>">
  Arbitrary key-value data attached to the user at creation time.
</ParamField>

<ParamField type="Record<string, any>">
  Sensitive key-value data attached to the user, not exposed to clients.
</ParamField>

**Returns** — `Promise<{ user: AuthUser; accessToken: string; refreshToken: string }>`

***

### signIn

Authenticates with email/password and stores the returned tokens.

```typescript theme={null}
const { user, accessToken, refreshToken } = await sublay.auth.signIn({
  email: "user@example.com",
  password: "s3cur3P@ss",
});
```

<ParamField type="string">
  The user's email address.
</ParamField>

<ParamField type="string">
  The user's password.
</ParamField>

**Returns** — `Promise<{ user: AuthUser; accessToken: string; refreshToken: string }>`

***

### signOut

Signs the user out (revokes the refresh token) and clears stored tokens.

```typescript theme={null}
await sublay.auth.signOut();
```

The whole argument is optional.

<ParamField type="string">
  The refresh token to revoke. Defaults to the SDK's stored refresh token.
</ParamField>

<ParamField type="PushDeviceIdentifier">
  Optional. The device the user is signing out on — `{ platform: "ios" | "android", token }`
  or `{ platform: "web", subscription }`. When supplied (and the project has the
  `push` bundle), the server deletes that user's push binding for the device in the
  **same transaction** as the sign-out.

  **The unbind needs a refresh token — the sign-out does not.** The unbind is
  scoped to the refresh token's subject — that is what stops one account removing
  another's binding on a shared device — so with no token to resolve, the server
  returns `204` without ever reading `pushDevice`. Rather than report a success
  that unbound nothing, the call **drops the field**, issues a request byte-identical
  to the same sign-out with no `pushDevice`, clears the local tokens, warns, and
  resolves with `pushUnbindSkipped: true`. Signing out always completes locally;
  what you lose is the unbind, and the result tells you so.

  That is the case to watch in **host-managed mode**: a client built with
  `getToken` and no `initialTokens` has an inert `setTokens`, so it never holds a
  refresh token. Pass `refreshToken` alongside `pushDevice` there — otherwise the
  device keeps receiving that account's notifications until something else removes
  the binding. A sign-out that asks for no unbind is unaffected and still works
  with no credential at all.
</ParamField>

```typescript theme={null}
await sublay.auth.signOut({
  pushDevice: { platform: "web", subscription },
});
```

<Warning>
  **A failed unbind is the only failure that keeps you signed in.** If the unbind
  fails, nothing is committed — the call rejects with `500` /
  `auth/device-deregistration-failed` (or `auth/sign-out-failed`), the session
  survives, and the SDK's stored tokens are left in place so you can retry. Never
  treat *that* rejection as signed out.

  Every other failure — a `429` from the rate limiter or a quota gate, a `423`, a
  `503`, a `400` on the body, a dropped connection — never touched a push binding,
  so `signOut` clears the local tokens and **resolves**: a user must always be able
  to sign out. The server-side session can outlive that teardown; it ends when the
  refresh token expires, or on the next successful `signOut` from a client that
  still holds one.

  If you do get the unbind rejection and decide to abandon the session locally
  anyway, `sublay.clearTokens()` drops the SDK's stored tokens (SDK-managed mode;
  it is a no-op when the host owns the token). That gives up the credential a retry
  would need, so the binding then clears only when that account next registers on
  this device, or when the server prunes the token as undeliverable.
</Warning>

**Returns** — `Promise<{ pushUnbindSkipped: boolean; pushUnbindSkipReason?: "no-refresh-token" | "push-unbind-status-unknown" }>`

`pushUnbindSkipped` is `true` whenever a `pushDevice` was supplied and the unbind did
not happen, so this device's binding for that account may still be live. The sign-out
itself completes either way. There are two ways to get it, and they are recovered
differently — `pushUnbindSkipReason` says which:

* **`"no-refresh-token"`** — the SDK never asked, because no refresh token could be
  resolved (see `pushDevice` above). Nothing was destroyed either: with no token the
  server has no session to end, so the account, its credential and its binding are all
  still there. **Retryable** — re-issue the sign-out with an explicit `refreshToken`,
  or remove the binding from a client that holds one.
* **`"push-unbind-status-unknown"`** — the server was asked and could not answer: it
  could not determine whether the project has push devices, so it attempted no unbind
  and said so in a `200` body (see
  [`POST /auth/sign-out`](/api-reference/auth/sign-out#response)). The sign-out itself
  committed, so there is no credential left to retry with. The binding clears when
  that account next registers on this device, or when the server prunes the token as
  undeliverable.

`false` means **no skip was reported** — not by this SDK, and not by the server. It is
not a promise that no skip happened. The server declines the unbind for several reasons
it answers with a plain `204`, and every one of them reads `false` here: a refresh token
that is authentic but expired beyond the server's 90-day unbind window (reachable by
passing an old `refreshToken` explicitly), a malformed or wrong-signature token, a
project without the `push` bundle, and an unbind that ran and matched no row. The server
records each of those in its own logs. Only the case where it could not determine
whether a binding exists is reported back, because that is the one where the binding may
still be live and nobody looked.

Both reported skips also log a warning, so a caller that ignores the result still hears
about it.

***

### verifyExternalUser

Exchanges a host-issued user JWT for Sublay tokens and stores them. Use this when your app manages its own auth.

```typescript theme={null}
const { user, accessToken, refreshToken } = await sublay.auth.verifyExternalUser({
  userJwt: signedJwt,
});
```

<ParamField type="string">
  A JWT issued by your application, containing user identity claims.
</ParamField>

**Returns** — `Promise<{ user: AuthUser; accessToken: string; refreshToken: string }>`

***

### requestNewAccessToken

Manually rotates the access token using a refresh token. Normally this is handled automatically on a `403` in SDK-managed mode.

```typescript theme={null}
const { accessToken, refreshToken } = await sublay.auth.requestNewAccessToken();
```

The whole argument is optional.

<ParamField type="string">
  The refresh token to exchange. Defaults to the SDK's stored refresh token.
</ParamField>

<Note>
  Persist the new `refreshToken` if one is present (token rotation), or use SDK-managed mode, which does this for you.
</Note>

**Returns** — `Promise<{ accessToken: string; refreshToken?: string }>`

***

### requestPasswordReset

Sends a password-reset email.

```typescript theme={null}
await sublay.auth.requestPasswordReset({ email: "user@example.com" });
```

<ParamField type="string">
  The email address to send the reset link to.
</ParamField>

**Returns** — `Promise<void>`

***

### resetPassword

Completes a password reset using a token from the email.

This revokes **every** session for that user and removes **every** push binding they hold, on every device — a reset is the remedy for a suspected compromise, so nothing is spared and there is no field to spare one with. They sign in again everywhere, and each device re-binds for push on its own once it is next opened. Projects without the `push` bundle skip the binding step and are otherwise unaffected.

```typescript theme={null}
await sublay.auth.resetPassword({
  token: resetToken,
  newPassword: "newS3cur3P@ss",
});
```

<ParamField type="string">
  The reset token from the password reset email.
</ParamField>

<ParamField type="string">
  The new password to set for the account.
</ParamField>

**Returns** — `Promise<void>`

***

### changePassword

Changes the authenticated user's password after verifying the current one. Use this for an authenticated "change password" flow, as opposed to the token-based `resetPassword`.

A password change ends **every other session** for that user and deletes every push binding they hold — see [Change Password](/api-reference/auth/change-password). The session making the call survives: the server reads which session is asking off the access token the request is already authenticated with, so nothing about it has to be sent.

```typescript theme={null}
const { success, message } = await sublay.auth.changePassword({
  password: "currentP@ss",
  newPassword: "newS3cur3P@ss",
});
```

<ParamField type="string">
  The user's current password (verified before the change).
</ParamField>

<ParamField type="string">
  The new password to set.
</ParamField>

<ParamField type="object">
  This device, so its push binding survives the change. Same value `auth.signOut` takes and the same one [Register Device](/api-reference/push-notifications/register-device) was called with: `{ platform: "ios" | "android", token }` or `{ platform: "web", subscription }`. (`@sublay/js`'s own `push` module covers preferences only — device registration is the REST endpoint, or `usePushRegistration` in the React packages.)

  Omit it and every push binding for the user is deleted, this device's included — and nothing re-binds it until the app cold-starts, switches accounts or rotates its token, so it stops notifying until then.
</ParamField>

**Returns** — `Promise<{ success: boolean; message: string }>`

***

### setPassword

Sets an **initial** password for an OAuth-only user who has no password yet. Unlike `changePassword`, there is no current password to verify. Use this to let an OAuth-only user add a password (for example, so they can sign in with email/password, or unlink their last OAuth identity). If the user already has a password, this fails with `auth/already-password-authenticated` — use `changePassword` instead.

```typescript theme={null}
const { success, message } = await sublay.auth.setPassword({
  newPassword: "newS3cur3P@ss",
});
```

<ParamField type="string">
  The password to set for the account.
</ParamField>

**Returns** — `Promise<{ success: boolean; message: string }>`

***

### sendVerificationEmail

Sends (or re-sends) an email-verification message to the authenticated user, delivered as a code or a link.

```typescript theme={null}
const { success } = await sublay.auth.sendVerificationEmail({
  mode: "code",
  tokenFormat: "numeric",
  tokenLength: 6,
});
```

The argument is required, and `mode` determines what else is required — enforced by TypeScript as a discriminated union, not just documented.

<ParamField type="&#x22;code&#x22; | &#x22;link&#x22;">
  `"code"` emails a short token the user enters; `"link"` emails a verification URL.
</ParamField>

<ParamField type="&#x22;hex&#x22; | &#x22;numeric&#x22; | &#x22;alpha&#x22; | &#x22;alphanumeric&#x22;">
  Format of the generated token.

  * Required when `mode: "code"` — there's no default, since `"hex"` produces a 64-character token no one would want to type.
  * Optional when `mode: "link"` (defaults to `"hex"`) — the token sits in a URL, never read by a human, so format doesn't matter.
</ParamField>

<ParamField type="number">
  Length of the generated token (4–12).

  * Required when `mode: "code"` and `tokenFormat` isn't `"hex"`.
  * Not allowed when `tokenFormat` is `"hex"` — hex ignores length and always produces a fixed 64-character token.
  * Optional when `mode: "link"` (defaults to `6`).
</ParamField>

<ParamField type="string">
  For `mode: "link"` — where to send the user after the link is verified.
</ParamField>

**Returns** — `Promise<{ success: boolean }>`

***

### verifyEmail

Verifies a user's email using a verification token.

```typescript theme={null}
await sublay.auth.verifyEmail({ token: verificationToken });
```

<ParamField type="string">
  The email verification token.
</ParamField>

**Returns** — `Promise<void>`

***

### requestAccountDeletion

Starts self-service deletion of the authenticated user's account by emailing them a one-time confirmation code (valid for 10 minutes). This does not delete anything on its own — pass the code to [`confirmAccountDeletion`](#confirmaccountdeletion) to finish.

```typescript theme={null}
const { success } = await sublay.auth.requestAccountDeletion();
```

Only works for accounts with an email on file. Accounts without one (e.g. anonymous or foreign-id users) must be deleted server-side with a service key via [`@sublay/node`](/node-sdk/users). The request fails with `auth/no-email-on-file` otherwise.

Takes no arguments.

**Returns** — `Promise<{ success: boolean }>`

***

### confirmAccountDeletion

Verifies the emailed code and **permanently deletes** the authenticated user's account. The cascade matches the service-key delete — entities and comments are kept as hollow shells; everything else owned by the user is removed.

```typescript theme={null}
await sublay.auth.confirmAccountDeletion({ code: "048291" });
```

<Warning>
  Deletion is immediate and irreversible. The user and their session tokens no
  longer exist after this resolves.
</Warning>

<ParamField type="string">
  The one-time confirmation code from the deletion email.
</ParamField>

**Returns** — `Promise<void>`


# Chat
Source: https://docs.sublay.io/v7/js-sdk/chat

Conversations, messages, members, reactions, and read state

The `chat` module powers direct, group, and space conversations — sending and
editing messages (with file attachments), managing members, reacting, and tracking
read state. All actions are performed as the logged-in user.

<Note>
  **Two list endpoints use cursor (keyset) pagination, not `page`/`limit`:**
  [`listConversations`](#listconversations) and [`listMessages`](#listmessages).
  Their return shapes differ from the standard `PaginatedResponse` — see each
  below.
</Note>

***

### listConversations

Lists the user's conversations, newest activity first, with keyset pagination.

```typescript theme={null}
const { conversations, hasMore } = await sublay.chat.listConversations({
  types: "direct,group",
  limit: 20,
});

// Next page: pass the last item's lastMessageAt + createdAt as cursors.
const last = conversations[conversations.length - 1];
const next = await sublay.chat.listConversations({
  cursor: last.lastMessageAt,
  cursorCreatedAt: last.createdAt,
});
```

<ParamField type="string">
  Comma-separated conversation types to include, e.g. `"direct,group,space"`.
</ParamField>

<ParamField type="string">
  Keyset cursor — the `lastMessageAt` (ISO datetime) of the last item from the
  previous page.
</ParamField>

<ParamField type="string">
  Tie-breaker cursor — the `createdAt` (ISO datetime) of the last item from the
  previous page.
</ParamField>

<ParamField type="number">
  Page size. Defaults to `20`, max `50`.
</ParamField>

**Returns** — `Promise<{ conversations: ConversationPreview[]; hasMore: boolean }>`.

Each `ConversationPreview` includes `otherMembers` — up to 5 active members other than the current user (`id`, `name`, `username`, `avatar`) for `direct`/`group` conversations, so a DM/group can render the counterparty without a separate members fetch. Capped at 5 (use `memberCount` for the group total); empty for `space` conversations.

***

### createDirectConversation

Creates (or returns the existing) 1:1 direct conversation with another user.

```typescript theme={null}
const conversation = await sublay.chat.createDirectConversation({
  userId: "usr_abc123",
});
```

<ParamField type="string">
  The other participant's Sublay user ID.
</ParamField>

**Returns** — `Promise<Conversation>`

***

### createGroupConversation

Creates a group conversation.

```typescript theme={null}
const conversation = await sublay.chat.createGroupConversation({
  name: "Design Team",
  memberIds: ["usr_abc123", "usr_def456"],
});
```

<ParamField type="string">
  Group name.
</ParamField>

<ParamField type="string">
  Group description.
</ParamField>

<ParamField type="string[]">
  Sublay user IDs to add to the group. Defaults to an empty list.
</ParamField>

<ParamField type="object">
  Arbitrary key-value data attached to the conversation.
</ParamField>

**Returns** — `Promise<Conversation>`

***

### getConversation

Fetches a single conversation by ID.

```typescript theme={null}
const conversation = await sublay.chat.getConversation({
  conversationId: "cnv_abc123",
});
```

<ParamField type="string">
  The conversation ID.
</ParamField>

**Returns** — `Promise<Conversation>`

***

### updateConversation

Updates a conversation's settings.

```typescript theme={null}
const conversation = await sublay.chat.updateConversation({
  conversationId: "cnv_abc123",
  name: "Renamed Group",
});
```

<ParamField type="string">
  The conversation ID.
</ParamField>

<ParamField type="string">
  New name.
</ParamField>

<ParamField type="string">
  New description.
</ParamField>

<ParamField type="string | null">
  File ID for the conversation avatar, or `null` to clear it.
</ParamField>

<ParamField type="&#x22;members&#x22; | &#x22;admins&#x22;">
  Space conversations only: who may post.
</ParamField>

**Returns** — `Promise<Conversation>`

***

### deleteConversation

Deletes a conversation.

```typescript theme={null}
await sublay.chat.deleteConversation({ conversationId: "cnv_abc123" });
```

<ParamField type="string">
  The conversation ID.
</ParamField>

**Returns** — `Promise<{ message: string }>`

***

### getUnreadCount

Returns the user's total unread message count and unread-conversation count. Takes
no arguments.

```typescript theme={null}
const { totalUnread, unreadConversationCount } = await sublay.chat.getUnreadCount();
```

**Returns** — `Promise<{ totalUnread: number; unreadConversationCount: number }>`

***

### listMembers

Lists the members of a conversation (standard page-based pagination).

```typescript theme={null}
const { data, pagination } = await sublay.chat.listMembers({
  conversationId: "cnv_abc123",
  page: 1,
  limit: 50,
});
```

<ParamField type="string">
  The conversation ID.
</ParamField>

<ParamField type="number">
  Page number (1-indexed).
</ParamField>

<ParamField type="number">
  Results per page.
</ParamField>

<ParamField type="&#x22;admin&#x22; | &#x22;member&#x22;">
  Filter members by role.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<PaginatedResponse<ConversationMember>>`

***

### addMember

Adds a user as a member of a conversation.

```typescript theme={null}
const member = await sublay.chat.addMember({
  conversationId: "cnv_abc123",
  userId: "usr_def456",
});
```

<ParamField type="string">
  The conversation ID.
</ParamField>

<ParamField type="string">
  The user to add (the target member).
</ParamField>

**Returns** — `Promise<ConversationMember>`

***

### removeMember

Removes a member from a conversation.

```typescript theme={null}
await sublay.chat.removeMember({
  conversationId: "cnv_abc123",
  userId: "usr_def456",
});
```

<ParamField type="string">
  The conversation ID.
</ParamField>

<ParamField type="string">
  The member to remove (the target).
</ParamField>

**Returns** — `Promise<{ message: string }>`

***

### changeMemberRole

Changes a member's role within a conversation.

```typescript theme={null}
const member = await sublay.chat.changeMemberRole({
  conversationId: "cnv_abc123",
  userId: "usr_def456",
  role: "admin",
});
```

<ParamField type="string">
  The conversation ID.
</ParamField>

<ParamField type="string">
  The member whose role to change (the target).
</ParamField>

<ParamField type="&#x22;admin&#x22; | &#x22;member&#x22;">
  The new role.
</ParamField>

**Returns** — `Promise<ConversationMember>`

***

### leaveConversation

The logged-in user leaves a conversation.

```typescript theme={null}
await sublay.chat.leaveConversation({ conversationId: "cnv_abc123" });
```

<ParamField type="string">
  The conversation ID.
</ParamField>

**Returns** — `Promise<{ message: string }>`

***

### listMessages

Lists messages in a conversation with keyset (before/after) pagination.

```typescript theme={null}
const { messages, hasMore, oldestCreatedAt } = await sublay.chat.listMessages({
  conversationId: "cnv_abc123",
  limit: 50,
  sort: "desc",
});

// Older page: pass the oldest message's timestamp as `before`.
const older = await sublay.chat.listMessages({
  conversationId: "cnv_abc123",
  before: oldestCreatedAt,
});

// Only messages that have thread replies.
const withReplies = await sublay.chat.listMessages({
  conversationId: "cnv_abc123",
  filters: { hasReplies: true },
});
```

<ParamField type="string">
  The conversation ID.
</ParamField>

<ParamField type="string">
  Restrict to replies of this message (thread view).
</ParamField>

<ParamField type="string">
  Keyset cursor (ISO timestamp) — return messages created before this. Mutually
  exclusive with `after`.
</ParamField>

<ParamField type="string">
  Keyset cursor (ISO timestamp) — return messages created after this. Mutually
  exclusive with `before`.
</ParamField>

<ParamField type="number">
  Page size. Defaults to `50`, max `100`.
</ParamField>

<ParamField type="&#x22;asc&#x22; | &#x22;desc&#x22;">
  Sort direction by creation time.
</ParamField>

<ParamField type="string">
  Comma-separated associations to populate: `"files"` (message attachments) and `"grants"` (each message's [reputation-grant summary](/data-models/reputation-grant#grantsummary)). Combine them as `"files,grants"`.
</ParamField>

<ParamField type="MessageFilters">
  Optional filters. `filters.hasReplies` (boolean): when `true`, returns only
  messages that have thread replies (`threadReplyCount > 0`); when `false`, only
  messages with none. Filters by thread replies, not quotings.

  Threads are one level deep, so `hasReplies: true` together with `parentId`
  always returns an empty list — the response's `notice` field explains why.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<{ messages: ChatMessage[]; hasMore: boolean; oldestCreatedAt: string | null; newestCreatedAt: string | null }>`.

***

### sendMessage

Sends a message to a conversation, optionally with file attachments. When `files`
is provided the request is sent as `multipart/form-data` (pass browser `File` /
`Blob` objects); otherwise it is a plain JSON body.

```typescript theme={null}
const input = document.querySelector('input[type="file"]');

const message = await sublay.chat.sendMessage({
  conversationId: "cnv_abc123",
  content: "Here's the doc 👇",
  files: Array.from(input.files), // up to 10 File/Blob attachments
});
```

<ParamField type="string">
  The conversation ID.
</ParamField>

<ParamField type="string">
  Message text.
</ParamField>

<ParamField type="GifData | null">
  An attached GIF, or `null`.
</ParamField>

<ParamField type="Mention[]">
  User mentions embedded in the message.
</ParamField>

<ParamField type="string">
  The message this is a threaded reply to.
</ParamField>

<ParamField type="string">
  A message being quoted.
</ParamField>

<ParamField type="object">
  Arbitrary key-value data attached to the message.
</ParamField>

<ParamField type="string">
  A client-generated ID echoed back on the created message (for optimistic UI);
  not stored.
</ParamField>

<ParamField type="(Blob | File)[]">
  Up to 10 file attachments, as browser `File` / `Blob` objects. Triggers a
  `multipart/form-data` upload.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<ChatMessage>`

***

### getMessage

Fetches a single message by ID.

```typescript theme={null}
const message = await sublay.chat.getMessage({
  conversationId: "cnv_abc123",
  messageId: "msg_xyz789",
});
```

<ParamField type="string">
  The conversation ID.
</ParamField>

<ParamField type="string">
  The message ID.
</ParamField>

<ParamField type="string">
  Comma-separated associations to populate. Only `"grants"` is supported here — it attaches the message's [reputation-grant summary](/data-models/reputation-grant#grantsummary) at `message.grants`.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<ChatMessage>`

***

### editMessage

Edits an existing message.

```typescript theme={null}
const message = await sublay.chat.editMessage({
  conversationId: "cnv_abc123",
  messageId: "msg_xyz789",
  content: "Edited text",
});
```

<ParamField type="string">
  The conversation ID.
</ParamField>

<ParamField type="string">
  The message ID.
</ParamField>

<ParamField type="string">
  New message text.
</ParamField>

<ParamField type="GifData | null">
  A [GifData](/data-models/chat-message#gifdata) attachment, or `null` to clear it.
</ParamField>

<ParamField type="Mention[]">
  Updated mentions.
</ParamField>

<ParamField type="object | null">
  Updated metadata, or `null` to clear it.
</ParamField>

**Returns** — `Promise<ChatMessage>`

***

### deleteMessage

Deletes a message in a conversation.

```typescript theme={null}
await sublay.chat.deleteMessage({
  conversationId: "cnv_abc123",
  messageId: "msg_xyz789",
});
```

<ParamField type="string">
  The conversation ID.
</ParamField>

<ParamField type="string">
  The message ID.
</ParamField>

**Returns** — `Promise<{ message: string; userDeletedAt?: string }>` (`userDeletedAt`
is set when the author soft-deletes their own message).

***

### Reporting a message

Message reports go through the shared reports API, not a chat-specific
function — the same call that reports entities and comments.

```typescript theme={null}
const result = await sublay.reports.createReport({
  targetType: "message",
  targetId: "msg_xyz789",
  reason: "spam",
});
```

`targetId` is the message id; the conversation is resolved server-side, so no
`conversationId` is needed. The reporter must be a member of the conversation
and cannot report their own message. See [createReport](/js-sdk/reports).

**Returns** — `Promise<{ message: string; code: string }>`

***

### toggleReaction

Toggles (adds or removes) an emoji reaction on a message for the logged-in user.

```typescript theme={null}
const { reactionCounts, userReactions, delta } = await sublay.chat.toggleReaction({
  conversationId: "cnv_abc123",
  messageId: "msg_xyz789",
  emoji: "👍",
});
// delta is +1 if the reaction was added, -1 if removed.
```

<ParamField type="string">
  The conversation ID.
</ParamField>

<ParamField type="string">
  The message ID.
</ParamField>

<ParamField type="string">
  The reaction emoji (1–10 characters).
</ParamField>

**Returns** — `Promise<{ reactionCounts: Record<string, number>; userReactions: string[]; delta: 1 | -1 }>`

***

### listReactions

Lists the users who reacted to a message with a given emoji.

```typescript theme={null}
const { data, pagination } = await sublay.chat.listReactions({
  conversationId: "cnv_abc123",
  messageId: "msg_xyz789",
  emoji: "👍",
});
```

<ParamField type="string">
  The conversation ID.
</ParamField>

<ParamField type="string">
  The message ID.
</ParamField>

<ParamField type="string">
  The reaction emoji to list reactors for.
</ParamField>

<ParamField type="number">
  Page number. Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Defaults to `50`, max `100`.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<{ data: MessageReaction[]; pagination: { page: number; limit: number; total: number; hasMore: boolean } }>`,
where `MessageReaction` is `{ user: User; emoji: string; createdAt: Date }`.

***

### markAsRead

Marks a conversation as read up to a given message.

```typescript theme={null}
await sublay.chat.markAsRead({
  conversationId: "cnv_abc123",
  messageId: "msg_xyz789",
});
```

<ParamField type="string">
  The conversation ID.
</ParamField>

<ParamField type="string">
  The message up to which the conversation is marked read.
</ParamField>

**Returns** — `Promise<{ message: string }>`

***

### muteConversation

Sets or clears the signed-in user's mute on a conversation. Muting suppresses the `message` push for this conversation only; the message is still delivered and readable. See [Notification Preferences & Mute](/notification-preferences).

```typescript theme={null}
// Mute for 24 hours
await sublay.chat.muteConversation({
  conversationId: "cnv_abc123",
  duration: "24h",
});

// Unmute
await sublay.chat.muteConversation({
  conversationId: "cnv_abc123",
  duration: null,
});
```

<ParamField type="string">
  The conversation to mute or unmute.
</ParamField>

<ParamField type="&#x22;8h&#x22; | &#x22;24h&#x22; | &#x22;1w&#x22; | &#x22;forever&#x22; | null">
  The mute **duration choice**, or `null` to clear the mute. Send the choice, never a raw timestamp — the server resolves the window.
</ParamField>

**Returns** — `Promise<{ currentMember: ConversationMember }>` — the signed-in user's own member row.

<Info>
  **"Forever" is an explicit signal.** A `forever` mute returns `mutedForever: true` with `mutedUntil: null`; a timed mute returns `mutedForever: false` with a real ISO `mutedUntil`. Read the boolean — never string-match a far-future date.
</Info>


# Collections
Source: https://docs.sublay.io/v7/js-sdk/collections

Organize the logged-in user's saved entities into a tree of collections

The `collections` module organizes the logged-in user's saved content. Every user has a single **root collection**, under which they can nest sub-collections and into which they can save entities.

***

### fetchRootCollection

Fetches the logged-in user's root collection.

```typescript theme={null}
const root = await sublay.collections.fetchRootCollection();
```

**Returns** — `Promise<Collection>`

***

### fetchSubCollections

Fetches the immediate sub-collections of a collection.

```typescript theme={null}
const subCollections = await sublay.collections.fetchSubCollections({
  collectionId: "col_root123",
});
```

<ParamField type="string">
  The parent collection ID.
</ParamField>

**Returns** — `Promise<Collection[]>`

***

### createNewCollection

Creates a sub-collection under a parent collection.

```typescript theme={null}
const collection = await sublay.collections.createNewCollection({
  collectionId: "col_root123",
  collectionName: "Recipes",
});
```

<ParamField type="string">
  The parent collection under which to create the sub-collection.
</ParamField>

<ParamField type="string">
  The name of the new collection.
</ParamField>

**Returns** — `Promise<Collection>`

***

### fetchCollectionEntities

Fetches the entities within a collection, paginated.

```typescript theme={null}
const { data, pagination } = await sublay.collections.fetchCollectionEntities({
  collectionId: "col_abc123",
  sortBy: "added",
  sortDir: "desc",
});
```

<ParamField type="string">
  The collection ID.
</ParamField>

<ParamField type="number">
  The page number to fetch.
</ParamField>

<ParamField type="number">
  The number of entities to return per page.
</ParamField>

<ParamField type="&#x22;new&#x22; | &#x22;added&#x22; | &#x22;top&#x22; | &#x22;hot&#x22;">
  Sort order.
</ParamField>

<ParamField type="&#x22;asc&#x22; | &#x22;desc&#x22;">
  Sort direction.
</ParamField>

<ParamField type="string">
  Comma-separated related resources to include in the response.
</ParamField>

**Returns** — `Promise<PaginatedResponse<Entity>>`

***

### addEntityToCollection

Adds an entity to a collection.

```typescript theme={null}
const result = await sublay.collections.addEntityToCollection({
  collectionId: "col_abc123",
  entityId: "ent_222",
});
```

<ParamField type="string">
  The collection ID.
</ParamField>

<ParamField type="string">
  The ID of the entity to add.
</ParamField>

**Returns** — `Promise<{ success: boolean; collection: { id: string; entityCount: number } }>`

***

### removeEntityFromCollection

Removes an entity from a collection.

```typescript theme={null}
const result = await sublay.collections.removeEntityFromCollection({
  collectionId: "col_abc123",
  entityId: "ent_222",
});
```

<ParamField type="string">
  The collection ID.
</ParamField>

<ParamField type="string">
  The ID of the entity to remove.
</ParamField>

**Returns** — `Promise<{ success: boolean; collection: { id: string; entityCount: number } }>`

***

### updateCollection

Renames a collection.

```typescript theme={null}
const collection = await sublay.collections.updateCollection({
  collectionId: "col_abc123",
  name: "Favorite Recipes",
});
```

<ParamField type="string">
  The collection ID.
</ParamField>

<ParamField type="string">
  The new collection name. Must be a non-empty string.
</ParamField>

**Returns** — `Promise<Collection>`

***

### deleteCollection

Deletes a collection.

```typescript theme={null}
await sublay.collections.deleteCollection({ collectionId: "col_abc123" });
```

<ParamField type="string">
  The collection ID.
</ParamField>

**Returns** — `Promise<void>`


# Comments
Source: https://docs.sublay.io/v7/js-sdk/comments

Create and manage threaded comments and reactions

Comments are threaded discussions attached to entities. The `comments` module lets you create, fetch, update, and delete comments, and manage reactions on them. All actions are performed on behalf of the logged-in user.

***

### createComment

Creates a comment on an entity. Optionally a reply, with a GIF, mentions, attachments, or metadata.

```typescript theme={null}
const comment = await sublay.comments.createComment({
  entityId: "ent_xyz789",
  content: "Great post!",
});
```

<ParamField type="string">
  The Sublay entity ID the comment belongs to.
</ParamField>

<ParamField type="string">
  Your application's identifier for this comment.
</ParamField>

<ParamField type="string">
  The comment's text content.
</ParamField>

<ParamField type="GifData | null">
  An optional GIF attached to the comment.
</ParamField>

<ParamField type="Mention[]">
  User mentions embedded in the comment.
</ParamField>

<ParamField type="string | null">
  The ID of the parent comment when this is a reply.
</ParamField>

<ParamField type="string">
  The ID of another comment this comment references.
</ParamField>

<ParamField type="Record<string, any>[]">
  File or media attachments.
</ParamField>

<ParamField type="Record<string, any>">
  Arbitrary public metadata.
</ParamField>

**Returns** — `Promise<Comment>`

***

### fetchComment

Fetches a single comment by its ID.

```typescript theme={null}
const comment = await sublay.comments.fetchComment({ commentId: "cmt_abc123" });
```

<ParamField type="string">
  The Sublay comment ID.
</ParamField>

<ParamField type="string">
  Comma-separated list of associations to populate.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<Comment>`

***

### fetchCommentByForeignId

Fetches a comment by your application's own identifier.

```typescript theme={null}
const comment = await sublay.comments.fetchCommentByForeignId({
  foreignId: "comment-99",
});
```

<ParamField type="string">
  Your application's comment identifier.
</ParamField>

<ParamField type="string">
  Comma-separated list of associations to populate.
</ParamField>

**Returns** — `Promise<Comment>`

***

### updateComment

Updates a comment's content.

```typescript theme={null}
const comment = await sublay.comments.updateComment({
  commentId: "cmt_abc123",
  content: "Edited comment text",
});
```

<ParamField type="string">
  The Sublay comment ID to update.
</ParamField>

<ParamField type="string">
  The new content for the comment.
</ParamField>

**Returns** — `Promise<Comment>`

***

### deleteComment

Deletes a comment.

```typescript theme={null}
await sublay.comments.deleteComment({ commentId: "cmt_abc123" });
```

<ParamField type="string">
  The Sublay comment ID to delete.
</ParamField>

**Returns** — `Promise<void>`

***

### fetchManyComments

Fetches a paginated list of comments, filterable by entity, user, or parent.

```typescript theme={null}
const { data, pagination } = await sublay.comments.fetchManyComments({
  entityId: "ent_xyz789",
  sortBy: "top",
  page: 1,
  limit: 20,
});
```

<ParamField type="string">
  Filter to comments on a specific entity.
</ParamField>

<ParamField type="string">
  Filter to comments authored by a given user.
</ParamField>

<ParamField type="string">
  Filter to replies of a specific parent comment.
</ParamField>

<ParamField type="number">
  Page number (1-indexed).
</ParamField>

<ParamField type="number">
  Results per page.
</ParamField>

<ParamField type="string">
  Sort order: `"createdAt"` (newest first; honors `sortDir`), `"top"`, or `"controversial"`. `"new"` and `"old"` are deprecated aliases for `"createdAt"` (removed in v8) — the server still accepts them but responds with a deprecation header.
</ParamField>

<ParamField type="string">
  Comma-separated list of associations to populate.
</ParamField>

<ParamField type="string">
  Filter by source ID.
</ParamField>

<ParamField type="&#x22;exclude&#x22; | &#x22;include-outbound-blocked&#x22;">
  How to treat comments authored by users the viewer is [block-edged](/sdk/moderation/overview#blocking) with. `"exclude"` (default) hides them; `"include-outbound-blocked"` re-includes only the viewer's own outbound-blocked authors — never content from users who blocked the viewer. No effect without the `moderation` bundle.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<PaginatedResponse<Comment>>`

***

### addReaction

Adds the logged-in user's reaction to a comment and returns the full populated comment.

```typescript theme={null}
const comment = await sublay.comments.addReaction({
  commentId: "cmt_abc123",
  reactionType: "like",
});
```

<ParamField type="string">
  The Sublay comment ID.
</ParamField>

<ParamField type="ReactionType">
  One of: `"upvote"`, `"downvote"`, `"like"`, `"love"`, `"wow"`, `"sad"`, `"angry"`, `"funny"`.
</ParamField>

**Returns** — `Promise<Comment>`

***

### removeReaction

Removes the logged-in user's reaction from a comment and returns the full populated comment.

```typescript theme={null}
const comment = await sublay.comments.removeReaction({
  commentId: "cmt_abc123",
});
```

<ParamField type="string">
  The Sublay comment ID.
</ParamField>

**Returns** — `Promise<Comment>`

***

### fetchReactions

Fetches a paginated list of reactions on a comment, optionally filtered by reaction type.

```typescript theme={null}
const { data, pagination } = await sublay.comments.fetchReactions({
  commentId: "cmt_abc123",
  reactionType: "like",
  page: 1,
  limit: 20,
});
```

<ParamField type="string">
  The Sublay comment ID.
</ParamField>

<ParamField type="ReactionType">
  Filter to a specific reaction type.
</ParamField>

<ParamField type="number">
  Page number (1-indexed).
</ParamField>

<ParamField type="number">
  Results per page.
</ParamField>

<ParamField type="string">
  Sort direction: `"asc"` or `"desc"`.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<{ data: Reaction[]; pagination: { page: number; limit: number; total: number; totalPages: number; hasMore: boolean } }>`

***

### getUserReaction

Gets the logged-in user's reaction on a comment. Returns `null` if there is no reaction.

```typescript theme={null}
const { reactionType } = await sublay.comments.getUserReaction({
  commentId: "cmt_abc123",
});
// reactionType is "like" | "upvote" | ... | null
```

<ParamField type="string">
  The Sublay comment ID.
</ParamField>

**Returns** — `Promise<{ reactionType: ReactionType | null }>`


# Connections
Source: https://docs.sublay.io/v7/js-sdk/connections

Read and manage the logged-in user's own connections and pending requests

The `connections` module acts on the **logged-in user's own** mutual connections — bidirectional relationships, similar to "friends." Use it to list established connections, inspect outgoing and incoming pending requests, and accept, decline, or remove connections.

<Tip>
  To **request** a connection with someone, check the connection status against a
  specific user, or remove a connection by the other user's ID, use the
  [`users`](/v7/js-sdk/users) module.
</Tip>

***

### fetchConnections

Returns a paginated list of your established (mutual) connections.

```typescript theme={null}
const { data, pagination } = await sublay.connections.fetchConnections({
  page: 1,
  limit: 20,
});
```

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Defaults to `20`.
</ParamField>

<ParamField type="string">
  Optional search term. Filters the list to connections whose connected user's username or name contains this text (case-insensitive). When omitted, no filtering is applied.
</ParamField>

<ParamField type="string">
  Restricts which field `query` matches against — `username` or `name`. When omitted, `query` matches either field.
</ParamField>

**Returns** — `Promise<PaginatedResponse<EstablishedConnection>>`, where `EstablishedConnection` is `{ id, connectedUser, connectedAt }`.

***

### fetchConnectionsCount

Returns the number of your established connections.

```typescript theme={null}
const { count } = await sublay.connections.fetchConnectionsCount();
```

**Returns** — `Promise<{ count: number }>`

***

### fetchSentPendingConnections

Returns a paginated list of your outgoing connection requests that are still pending.

```typescript theme={null}
const { data, pagination } =
  await sublay.connections.fetchSentPendingConnections({
    page: 1,
    limit: 20,
  });
```

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Defaults to `20`.
</ParamField>

**Returns** — `Promise<PaginatedResponse<PendingConnection>>`, where `PendingConnection` is `{ id, message?, createdAt, user, type: "received" | "sent" }`.

***

### fetchReceivedPendingConnections

Returns a paginated list of incoming connection requests you have received.

```typescript theme={null}
const { data, pagination } =
  await sublay.connections.fetchReceivedPendingConnections({
    page: 1,
    limit: 20,
  });
```

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Defaults to `20`.
</ParamField>

**Returns** — `Promise<PaginatedResponse<PendingConnection>>`

***

### acceptConnection

Accepts a pending incoming connection request.

```typescript theme={null}
const result = await sublay.connections.acceptConnection({
  connectionId: "con_xyz789",
});
```

<ParamField type="string">
  The ID of the pending connection request to accept.
</ParamField>

**Returns** — `Promise<{ id: string; status: string; createdAt?: string; respondedAt?: string }>`

***

### declineConnection

Declines a pending incoming connection request.

```typescript theme={null}
const result = await sublay.connections.declineConnection({
  connectionId: "con_xyz789",
});
```

<ParamField type="string">
  The ID of the pending connection request to decline.
</ParamField>

**Returns** — `Promise<{ id: string; status: string; createdAt?: string; respondedAt?: string }>`

***

### removeConnection

Removes an established connection by its connection ID.

```typescript theme={null}
await sublay.connections.removeConnection({ connectionId: "con_xyz789" });
```

<ParamField type="string">
  The connection ID to remove.
</ParamField>

**Returns** — `Promise<void>`


# Entities
Source: https://docs.sublay.io/v7/js-sdk/entities

Create and manage content entities, reactions, and drafts

<Note>
  **Requires the `entities` bundle.** A project without the entities bundle returns `403 database/tables-not-available` for entity calls. See [Bundles](/bundles).
</Note>

Entities are the central content objects in Sublay — posts, articles, products, or any item in your application that users interact with. The `entities` module gives you full control over their lifecycle, reactions, and drafts. All actions are performed on behalf of the logged-in user.

***

### createEntity

Creates a new entity, optionally as a draft or without attributing it to the logged-in user.

```typescript theme={null}
const entity = await sublay.entities.createEntity({
  foreignId: "post-42",
  title: "My First Post",
  content: "Hello world",
  keywords: ["intro", "welcome"],
  metadata: { category: "blog" },
});
```

<ParamField type="string">
  Your application's identifier for this entity. Used for idempotent lookups via `fetchEntityByForeignId`.
</ParamField>

<ParamField type="string">
  An optional secondary identifier for grouping or filtering entities.
</ParamField>

<ParamField type="string">
  The space this entity belongs to.
</ParamField>

<ParamField type="string">
  Title text for the entity.
</ParamField>

<ParamField type="string">
  Body/content text for the entity.
</ParamField>

<ParamField type="Record<string, any>[]">
  File or media attachments.
</ParamField>

<ParamField type="string[]">
  Tags or keywords used for filtering and discovery.
</ParamField>

<ParamField type="Mention[]">
  User mentions embedded in the entity.
</ParamField>

<ParamField type="object">
  Geographic coordinates `{ latitude: number; longitude: number }`.
</ParamField>

<ParamField type="Record<string, any>">
  Arbitrary public metadata.
</ParamField>

<ParamField type="boolean">
  The entity's own NSFW flag. Defaults to `false`. Effective NSFW also inherits from the entity's space. See [Entity NSFW flagging](/data-models/entity#nsfw-flagging).
</ParamField>

<ParamField type="boolean">
  When `true`, the entity is created as an unpublished draft.
</ParamField>

<ParamField type="boolean">
  When `true`, creates the entity without attributing it to the logged-in user (authorless).
</ParamField>

**Returns** — `Promise<Entity>`

***

### fetchEntity

Fetches a single entity by its Sublay ID.

```typescript theme={null}
const entity = await sublay.entities.fetchEntity({ entityId: "ent_xyz789" });
```

<ParamField type="string">
  The Sublay entity ID.
</ParamField>

<ParamField type="string">
  Comma-separated list of associations to populate.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<Entity>`

***

### fetchEntityByForeignId

Fetches an entity by your application's own identifier. Optionally creates it if not found.

```typescript theme={null}
const entity = await sublay.entities.fetchEntityByForeignId({
  foreignId: "post-42",
  createIfNotFound: true,
});
```

<ParamField type="string">
  Your application's entity identifier.
</ParamField>

<ParamField type="boolean">
  When `true`, creates a stub entity if no match is found.
</ParamField>

<ParamField type="string">
  Comma-separated list of associations to populate.
</ParamField>

**Returns** — `Promise<Entity>`

***

### fetchEntityByShortId

Fetches an entity by its short, human-readable ID (used in share URLs).

```typescript theme={null}
const entity = await sublay.entities.fetchEntityByShortId({ shortId: "abc12" });
```

<ParamField type="string">
  The entity's short ID.
</ParamField>

<ParamField type="string">
  Comma-separated list of associations to populate.
</ParamField>

**Returns** — `Promise<Entity>`

***

### fetchManyEntities

Fetches a filtered, paginated list of entities (feeds). Supports rich filtering by metadata, keywords, location, and more.

```typescript theme={null}
const { data, pagination } = await sublay.entities.fetchManyEntities({
  spaceId: "spc_abc123",
  sortBy: "hot",
  page: 1,
  limit: 20,
  metadataFilters: { includes: { category: "blog" } },
});
```

<ParamField type="string">
  Filter by source ID.
</ParamField>

<ParamField type="string">
  Filter to entities within a specific space.
</ParamField>

<ParamField type="string">
  Sort order: `"createdAt"` (chronological — honors `sortDir`), `"hot"` (trending), `"top"` (highest scored), or `"controversial"`. A `"metadata.<prop>"` value is also accepted to sort by a metadata field.
</ParamField>

<ParamField type="string">
  Sort direction: `"asc"` or `"desc"`.
</ParamField>

<ParamField type="string">
  How to interpret a metadata sort value: `"auto"`, `"numeric"`, `"text"`, `"boolean"`, or `"timestamp"`.
</ParamField>

<ParamField type="string">
  Sort by the count of a specific reaction: `"upvote"`, `"downvote"`, `"like"`, `"love"`, `"wow"`, `"sad"`, `"angry"`, or `"funny"`.
</ParamField>

<ParamField type="number">
  Page number (1-indexed).
</ParamField>

<ParamField type="number">
  Results per page.
</ParamField>

<ParamField type="string">
  Comma-separated list of associations to populate (e.g. `"user"`).
</ParamField>

<ParamField type="string">
  Time window to restrict results to: `"hour"`, `"day"`, `"week"`, `"month"`, or `"year"`.
</ParamField>

<ParamField type="string">
  The author to filter by, also used as the viewing user to resolve `followedOnly`.
</ParamField>

<ParamField type="&#x22;true&#x22; | &#x22;false&#x22;">
  When `"true"`, returns only entities from users the given `userId` follows.
</ParamField>

<ParamField type="object">
  Filter by keyword tags: `{ includes?: string[]; doesNotInclude?: string[] }`.
</ParamField>

<ParamField type="object">
  Filter by metadata fields: `{ includes?: object; includesAny?: object[]; doesNotInclude?: object; exists?: string[]; doesNotExist?: string[] }`.
</ParamField>

<ParamField type="object">
  Filter by title: `{ hasTitle?: "true" | "false"; includes?: string | string[]; doesNotInclude?: string | string[] }`.
</ParamField>

<ParamField type="object">
  Filter by content: `{ hasContent?: "true" | "false"; includes?: string | string[]; doesNotInclude?: string | string[] }`.
</ParamField>

<ParamField type="object">
  Filter by attachments: `{ hasAttachments?: "true" | "false" }`.
</ParamField>

<ParamField type="object">
  Filter within a geographic radius: `{ latitude: string; longitude: string; radius: string }`.
</ParamField>

<ParamField type="&#x22;include-all&#x22; | &#x22;exclude&#x22; | &#x22;only&#x22;">
  Filter by effective NSFW (`entity.nsfw OR its space's nsfwEffective`). `"include-all"` (default) adds no predicate; `"exclude"` drops effective-NSFW entities; `"only"` returns only them. See [Entity NSFW flagging](/data-models/entity#nsfw-flagging).
</ParamField>

<ParamField type="&#x22;exclude&#x22; | &#x22;include-outbound-blocked&#x22;">
  How to treat entities authored by users the viewer is [block-edged](/sdk/moderation/overview#blocking) with. `"exclude"` (default) hides them; `"include-outbound-blocked"` re-includes only the viewer's own outbound-blocked authors — never content from users who blocked the viewer. No effect without the `moderation` bundle.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<PaginatedResponse<Entity>>`

***

### updateEntity

Updates fields on an existing entity.

```typescript theme={null}
const entity = await sublay.entities.updateEntity({
  entityId: "ent_xyz789",
  title: "Updated Title",
  metadata: { featured: true },
});
```

<ParamField type="string">
  The Sublay entity ID to update.
</ParamField>

<ParamField type="string">
  New title.
</ParamField>

<ParamField type="string">
  New content body.
</ParamField>

<ParamField type="Record<string, any>[]">
  Updated attachments list.
</ParamField>

<ParamField type="string[]">
  Updated keywords list.
</ParamField>

<ParamField type="Mention[]">
  Updated user mentions list.
</ParamField>

<ParamField type="object">
  Updated coordinates `{ latitude: number; longitude: number }`.
</ParamField>

<ParamField type="Record<string, any>">
  Updated metadata. Merged with existing values.
</ParamField>

<ParamField type="boolean">
  Updated NSFW own-flag. A space moderator flagging another user's entity uses `spaces.setSpaceEntityNsfw` instead. See [Entity NSFW flagging](/data-models/entity#nsfw-flagging).
</ParamField>

**Returns** — `Promise<Entity>`

***

### deleteEntity

Permanently deletes an entity and its associated data.

```typescript theme={null}
await sublay.entities.deleteEntity({ entityId: "ent_xyz789" });
```

<ParamField type="string">
  The Sublay entity ID to delete.
</ParamField>

**Returns** — `Promise<void>`

***

### fetchDrafts

Fetches the logged-in user's unpublished draft entities.

```typescript theme={null}
const { data, pagination } = await sublay.entities.fetchDrafts({
  page: 1,
  limit: 20,
});
```

<ParamField type="number">
  Page number (1-indexed).
</ParamField>

<ParamField type="number">
  Results per page.
</ParamField>

<ParamField type="string">
  Filter drafts by source ID.
</ParamField>

<ParamField type="string">
  Filter drafts to a specific space.
</ParamField>

<ParamField type="string">
  Comma-separated list of associations to populate.
</ParamField>

**Returns** — `Promise<PaginatedResponse<Entity>>`

***

### publishDraft

Publishes a draft entity, making it publicly visible.

```typescript theme={null}
const entity = await sublay.entities.publishDraft({ entityId: "ent_xyz789" });
```

<ParamField type="string">
  The Sublay entity ID of the draft to publish.
</ParamField>

**Returns** — `Promise<Entity>`

***

### fetchTopComment

Fetches the highest-scored (top) comment on an entity. Returns `null` if the entity has no comments.

```typescript theme={null}
const topComment = await sublay.entities.fetchTopComment({
  entityId: "ent_xyz789",
});
```

<ParamField type="string">
  The Sublay entity ID.
</ParamField>

**Returns** — `Promise<TopComment | null>`

***

### addReaction

Adds the logged-in user's reaction to an entity and returns the updated entity.

```typescript theme={null}
const entity = await sublay.entities.addReaction({
  entityId: "ent_xyz789",
  reactionType: "like",
});
```

<ParamField type="string">
  The Sublay entity ID.
</ParamField>

<ParamField type="ReactionType">
  One of: `"upvote"`, `"downvote"`, `"like"`, `"love"`, `"wow"`, `"sad"`, `"angry"`, `"funny"`.
</ParamField>

**Returns** — `Promise<Entity>`

***

### removeReaction

Removes the logged-in user's reaction from an entity and returns the updated entity.

```typescript theme={null}
const entity = await sublay.entities.removeReaction({
  entityId: "ent_xyz789",
});
```

<ParamField type="string">
  The Sublay entity ID.
</ParamField>

**Returns** — `Promise<Entity>`

***

### fetchReactions

Fetches a paginated list of reactions on an entity, optionally filtered by reaction type.

```typescript theme={null}
const { data, pagination } = await sublay.entities.fetchReactions({
  entityId: "ent_xyz789",
  reactionType: "like",
  page: 1,
  limit: 20,
});
```

<ParamField type="string">
  The Sublay entity ID.
</ParamField>

<ParamField type="ReactionType">
  Filter to a specific reaction type.
</ParamField>

<ParamField type="number">
  Page number (1-indexed).
</ParamField>

<ParamField type="number">
  Results per page.
</ParamField>

<ParamField type="string">
  Sort direction: `"asc"` or `"desc"`.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<{ data: Reaction[]; pagination: { page: number; limit: number; total: number; totalPages: number; hasMore: boolean } }>`

***

### getUserReaction

Gets the logged-in user's reaction on an entity. Returns `null` if there is no reaction.

```typescript theme={null}
const { reactionType } = await sublay.entities.getUserReaction({
  entityId: "ent_xyz789",
});
// reactionType is "like" | "upvote" | ... | null
```

<ParamField type="string">
  The Sublay entity ID.
</ParamField>

**Returns** — `Promise<{ reactionType: ReactionType | null }>`

***

### isEntitySaved

Checks whether the logged-in user has saved an entity, and in which collections.

```typescript theme={null}
const { saved, collections } = await sublay.entities.isEntitySaved({
  entityId: "ent_xyz789",
});
```

<ParamField type="string">
  The Sublay entity ID.
</ParamField>

**Returns** — `Promise<{ saved: boolean; collections: { id: string; name: string }[] }>`


# Events
Source: https://docs.sublay.io/v7/js-sdk/events

Create and manage events, RSVPs, hosts, and invites from the browser

The `events` module covers the full events surface: creating and editing events (with inline cover/gallery image upload), the RSVP lifecycle, host and invite management, and the guest list. It maps directly to the [Events API](/api-reference/events/create-event).

Because the JS SDK authenticates as an **end user** (bearer token), you never pass an actor `userId` — the server derives who is acting from the token. The only `userId` arguments are **targets**: the host or invitee on the host/invite functions.

Requires the `events` bundle. Space-scoping needs the `spaces` bundle; images need `files-images`; notifications need `notifications`.

***

### createEvent

Creates an event. The logged-in user becomes the creator and first host. Pass `cover` and/or `gallery` to upload images inline (the request is sent as `multipart/form-data`).

```typescript theme={null}
const event = await sublay.events.createEvent({
  title: "Launch Party",
  type: "physical",
  startTime: "2026-09-01T18:00:00.000Z",
  venueName: "The Loft",
  address: "123 Main St, New York, NY",
  capacity: 100,
  cover: {
    file: coverBlob,
    options: { mode: "original-aspect", sizes: { full: 1600 }, format: "webp" },
  },
});
```

<ParamField type="string">Event title. 1–300 characters.</ParamField>
<ParamField type="string">ISO datetime when the event starts.</ParamField>

<ParamField type="&#x22;online&#x22; | &#x22;physical&#x22; | &#x22;hybrid&#x22;">
  `online` requires `url`; `physical` requires `address` or `location`; `hybrid` requires both.
</ParamField>

<ParamField type="string">Optional description.</ParamField>
<ParamField type="string">Optional ISO end datetime.</ParamField>
<ParamField type="string">Optional IANA timezone.</ParamField>
<ParamField type="string">Join/stream URL.</ParamField>
<ParamField type="string">Venue name.</ParamField>
<ParamField type="string">Street address.</ParamField>
<ParamField type="{ latitude: number; longitude: number }">Coordinates for proximity search.</ParamField>
<ParamField type="string">Scope to a space. Required when `visibility` is `"members"`.</ParamField>
<ParamField type="&#x22;public&#x22; | &#x22;members&#x22; | &#x22;invite&#x22;">Defaults to `"public"`.</ParamField>
<ParamField type="number">Max `going` RSVPs. Omit for unlimited.</ParamField>
<ParamField type="boolean">Allow `"maybe"` RSVPs. Defaults to `true`.</ParamField>
<ParamField type="boolean">Expose the named guest list. Defaults to `true`.</ParamField>
<ParamField type="string[]">Additional host user IDs (the logged-in user is auto-added).</ParamField>
<ParamField type="object">Arbitrary key-value data. Up to 1 MB.</ParamField>

<ParamField type="{ file: Blob | File; options: ImageOptions }">
  Single cover image plus its processing options. Requires the `files-images` bundle.
</ParamField>

<ParamField type="{ files: (Blob | File)[]; options: ImageOptions }">
  Gallery image set (up to 10) plus shared processing options. Requires the `files-images` bundle.
</ParamField>

**Returns** — `Promise<Event>`

***

### fetchEvent

Fetches a single event by ID. Visibility and `userRsvp` are resolved from the logged-in user's token.

```typescript theme={null}
const event = await sublay.events.fetchEvent({
  eventId: "evt_abc123",
  include: "user,space,files,userRsvp",
});
```

<ParamField type="string">The event ID.</ParamField>
<ParamField type="string">Comma-separated associations: `"user"`, `"space"`, `"files"`, `"userRsvp"`.</ParamField>

**Returns** — `Promise<Event>`

***

### fetchManyEvents

Lists events with visibility enforced, plus filtering, sorting, geo, and free-text search. The `myRsvp` filter and `userRsvp` enrichment use the logged-in user.

```typescript theme={null}
const { data, pagination } = await sublay.events.fetchManyEvents({
  timeWindow: "upcoming",
  sortBy: "startTime",
  myRsvp: "going,maybe",
  include: "userRsvp",
  page: 1,
  limit: 20,
});
```

<ParamField type="number">Page number (1-indexed). Defaults to `1`.</ParamField>
<ParamField type="number">Results per page. Capped at `100`.</ParamField>
<ParamField type="&#x22;startTime&#x22; | &#x22;going&#x22;">Sort field. Defaults to `"startTime"`.</ParamField>
<ParamField type="&#x22;asc&#x22; | &#x22;desc&#x22;">Sort direction. Defaults to `"asc"`.</ParamField>
<ParamField type="&#x22;upcoming&#x22; | &#x22;ongoing&#x22; | &#x22;past&#x22;">Derived time window.</ParamField>
<ParamField type="string">ISO datetime lower bound on `startTime`.</ParamField>
<ParamField type="string">ISO datetime upper bound on `startTime`.</ParamField>
<ParamField type="string">Restrict to one space.</ParamField>
<ParamField type="string">Only events this user hosts.</ParamField>
<ParamField type="&#x22;online&#x22; | &#x22;physical&#x22; | &#x22;hybrid&#x22;">Filter by type.</ParamField>
<ParamField type="&#x22;active&#x22; | &#x22;cancelled&#x22;">Defaults to `"active"`.</ParamField>
<ParamField type="string">Comma-separated statuses the logged-in user RSVP'd with, e.g. `"going,maybe"`.</ParamField>
<ParamField type="{ latitude: string; longitude: string; radius: string }">Proximity filter (radius in meters).</ParamField>
<ParamField type="{ hasTitle?; includes?; doesNotInclude? }">Free-text filter on `title`.</ParamField>
<ParamField type="{ hasDescription?; includes?; doesNotInclude? }">Free-text filter on `description`.</ParamField>
<ParamField type="string">Comma-separated associations.</ParamField>

**Returns** — `Promise<PaginatedResponse<Event>>`

***

### updateEvent

Edits an event's mutable fields. Host-only. `hostIds`, `status`, and `spaceId` are not editable here.

<Note>
  The JS SDK `updateEvent` accepts a flat JSON body. To curate images on update
  (replace the cover, append gallery photos, or remove images via
  `removeImageIds`), use the [React SDK's `useUpdateEvent`](/hooks/events/use-update-event)
  which supports inline multipart upload, or the underlying
  [Update Event API](/api-reference/events/update-event) directly.
</Note>

```typescript theme={null}
const event = await sublay.events.updateEvent({
  eventId: "evt_abc123",
  capacity: 150,
  description: "Now with more space!",
});
```

<ParamField type="string">The event ID.</ParamField>
<ParamField type="string">New title.</ParamField>
<ParamField type="string">New description.</ParamField>
<ParamField type="string">New ISO start datetime.</ParamField>
<ParamField type="string">New ISO end datetime.</ParamField>
<ParamField type="string">New timezone.</ParamField>
<ParamField type="&#x22;online&#x22; | &#x22;physical&#x22; | &#x22;hybrid&#x22;">New type.</ParamField>
<ParamField type="string">New URL.</ParamField>
<ParamField type="string">New venue name.</ParamField>
<ParamField type="string">New address.</ParamField>
<ParamField type="{ latitude: number; longitude: number }">New coordinates.</ParamField>
<ParamField type="&#x22;public&#x22; | &#x22;members&#x22; | &#x22;invite&#x22;">New visibility.</ParamField>
<ParamField type="number">New capacity.</ParamField>
<ParamField type="boolean">Allow `"maybe"` RSVPs.</ParamField>
<ParamField type="boolean">Expose the guest list.</ParamField>
<ParamField type="object">New metadata.</ParamField>

**Returns** — `Promise<Event>`

***

### cancelEvent

Cancels an event (sets `status: "cancelled"`). Host-only. The event stays fetchable but rejects new RSVPs.

```typescript theme={null}
const event = await sublay.events.cancelEvent({ eventId: "evt_abc123" });
```

<ParamField type="string">The event ID.</ParamField>

**Returns** — `Promise<Event>`

***

### deleteEvent

Deletes an event (soft or hard per the project's `eventDeletion` settings). Host-only.

```typescript theme={null}
await sublay.events.deleteEvent({ eventId: "evt_abc123" });
```

<ParamField type="string">The event ID.</ParamField>

**Returns** — `Promise<void>`

***

### setRsvp

Sets or changes the logged-in user's RSVP. Transitions into `going` are capacity-checked.

```typescript theme={null}
const event = await sublay.events.setRsvp({
  eventId: "evt_abc123",
  status: "going",
});
```

<ParamField type="string">The event ID.</ParamField>
<ParamField type="&#x22;going&#x22; | &#x22;maybe&#x22; | &#x22;not_going&#x22;">The RSVP response.</ParamField>

**Returns** — `Promise<Event>` (with refreshed `rsvpCounts`)

***

### withdrawRsvp

Removes the logged-in user's RSVP. Idempotent.

```typescript theme={null}
const event = await sublay.events.withdrawRsvp({ eventId: "evt_abc123" });
```

<ParamField type="string">The event ID.</ParamField>

**Returns** — `Promise<Event>`

***

### addHost

Grants a user host privileges. Host-only. The `userId` is the **target** host.

```typescript theme={null}
const event = await sublay.events.addHost({
  eventId: "evt_abc123",
  userId: "usr_cohost",
});
```

<ParamField type="string">The event ID.</ParamField>
<ParamField type="string">The user to grant host on the event.</ParamField>

**Returns** — `Promise<Event>`

***

### removeHost

Revokes a user's host privileges. Host-only. Rejected if it would leave the event with no hosts.

```typescript theme={null}
const event = await sublay.events.removeHost({
  eventId: "evt_abc123",
  userId: "usr_cohost",
});
```

<ParamField type="string">The event ID.</ParamField>
<ParamField type="string">The host to remove.</ParamField>

**Returns** — `Promise<Event>`

***

### addInvite

Invites a user to the event. Host-only. Idempotent. The `userId` is the **target** invitee.

```typescript theme={null}
const event = await sublay.events.addInvite({
  eventId: "evt_abc123",
  userId: "usr_guest",
});
```

<ParamField type="string">The event ID.</ParamField>
<ParamField type="string">The user to invite (userId only — never a foreign ID).</ParamField>

**Returns** — `Promise<Event>`

***

### removeInvite

Removes a user's invite, revoking their access and dropping their RSVP. Host-only.

```typescript theme={null}
const event = await sublay.events.removeInvite({
  eventId: "evt_abc123",
  userId: "usr_guest",
});
```

<ParamField type="string">The event ID.</ParamField>
<ParamField type="string">The invitee to remove.</ParamField>

**Returns** — `Promise<Event>`

***

### fetchInvitees

Host-only invitee (guest) list. Returns paginated [EventInvite](/data-models/event-invite) records with the invited user populated.

```typescript theme={null}
const { data, pagination } = await sublay.events.fetchInvitees({
  eventId: "evt_abc123",
  page: 1,
  limit: 20,
});
```

<ParamField type="string">The event ID.</ParamField>
<ParamField type="number">Page number (1-indexed).</ParamField>
<ParamField type="number">Results per page. Capped at `100`.</ParamField>

**Returns** — `Promise<PaginatedResponse<EventInvite>>`

***

### fetchEventRsvps

Named RSVP (guest) list. Returns paginated [EventRsvp](/data-models/event-rsvp) records with the user populated. Visible to hosts always, to any viewer when `guestListVisible` is `true`. RSVP counts themselves are public via the event's `rsvpCounts`.

```typescript theme={null}
const { data, pagination } = await sublay.events.fetchEventRsvps({
  eventId: "evt_abc123",
  status: "going,maybe",
  page: 1,
  limit: 20,
});
```

<ParamField type="string">The event ID.</ParamField>
<ParamField type="string">Comma-separated statuses to filter by, e.g. `"going,maybe"`. Omit for all.</ParamField>
<ParamField type="number">Page number (1-indexed).</ParamField>
<ParamField type="number">Results per page. Capped at `100`.</ParamField>

**Returns** — `Promise<PaginatedResponse<EventRsvp>>`


# Follows
Source: https://docs.sublay.io/v7/js-sdk/follows

Read and manage the logged-in user's own follow graph

The `follows` module acts on **your own** follow graph — the graph of the logged-in token holder. Use it to list the users you follow, list your followers, count either, and delete one of your follow relationships by its record ID.

<Tip>
  To read **another** user's followers, or to follow or unfollow someone by their
  user ID, use the [`users`](/v7/js-sdk/users) module.
</Tip>

***

### fetchFollowing

Returns a paginated list of users you follow.

```typescript theme={null}
const { data, pagination } = await sublay.follows.fetchFollowing({
  page: 1,
  limit: 20,
});
```

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Defaults to `20`.
</ParamField>

<ParamField type="string">
  Optional search term. Filters the list to users whose username or name contains this text (case-insensitive). When omitted, no filtering is applied.
</ParamField>

<ParamField type="string">
  Restricts which field `query` matches against — `username` or `name`. When omitted, `query` matches either field.
</ParamField>

**Returns** — `Promise<PaginatedResponse<FollowListItem>>`, where `FollowListItem` is `{ followId, user, followedAt }`.

***

### fetchFollowers

Returns a paginated list of your followers.

```typescript theme={null}
const { data, pagination } = await sublay.follows.fetchFollowers({
  page: 1,
  limit: 20,
});
```

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Defaults to `20`.
</ParamField>

<ParamField type="string">
  Optional search term. Filters the list to users whose username or name contains this text (case-insensitive). When omitted, no filtering is applied.
</ParamField>

<ParamField type="string">
  Restricts which field `query` matches against — `username` or `name`. When omitted, `query` matches either field.
</ParamField>

**Returns** — `Promise<PaginatedResponse<FollowListItem>>`

***

### fetchFollowingCount

Returns the number of users you follow.

```typescript theme={null}
const { count } = await sublay.follows.fetchFollowingCount();
```

**Returns** — `Promise<{ count: number }>`

***

### fetchFollowersCount

Returns the number of your followers.

```typescript theme={null}
const { count } = await sublay.follows.fetchFollowersCount();
```

**Returns** — `Promise<{ count: number }>`

***

### deleteFollow

Deletes one of your follow relationships by its follow ID.

```typescript theme={null}
await sublay.follows.deleteFollow({ followId: "flw_xyz789" });
```

<ParamField type="string">
  The ID of the follow relationship to delete.
</ParamField>

**Returns** — `Promise<void>`


# OAuth
Source: https://docs.sublay.io/v7/js-sdk/oauth

OAuth sign-in and account-linking redirect flows, and managing linked identities

The `oauth` module starts browser **redirect** flows for signing in (or signing up)
with a third-party provider, and for linking an additional provider to the current
user — plus reading and removing the user's linked identities.

<Note>
  `authorize` and `linkIdentity` return only an `authorizationUrl` — **not tokens**.
  Redirect the browser to that URL; the provider bounces back to Sublay's callback,
  which establishes the session and then redirects to your `redirectAfterAuth`. This
  is why OAuth lives in the framework-agnostic SDK but not in the server-side
  `@sublay/node` SDK.
</Note>

Supported providers (`OAuthProvider`): `"google"`, `"github"`, `"apple"`, `"facebook"`.

***

### authorize

Begins an **unauthenticated** OAuth sign-in / sign-up flow and returns the
provider's authorization URL.

```typescript theme={null}
const { authorizationUrl } = await sublay.oauth.authorize({
  provider: "google",
  redirectAfterAuth: "https://app.example.com/welcome",
});

window.location.href = authorizationUrl; // hand off to the provider
```

<ParamField type="&#x22;google&#x22; | &#x22;github&#x22; | &#x22;apple&#x22; | &#x22;facebook&#x22;">
  The OAuth provider to authenticate with.
</ParamField>

<ParamField type="string">
  Where to send the user after the flow completes. Must be one of the project's
  allowed redirect URIs.
</ParamField>

**Returns** — `Promise<{ authorizationUrl: string }>`

***

### linkIdentity

Links a new OAuth provider to the **current authenticated user** and returns the
provider's authorization URL. The user is taken from the auth token, never the body.

```typescript theme={null}
const { authorizationUrl } = await sublay.oauth.linkIdentity({
  provider: "github",
  redirectAfterAuth: "https://app.example.com/settings/connections",
});

window.location.href = authorizationUrl;
```

<ParamField type="&#x22;google&#x22; | &#x22;github&#x22; | &#x22;apple&#x22; | &#x22;facebook&#x22;">
  The OAuth provider to link.
</ParamField>

<ParamField type="string">
  Where to send the user after linking completes. Must be one of the project's
  allowed redirect URIs.
</ParamField>

**Returns** — `Promise<{ authorizationUrl: string }>`

***

### listIdentities

Lists the current user's linked OAuth identities. Takes no arguments.

```typescript theme={null}
const { identities } = await sublay.oauth.listIdentities();
```

**Returns** — `Promise<{ identities: OAuthIdentity[] }>`, where each `OAuthIdentity`
is `{ id, provider, providerAccountId, email, name, avatar, isVerified, createdAt }`.

***

### unlinkIdentity

Unlinks one of the current user's OAuth identities by ID.

```typescript theme={null}
const { success } = await sublay.oauth.unlinkIdentity({
  identityId: "oid_abc123",
});
```

<ParamField type="string">
  The linked-identity ID to remove.
</ParamField>

**Returns** — `Promise<{ success: boolean }>`

<Note>
  The server refuses to remove the last remaining identity if the user has no
  password set — otherwise they would be locked out.
</Note>


# JavaScript SDK
Source: https://docs.sublay.io/v7/js-sdk/overview

Framework-agnostic, user-authenticated SDK for Sublay — use in any browser app or JS runtime

The `@sublay/js` SDK gives you full access to the Sublay v7 API from any JavaScript environment, with **no React, Redux, or state-management dependencies**. Its only runtime dependency is `axios`. Use it in vanilla JS apps, Vue/Svelte/Solid apps, web workers, or anywhere you want the Sublay API without the React provider tree.

<Note>
  This SDK authenticates as an **end user** via a bearer token. The server derives
  who is acting from that token, so — unlike the server-side
  [`@sublay/node`](/v7/node-sdk/overview) SDK — you never pass an actor `userId`.
  For server-side, service-key access (acting on behalf of any user), use
  `@sublay/node` instead.
</Note>

## Installation

```bash theme={null}
npm install @sublay/js
```

## Initialization

`SublayClient.init` builds a client whose module namespaces are pre-bound to your project. It is async, so `await` it.

```typescript theme={null}
import { SublayClient } from "@sublay/js";

const sublay = await SublayClient.init({
  projectId: "your-project-id",
});
```

### Configuration

<ParamField type="string">
  Your Sublay project ID, found in the dashboard under **Settings → General**.
</ParamField>

<ParamField type="{ accessToken: string; refreshToken: string }">
  Tokens to hydrate the SDK on init (SDK-managed mode) — e.g. tokens your app
  persisted from a previous session, so a reload restores the session.
</ParamField>

<ParamField type="() => string | null | undefined | Promise<string | null | undefined>">
  An async hook returning the current access token. **Providing it switches the
  SDK to host-managed mode** (see below): the SDK never stores or refreshes
  tokens — it reads the current one from `getToken()` on every request.
</ParamField>

<ParamField type="(tokens: { accessToken: string; refreshToken: string } | null) => void">
  Called whenever the SDK sets, rotates, or clears tokens (SDK-managed mode only).
  Receives `null` on sign-out. Use it to persist tokens so a session survives a
  reload.
</ParamField>

## Authentication

The SDK runs in one of two auth modes, chosen by whether you pass `getToken`.

### SDK-managed (default)

The SDK keeps the `accessToken` / `refreshToken` pair in memory, attaches
`Authorization: Bearer <token>` on every request, and **auto-refreshes** on a
`403` (with a single-flight mutex so concurrent failures trigger only one
refresh). No storage is baked in — the SDK runs in any JS runtime — so persistence
is your job: listen to `onAuthChange` to save tokens, and pass them back via
`initialTokens` on the next load.

```typescript theme={null}
const sublay = await SublayClient.init({
  projectId: "your-project-id",
  initialTokens: loadTokensFromStorage() ?? undefined,
  onAuthChange: (tokens) => {
    if (tokens) saveTokensToStorage(tokens);
    else clearTokensFromStorage();
  },
});

// Sign-in stores the tokens for you and fires onAuthChange.
await sublay.auth.signIn({ email, password });
```

The `auth` module's `signIn`, `signUp`, and `verifyExternalUser` store the
returned tokens automatically; `signOut` clears them. You can also set or clear
them imperatively:

```typescript theme={null}
sublay.setTokens({ accessToken, refreshToken });
sublay.clearTokens();
```

<Warning>
  **Refresh-token rotation.** The v7 server rotates the refresh token on every
  refresh and runs reuse detection — re-sending a spent refresh token destroys the
  whole session family. In SDK-managed mode the SDK handles this for you (it
  persists the new pair through `onAuthChange`). If you call
  `auth.requestNewAccessToken` yourself, persist the **new** `refreshToken` from
  the response.
</Warning>

### Host-managed

If your app already owns the access token and its refresh lifecycle, pass a
`getToken` hook. The SDK then never stores or refreshes tokens — it reads the
current token from `getToken()` on each request, and on a `403` re-reads it once.
In this mode `setTokens`, `clearTokens`, and the `onAuthChange` callback are
no-ops.

```typescript theme={null}
const sublay = await SublayClient.init({
  projectId: "your-project-id",
  getToken: async () => myAuthStore.getAccessToken(),
});
```

An explicit `Authorization` header set on an individual request always wins over
both modes.

## Modules

Once initialized, all functionality is accessed through module namespaces on the client:

```typescript theme={null}
sublay.auth              // Authentication — sign up, sign in, tokens, passwords
sublay.users             // User profiles, and the per-user follow/connection graph
sublay.entities          // Content entities — CRUD, reactions, drafts
sublay.comments          // Comments — CRUD, reactions
sublay.collections       // Saved-content collections
sublay.follows           // The logged-in user's own follow graph
sublay.connections       // The logged-in user's own connections and requests
sublay.spaces            // Spaces — CRUD, members, moderation, rules
sublay.events            // Events — RSVPs, hosts, invites, guest list
sublay.chat              // Conversations, messages, members, reactions, read state
sublay.search            // Semantic search and streaming AI Q&A
sublay.reports           // File content reports and read the moderation queue
sublay.appNotifications  // In-app notification feed
sublay.storage           // File and image uploads, read, delete
sublay.oauth             // OAuth sign-in/link redirect flows and linked identities
```

## How this differs from `@sublay/node`

If you're coming from the server SDK, three things are different here:

* **No actor `userId`.** Functions act as the user behind the token. Params that
  named the acting user server-side are gone. A `userId` you *do* see here is
  always a real **target** or **filter** — the user you're following, a ban
  target, the author whose entities you're listing — never "who is acting".
* **Streaming AI Q\&A.** [`search.askContent`](/v7/js-sdk/search#askcontent) is an
  **async generator** over Server-Sent Events — `for await` over it to stream
  tokens — not a single awaited response.
* **Browser file uploads.** [`storage`](/v7/js-sdk/storage),
  [`chat.sendMessage`](/v7/js-sdk/chat#sendmessage), and
  [`users.updateUser`](/v7/js-sdk/users#updateuser) accept browser `File` / `Blob`
  objects and send `multipart/form-data` — there's no `Uint8Array` + `mimeType`
  path.

## Paginated responses

Most list functions return a shared `PaginatedResponse<T>` shape:

```typescript theme={null}
{
  data: T[];
  pagination: {
    page: number;
    pageSize: number;
    totalPages: number;
    totalItems: number;
    hasMore: boolean;
  };
}
```

Pass `page` and `limit` to control pagination. A few endpoints use different
shapes — notably `chat.listConversations` / `chat.listMessages` use **cursor**
pagination, the `search.search*` functions return **raw arrays**, and a handful
of reaction-list endpoints return a `{ data, pagination: { page, limit, total,
hasMore } }` shape. Each is called out on its module page.

<CardGroup>
  <Card title="Auth" icon="lock" href="/v7/js-sdk/auth">
    Sign up, sign in, token management, password reset, email verification
  </Card>

  <Card title="Users" icon="user" href="/v7/js-sdk/users">
    Fetch and update profiles, and the per-user follow/connection graph
  </Card>

  <Card title="Entities" icon="file" href="/v7/js-sdk/entities">
    Create and manage content, reactions, drafts
  </Card>

  <Card title="Comments" icon="comment" href="/v7/js-sdk/comments">
    Create and manage comments, reactions
  </Card>

  <Card title="Collections" icon="folder" href="/v7/js-sdk/collections">
    Organize the user's saved entities into collections
  </Card>

  <Card title="Follows" icon="user-plus" href="/v7/js-sdk/follows">
    The logged-in user's own follow graph and counts
  </Card>

  <Card title="Connections" icon="link" href="/v7/js-sdk/connections">
    Mutual connections, pending requests, accept/decline
  </Card>

  <Card title="Spaces" icon="layer-group" href="/v7/js-sdk/spaces">
    Space CRUD, navigation, slug management
  </Card>

  <Card title="Space Members" icon="users" href="/v7/js-sdk/spaces-members">
    Membership, roles, approvals, bans
  </Card>

  <Card title="Space Moderation" icon="shield" href="/v7/js-sdk/spaces-moderation">
    Reports, content moderation, rules
  </Card>

  <Card title="Chat" icon="message" href="/v7/js-sdk/chat">
    Conversations, messages, members, reactions, read state
  </Card>

  <Card title="Search" icon="magnifying-glass" href="/v7/js-sdk/search">
    Semantic search and streaming AI Q\&A
  </Card>

  <Card title="Reports" icon="flag" href="/v7/js-sdk/reports">
    File content reports and read the moderation queue
  </Card>

  <Card title="App Notifications" icon="bell" href="/v7/js-sdk/app-notifications">
    Read and mark the user's in-app notifications
  </Card>

  <Card title="Storage" icon="upload" href="/v7/js-sdk/storage">
    Upload, fetch, and delete files and images
  </Card>

  <Card title="OAuth" icon="key" href="/v7/js-sdk/oauth">
    OAuth sign-in/link redirect flows and linked identities
  </Card>
</CardGroup>


# Push Notifications
Source: https://docs.sublay.io/v7/js-sdk/push-notifications

Read and update the signed-in user's push notification preferences

The `push` module lets the signed-in user manage which event types they receive as a push notification. Because `@sublay/js` authenticates as an **end user**, these acting-user-scoped endpoints fit naturally — the server derives the user from the token, so there is no `userId` parameter.

<Note>
  Requires the `push` bundle installed on the project. See [Notification Preferences & Mute](/notification-preferences) for the model and the full event palette.
</Note>

Per-conversation muting lives on the [`chat`](/js-sdk/chat#muteconversation) module (`chat.muteConversation`).

***

### getNotificationPreferences

Reads the signed-in user's disabled push types. Returns an empty array (all-on) when no preferences are set.

```typescript theme={null}
const { disabledTypes } = await sublay.push.getNotificationPreferences();
```

**Returns** — `Promise<NotificationPreferences>`

```typescript theme={null}
interface NotificationPreferences {
  disabledTypes: PushEventType[]; // e.g. ["new-follow", "message"]
}
```

***

### updateNotificationPreferences

Replaces the signed-in user's disabled-types set (upsert). Send the **complete** set you want stored, not a delta; only valid event type names are accepted.

```typescript theme={null}
import { PUSH_EVENT_TYPES } from "@sublay/js";

await sublay.push.updateNotificationPreferences({
  disabledTypes: ["comment-mention", "message"],
});
```

<ParamField type="PushEventType[]">
  The complete set of event types to disable for push. Values must be from `PUSH_EVENT_TYPES` (see the [event palette](/notification-preferences#the-event-palette)); unknown names are rejected. Pass `[]` to re-enable everything.
</ParamField>

**Returns** — `Promise<NotificationPreferences>` (the stored, deduplicated set).


# Reports
Source: https://docs.sublay.io/v7/js-sdk/reports

File content reports against entities and comments, and read the moderation queue

The `reports` module lets end users file reports against entities and comments, and lets moderators read the moderated reports queue.

***

### createReport

Files a report against an entity, comment, or chat message. Repeat reports of the same target are deduplicated.

```typescript theme={null}
const { message, code } = await sublay.reports.createReport({
  targetType: "comment",
  targetId: "cmt_abc123",
  reason: "spam",
  details: "Posting the same link repeatedly.",
});
```

<ParamField type="&#x22;entity&#x22; | &#x22;comment&#x22; | &#x22;message&#x22;">
  The kind of content being reported.
</ParamField>

<ParamField type="string">
  The ID of the entity, comment, or chat message being reported.
</ParamField>

<ParamField type="ReportReason">
  One of `spam`, `inappropriateContent`, `harassment`, `misinformation`,
  `hateSpeech`, `violence`, `illegalActivity`, `selfHarm`, `other`. The API
  rejects anything else — use `other` plus `details` for the rest.
</ParamField>

<ParamField type="string">
  Additional context about the report.
</ParamField>

<Note>
  Reporting a chat message uses `targetType: "message"` with the **message id**
  as `targetId` — the conversation is resolved server-side. Reports on space
  conversations reach space moderators; reports on DMs and group chats are
  project-level and appear only in the Sublay dashboard.
</Note>

**Returns** — `Promise<{ message: string; code: "report/created" | "report/updated" | "report/already-reported" }>`

***

### fetchModeratedReports

Fetches a paginated list of moderated reports, with optional filters.

```typescript theme={null}
const { data, pagination } = await sublay.reports.fetchModeratedReports({
  status: "pending",
  sortBy: "new",
  page: 1,
  limit: 20,
});
```

<ParamField type="string">
  Restrict results to reports within a specific space.
</ParamField>

<ParamField type="&#x22;entity&#x22; | &#x22;comment&#x22; | &#x22;message&#x22;">
  Restrict results to reports of a specific target type. Message reports appear
  in this queue only for space conversations — DM and group reports are
  project-level and surface in the dashboard.
</ParamField>

<ParamField type="&#x22;pending&#x22; | &#x22;on-hold&#x22; | &#x22;escalated&#x22; | &#x22;dismissed&#x22; | &#x22;actioned&#x22;">
  Restrict results to reports with a specific moderation status.
</ParamField>

<ParamField type="&#x22;new&#x22; | &#x22;old&#x22;">
  Sort order for the returned reports.
</ParamField>

<ParamField type="number">
  The page of results to fetch.
</ParamField>

<ParamField type="number">
  The number of reports to return per page.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<PaginatedResponse<Report>>`

Each `Report` carries `id`, `spaceId`, `targetId`, `targetType`, `status`, `reporterCount`, timestamps, and optional `userReports`, `target`, and `space` associations.


# Reputation
Source: https://docs.sublay.io/v7/js-sdk/reputation

Give and list reputation grants from the browser

The `reputation` module gives reputation deliberately and reads grants back. It maps directly to the [Reputation Grants API](/api-reference/reputation-grants/create-reputation-grant).

Because the JS SDK authenticates as an **end user** (bearer token), you never pass an actor `userId` — the sender is always the user the token belongs to. Naming somebody else as the sender requires a service key, which this SDK never holds.

There is deliberately **no mint function**. Creating reputation from nothing — and destroying it — is service/master-key only and lives in [`@sublay/node`](/v7/node-sdk/reputation).

Requires the `reputation` bundle. A `chat-message` target additionally needs the `chat` bundle, and a `spaceId` needs the `spaces` bundle.

***

### createGrant

Transfers reputation from the logged-in user to another user. The amount leaves the sender's bucket and lands in the recipient's bucket **for the same space** — nothing is created, and reputation never crosses between the project-general bucket and a space bucket.

```typescript theme={null}
const grant = await sublay.reputation.createGrant({
  recipientId: "usr_def456",
  amount: 50,
  spaceId: "spc_789",
  note: "Best answer",
  targetType: "comment",
  targetId: "cmt_012",
});
```

<ParamField type="string">The user receiving the reputation. Cannot be the logged-in user.</ParamField>

<ParamField type="number">
  Whole number from `1` to `2147483647` (the signed 32-bit maximum). Never zero, negative, or fractional, and never more than the sender holds in the source bucket.
</ParamField>

<ParamField type="string | null">
  The bucket both legs move in. Omitted or `null` = the project-general bucket. Validated before anything moves: an ID naming no space is rejected with `404 reputation-grant/space-not-found`, and naming a space at all on a project without the `spaces` bundle is rejected with `403 database/tables-not-available`.
</ParamField>

<ParamField type="string | null">Free-text note. Trimmed, up to 2000 characters.</ParamField>
<ParamField type="object">Arbitrary key-value data. Up to 1 MB. Omit when unused.</ParamField>

<ParamField type="&#x22;entity&#x22; | &#x22;comment&#x22; | &#x22;chat-message&#x22;">
  What the grant is for. Supplied together with `targetId`. An annotation only — it never determines which bucket is used, and need not be authored by the recipient.
</ParamField>

<ParamField type="string">The rewarded record's ID. Supplied together with `targetType`, and must exist.</ParamField>

**Returns** — `Promise<ReputationGrant>` with `sourceType: "user"`.

Common rejections: `409 reputation-grant/insufficient-reputation` (the chosen bucket is short — nothing moved), `400 reputation-grant/self-grant`, `403 reputation-grant/user-grants-disabled` (the project has `settings.reputationGrants.allowUserInitiated` set to `false` and routes grants through its own backend instead), `404 reputation-grant/space-not-found`, `404 reputation-grant/target-not-found` (which is also the answer when a `chat-message` target sits in a conversation the sender isn't an active member of), and `404 reputation-grant/user-not-found` (which is also the non-disclosing answer when one party has blocked the other).

<Warning>
  **Grant creation is not idempotent.** A retried call creates a second grant and moves the points a second time. Guard your submit path.
</Warning>

***

### listGrants

Lists grants. Exactly one filter shape per request — by recipient, by sender, or by target. The shapes are mutually exclusive and are not AND-ed; supplying none or combining two is a `400`.

```typescript theme={null}
const { data, pagination, summary } = await sublay.reputation.listGrants({
  targetType: "entity",
  targetId: "ent_abc123",
  include: "user",
  limit: 25,
});

console.log(summary?.total, "points from", summary?.count, "people");
```

<ParamField type="string">What this user received.</ParamField>
<ParamField type="string">What this user sent.</ParamField>
<ParamField type="&#x22;entity&#x22; | &#x22;comment&#x22; | &#x22;chat-message&#x22;">Who rewarded this item. Supplied together with `targetId`.</ParamField>
<ParamField type="string">The rewarded record's ID. Supplied together with `targetType`.</ParamField>
<ParamField type="number">Page number (1-indexed). Defaults to `1`.</ParamField>
<ParamField type="number">Page size. Defaults to `20`; the maximum is `100`. A larger value is rejected with `400 reputation-grant/invalid-query` rather than clamped.</ParamField>

<ParamField type="string">
  Comma-separated associations. Only `"user"` is supported — it hydrates both the sender and the recipient.
</ParamField>

<ParamField type="object">
  Opt-in per-user space reputation on the hydrated users. `{ spaceId: "context" }` scores each user against that grant's own space. See [Reputation](/data-models/reputation#reading-space-scoped-reputation).
</ParamField>

**Returns** — `Promise<{ data: ReputationGrant[]; pagination; summary? }>`. The `summary` block (`{ total, count, viewerTotal }`) is returned **only** on the target filter shape — it's exactly what a standalone "who rewarded this" view needs, so you don't have to fetch the parent item to print the totals.

<Note>
  **Grants on chat messages are private to their conversation.** With `targetType: "chat-message"` the list is populated only when the token's user is a member of that conversation — having left it still counts; everyone else gets an empty list and a `{ total: 0, count: 0, viewerTotal: 0 }` summary rather than an error. The `recipientId` / `senderId` shapes run the same test per row, so the token holder's own "reputation I received" feed *does* carry the grants made on messages in their own conversations, while a grant on a conversation they are not in drops out of the page and out of `pagination.totalItems` together. On either shape, grants on a message moderation has removed are hidden.
</Note>

<Note>
  **Only positive grants are returned, and lists are never block-filtered.** Negative grants (an app's moderation deductions) are invisible on every public surface. And unlike entity or comment feeds, grant lists apply no block exclusion — so the amounts you render always add up to the total you render beside them.
</Note>

***

## Reading totals inline

For per-item totals, don't page through this module — ask the read that already returns the item. Entities, comments and chat messages all accept a `"grants"` token in their `include` string (combine it with others, e.g. `"files,grants"`). Each item then carries `grants: { total, count, viewerTotal }`. See [GrantSummary](/data-models/reputation-grant#grantsummary).

## See Also

* [ReputationGrant data model](/data-models/reputation-grant)
* [Create Reputation Grant API](/api-reference/reputation-grants/create-reputation-grant)
* [Fetch Many Reputation Grants API](/api-reference/reputation-grants/fetch-many-reputation-grants)
* [Node SDK reputation module](/v7/node-sdk/reputation)


# Search
Source: https://docs.sublay.io/v7/js-sdk/search

Semantic search across content, users, and spaces, plus streaming AI Q&A

The `search` module runs semantic (vector) search over your project's content and powers a streaming, RAG-style question-answering endpoint.

<Note>
  These features require semantic search to be enabled for your project. See the
  [Semantic Search & AI](/v7/semantic-search-ai) guide for setup.
</Note>

The three `search*` functions return **raw arrays** of similarity-ranked results
(not a `PaginatedResponse`); each element is `{ similarity, record }`. `askContent`
is different — it **streams** its answer (see below).

***

### searchContent

Semantic search over content — entities, comments, and chat messages.

```typescript theme={null}
const results = await sublay.search.searchContent({
  query: "getting started guide",
  sourceTypes: ["entity", "comment"],
  spaceId: "spc_abc123",
  limit: 10,
});

for (const { sourceType, similarity, record } of results) {
  console.log(sourceType, similarity, record);
}
```

<ParamField type="string">
  The search query string.
</ParamField>

<ParamField type="(&#x22;entity&#x22; | &#x22;comment&#x22; | &#x22;message&#x22;)[]">
  Which content types to search. Defaults to all.
</ParamField>

<ParamField type="string">
  Scope the search to a specific space.
</ParamField>

<ParamField type="boolean">
  Only applies with `spaceId`. When `true`, the search also covers every space nested under it — the whole subtree at any depth — not just the named space. Ignored without `spaceId`.
</ParamField>

<ParamField type="string">
  Scope the search to a specific conversation.
</ParamField>

<ParamField type="number">
  Maximum number of results to return.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<ContentSearchResult[]>`, where each element is
`{ sourceType: "entity" | "comment" | "message"; similarity: number; record: Entity | Comment | ChatMessage }`.

***

### searchUsers

Semantic search over the project's users.

```typescript theme={null}
const results = await sublay.search.searchUsers({ query: "alice", limit: 10 });
// results: [{ similarity, record: User }, ...]
```

<ParamField type="string">
  The search query string.
</ParamField>

<ParamField type="number">
  Maximum number of results to return.
</ParamField>

**Returns** — `Promise<UserSearchResult[]>`, where each element is
`{ similarity: number; record: User }`.

***

### searchSpaces

Semantic search over the project's spaces.

```typescript theme={null}
const results = await sublay.search.searchSpaces({ query: "photography", limit: 10 });
// results: [{ similarity, record: Space }, ...]
```

<ParamField type="string">
  The search query string.
</ParamField>

<ParamField type="number">
  Maximum number of results to return.
</ParamField>

**Returns** — `Promise<SpaceSearchResult[]>`, where each element is
`{ similarity: number; record: Space }`.

***

### askContent

Asks a natural-language question over your content and **streams** the answer back
as it is generated. Unlike every other SDK function, `askContent` is an **async
generator** over Server-Sent Events — you `for await` over it rather than awaiting
a single result.

<Note>
  `askContent` streams via `fetch` rather than axios, so it does **not** get the
  automatic token-refresh-on-`403` retry that other calls have. In SDK-managed
  mode, make sure a fresh access token is in place before starting a long stream.
</Note>

```typescript theme={null}
const controller = new AbortController();

const stream = sublay.search.askContent({
  query: "What are the best practices for error handling?",
  spaceId: "spc_abc123",
  signal: controller.signal,
});

let answer = "";
let sources = [];

for await (const event of stream) {
  switch (event.type) {
    case "token":
      answer += event.content; // append streamed text
      break;
    case "sources":
      sources = event.sources; // ContentSearchResult[] the answer draws on
      break;
    case "done":
      break; // the stream is complete
    case "error":
      console.error(event.error);
      break;
  }
}

// Cancel early with controller.abort() — or simply `break` out of the loop.
```

<ParamField type="string">
  The natural-language question to answer.
</ParamField>

<ParamField type="(&#x22;entity&#x22; | &#x22;comment&#x22; | &#x22;message&#x22;)[]">
  Which content types to draw from. Defaults to all.
</ParamField>

<ParamField type="string">
  Scope the answer to content within a specific space.
</ParamField>

<ParamField type="boolean">
  Only applies with `spaceId`. When `true`, the context lookup also covers every space nested under it — the whole subtree at any depth — so you can ask across a community and all of its channels at once. Ignored without `spaceId`.
</ParamField>

<ParamField type="string">
  Scope the answer to a specific conversation.
</ParamField>

<ParamField type="number">
  Maximum number of sources to draw from.
</ParamField>

<SpaceReputationParams />

<ParamField type="AbortSignal">
  Aborts the in-flight stream (e.g. when the user navigates away). You can also
  stop consuming by `break`ing out of the `for await` loop.
</ParamField>

**Returns** — `AsyncGenerator<AskContentEvent, void, unknown>`. Each yielded event
is one of:

```typescript theme={null}
type AskContentEvent =
  | { type: "token"; content: string }              // a chunk of answer text
  | { type: "sources"; sources: ContentSearchResult[] } // the cited sources
  | { type: "done" }                                 // stream finished
  | { type: "error"; error: string };                // a stream/server error
```

Completion and errors are signalled **in-band** as `done` / `error` events — the
generator itself returns `void` and does not throw on a server-reported error.

***

### matchUsers

Matches people by **activity-derived interest facets**, in `passive` mode (against the current user's own facets) or `directed` mode (against a free-text topic). See the [Interest Matching](/v7/interest-matching) guide for setup and the model.

<Note>
  Requires a paid plan, the `ai-search` and `interest-matching` bundles, and `interestMatching.enabled` on the project. `passive` requires an identified user; `directed` requires one too.
</Note>

```typescript theme={null}
const { results } = await sublay.search.matchUsers({
  mode: "passive",
  limit: 10,
});

// results: [{ user, score, matchedFacets: [{ similarity, candidateFacet, askerFacet?, sampleContent? }] }]
```

<ParamField type="string">
  `"passive"` or `"directed"`.
</ParamField>

<ParamField type="string">
  The topic to match against. Required in `directed` mode; rejected in `passive` mode.
</ParamField>

<ParamField type="number">
  Maximum number of matched users. Maximum `50`.
</ParamField>

<ParamField type="string">
  Restrict candidates to users active in this space.
</ParamField>

<ParamField type="boolean">
  With `spaceId`, also include users active in the space's subtree.
</ParamField>

<ParamField type="boolean">
  Request illustrative sample content per matched facet. Only honored when the project has `interestMatching.exposeSampleContent` on; otherwise returns `403 match/sample-content-disabled`.
</ParamField>

<ParamField type="boolean">
  Exclude the current user from results.
</ParamField>

**Returns** — `Promise<{ results: UserMatchResult[] }>`. Unlike `searchContent`/`searchUsers`/`searchSpaces` (which return bare arrays), match returns the `{ results }` envelope, ordered by descending `score`.


# Spaces
Source: https://docs.sublay.io/v7/js-sdk/spaces

Create, fetch, update, and navigate spaces from the browser

Spaces are containers — communities for organizing content. The `spaces` module covers the space lifecycle and navigation: creating spaces, looking them up by ID, slug, or short ID, updating settings, and traversing parent-child hierarchies.

For membership management see [Space Members](/v7/js-sdk/spaces-members), and for moderation and rules see [Space Moderation](/v7/js-sdk/spaces-moderation).

***

### createSpace

Creates a new space.

```typescript theme={null}
const space = await sublay.spaces.createSpace({
  name: "Photography",
  slug: "photography",
  description: "A community for photographers",
  postingPermission: "members",
});
```

<ParamField type="string">
  Display name for the space.
</ParamField>

<ParamField type="string">
  URL-friendly identifier. Must be unique within the project. Generated from `name` if omitted.
</ParamField>

<ParamField type="string">
  Short description of the space.
</ParamField>

<ParamField type="string">
  Who can read content: `"anyone"` or `"members"`.
</ParamField>

<ParamField type="string">
  Who can post content: `"anyone"`, `"members"`, or `"admins"`.
</ParamField>

<ParamField type="string">
  Listing/discoverability: `"public"` (default), `"unlisted"`, or `"private"`. Independent of `readingPermission` (which governs content). `"unlisted"` hides the space from discovery and search but keeps it reachable by direct link; `"private"` currently behaves like `"unlisted"`.
</ParamField>

<ParamField type="boolean">
  When `true`, join requests must be manually approved.
</ParamField>

<ParamField type="boolean">
  The space's own NSFW flag. Defaults to `false`. A space created under an NSFW parent is effectively NSFW regardless of this value. See [Space NSFW flagging](/data-models/space#nsfw-flagging).
</ParamField>

<ParamField type="string">
  Makes this space a child of the specified parent space.
</ParamField>

<ParamField type="Record<string, any>">
  Arbitrary metadata attached to the space.
</ParamField>

**Returns** — `Promise<Space>`

***

### fetchSpace

Fetches a single space, including detailed information, by its ID.

```typescript theme={null}
const space = await sublay.spaces.fetchSpace({ spaceId: "spc_abc123" });
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

**Returns** — `Promise<SpaceDetailed>`

***

### fetchManySpaces

Fetches a paginated, filterable list of spaces.

```typescript theme={null}
const { data, pagination } = await sublay.spaces.fetchManySpaces({
  sortBy: "members",
  parentSpaceId: "null",
  limit: 20,
});
```

<ParamField type="number">
  The page number to fetch.
</ParamField>

<ParamField type="number">
  The number of spaces to return per page.
</ParamField>

<ParamField type="string">
  Sort order: `"alphabetical"`, `"newest"`, or `"members"`.
</ParamField>

<ParamField type="string">
  Filter by matching slug.
</ParamField>

<ParamField type="string">
  Filter by matching name.
</ParamField>

<ParamField type="string">
  Filter by matching description.
</ParamField>

<ParamField type="string">
  Filter by matching across slug, name, and description.
</ParamField>

<ParamField type="string">
  Pass `"true"` to return only spaces you belong to.
</ParamField>

<ParamField type="string">
  Filter by parent space. Pass `"null"` for top-level spaces.
</ParamField>

<ParamField type="&#x22;include-all&#x22; | &#x22;exclude&#x22; | &#x22;only&#x22;">
  Filter by each space's `nsfwEffective` (own flag OR any ancestor). `"include-all"` (default) adds no predicate; `"exclude"` drops effective-NSFW spaces; `"only"` returns only them. `"only"` may return an NSFW child whose safe parent is omitted. See [Space NSFW flagging](/data-models/space#nsfw-flagging).
</ParamField>

<ParamField type="string">
  Comma-separated related resources to include in the response.
</ParamField>

**Returns** — `Promise<PaginatedResponse<Space>>`

***

### fetchSpaceBySlug

Fetches a detailed space by its slug.

```typescript theme={null}
const space = await sublay.spaces.fetchSpaceBySlug({ slug: "photography" });
```

<ParamField type="string">
  The space slug.
</ParamField>

**Returns** — `Promise<SpaceDetailed>`

***

### fetchSpaceByShortId

Fetches a detailed space by its short ID.

```typescript theme={null}
const space = await sublay.spaces.fetchSpaceByShortId({ shortId: "a1b2c3" });
```

<ParamField type="string">
  The space short ID.
</ParamField>

**Returns** — `Promise<SpaceDetailed>`

***

### fetchUserSpaces

Fetches the spaces the logged-in user belongs to.

```typescript theme={null}
const userSpaces = await sublay.spaces.fetchUserSpaces({
  role: "admin,moderator",
  sortBy: "newest",
});
```

<ParamField type="number">
  The page number to fetch.
</ParamField>

<ParamField type="number">
  The number of spaces to return per page.
</ParamField>

<ParamField type="string">
  Sort order: `"alphabetical"`, `"newest"`, or `"members"`.
</ParamField>

<ParamField type="string">
  Comma-separated related resources to include in the response.
</ParamField>

<ParamField type="string">
  Filter by role. A single role or a comma-separated list, e.g. `"admin,moderator"`.
</ParamField>

<ParamField type="string">
  Membership status to list: `"active"` (default), `"pending"`, or `"banned"`. Use `"pending"` to find join requests still awaiting approval.
</ParamField>

<ParamField type="string">
  Pass `"true"` or `"false"`.
</ParamField>

**Returns** — `Promise<UserSpacesResponse>`

***

### fetchMutualSpaces

Fetches the spaces the logged-in user shares with another user — the spaces both are active members of.

```typescript theme={null}
const mutual = await sublay.spaces.fetchMutualSpaces({
  userId: "usr_other",
  page: 1,
  limit: 20,
});
```

<ParamField type="string">
  The other user's ID. Mutual spaces are computed between this user and the logged-in user.
</ParamField>

<ParamField type="number">
  The page number to fetch.
</ParamField>

<ParamField type="number">
  The number of spaces to return per page. Max `100`.
</ParamField>

<ParamField type="string">
  Comma-separated related resources to include (e.g. `"files"`).
</ParamField>

**Returns** — `Promise<PaginatedResponse<Space>>`

***

### updateSpace

Updates a space's settings.

```typescript theme={null}
const space = await sublay.spaces.updateSpace({
  spaceId: "spc_abc123",
  description: "An updated description",
  postingPermission: "admins",
});
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

<ParamField type="string">
  New display name for the space.
</ParamField>

<ParamField type="string">
  New URL-friendly identifier.
</ParamField>

<ParamField type="string">
  New description of the space.
</ParamField>

<ParamField type="string">
  Who can read content: `"anyone"` or `"members"`.
</ParamField>

<ParamField type="string">
  Who can post content: `"anyone"`, `"members"`, or `"admins"`.
</ParamField>

<ParamField type="string">
  Updated visibility: `"public"`, `"unlisted"`, or `"private"`. Controls listing/discoverability, independent of `readingPermission`.
</ParamField>

<ParamField type="boolean">
  Updated NSFW own-flag. Toggling it recomputes this space's effective NSFW and cascades it top-down to every descendant space (and, live, to their entities). See [Space NSFW flagging](/data-models/space#nsfw-flagging).
</ParamField>

<ParamField type="Record<string, any>">
  Arbitrary metadata attached to the space.
</ParamField>

**Returns** — `Promise<Space>`

***

### deleteSpace

Deletes a space.

```typescript theme={null}
const result = await sublay.spaces.deleteSpace({ spaceId: "spc_abc123" });
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

**Returns** — `Promise<DeleteSpaceResponse>`

***

### checkSlugAvailability

Checks whether a space slug is available.

```typescript theme={null}
const { available } = await sublay.spaces.checkSlugAvailability({
  slug: "photography",
});
```

<ParamField type="string">
  The slug to check.
</ParamField>

**Returns** — `Promise<{ available: boolean }>`

***

### fetchChildSpaces

Fetches a paginated list of child spaces under a parent.

```typescript theme={null}
const { data, pagination } = await sublay.spaces.fetchChildSpaces({
  spaceId: "spc_abc123",
  sortBy: "alphabetical",
});
```

<ParamField type="string">
  The parent space ID.
</ParamField>

<ParamField type="number">
  The page number to fetch.
</ParamField>

<ParamField type="number">
  The number of spaces to return per page.
</ParamField>

<ParamField type="string">
  Sort order: `"alphabetical"`, `"newest"`, or `"members"`.
</ParamField>

<ParamField type="string">
  Comma-separated related resources to include in the response.
</ParamField>

**Returns** — `Promise<PaginatedResponse<Space>>`

***

### fetchSpaceBreadcrumb

Fetches the ancestor breadcrumb chain for a space.

```typescript theme={null}
const breadcrumb = await sublay.spaces.fetchSpaceBreadcrumb({
  spaceId: "spc_abc123",
});
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

**Returns** — `Promise<SpaceBreadcrumb>`

***

### getSpaceConversation

Gets the chat conversation object associated with a space.

```typescript theme={null}
const conversation = await sublay.spaces.getSpaceConversation({
  spaceId: "spc_abc123",
});
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

**Returns** — `Promise<Conversation>`

<Note>
  Space chat messages are sent and read via the [chat](/v7/js-sdk/chat) module.
</Note>


# Space Members
Source: https://docs.sublay.io/v7/js-sdk/spaces-members

Join and leave spaces, and manage roles, approvals, and bans

The space membership functions let the logged-in user join and leave spaces, and let admins and moderators manage a space's membership — roles, pending approvals, and bans.

***

### joinSpace

Joins a space as the logged-in user, or requests to join if the space requires approval.

```typescript theme={null}
const result = await sublay.spaces.joinSpace({ spaceId: "spc_abc123" });
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

**Returns** — `Promise<JoinSpaceResponse>`

***

### leaveSpace

Leaves a space as the logged-in user.

```typescript theme={null}
const result = await sublay.spaces.leaveSpace({ spaceId: "spc_abc123" });
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

**Returns** — `Promise<LeaveSpaceResponse>`

***

### checkMyMembership

Checks the logged-in user's membership status in a space.

```typescript theme={null}
const membership = await sublay.spaces.checkMyMembership({
  spaceId: "spc_abc123",
});
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

**Returns** — `Promise<CheckMyMembershipResponse>`

***

### fetchSpaceMembers

Fetches a paginated list of a space's members, filterable by role and status.

```typescript theme={null}
const members = await sublay.spaces.fetchSpaceMembers({
  spaceId: "spc_abc123",
  role: "member",
  status: "active",
});
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

<ParamField type="number">
  The page number to fetch.
</ParamField>

<ParamField type="number">
  The number of members to return per page.
</ParamField>

<ParamField type="string">
  Filter by role: `"admin"`, `"moderator"`, or `"member"`.
</ParamField>

<ParamField type="string">
  Filter by status: `"pending"`, `"active"`, `"banned"`, or `"rejected"`.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<SpaceMembersResponse>`

***

### fetchSpaceTeam

Fetches the team (admins and moderators) of a space.

```typescript theme={null}
const team = await sublay.spaces.fetchSpaceTeam({ spaceId: "spc_abc123" });
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<SpaceTeamResponse>`

***

### updateMemberRole

Updates a member's role within a space.

```typescript theme={null}
const result = await sublay.spaces.updateMemberRole({
  spaceId: "spc_abc123",
  memberId: "mbr_xyz789",
  role: "moderator",
});
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

<ParamField type="string">
  The membership ID of the member to update.
</ParamField>

<ParamField type="string">
  The new role: `"admin"`, `"moderator"`, or `"member"`.
</ParamField>

**Returns** — `Promise<UpdateMemberRoleResponse>`

***

### approveMembership

Approves a pending membership request.

```typescript theme={null}
const result = await sublay.spaces.approveMembership({
  spaceId: "spc_abc123",
  memberId: "mbr_xyz789",
});
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

<ParamField type="string">
  The membership ID of the pending member.
</ParamField>

**Returns** — `Promise<ApproveMemberResponse>`

***

### declineMembership

Declines a pending membership request.

```typescript theme={null}
const result = await sublay.spaces.declineMembership({
  spaceId: "spc_abc123",
  memberId: "mbr_xyz789",
});
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

<ParamField type="string">
  The membership ID of the pending member.
</ParamField>

**Returns** — `Promise<DeclineMemberResponse>`

***

### banMember

Bans a member from a space.

```typescript theme={null}
const result = await sublay.spaces.banMember({
  spaceId: "spc_abc123",
  memberId: "mbr_xyz789",
});
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

<ParamField type="string">
  The membership ID of the member to ban.
</ParamField>

**Returns** — `Promise<{ message: string; membership: { id: string; status: "banned" } }>`

***

### unbanMember

Unbans a previously banned member.

```typescript theme={null}
const result = await sublay.spaces.unbanMember({
  spaceId: "spc_abc123",
  memberId: "mbr_xyz789",
});
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

<ParamField type="string">
  The membership ID of the member to unban.
</ParamField>

**Returns** — `Promise<{ message: string; membership: { id: string; status: "active" } }>`


# Space Moderation
Source: https://docs.sublay.io/v7/js-sdk/spaces-moderation

Resolve reports, moderate content, and manage rules

The space moderation functions let admins and moderators resolve reports, moderate entities, comments, and chat messages, and manage community rules within a space.

***

### handleEntityReport

Resolves a reported entity by applying one or more actions.

```typescript theme={null}
const result = await sublay.spaces.handleEntityReport({
  spaceId: "spc_abc123",
  reportId: "rep_111",
  entityId: "ent_222",
  actions: ["remove-entity", "ban-user"],
  userId: "usr_333",
});
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

<ParamField type="string">
  The ID of the report to resolve.
</ParamField>

<ParamField type="string">
  The ID of the reported entity.
</ParamField>

<ParamField type="string[]">
  One or more actions to apply: `"remove-entity"`, `"ban-user"`, and/or `"dismiss"`.
</ParamField>

<ParamField type="string">
  A summary of the resolution.
</ParamField>

<ParamField type="string">
  The reason for the resolution.
</ParamField>

<ParamField type="string">
  The user to ban. Required when `actions` includes `"ban-user"`.
</ParamField>

<Note>
  `userId` here is the ban **target** — the user being banned — not the actor performing the moderation.
</Note>

**Returns** — `Promise<{ message: string; code: string }>`

***

### handleCommentReport

Resolves a reported comment by applying one or more actions.

```typescript theme={null}
const result = await sublay.spaces.handleCommentReport({
  spaceId: "spc_abc123",
  reportId: "rep_111",
  commentId: "cmt_222",
  actions: ["dismiss"],
});
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

<ParamField type="string">
  The ID of the report to resolve.
</ParamField>

<ParamField type="string">
  The ID of the reported comment.
</ParamField>

<ParamField type="string[]">
  One or more actions to apply: `"remove-comment"`, `"ban-user"`, and/or `"dismiss"`.
</ParamField>

<ParamField type="string">
  A summary of the resolution.
</ParamField>

<ParamField type="string">
  The reason for the resolution.
</ParamField>

<ParamField type="string">
  The user to ban. Required when `actions` includes `"ban-user"`.
</ParamField>

<Note>
  `userId` here is the ban **target** — the user being banned — not the actor performing the moderation.
</Note>

**Returns** — `Promise<{ message: string; code: string }>`

***

### handleSpaceChatReport

Resolves a reported space chat message by applying one or more actions.

```typescript theme={null}
const result = await sublay.spaces.handleSpaceChatReport({
  spaceId: "spc_abc123",
  reportId: "rep_111",
  actions: ["remove-message"],
  messageId: "msg_222",
});
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

<ParamField type="string">
  The ID of the report to resolve.
</ParamField>

<ParamField type="string[]">
  One or more actions to apply: `"remove-message"`, `"ban-user"`, and/or `"dismiss"`.
</ParamField>

<ParamField type="string">
  A summary of the resolution.
</ParamField>

<ParamField type="string">
  The reason for the resolution.
</ParamField>

<ParamField type="string">
  The user to ban. Required when `actions` includes `"ban-user"`.
</ParamField>

<ParamField type="string">
  The message to remove. Required when `actions` includes `"remove-message"`.
</ParamField>

<Note>
  `userId` here is the ban **target** — the user being banned — not the actor performing the moderation.
</Note>

**Returns** — `Promise<{ message: string; code: string }>`

***

### moderateSpaceEntity

Approves or removes an entity in a space.

```typescript theme={null}
const result = await sublay.spaces.moderateSpaceEntity({
  spaceId: "spc_abc123",
  entityId: "ent_222",
  action: "remove",
  reason: "Off-topic",
});
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

<ParamField type="string">
  The ID of the entity to moderate.
</ParamField>

<ParamField type="string">
  The action to take: `"approve"` or `"remove"`.
</ParamField>

<ParamField type="string">
  The reason for the moderation action.
</ParamField>

**Returns** — `Promise<{ message: string; moderationStatus: "approved" | "removed" }>`

***

### setSpaceEntityNsfw

Sets the NSFW own-flag on an entity within a space — including other users' entities. Separate from `moderateSpaceEntity`: it **labels** the entity (`nsfw`), it does not approve/remove it. Requires the acting user to be an admin or moderator of the space.

```typescript theme={null}
const result = await sublay.spaces.setSpaceEntityNsfw({
  spaceId: "spc_abc123",
  entityId: "ent_222",
  nsfw: true,
});
```

<ParamField type="string">
  The Sublay space ID containing the entity.
</ParamField>

<ParamField type="string">
  The ID of the entity to flag or unflag.
</ParamField>

<ParamField type="boolean">
  The NSFW own-flag to set on the entity.
</ParamField>

**Returns** — `Promise<{ message: string; nsfw: boolean }>`

***

### moderateSpaceComment

Approves or removes a comment in a space.

```typescript theme={null}
const result = await sublay.spaces.moderateSpaceComment({
  spaceId: "spc_abc123",
  commentId: "cmt_222",
  action: "approve",
});
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

<ParamField type="string">
  The ID of the comment to moderate.
</ParamField>

<ParamField type="string">
  The action to take: `"approve"` or `"remove"`.
</ParamField>

<ParamField type="string">
  The reason for the moderation action.
</ParamField>

**Returns** — `Promise<{ message: string; moderationStatus: "approved" | "removed" }>`

***

### moderateSpaceChatMessage

Applies a moderation status to a space chat message.

```typescript theme={null}
const result = await sublay.spaces.moderateSpaceChatMessage({
  spaceId: "spc_abc123",
  messageId: "msg_222",
  moderationStatus: "removed",
  moderationReason: "Spam",
});
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

<ParamField type="string">
  The ID of the chat message to moderate.
</ParamField>

<ParamField type="string">
  The moderation status to apply: `"removed"`.
</ParamField>

<ParamField type="string">
  The reason for the moderation action.
</ParamField>

**Returns** — `Promise<{ message: string; moderationStatus: string }>`

***

### fetchManyRules

Fetches all rules for a space.

```typescript theme={null}
const rules = await sublay.spaces.fetchManyRules({ spaceId: "spc_abc123" });
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

**Returns** — `Promise<FetchManyRulesResponse>`

***

### fetchRule

Fetches a single rule by ID.

```typescript theme={null}
const rule = await sublay.spaces.fetchRule({
  spaceId: "spc_abc123",
  ruleId: "rul_222",
});
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

<ParamField type="string">
  The ID of the rule to fetch.
</ParamField>

**Returns** — `Promise<Rule>`

***

### createRule

Creates a rule in a space.

```typescript theme={null}
const rule = await sublay.spaces.createRule({
  spaceId: "spc_abc123",
  title: "Be respectful",
  description: "No harassment or hate speech.",
});
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

<ParamField type="string">
  The rule title.
</ParamField>

<ParamField type="string">
  The rule description.
</ParamField>

**Returns** — `Promise<Rule>`

***

### updateRule

Updates a rule's title and/or description.

```typescript theme={null}
const rule = await sublay.spaces.updateRule({
  spaceId: "spc_abc123",
  ruleId: "rul_222",
  title: "Be kind",
});
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

<ParamField type="string">
  The ID of the rule to update.
</ParamField>

<ParamField type="string">
  The new rule title.
</ParamField>

<ParamField type="string">
  The new rule description.
</ParamField>

**Returns** — `Promise<Rule>`

***

### deleteRule

Deletes a rule.

```typescript theme={null}
const result = await sublay.spaces.deleteRule({
  spaceId: "spc_abc123",
  ruleId: "rul_222",
});
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

<ParamField type="string">
  The ID of the rule to delete.
</ParamField>

**Returns** — `Promise<DeleteRuleResponse>`

***

### reorderRules

Reorders a space's rules.

```typescript theme={null}
const rules = await sublay.spaces.reorderRules({
  spaceId: "spc_abc123",
  ruleIds: ["rul_333", "rul_111", "rul_222"],
});
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

<ParamField type="string[]">
  The rule IDs in the new order.
</ParamField>

**Returns** — `Promise<Rule[]>`


# Storage
Source: https://docs.sublay.io/v7/js-sdk/storage

Upload, retrieve, and delete files and images from the browser

The `storage` module uploads files and images to managed cloud storage and returns
proxy URLs, plus reads and deletes existing files. Uploads are sent as
`multipart/form-data` — pass a browser **`File`** (e.g. from an `<input type="file">`)
or a **`Blob`**. There is no `Uint8Array` + `mimeType` path; the browser supplies
the content type.

<Note>
  Uploads are attributed to the logged-in user automatically (from the token) —
  there is no `userId` param. A user may delete files they own; reads are
  project-scoped.
</Note>

***

### uploadFile

Uploads a generic file (PDF, video, document, …) without server-side processing.

```typescript theme={null}
const input = document.querySelector('input[type="file"]');
const file = input.files[0];

const uploaded = await sublay.storage.uploadFile({
  file,
  filename: "report.pdf",
  pathParts: ["documents", "reports"],
  entityId: "ent_xyz789",
});
// uploaded.publicPath → proxy URL
```

<ParamField type="Blob | File">
  The file to upload, as a browser `File` or `Blob`.
</ParamField>

<ParamField type="string[]">
  Storage path segments. The file is stored under the joined path with a UUID
  sub-folder appended, e.g. `["documents", "reports"]` →
  `documents/reports/<uuid>/<filename>`.
</ParamField>

<ParamField type="string">
  Filename for the multipart part. Defaults to the `File.name`, or `"upload"`.
</ParamField>

<ParamField type="number">
  Display order when a record has multiple attachments.
</ParamField>

<ParamField type="object">
  Custom key-value data stored alongside the file record.
</ParamField>

<ParamField type="string">
  Associates the file with an entity for cascade deletion. Only one of
  `entityId` / `commentId` / `spaceId` may be set.
</ParamField>

<ParamField type="string">
  Associates the file with a comment for cascade deletion.
</ParamField>

<ParamField type="string">
  Associates the file with a space.
</ParamField>

**Returns** — `Promise<UploadFileResponse>`:

```typescript theme={null}
{
  fileId: string;
  type: string;
  relativePath: string;
  publicPath: string; // proxy URL
  size: number;
  mimeType: string;
  createdAt: string;
}
```

***

### uploadImage

Uploads an image, processes it server-side, and stores the original plus all
requested variants. The `imageOptions` object is a discriminated union on `mode` —
the other fields depend on the mode you pick.

```typescript theme={null}
const input = document.querySelector('input[type="file"]');
const file = input.files[0];

const uploaded = await sublay.storage.uploadImage({
  file,
  filename: "avatar.png",
  imageOptions: {
    mode: "exact-dimensions",
    dimensions: {
      thumbnail: { width: 64, height: 64 },
      card: { width: 400, height: 300 },
    },
    format: "webp",
    quality: 85,
  },
  pathParts: ["avatars"],
});
// uploaded.variants → { thumbnail: {...}, card: {...} }
```

<ParamField type="Blob | File">
  The image to upload, as a browser `File` or `Blob`. Must be a format the server
  can process.
</ParamField>

<ParamField type="ImageOptions">
  Image-processing configuration — a discriminated union on `mode`. The supported
  modes and their required fields:

  | `mode`                      | Required fields                                    | Notes                                                        |
  | --------------------------- | -------------------------------------------------- | ------------------------------------------------------------ |
  | `exact-dimensions`          | `dimensions` (`{ [variant]: { width, height } }`)  | Fixed-size crops.                                            |
  | `aspect-ratio-width-based`  | `aspectRatio`, `widths` (`{ [variant]: number }`)  | Heights computed from the ratio.                             |
  | `aspect-ratio-height-based` | `aspectRatio`, `heights` (`{ [variant]: number }`) | Widths computed from the ratio.                              |
  | `original-aspect`           | `sizes` (`{ [variant]: number }`)                  | Preserves source ratio; `fit` limited to `inside`/`outside`. |
  | `multi-aspect-ratio`        | `aspectRatios` (`{ width, height }[]`), `sizes`    | 1–10 aspect ratios.                                          |

  All modes also accept optional `quality` (1–100), `format` (`webp` | `jpeg` |
  `png` | `original`), `stripExif` (boolean), and `fit` (`cover` | `contain` |
  `inside` | `outside`). Dimension/size values are 50–10000.
</ParamField>

<ParamField type="string">
  Filename for the multipart part. Defaults to the `File.name`, or `"upload"`.
</ParamField>

<ParamField type="string[]">
  Storage path segments. Defaults to `["images", "<fileId>"]`.
</ParamField>

<ParamField type="string">
  Associates the image with an entity. Only one of `entityId` / `commentId` /
  `spaceId` / `eventId` may be set.
</ParamField>

<ParamField type="string">
  Associates the image with a comment.
</ParamField>

<ParamField type="string">
  Associates the image with a space.
</ParamField>

<ParamField type="string">
  Associates the image with an event. Most apps attach event images inline via
  `sublay.events.createEvent`/`updateEvent` (`cover` / `gallery`); use this only
  to attach an image to an existing event out-of-band.
</ParamField>

**Returns** — `Promise<UploadImageResponse>`:

```typescript theme={null}
{
  fileId: string;
  type: "image";
  originalPath: string;
  originalSize: number;
  originalWidth: number;
  originalHeight: number;
  variants: Record<string, UploadedImageVariant>; // { path, width, height, size, format, publicPath }
  format: string;
  quality: number;
  createdAt: string;
}
```

***

### getFile

Fetches a file's metadata and proxy URLs by ID. For images, an `image` extension
(variants, processing details) is included. Reads are project-scoped.

```typescript theme={null}
const file = await sublay.storage.getFile({ fileId: "fil_abc123" });
```

<ParamField type="string">
  The ID of the file to retrieve.
</ParamField>

**Returns** — `Promise<GetFileResponse>` — a flat projection carrying `fileId`,
`type`, `originalPath`, `originalSize`, `originalMimeType`, `position`, `metadata`,
`createdAt`/`updatedAt`, the optional association ids (`userId`, `entityId`,
`commentId`, `spaceId`), and — for images — an `image` object with `variants`,
`processingStatus`, `format`, `quality`, and `exifStripped`.

***

### deleteFile

Deletes a file record and removes all associated storage objects (for images,
every generated variant too).

```typescript theme={null}
await sublay.storage.deleteFile({ fileId: "fil_abc123" });
```

<ParamField type="string">
  The ID of the file to delete.
</ParamField>

**Returns** — `Promise<void>`

<Note>
  The call only succeeds when the logged-in user owns the file; otherwise it
  returns `403`.
</Note>


# Tables
Source: https://docs.sublay.io/v7/js-sdk/tables

Read and write custom-table rows from any browser or JS runtime with the client.table(name) accessor

Custom tables let your project provision its own database tables alongside Sublay's built-in models. The `client.table(name)` accessor gives you row-level access to a custom table from any JavaScript environment. For an overview of the feature — the `custom_` naming model, managed columns, and soft-delete — see [Custom Tables](/v7/custom-tables).

<Note>
  The JS SDK is **row-only**. Creating tables and columns (DDL) is service-key
  work, and the browser SDK holds no service key — so there is no
  table-management surface here. Manage schema from the
  [`@sublay/node`](/v7/node-sdk/tables-management) SDK or the
  [dashboard](/v7/custom-tables#the-dashboard-data-editor).
</Note>

`client.table(name)` is a **callable accessor** — it closes over the table name and returns the row-operation object. Type the rows with a generic:

```typescript theme={null}
interface EventRow {
  id: string;
  name: string;
  capacity: number;
  createdAt: string;
}

const events = sublay.table<EventRow>("Events");
const { data } = await events.find({ limit: 20 });
```

The `name` you pass is the **logical** table name — Sublay applies the `custom_` prefix for you. As with the rest of the JS SDK, these operations act as the **user behind the token** — you never pass an actor `userId`.

***

### find

Fetches a filtered, sorted, paginated page of rows. Returns the shared `{ data, pagination }` envelope.

```typescript theme={null}
const { data, pagination } = await sublay.table<EventRow>("Events").find({
  page: 1,
  limit: 20,
  sortBy: "createdAt",
  sortDir: "desc",
  filters: [{ column: "capacity", operator: "gte", value: 100 }],
});
```

<ParamField type="number">
  Page number (1-indexed).
</ParamField>

<ParamField type="number">
  Rows per page.
</ParamField>

<ParamField type="string">
  Column to sort by. Defaults to `createdAt` (descending) on a table with
  timestamps, otherwise `id`.
</ParamField>

<ParamField type="&#x22;asc&#x22; | &#x22;desc&#x22;">
  Sort direction.
</ParamField>

<ParamField type="DbFilter[]">
  An array of `{ column, operator, value }` clauses, **AND-combined**. Operators:
  `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `contains`, `like`, `isNull`.
</ParamField>

<ParamField type="boolean">
  On a paranoid table, set `true` to include soft-deleted rows. Defaults to
  `false`.
</ParamField>

**Returns** — `Promise<PaginatedResponse<T>>`

***

### findOne

Fetches a single row by its `id`. Throws (axios `404`) if the row doesn't exist or has been soft-deleted.

```typescript theme={null}
const event = await sublay.table<EventRow>("Events").findOne("a1b2c3d4-...");
```

<ParamField type="string">
  The row's `id` (UUID).
</ParamField>

**Returns** — `Promise<T>`

***

### create

Inserts a single row. Managed columns (`id`, `createdAt`, `updatedAt`, `deletedAt`) are rejected from the body.

```typescript theme={null}
const event = await sublay.table<EventRow>("Events").create({
  name: "Launch Summit",
  capacity: 250,
});
```

<ParamField type="Partial<T>">
  The column values for the new row.
</ParamField>

**Returns** — `Promise<T>`

***

### bulkCreate

Inserts many rows in one call. Capped at **100 rows** per request.

```typescript theme={null}
const rows = await sublay.table<EventRow>("Events").bulkCreate([
  { name: "Workshop A", capacity: 40 },
  { name: "Workshop B", capacity: 40 },
]);
```

<ParamField type="Partial<T>[]">
  The rows to insert (max 100).
</ParamField>

**Returns** — `Promise<T[]>`

***

### update

Updates a row by `id`. On a table with timestamps, `updatedAt` is bumped automatically. Managed columns are rejected from the body.

```typescript theme={null}
const event = await sublay.table<EventRow>("Events").update("a1b2c3d4-...", {
  capacity: 300,
});
```

<ParamField type="string">
  The row's `id`.
</ParamField>

<ParamField type="Partial<T>">
  The column values to change.
</ParamField>

**Returns** — `Promise<T>`

***

### delete

Deletes a row by `id`. On a **paranoid** table this is a soft delete; pass `force: true` to hard-delete. On a non-paranoid table it is always a hard delete.

```typescript theme={null}
await sublay.table("Events").delete("a1b2c3d4-...");
await sublay.table("Events").delete("a1b2c3d4-...", { force: true });
```

<ParamField type="string">
  The row's `id`.
</ParamField>

<ParamField type="boolean">
  When `true`, hard-deletes a paranoid row instead of soft-deleting it.
</ParamField>

**Returns** — `Promise<{ deleted: boolean; soft: boolean }>`

***

### bulkDelete

Deletes many rows by an id list and/or a `filters` predicate (at least one required). Paranoid-aware and capped.

```typescript theme={null}
await sublay.table("Events").bulkDelete({
  filters: [{ column: "capacity", operator: "lt", value: 10 }],
});
```

<ParamField type="string[]">
  Rows to delete by `id`.
</ParamField>

<ParamField type="DbFilter[]">
  A predicate selecting rows to delete.
</ParamField>

<ParamField type="boolean">
  When `true`, hard-deletes matched paranoid rows.
</ParamField>

**Returns** — `Promise<{ deletedCount: number; soft: boolean }>`

***

### restore

Clears `deletedAt` on a soft-deleted row. Only valid on a **paranoid** table.

```typescript theme={null}
const event = await sublay.table<EventRow>("Events").restore("a1b2c3d4-...");
```

<ParamField type="string">
  The soft-deleted row's `id`.
</ParamField>

**Returns** — `Promise<T>`

***

<Warning>
  Row CRUD on the `/db` surface is currently **open** — identity is captured but
  not enforced. See the [security note](/v7/custom-tables#security-open-row-crud)
  on the overview page before storing access-controlled data in custom tables.
</Warning>


# Users
Source: https://docs.sublay.io/v7/js-sdk/users

Fetch and update user profiles, check usernames, and act on a specific user's follow and connection graph

The `users` module reads and updates user profiles and lets the logged-in user act on the social graph of an **arbitrary target user**, addressed by `userId`.

In the follow and connection helpers below, `userId` is always the **target** — the user being followed, the other party in a connection, or the user whose followers you're reading. The **actor** is always the logged-in token holder. To act on your own graph (your own followers, the users you follow, your own connections and pending requests), use the [`follows`](/v7/js-sdk/follows) and [`connections`](/v7/js-sdk/connections) modules instead.

***

### fetchUserById

Fetches a user by their internal Sublay user ID.

```typescript theme={null}
const user = await sublay.users.fetchUserById({ userId: "usr_abc123" });
```

<ParamField type="string">
  The Sublay user ID.
</ParamField>

<ParamField type="string">
  Comma-separated list of associations to populate.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<User>`

***

### fetchUserByForeignId

Fetches a user by your application's own user identifier.

```typescript theme={null}
const user = await sublay.users.fetchUserByForeignId({
  foreignId: "external-user-42",
});
```

<ParamField type="string">
  Your application's user identifier.
</ParamField>

<ParamField type="string">
  Comma-separated list of associations to populate.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<User>`

***

### fetchUserByUsername

Fetches a user by their username.

```typescript theme={null}
const user = await sublay.users.fetchUserByUsername({ username: "alice" });
```

<ParamField type="string">
  The user's unique username.
</ParamField>

<ParamField type="string">
  Comma-separated list of associations to populate.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<User>`

***

### fetchUserSuggestions

Returns users whose name or username matches a partial query string. Useful for mention autocomplete.

```typescript theme={null}
const users = await sublay.users.fetchUserSuggestions({ query: "ali" });
```

<ParamField type="string">
  Partial name or username to search for.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<User[]>`

***

### checkUsernameAvailability

Checks whether a username is available.

```typescript theme={null}
const { available } = await sublay.users.checkUsernameAvailability({
  username: "alice",
});
```

<ParamField type="string">
  The username to check.
</ParamField>

**Returns** — `Promise<{ available: boolean }>`

***

### updateUser

Updates a user's profile, optionally uploading a new avatar and/or banner image. A user token may only update its own profile.

```typescript theme={null}
const updatedUser = await sublay.users.updateUser({
  userId: "usr_abc123",
  name: "Alice Updated",
  bio: "New bio",
  location: { latitude: 37.7749, longitude: -122.4194 },
});
```

<ParamField type="string">
  The Sublay user ID to update. A user token may only update itself.
</ParamField>

<ParamField type="string">
  New display name.
</ParamField>

<ParamField type="string">
  New username. Must be available.
</ParamField>

<ParamField type="string">
  New avatar URL.
</ParamField>

<ParamField type="string">
  New bio text.
</ParamField>

<ParamField type="string">
  ISO 8601 date string for the user's birthdate.
</ParamField>

<ParamField type="object">
  Geographic location `{ latitude: number; longitude: number }`, or `null` to clear it.
</ParamField>

<ParamField type="object">
  Updated public metadata (`Record<string, any>`).
</ParamField>

<ParamField type="object">
  Updated secure metadata (`Record<string, any>`, not exposed in public responses).
</ParamField>

<ParamField type="object">
  A new avatar image to upload: `{ file: Blob | File; options: ImageOptions }`.
</ParamField>

<ParamField type="object">
  A new banner image to upload: `{ file: Blob | File; options: ImageOptions }`.
</ParamField>

<Note>
  When `avatarFile` or `bannerFile` is supplied the request is sent as
  `multipart/form-data` carrying the browser `File`/`Blob`. The image `options`
  (an `ImageOptions` object whose `mode` selects a processing strategy) are sent
  alongside the file.
</Note>

```typescript theme={null}
// Uploading an avatar from an <input type="file"> element
const input = document.querySelector<HTMLInputElement>("#avatar-input");
const file = input.files[0];

const updatedUser = await sublay.users.updateUser({
  userId: "usr_abc123",
  avatarFile: {
    file,
    options: {
      mode: "exact-dimensions",
      dimensions: { default: { width: 256, height: 256 } },
      format: "webp",
    },
  },
});
```

**Returns** — `Promise<AuthUser>`

***

### fetchFollowersByUserId

Returns a paginated list of users following the target user.

```typescript theme={null}
const { data, pagination } = await sublay.users.fetchFollowersByUserId({
  userId: "usr_abc123",
  page: 1,
  limit: 20,
});
```

<ParamField type="string">
  The Sublay user ID whose followers to fetch.
</ParamField>

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Defaults to `20`.
</ParamField>

<ParamField type="string">
  Optional search term. Filters the list to users whose username or name contains this text (case-insensitive). When omitted, no filtering is applied.
</ParamField>

<ParamField type="string">
  Restricts which field `query` matches against — `username` or `name`. When omitted, `query` matches either field.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<PaginatedResponse<FollowListItem>>`

***

### fetchFollowersCountByUserId

Returns the total number of followers for the target user.

```typescript theme={null}
const { count } = await sublay.users.fetchFollowersCountByUserId({
  userId: "usr_abc123",
});
```

<ParamField type="string">
  The Sublay user ID.
</ParamField>

**Returns** — `Promise<{ count: number }>`

***

### fetchFollowingByUserId

Returns a paginated list of users that the target user is following.

```typescript theme={null}
const { data, pagination } = await sublay.users.fetchFollowingByUserId({
  userId: "usr_abc123",
  page: 1,
  limit: 20,
});
```

<ParamField type="string">
  The Sublay user ID whose following list to fetch.
</ParamField>

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Defaults to `20`.
</ParamField>

<ParamField type="string">
  Optional search term. Filters the list to users whose username or name contains this text (case-insensitive). When omitted, no filtering is applied.
</ParamField>

<ParamField type="string">
  Restricts which field `query` matches against — `username` or `name`. When omitted, `query` matches either field.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<PaginatedResponse<FollowListItem>>`

***

### fetchFollowingCountByUserId

Returns the number of users the target user is following.

```typescript theme={null}
const { count } = await sublay.users.fetchFollowingCountByUserId({
  userId: "usr_abc123",
});
```

<ParamField type="string">
  The Sublay user ID.
</ParamField>

**Returns** — `Promise<{ count: number }>`

***

### fetchConnectionsByUserId

Returns a paginated list of the target user's established connections.

```typescript theme={null}
const { data, pagination } = await sublay.users.fetchConnectionsByUserId({
  userId: "usr_abc123",
  page: 1,
  limit: 20,
});
```

<ParamField type="string">
  The Sublay user ID whose connections to fetch.
</ParamField>

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Defaults to `20`.
</ParamField>

<ParamField type="string">
  Optional search term. Filters the list to connections whose connected user's username or name contains this text (case-insensitive). When omitted, no filtering is applied.
</ParamField>

<ParamField type="string">
  Restricts which field `query` matches against — `username` or `name`. When omitted, `query` matches either field.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<PaginatedResponse<EstablishedConnection>>`

***

### fetchConnectionsCountByUserId

Returns the number of established connections for the target user.

```typescript theme={null}
const { count } = await sublay.users.fetchConnectionsCountByUserId({
  userId: "usr_abc123",
});
```

<ParamField type="string">
  The Sublay user ID.
</ParamField>

**Returns** — `Promise<{ count: number }>`

***

### createFollow

The logged-in user follows the target user.

```typescript theme={null}
const follow = await sublay.users.createFollow({ userId: "usr_target" });
```

<ParamField type="string">
  The user being followed (the target).
</ParamField>

**Returns** — `Promise<Follow>`

***

### deleteFollow

The logged-in user unfollows the target user.

```typescript theme={null}
await sublay.users.deleteFollow({ userId: "usr_target" });
```

<ParamField type="string">
  The user being unfollowed (the target).
</ParamField>

<Note>
  This unfollows by the target's `userId`. To delete one of your own follow
  relationships by its record ID, use
  [`follows.deleteFollow`](/v7/js-sdk/follows), which takes a `followId`.
</Note>

**Returns** — `Promise<void>`

***

### fetchFollowStatus

Returns whether the logged-in user follows the target user.

```typescript theme={null}
const { isFollowing, followId } = await sublay.users.fetchFollowStatus({
  userId: "usr_target",
});
```

<ParamField type="string">
  The user whose follow relationship is being checked (the target).
</ParamField>

**Returns** — `Promise<{ isFollowing: boolean; followId?: string; followedAt?: string }>`

***

### requestConnection

Sends a connection request from the logged-in user to the target user.

```typescript theme={null}
const connection = await sublay.users.requestConnection({
  userId: "usr_target",
  message: "Let's connect!",
});
```

<ParamField type="string">
  The user the connection is requested with (the target).
</ParamField>

<ParamField type="string">
  Optional message to include with the request.
</ParamField>

**Returns** — `Promise<ConnectionRequestResponse>` — the created/pending connection.

***

### fetchConnectionStatus

Returns the connection status between the logged-in user and the target user.

```typescript theme={null}
const status = await sublay.users.fetchConnectionStatus({
  userId: "usr_target",
});
```

<ParamField type="string">
  The other user in the connection (the target).
</ParamField>

**Returns** — `Promise<ConnectionStatusResponse>`

***

### removeConnectionByUserId

Removes the connection with the target user — withdrawing a sent request, declining a received one, or disconnecting an established connection, depending on the current state.

```typescript theme={null}
const result = await sublay.users.removeConnectionByUserId({
  userId: "usr_target",
});
```

<ParamField type="string">
  The other user in the connection (the target).
</ParamField>

**Returns** — `Promise<RemoveConnectionByUserIdResponse>`

## Blocking

User-to-user **blocking** is part of the trust & safety [moderation bundle](/sdk/moderation/overview#blocking). These functions require that bundle; a project without it returns `403 database/tables-not-available`. The blocker is the **token holder** — there is no `actingUserId`.

<Note>
  Blocking severs interaction between two users across every Sublay surface and is **non-disclosing** — the blocked user is never notified. See [Moderation — Blocking](/sdk/moderation/overview#blocking) for the full enforcement behavior.
</Note>

***

### createBlock

Blocks a user. On a new block, existing follows and connections between the pair are torn down (both directions). Idempotent — re-blocking succeeds. Self-block is rejected server-side.

```typescript theme={null}
const block = await sublay.users.createBlock({ userId: "usr_target" });
```

<ParamField type="string">
  The user being blocked (the target). The blocker is the token holder.
</ParamField>

**Returns** — `Promise<BlockResponse>` — `{ id, blockerId, blockedId, createdAt }`.

***

### deleteBlock

Unblocks a user. Idempotent; restores nothing.

```typescript theme={null}
await sublay.users.deleteBlock({ userId: "usr_target" });
```

<ParamField type="string">
  The user being unblocked (the target).
</ParamField>

**Returns** — `Promise<void>`

***

### fetchBlockStatus

Checks whether the token holder blocks the target user. **Outbound-only** — it never reveals whether the target has blocked the token holder.

```typescript theme={null}
const { blocked, blockId } = await sublay.users.fetchBlockStatus({
  userId: "usr_target",
});
```

<ParamField type="string">
  The user whose block relationship is being checked (the target).
</ParamField>

**Returns** — `Promise<BlockStatusResponse>` — `{ blocked: boolean; blockId?: string; createdAt?: string }`.

***

### fetchBlockedUsers

Returns a paginated list of the users the token holder has blocked (their outbound blocks), each row carrying a public profile summary. This block list is **private** to the blocker.

```typescript theme={null}
const { data, pagination } = await sublay.users.fetchBlockedUsers({
  page: 1,
  limit: 20,
});
```

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Defaults to `20`. Max `100`.
</ParamField>

**Returns** — `Promise<PaginatedResponse<BlockedUserListItem>>`, where each `BlockedUserListItem` is `{ id, blockedUser, createdAt }`.


# Workspaces
Source: https://docs.sublay.io/v7/js-sdk/workspaces

Framework-agnostic client surface for workspaces — the full 21-endpoint bundle

The `workspaces` module in `@sublay/js` is the **client-side** surface of the [Workspaces bundle](/data-models/workspace). It covers **all 21 endpoints** — workspace CRUD, membership management, the full invitation lifecycle, and the authority read — so a members-management UI needs no server-side code.

The actor is always derived from the **bearer token**. **No actor field is ever sent from the client** — the props types simply do not carry one, and a call that hand-writes `actingUserId` past the types to name a user other than the token's own is rejected by the server with a `403`. Acting on behalf of a *different* user is the [node SDK](/node-sdk/workspaces) service-key capability, and it is the only difference in reach between the two SDKs for this bundle — **not** a restriction on which operations a client may perform.

<Note>
  **Requires the `workspaces` bundle.** See [Bundles](/bundles) to install it.
</Note>

Every call is authorized against the **signed-in user's own standing** on the workspace: owner-only, capability-gated, rank-bounded, visibility-gated, or self-service. Each function below states which. (`fetchWorkspace` is the one read that also works without a token, returning the workspace when visibility permits.) Read the concepts first: [capabilities vs permissions](/data-models/workspace-member#the-two-arrays-capabilities-vs-permissions), [rank](/data-models/workspace-member#rank-semantics), [reach & ownership](/data-models/workspace#reach-and-the-wall-door-rule), and the [identity-matched, no-token invite model](/data-models/workspace-invitation#acceptance-model).

<Tip>
  A `userId` that names a **target** is fully available on the client — the invitee `userId` on `createWorkspaceInvite`, and the `targetUserId` path param on the member functions. Only the *actor* field, `actingUserId`, is node-SDK-only.
</Tip>

<Warning>
  **Pass only the documented fields — the props object is sent whole.**
  `createWorkspace` and its siblings hand your object straight to the request body, and every workspaces endpoint refuses a top-level field it does not declare: `{ "error": "Unrecognized key: \"slug\"", "code": "workspace/invalid-body" }` (plural `Unrecognized keys: "a", "b"` for two or more, `workspace/invalid-query` for a query-string offender).

  ```typescript theme={null}
  // ❌ 400 — `slug` and `plan` are not fields of this endpoint.
  await sublay.workspaces.createWorkspace({ ...orgTemplate });

  // ✅ Name the fields; your own data belongs in `metadata`.
  await sublay.workspaces.createWorkspace({
    name: orgTemplate.name,
    metadata: { slug: orgTemplate.slug, plan: orgTemplate.plan },
  });
  ```

  Strictness governs **top-level** keys only, so nothing inside `metadata` is inspected. See [Shapes the server rejects](/sdk/workspaces/overview#shapes-the-server-rejects).
</Warning>

***

## Workspace lifecycle

### createWorkspace

The bearer-token user becomes the owner. Root creation requires a **verified email**; child creation requires `create-sub-workspace` on the parent.

```typescript theme={null}
const workspace = await sublay.workspaces.createWorkspace({
  name: "Acme Inc",
  parentWorkspaceId: null,   // omit/null → root; set → child
});
```

<ParamField type="string">Display name (1–100 characters).</ParamField>
<ParamField type="object">Opaque developer data.</ParamField>
<ParamField type="string">Parent for child creation.</ParamField>

### fetchWorkspace

```typescript theme={null}
const workspace = await sublay.workspaces.fetchWorkspace({
  workspaceId: "ws_abc",
  include: "memberCount",
});
```

<ParamField type="string" />

<ParamField type="string">Comma-separated include flags. `memberCount` adds the workspace's direct member count; omit it and the field is absent. An unrecognized flag value is ignored.</ParamField>

### fetchManyWorkspaces

Lists the bearer-token user's direct-membership + owned workspaces (paginated). Self-service.

```typescript theme={null}
const { data, pagination } = await sublay.workspaces.fetchManyWorkspaces({
  page: 1,
  limit: 20,
  include: "memberCount", // each row gains a `memberCount`
});
```

<ParamField type="number" />

<ParamField type="number" />

<ParamField type="string">Comma-separated include flags, sent as a query param. `memberCount` adds a `memberCount` to **every row** — the workspace's direct member count, resolved in one grouped query over the returned page rather than one request per row. Omit it and the field is absent from each row.</ParamField>

### updateWorkspace

Edits `name`/`metadata`. Requires the **`edit-workspace`** capability (or ownership). Does **not** flip the inherit flag.

```typescript theme={null}
const workspace = await sublay.workspaces.updateWorkspace({
  workspaceId: "ws_abc",
  name: "Acme Corp",
});
```

<ParamField type="string" />

<ParamField type="string" />

<ParamField type="object" />

### updateWorkspaceInheritFlag

Flips whether authority held on an ancestor reaches into this node. **Owner-only** in both directions (own owner or an ancestor owner) — not a capability. Blocked with `403 workspace/inherit-enforced` when the project enforces its default.

```typescript theme={null}
const workspace = await sublay.workspaces.updateWorkspaceInheritFlag({
  workspaceId: "ws_child",
  inheritsFromParent: true,
});
```

<ParamField type="string" />

<ParamField type="boolean">`true` = open/door, `false` = sealed/wall.</ParamField>

### deleteWorkspace

**Owner-only** (own owner or an ancestor owner). Cascades the whole subtree transactionally and fires `workspace.deleted` per deleted workspace — and **no** `workspace.member.removed` events for the memberships it tears down (see [Webhooks](/sdk/workspaces/webhooks)).

```typescript theme={null}
const { message } = await sublay.workspaces.deleteWorkspace({ workspaceId: "ws_abc" });
```

<ParamField type="string" />

### transferWorkspaceOwnership

**Owner-only** (own owner or an ancestor owner). `newOwnerId` addresses the **target** — any verified user in the tenant, who need not already be a member.

```typescript theme={null}
const workspace = await sublay.workspaces.transferWorkspaceOwnership({
  workspaceId: "ws_abc",
  newOwnerId: "usr_new",
  previousOwnerDisposition: "demote",
  previousOwnerRank: 0,
});
```

<ParamField type="string" />

<ParamField type="string">The new owner (any verified user).</ParamField>
<ParamField type="string">`"demote"` or `"remove"`. Defaults to `"remove"` when omitted.</ParamField>
<ParamField type="number">On demote, the ex-owner's rank (absolute only). Defaults to **one rung below the acting user's anchor** — `0` for the usual apex actor, or one below their own row if they sit in this workspace's ladder.</ParamField>

<ParamField type="string[]" />

***

## Membership

### fetchWorkspaceMembers

The [unified roster](/api-reference/workspaces/members/list-members) — `WorkspaceRosterResponse`, or `WorkspaceRosterCountsResponse` with `countOnly`. Never paginated. Requires roster visibility — **any relation** to the workspace.

<Warning>
  **`rank`, `relativeRank`, `capabilities` and `permissions` are fenced on other users' entries.** They are omitted (absent — not `null`) unless the bearer-token user holds one of the four people-operating capabilities (`invite`, `remove-member`, `edit-member-access`, `edit-member-profile`) or is the `owner` / an `ancestor-owner` — evaluated **per node**, so with `include=descendants` each `descendant-member` reason is judged on its own workspace and authority over the parent does not unfence a **sealed** child. The caller's own entry always carries them. Who is on the roster — `user`, reason `type`s, `title`, `metadata`, `viaWorkspaceId` — stays visible to any relation, so read the fenced fields defensively (`reason.capabilities ?? []`).

  A `member` reason carries **both rank coordinates**: absolute `rank` and `relativeRank`, the member's position as an offset from you (`1` = one rung below you, `-3` = three above). `descendant-member` reasons carry `rank` only. `relativeRank` is fenced *with* `rank` because it is `rank` minus a number you already know.
</Warning>

```typescript theme={null}
const roster = await sublay.workspaces.fetchWorkspaceMembers({ workspaceId: "ws_abc" });
const counts = await sublay.workspaces.fetchWorkspaceMembers({ workspaceId: "ws_abc", countOnly: true });
```

<ParamField type="string" />

<ParamField type="string">`ancestorOwners`, `reachHolders`, `descendants`.</ParamField>

<ParamField type="boolean" />

### fetchWorkspaceMemberStanding

One user's resolved standing, addressed by user id — works for any relation, including users with no direct member row. Requires roster visibility — **any relation** to the workspace.

<Warning>
  **`capabilities`, `permissions`, `rank` and `relativeRank` are fenced.** They are omitted unless the bearer-token user holds one of the four people-operating capabilities (`invite`, `remove-member`, `edit-member-access`, `edit-member-profile`), is the `owner` / an `ancestor-owner`, or is reading **their own** standing — all judged on **this** workspace, a per-node verdict that says nothing about any other node. `user`, `reasons`, `title` and `metadata` are always returned. `relativeRank` is the target's rank as an offset from you (negative = senior to you), `null` exactly when `rank` is.
</Warning>

```typescript theme={null}
const standing = await sublay.workspaces.fetchWorkspaceMemberStanding({
  workspaceId: "ws_abc",
  targetUserId: "usr_pat",
});
```

<ParamField type="string" />

<ParamField type="string">The **target** whose standing to read (path param, not an actor).</ParamField>

Returns `WorkspaceMemberStanding`. On its `user` field **only `id` is guaranteed** (`WorkspaceStandingUser`): the server returns the full user record when the user row still exists and falls back to `{ id }` alone when it does not — a deleted user with a lingering membership row is a reachable case. Read the rest defensively (`standing.user.username ?? "Deleted user"`).

`reasons` is an array of structured `{ type, viaWorkspaceId? }` entries — the same shape a roster entry's `reasons` carries — so you learn which ancestor grants an `ancestor-owner` / `reach-holder` standing.

### updateWorkspaceMember

Two capability tiers: **powerful** fields (`capabilities`, `permissions`, and rank as either `rank` or `relativeRank`) need `edit-member-access` plus the rank rule and [no-escalation](/data-models/workspace-member#no-privilege-escalation); **cosmetic** fields (`title`, `metadata`) need only `edit-member-profile`, and a member editing their own `title` needs nothing.

Rank moves in **either coordinate**, never both; omitting both means **rank unchanged**. See [choosing a rank](/sdk/workspaces/overview#choosing-a-rank).

```typescript theme={null}
const member = await sublay.workspaces.updateWorkspaceMember({
  workspaceId: "ws_abc",
  targetUserId: "usr_pat",
  capabilities: ["view", "invite"],
  rank: 3,
});
```

<ParamField type="string" />

<ParamField type="string">The member being edited (path param, not an actor).</ParamField>

<ParamField type="string[]" />

<ParamField type="string[]" />

<ParamField type="number">Absolute. Mutually exclusive with `relativeRank`; omit both to leave rank unchanged.</ParamField>
<ParamField type="number">An offset from you — `1` = one rung below me. Must be `>= 1`. Resolved to an absolute rank at write time and frozen. No default.</ParamField>

<ParamField type="string" />

<ParamField type="object" />

### removeWorkspaceMember

Removes a member from **this node only**. Requires `remove-member` and is **rank-bounded**; sole-owner protected.

```typescript theme={null}
await sublay.workspaces.removeWorkspaceMember({
  workspaceId: "ws_abc",
  targetUserId: "usr_pat",
});
```

<ParamField type="string" />

<ParamField type="string">The member to remove (path param, not an actor).</ParamField>

### removeWorkspaceMemberFromSubtree

Removes the target's direct memberships on this workspace and every descendant you can reach. Requires `remove-member`, rank-bounded **per node**. Blocks with `409 workspace/owns-descendants` (and reports them) if the target owns any descendant workspace.

```typescript theme={null}
const { removedCount, removed, skippedCount, skipped } =
  await sublay.workspaces.removeWorkspaceMemberFromSubtree({
    workspaceId: "ws_root",
    targetUserId: "usr_pat",
  });

if (skippedCount > 0) {
  // NOT fully offboarded — memberships survived in branches you cannot reach.
  // `id`/`name` are null where you have no standing on that workspace.
  console.warn("Still a member of", skippedCount, "workspace(s):", skipped);
}
```

<Warning>
  **A non-owner's sweep may be partial.** It stops at sealed sub-workspaces (`inheritsFromParent = false`), so the target can keep a membership you never saw. Always check `skippedCount` / `skipped` — `removedCount` alone does **not** mean the user is gone from the subtree. An owner or ancestor owner always gets `skippedCount: 0`. Where you have no standing on a skipped workspace its `id` and `name` come back `null`: you learn *that* a membership survived, not *where* — escalate to an owner of that branch.
</Warning>

<ParamField type="string" />

<ParamField type="string">The user to offboard (path param, not an actor).</ParamField>

### leaveWorkspace

**Self-service** — removes the bearer-token user's *own* direct membership on this node only. No capability required. An owner cannot leave (`409 workspace/sole-owner`); transfer or delete first.

```typescript theme={null}
await sublay.workspaces.leaveWorkspace({ workspaceId: "ws_abc" });
```

<ParamField type="string" />

***

## Invitations

### createWorkspaceInvite

Requires the **`invite`** capability (or ownership); the inviter is the bearer-token user. Address the invitee by **exactly one** of `email`, `userId`, or `username` — here `userId`/`username` address the invite **target**, not an actor. Email matching against existing accounts is **case-insensitive**.

<Warning>
  **The project must have `workspaces.inviteAcceptUrl` configured**, or this call fails with `409 workspace/missing-invite-accept-url` and persists nothing — the invitation email would have nowhere to deep-link. It has no default. Applies even when the invitee already has an account. See [Project settings](/sdk/workspaces/overview#project-settings).
</Warning>

```typescript theme={null}
const invite = await sublay.workspaces.createWorkspaceInvite({
  workspaceId: "ws_abc",
  email: "pat@example.com",
  capabilities: ["view"],
  // One rung below me. Omitting both rank fields means exactly this.
  relativeRank: 1,
});
```

<ParamField type="string" />

<ParamField type="string">One of `email`/`userId`/`username`.</ParamField>
<ParamField type="string">Invite **target** user id.</ParamField>
<ParamField type="string">Invite **target** username.</ParamField>

<ParamField type="string[]" />

<ParamField type="string[]" />

<ParamField type="number">Absolute. **Not required** — mutually exclusive with `relativeRank`, and omitting both applies the `relativeRank: 1` default.</ParamField>
<ParamField type="number">An offset from the inviter — `1` = one rung below me. Must be `>= 1`. Anchored on your own rank if you hold a member row here, apex otherwise. A **snapshot**: resolved to an absolute rank at invite time and frozen. Relying on the default puts everyone on the same rung, and equals cannot manage each other. Sharper case: an inviter with **no member row here** (the `owner`, an ancestor owner, a reach holder) anchors at apex, so their default mints **rank 0** — name a coordinate if that is not what you want. See [choosing a rank](/sdk/workspaces/overview#choosing-a-rank).</ParamField>

<ParamField type="string" />

### fetchWorkspaceInvites

The workspace's **outbox** — the live pending invites *it has issued* (`status='pending' AND expiresAt > now`). Requires the `invite` capability (or ownership). Always returned in full; deliberately unpaginated.

```typescript theme={null}
const { data } = await sublay.workspaces.fetchWorkspaceInvites({ workspaceId: "ws_abc" });
```

<ParamField type="string" />

<Warning>
  Do not confuse this with [`fetchMyWorkspaceInvites`](#fetchmyworkspaceinvites). `fetchWorkspaceInvites` is scoped to **one workspace** and lists what **it sent out** (needs `invite`). `fetchMyWorkspaceInvites` is scoped to **the caller**, spans every workspace, and lists what was **addressed to them** (needs nothing).
</Warning>

### revokeWorkspaceInvite

Marks a pending invitation `revoked`. Requires the `invite` capability (or ownership). Note the verb-suffixed **`POST .../revoke`** route — this is not a `DELETE`.

```typescript theme={null}
await sublay.workspaces.revokeWorkspaceInvite({ workspaceId: "ws_abc", inviteId: "inv_1" });
```

<ParamField type="string" />

<ParamField type="string" />

### resendWorkspaceInvite

Refreshes a pending invite — resets a 14-day expiry and resends the email — valid even on one already past `expiresAt`. Terminal invites → `409`. Requires the `invite` capability (or ownership). Also a verb-suffixed **`POST .../resend`**. Returns the refreshed `WorkspaceInvitation`, carrying the new `expiresAt`. Like `createWorkspaceInvite`, it requires [`workspaces.inviteAcceptUrl`](/sdk/workspaces/overview#project-settings) on the project → otherwise `409 workspace/missing-invite-accept-url` with `expiresAt` untouched.

```typescript theme={null}
const invite = await sublay.workspaces.resendWorkspaceInvite({ workspaceId: "ws_abc", inviteId: "inv_1" });
```

<ParamField type="string" />

<ParamField type="string" />

### fetchMyWorkspaceInvites

The caller's **inbox** — the bearer-token user's live pending invites across every workspace, matched by `userId` from the token. **Self-service**, and surfacing is not verification-gated — a user sees pending invites right after signup (which nudges them to verify). The verified check applies when they act on one (accept **or** decline).

```typescript theme={null}
const { data } = await sublay.workspaces.fetchMyWorkspaceInvites();
```

### acceptWorkspaceInvite

**Self-service** — identity-matched to the bearer-token user, and a **verified email is required**. The `inviteId` is non-secret. Idempotent when already a member/owner.

```typescript theme={null}
const { workspaceId } = await sublay.workspaces.acceptWorkspaceInvite({ inviteId: "inv_1" });
```

<ParamField type="string" />

### declineWorkspaceInvite

**Self-service** — identity-matched, and a **verified email is required** (the same gate as accept, so an unverified squatter on someone else's address cannot burn their invite). Returns `403 workspace/email-not-verified` otherwise.

```typescript theme={null}
await sublay.workspaces.declineWorkspaceInvite({ inviteId: "inv_1" });
```

<ParamField type="string" />

***

## Authority-as-a-service

### fetchWorkspaceAuthority

The bearer-token user's resolved standing on a workspace — `{ reasons, capabilities, permissions, rank }`. **Self-service**, so nothing is fenced here. (No `relativeRank`: it is an offset from you, and here the subject *is* you, so `rank` is the coordinate this read reports.) Drive your UI off this rather than guessing: a permission check is a one-line `.includes()` on the result.

`reasons` is an array of structured `{ type, viaWorkspaceId? }` entries (`viaWorkspaceId` on `ancestor-owner` / `reach-holder` only). `capabilities` is the fully-resolved set and **`view` is implied by every other capability** — any user with standing carries it, while a stranger gets `reasons: []` and an empty set.

```typescript theme={null}
const authority = await sublay.workspaces.fetchWorkspaceAuthority({ workspaceId: "ws_abc" });
if (authority.capabilities.includes("invite")) { /* show the invite button */ }
```

<ParamField type="string" />

Sublay never consumes your opaque `permissions` — there is deliberately no `?permission=` check or `can()` helper.


# App Notifications
Source: https://docs.sublay.io/v7/node-sdk/app-notifications

Read a user's in-app notifications and mark them as read from your server

The `appNotifications` module reads a user's in-app notification feed (comments, replies, mentions, reactions, follows, connection requests, milestones, and system messages) and marks notifications as read.

<Note>
  Every function acts on behalf of a named user. Pass that user's Sublay ID as
  `userId` — the feed and counts returned are that user's.
</Note>

***

### fetchNotifications

Returns a paginated list of a user's notifications, newest first.

```typescript theme={null}
const { data, pagination } = await sublay.appNotifications.fetchNotifications({
  userId: "usr_abc123",
  page: 1,
  limit: 20,
});
```

<ParamField type="string">
  The Sublay user ID whose notifications to fetch.
</ParamField>

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Defaults to `20`.
</ParamField>

**Returns** — `Promise<PaginatedResponse<UnifiedAppNotification>>`

Each notification is a discriminated union on `type` (e.g. `"entity-comment"`, `"comment-reply"`, `"new-follow"`, `"connection-request"`, `"system"`), with a `metadata` object whose shape depends on the type. See the [App Notification data model](/v7/data-models/app-notification) for the full set of variants.

***

### countUnreadNotifications

Returns the number of unread notifications for a user.

```typescript theme={null}
const count = await sublay.appNotifications.countUnreadNotifications({
  userId: "usr_abc123",
});
```

<ParamField type="string">
  The Sublay user ID.
</ParamField>

**Returns** — `Promise<number>`

***

### markNotificationAsRead

Marks a single notification as read.

```typescript theme={null}
await sublay.appNotifications.markNotificationAsRead({
  notificationId: "ntf_xyz789",
  userId: "usr_abc123",
});
```

<ParamField type="string">
  The ID of the notification to mark as read.
</ParamField>

<ParamField type="string">
  The Sublay user ID who owns the notification.
</ParamField>

**Returns** — `Promise<void>`

***

### markAllNotificationsAsRead

Marks all of a user's unread notifications as read.

```typescript theme={null}
const { markedAsRead } =
  await sublay.appNotifications.markAllNotificationsAsRead({
    userId: "usr_abc123",
  });
```

<ParamField type="string">
  The Sublay user ID whose notifications to mark as read.
</ParamField>

**Returns** — `Promise<{ markedAsRead: number }>`


# Auth
Source: https://docs.sublay.io/v7/node-sdk/auth

Sign users up, sign them in, manage tokens, and handle password resets from your server

The `auth` module handles user authentication flows server-side. This is useful for custom onboarding pipelines, admin-initiated account creation, token introspection, and password management.

<Note>
  All auth functions operate on behalf of your project. The caller is your server, authenticated via API key — not an end user.
</Note>

***

### signUp

Creates a new user account and returns credentials.

```typescript theme={null}
const { user, accessToken, refreshToken } = await sublay.auth.signUp({
  email: "user@example.com",
  password: "s3cur3P@ss",
  name: "Alice",
  username: "alice",
});
```

<ParamField type="string">
  The user's email address.
</ParamField>

<ParamField type="string">
  The user's plain-text password (hashed server-side).
</ParamField>

<ParamField type="string">
  Display name for the user.
</ParamField>

<ParamField type="string">
  Unique username. Must be available — check with `users.checkUsernameAvailability` first.
</ParamField>

<ParamField type="object">
  Arbitrary key-value data attached to the user at creation time.
</ParamField>

**Returns** — `Promise<{ user: AuthUser; accessToken: string; refreshToken: string }>`

***

### signIn

Authenticates an existing user and returns fresh credentials.

```typescript theme={null}
const { user, accessToken, refreshToken } = await sublay.auth.signIn({
  email: "user@example.com",
  password: "s3cur3P@ss",
});
```

<ParamField type="string">
  The user's email address.
</ParamField>

<ParamField type="string">
  The user's password.
</ParamField>

**Returns** — `Promise<{ user: AuthUser; accessToken: string; refreshToken: string }>`

***

### signOut

Invalidates a refresh token, ending the user's session.

```typescript theme={null}
await sublay.auth.signOut({ refreshToken });
```

<ParamField type="string">
  The refresh token to invalidate.
</ParamField>

<ParamField type="PushDeviceIdentifier">
  Optional. The device the user is signing out on — `{ platform: "ios" | "android", token }`
  or `{ platform: "web", subscription }`. When supplied (and the project has the
  `push` bundle), the server deletes that user's push binding for the device in the
  **same transaction** as the sign-out. Omit it and the sign-out revokes the token
  family only, leaving any push binding in place.
</ParamField>

```typescript theme={null}
await sublay.auth.signOut({
  refreshToken,
  pushDevice: { platform: "ios", token: deviceToken },
});
```

<Warning>
  If the unbind fails, **nothing is committed** — the call rejects with `500` /
  `auth/device-deregistration-failed` and the session survives so you can retry.
  Never treat a failed `signOut` as signed out; discarding the credential anyway
  leaves the user receiving notifications from an account they can no longer reach.

  A `200` carrying `auth/push-unbind-status-unknown` is a success, not a failure:
  the server signed the user out without attempting an unbind because it could not
  determine whether the project has push devices. See
  [`POST /auth/sign-out`](/api-reference/auth/sign-out#response).
</Warning>

**Returns** — `Promise<void>`

***

### requestNewAccessToken

Exchanges a valid refresh token for a new access token.

```typescript theme={null}
const { accessToken } = await sublay.auth.requestNewAccessToken({
  refreshToken,
});
```

<ParamField type="string">
  A valid, non-expired refresh token.
</ParamField>

**Returns** — `Promise<{ accessToken: string }>`

***

### verifyExternalUser

Verifies a signed JWT representing an externally-authenticated user and returns Sublay credentials. Use this when your application manages its own auth and you want to associate users with Sublay.

```typescript theme={null}
const { user, accessToken, refreshToken } = await sublay.auth.verifyExternalUser({
  userJwt: signedJwt,
});
```

<ParamField type="string">
  A JWT signed with your project's signing secret, containing user identity claims.
</ParamField>

**Returns** — `Promise<{ user: AuthUser; accessToken: string; refreshToken: string }>`

***

### requestPasswordReset

Sends a password reset email to the specified address.

```typescript theme={null}
await sublay.auth.requestPasswordReset({ email: "user@example.com" });
```

<ParamField type="string">
  The email address to send the reset link to.
</ParamField>

**Returns** — `Promise<void>`

***

### resetPassword

Completes a password reset using a token from the reset email.

This revokes **every** session for that user and removes **every** push binding they hold, on every device — a reset is the remedy for a suspected compromise, so nothing is spared and there is no field to spare one with. Contrast [`changePassword`](#changepassword), which keeps the calling session and can keep one device's binding. They sign in again everywhere, and each device re-binds for push on its own once it is next opened. Projects without the `push` bundle skip the binding step and are otherwise unaffected.

```typescript theme={null}
await sublay.auth.resetPassword({
  token: resetToken,
  newPassword: "newS3cur3P@ss",
});
```

<ParamField type="string">
  The reset token from the password reset email link.
</ParamField>

<ParamField type="string">
  The new password to set for the account.
</ParamField>

**Returns** — `Promise<void>`

***

### verifyEmail

Marks a user's email address as verified using a token from the verification email.

```typescript theme={null}
await sublay.auth.verifyEmail({ token: verificationToken });
```

<ParamField type="string">
  The email verification token.
</ParamField>

**Returns** — `Promise<void>`

***

### sendVerificationEmail

Sends (or re-sends) an email-verification message to a user. Verification can be delivered as a short code or as a clickable link.

```typescript theme={null}
const { success } = await sublay.auth.sendVerificationEmail({
  userId: "usr_abc123",
  mode: "code",
  tokenFormat: "numeric",
  tokenLength: 6,
});
```

`mode` is always required, and it determines what else is required — enforced by TypeScript as a discriminated union, not just documented:

<ParamField type="string">
  The Sublay user ID to send the verification email to.
</ParamField>

<ParamField type="&#x22;code&#x22; | &#x22;link&#x22;">
  `"code"` emails a short token the user enters; `"link"` emails a verification URL.
</ParamField>

<ParamField type="&#x22;hex&#x22; | &#x22;numeric&#x22; | &#x22;alpha&#x22; | &#x22;alphanumeric&#x22;">
  Format of the generated token.

  * Required when `mode: "code"` — there's no default, since `"hex"` produces a 64-character token no one would want to type.
  * Optional when `mode: "link"` (defaults to `"hex"`) — the token sits in a URL, never read by a human, so format doesn't matter.
</ParamField>

<ParamField type="number">
  Length of the generated token (4–12).

  * Required when `mode: "code"` and `tokenFormat` isn't `"hex"`.
  * Not allowed when `tokenFormat` is `"hex"` — hex ignores length and always produces a fixed 64-character token.
  * Optional when `mode: "link"` (defaults to `6`).
</ParamField>

<ParamField type="string">
  For `mode: "link"` — where to send the user after the link is verified.
</ParamField>

**Returns** — `Promise<{ success: boolean }>`

***

### changePassword

Changes a user's password, verifying their current password first. Use this for an authenticated "change password" flow (as opposed to the token-based `resetPassword`).

A password change ends **every session** for that user and deletes every push binding they hold — see [Change Password](/api-reference/auth/change-password). A service key is not a session, so a call made with one has nothing to spare.

```typescript theme={null}
const { success, message } = await sublay.auth.changePassword({
  userId: "usr_abc123",
  password: "currentP@ss",
  newPassword: "newS3cur3P@ss",
});
```

<ParamField type="string">
  The Sublay user ID whose password to change.
</ParamField>

<ParamField type="string">
  The user's current password (verified before the change).
</ParamField>

<ParamField type="string">
  The new password to set.
</ParamField>

<ParamField type="object">
  One device whose push binding should survive the change: `{ platform: "ios" | "android", token }` or `{ platform: "web", subscription }`.

  A server-side caller normally has no device to name and should omit this — every binding for the user then goes, which is the right default when acting on someone's behalf. Supply it only when your own client told you which device it is on and you want that one to keep receiving notifications.
</ParamField>

**Returns** — `Promise<{ success: boolean; message: string }>`


# Chat
Source: https://docs.sublay.io/v7/node-sdk/chat

Conversations, messages, members, reactions, and read state from your server

The `chat` module is the server-side client for Sublay's messaging: direct and group conversations, messages (with GIFs, mentions, threads, quotes, and file attachments), membership, reactions, read state, and reporting.

## Acting on behalf of a user

Your service key has no implicit session user, so **every** chat call takes the user it acts as. Most functions take that user as `userId`; the few where `userId` already names a *target* take the actor as `actingUserId` instead (`createDirectConversation`, `addMember`, `removeMember`, `changeMemberRole`).

<Warning>
  **Membership is enforced against the acting user (resolve-then-check).** Sublay
  resolves the named user first, then runs the normal conversation checks against
  *that* user. So you can only act as a user who is genuinely a member of the
  conversation, and admin-only actions (delete/update conversation, add/remove
  members, change roles) require that user to be a group **admin**. A service key
  cannot post into a conversation as a user who isn't in it.
</Warning>

<Note>
  Naming a user other than the caller's own is gated to service/master keys. With
  a service key, omitting the acting user returns `400 chat/missing-user-id`.
</Note>

***

## Conversations

### listConversations

Lists the acting user's conversations, newest activity first. Uses **cursor (keyset) pagination** — pass the last item's `lastMessageAt` as `cursor` and its `createdAt` as `cursorCreatedAt` to get the next page.

```typescript theme={null}
const { conversations, hasMore } = await sublay.chat.listConversations({
  userId: "usr_abc123",
  types: "direct,group",
  limit: 20,
});
```

<ParamField type="string">
  The user whose conversations are listed.
</ParamField>

<ParamField type="string">
  Comma-separated filter: any of `direct`, `group`, `space`.
</ParamField>

<ParamField type="string">
  Keyset cursor — the `lastMessageAt` of the last item from the previous page.
</ParamField>

<ParamField type="string">
  Tie-breaker cursor — the `createdAt` of the last item from the previous page.
</ParamField>

<ParamField type="number">
  Page size, 1–50. Defaults to `20`.
</ParamField>

**Returns** — `Promise<{ conversations: ConversationPreview[]; hasMore: boolean }>`

Each `ConversationPreview` includes `otherMembers` — up to 5 active members other than the acting user (`id`, `name`, `username`, `avatar`) for `direct`/`group` conversations, so a DM/group can render the counterparty without a separate members fetch. Capped at 5 (use `memberCount` for the group total); empty for `space` conversations.

***

### createDirectConversation

Creates (or returns the existing) one-to-one conversation between the acting user and a target user.

```typescript theme={null}
const conversation = await sublay.chat.createDirectConversation({
  actingUserId: "usr_abc123",
  userId: "usr_def456",
});
```

<ParamField type="string">
  The other participant (the target).
</ParamField>

<ParamField type="string">
  The user initiating the DM.
</ParamField>

**Returns** — `Promise<Conversation>`

***

### createGroupConversation

Creates a group conversation; the acting user becomes its admin.

```typescript theme={null}
const conversation = await sublay.chat.createGroupConversation({
  userId: "usr_abc123",
  name: "Project Falcon",
  memberIds: ["usr_def456", "usr_ghi789"],
});
```

<ParamField type="string">
  The acting user (becomes the group admin).
</ParamField>

<ParamField type="string">Group name.</ParamField>
<ParamField type="string">Group description.</ParamField>
<ParamField type="string[]">Initial members to add.</ParamField>
<ParamField type="object">Custom key-value data.</ParamField>

**Returns** — `Promise<Conversation>`

***

### getConversation

Fetches a single conversation the acting user is a member of.

```typescript theme={null}
const conversation = await sublay.chat.getConversation({
  conversationId: "cnv_abc123",
  userId: "usr_abc123",
});
```

<ParamField type="string" />

<ParamField type="string">The acting user (must be a member).</ParamField>

**Returns** — `Promise<Conversation>`

***

### updateConversation

Updates a group conversation. Requires the acting user to be a group admin.

```typescript theme={null}
const conversation = await sublay.chat.updateConversation({
  conversationId: "cnv_abc123",
  userId: "usr_abc123",
  name: "Project Falcon (Q3)",
  postingPermission: "admins",
});
```

<ParamField type="string" />

<ParamField type="string">The acting user (must be a group admin).</ParamField>

<ParamField type="string" />

<ParamField type="string" />

<ParamField type="string | null">File id for the avatar, or `null` to clear it.</ParamField>
<ParamField type="&#x22;members&#x22; | &#x22;admins&#x22;">Space conversations only.</ParamField>

**Returns** — `Promise<Conversation>`

***

### deleteConversation

Deletes a group conversation. Requires the acting user to be a group admin.

```typescript theme={null}
await sublay.chat.deleteConversation({
  conversationId: "cnv_abc123",
  userId: "usr_abc123",
});
```

<ParamField type="string" />

<ParamField type="string">The acting user (must be a group admin).</ParamField>

**Returns** — `Promise<void>`

***

### getUnreadCount

Returns the acting user's unread totals across all conversations.

```typescript theme={null}
const { totalUnread, unreadConversationCount } = await sublay.chat.getUnreadCount({
  userId: "usr_abc123",
});
```

<ParamField type="string" />

**Returns** — `Promise<{ totalUnread: number; unreadConversationCount: number }>`

***

## Members

### listMembers

```typescript theme={null}
const { data, pagination } = await sublay.chat.listMembers({
  conversationId: "cnv_abc123",
  userId: "usr_abc123",
  limit: 50,
});
```

<ParamField type="string" />

<ParamField type="string">The acting user (must be a member).</ParamField>
<ParamField type="number">Defaults to `1`.</ParamField>
<ParamField type="number">1–100, defaults to `50`.</ParamField>
<ParamField type="&#x22;admin&#x22; | &#x22;member&#x22;">Filter by role.</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<PaginatedResponse<ConversationMember>>`

***

### addMember

Adds a member to a group. Requires the acting caller to be a group admin.

```typescript theme={null}
await sublay.chat.addMember({
  conversationId: "cnv_abc123",
  userId: "usr_new789",      // member to add
  actingUserId: "usr_abc123", // the admin performing the action
});
```

<ParamField type="string" />

<ParamField type="string">The member to add (the target).</ParamField>
<ParamField type="string">The caller (must be a group admin).</ParamField>

**Returns** — `Promise<ConversationMember>`

***

### removeMember

Removes a member from a group. Requires the acting caller to be a group admin.

```typescript theme={null}
await sublay.chat.removeMember({
  conversationId: "cnv_abc123",
  userId: "usr_new789",
  actingUserId: "usr_abc123",
});
```

<ParamField type="string" />

<ParamField type="string">The member to remove (the target).</ParamField>
<ParamField type="string">The caller (must be a group admin).</ParamField>

**Returns** — `Promise<void>`

***

### changeMemberRole

Promotes or demotes a member. Requires the acting caller to be a group admin.

```typescript theme={null}
await sublay.chat.changeMemberRole({
  conversationId: "cnv_abc123",
  userId: "usr_new789",
  role: "admin",
  actingUserId: "usr_abc123",
});
```

<ParamField type="string" />

<ParamField type="string">The member whose role changes (the target).</ParamField>

<ParamField type="&#x22;admin&#x22; | &#x22;member&#x22;" />

<ParamField type="string">The caller (must be a group admin).</ParamField>

**Returns** — `Promise<ConversationMember>`

***

### leaveConversation

```typescript theme={null}
await sublay.chat.leaveConversation({
  conversationId: "cnv_abc123",
  userId: "usr_abc123",
});
```

<ParamField type="string" />

<ParamField type="string">The user leaving.</ParamField>

**Returns** — `Promise<void>`

***

## Messages

### listMessages

Lists messages in a conversation. Uses **cursor pagination** — pass `before` (an ISO timestamp) to page backwards, or `after` to page forwards (`before`/`after` are mutually exclusive).

```typescript theme={null}
const { messages, hasMore, oldestCreatedAt } = await sublay.chat.listMessages({
  conversationId: "cnv_abc123",
  userId: "usr_abc123",
  limit: 50,
});

// Next (older) page:
const older = await sublay.chat.listMessages({
  conversationId: "cnv_abc123",
  userId: "usr_abc123",
  before: oldestCreatedAt!,
});

// Only messages that have thread replies.
const withReplies = await sublay.chat.listMessages({
  conversationId: "cnv_abc123",
  userId: "usr_abc123",
  filters: { hasReplies: true },
});
```

<ParamField type="string" />

<ParamField type="string">The acting user (must be a member).</ParamField>
<ParamField type="string">Restrict to replies of this message (thread view).</ParamField>
<ParamField type="string">ISO timestamp — messages created before this. Mutually exclusive with `after`.</ParamField>
<ParamField type="string">ISO timestamp — messages created after this. Mutually exclusive with `before`.</ParamField>
<ParamField type="number">1–100, defaults to `50`.</ParamField>

<ParamField type="&#x22;asc&#x22; | &#x22;desc&#x22;" />

<ParamField type="string">Comma-separated associations to populate: `"files"` (message attachments) and `"grants"` (each message's [reputation-grant summary](/data-models/reputation-grant#grantsummary)). Combine them as `"files,grants"`.</ParamField>
<ParamField type="MessageFilters">Optional filters. `filters.hasReplies` (boolean): when `true`, returns only messages that have thread replies (`threadReplyCount > 0`); when `false`, only messages with none. Filters by thread replies, not quotings. Threads are one level deep, so `hasReplies: true` together with `parentId` always returns an empty list — the response's `notice` field explains why.</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<{ messages: ChatMessage[]; hasMore: boolean; oldestCreatedAt: string | null; newestCreatedAt: string | null }>`

***

### sendMessage

Sends a message as the acting user. A message must have content, a GIF, or at least one file. When `files` are attached the request is sent as `multipart/form-data`; otherwise it's a JSON body.

```typescript theme={null}
// Text + mention
const message = await sublay.chat.sendMessage({
  conversationId: "cnv_abc123",
  userId: "usr_abc123",
  content: "Welcome aboard!",
  mentions: [{ type: "user", id: "usr_def456", username: "dana" }],
});

// With a file attachment
import { readFile } from "node:fs/promises";
const buffer = await readFile("./diagram.png");

await sublay.chat.sendMessage({
  conversationId: "cnv_abc123",
  userId: "usr_abc123",
  content: "See attached",
  files: [{ file: new Uint8Array(buffer), filename: "diagram.png", mimeType: "image/png" }],
});
```

<ParamField type="string" />

<ParamField type="string">The message author (must be a member).</ParamField>
<ParamField type="string">Up to 4000 characters.</ParamField>
<ParamField type="GifData | null">An attached GIF object.</ParamField>
<ParamField type="Mention[]">User/space mentions.</ParamField>
<ParamField type="string">Reply within a thread.</ParamField>
<ParamField type="string">Quote another message.</ParamField>
<ParamField type="object">Custom key-value data.</ParamField>
<ParamField type="string">Client-generated id echoed back on the created message (not stored).</ParamField>

<ParamField type="ChatMessageFile[]">
  Attachments: `{ file: Uint8Array | Blob; filename?: string; mimeType?: string }[]`, up to 10.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<ChatMessage>`

***

### getMessage

```typescript theme={null}
const message = await sublay.chat.getMessage({
  conversationId: "cnv_abc123",
  messageId: "msg_xyz",
  userId: "usr_abc123",
});
```

<ParamField type="string" />

<ParamField type="string" />

<ParamField type="string">The acting user (must be a member).</ParamField>
<ParamField type="string">Comma-separated associations to populate. Only `"grants"` is supported here — it attaches the message's [reputation-grant summary](/data-models/reputation-grant#grantsummary) at `message.grants`.</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<ChatMessage>`

***

### editMessage

Edits a message. Requires the acting user to be the message author.

```typescript theme={null}
const message = await sublay.chat.editMessage({
  conversationId: "cnv_abc123",
  messageId: "msg_xyz",
  userId: "usr_abc123",
  content: "Edited text",
});
```

<ParamField type="string" />

<ParamField type="string" />

<ParamField type="string">The acting user (must be the message author).</ParamField>

<ParamField type="string" />

<ParamField type="GifData | null">A [GifData](/data-models/chat-message#gifdata) attachment, or `null` to clear it.</ParamField>

<ParamField type="Mention[]" />

<ParamField type="object | null" />

**Returns** — `Promise<ChatMessage>`

***

### deleteMessage

Soft-deletes a message. Requires the acting user to be the author or a group admin.

```typescript theme={null}
await sublay.chat.deleteMessage({
  conversationId: "cnv_abc123",
  messageId: "msg_xyz",
  userId: "usr_abc123",
});
```

<ParamField type="string" />

<ParamField type="string" />

<ParamField type="string">The acting user (author or group admin).</ParamField>

**Returns** — `Promise<void>`

***

### Reporting a message

Message reports go through the shared reports API, not a chat-specific
function — the same call that reports entities and comments.

```typescript theme={null}
await sublay.reports.createReport({
  targetType: "message",
  targetId: "msg_xyz",
  userId: "usr_abc123",
  reason: "harassment",
  details: "Targeted insults",
});
```

`targetId` is the message id; the conversation is resolved server-side, so no
`conversationId` is needed. The reporter must be a member of the conversation
and cannot report their own message. See [createReport](/node-sdk/reports).

***

## Reactions

### toggleReaction

Adds or removes the acting user's emoji reaction on a message.

```typescript theme={null}
const { delta, reactionCounts } = await sublay.chat.toggleReaction({
  conversationId: "cnv_abc123",
  messageId: "msg_xyz",
  emoji: "👍",
  userId: "usr_abc123",
});
// delta === 1 when the reaction was added, -1 when it was removed
```

<ParamField type="string" />

<ParamField type="string" />

<ParamField type="string" />

<ParamField type="string">The reacting user (must be a member).</ParamField>

**Returns** — `Promise<{ reactionCounts: Record<string, number>; userReactions: string[]; delta: 1 | -1 }>` (`delta` is `1` if the reaction was added, `-1` if removed).

***

### listReactions

Lists the users who reacted with a given emoji.

```typescript theme={null}
const { data, pagination } = await sublay.chat.listReactions({
  conversationId: "cnv_abc123",
  messageId: "msg_xyz",
  emoji: "👍",
  userId: "usr_abc123",
});
```

<ParamField type="string" />

<ParamField type="string" />

<ParamField type="string">The emoji to list reactors for.</ParamField>
<ParamField type="string">The acting user (must be a member).</ParamField>
<ParamField type="number">Defaults to `1`.</ParamField>
<ParamField type="number">1–100, defaults to `50`.</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<{ data: MessageReaction[]; pagination: { page; limit; total; hasMore } }>`

***

## Read state

### markAsRead

Marks the conversation read up to a given message.

```typescript theme={null}
await sublay.chat.markAsRead({
  conversationId: "cnv_abc123",
  messageId: "msg_xyz",
  userId: "usr_abc123",
});
```

<ParamField type="string" />

<ParamField type="string">The message up to which the conversation is marked read.</ParamField>
<ParamField type="string">The acting user (must be a member).</ParamField>

**Returns** — `Promise<void>`

***

### muteConversation

Sets or clears a user's mute on a conversation. Muting suppresses the `message` push for this conversation only; the message is still delivered. See [Notification Preferences & Mute](/notification-preferences).

```typescript theme={null}
// Mute for a week
await sublay.chat.muteConversation({
  conversationId: "cnv_abc123",
  duration: "1w",
  userId: "usr_abc123",
});

// Unmute
await sublay.chat.muteConversation({
  conversationId: "cnv_abc123",
  duration: null,
  userId: "usr_abc123",
});
```

<Note>
  Like every other `chat` call, the Node SDK names the acting user with `userId` (the service key acts on that user's behalf). The user must be a member of the conversation, and the returned `currentMember` is that user's own row. End-user-token clients (the React hooks, the browser JS SDK) act on the signed-in user and omit `userId`.
</Note>

<ParamField type="string" />

<ParamField type="&#x22;8h&#x22; | &#x22;24h&#x22; | &#x22;1w&#x22; | &#x22;forever&#x22; | null">
  The mute **duration choice**, or `null` to clear the mute. Send the choice, never a raw timestamp.
</ParamField>

<ParamField type="string">The user whose mute is set (must be a member).</ParamField>

**Returns** — `Promise<{ currentMember: ConversationMember }>` — that user's own member row.

```typescript theme={null}
interface ConversationMember {
  // ...
  mutedForever?: boolean;    // true when muted indefinitely
  mutedUntil?: string | null; // ISO timestamp for a timed mute; null otherwise
}
```

<Info>
  **"Forever" is an explicit signal.** A `forever` mute returns `mutedForever: true` with `mutedUntil: null`. A timed mute returns `mutedForever: false` with a real ISO `mutedUntil`. Read the boolean — never string-match a far-future date.
</Info>

***

## Space conversations

Each space has a single built-in conversation. These three live on **`client.spaces`** (they're `/spaces/...` routes), not on `client.chat`.

### spaces.getSpaceConversation

Fetches-or-creates a space's conversation and joins the acting user to it. The acting user must be a non-banned member of the space.

```typescript theme={null}
const conversation = await sublay.spaces.getSpaceConversation({
  spaceId: "spc_abc123",
  userId: "usr_abc123",
});
```

<ParamField type="string" />

<ParamField type="string">The acting user (must be a space member).</ParamField>

**Returns** — `Promise<Conversation>`

***

### spaces.moderateSpaceChatMessage

Removes a message in a space conversation.

<Note>
  Unlike the conversation-scoped chat calls, the two space-chat moderation routes
  are **service-key god-mode** — your service key passes the space-moderator check
  automatically. `actingUserId` here is **attribution only** (who moderated); omit
  it for a backend/system action.
</Note>

```typescript theme={null}
await sublay.spaces.moderateSpaceChatMessage({
  spaceId: "spc_abc123",
  messageId: "msg_xyz",
  moderationStatus: "removed",
  moderationReason: "Off-topic",
  actingUserId: "usr_mod123",
});
```

<ParamField type="string" />

<ParamField type="string" />

<ParamField type="&#x22;removed&#x22;" />

<ParamField type="string" />

<ParamField type="string">Acting moderator, for attribution.</ParamField>

**Returns** — `Promise<{ message: string; moderationStatus: string }>`

***

### spaces.handleSpaceChatReport

Resolves a report against a space-conversation message: remove the message, ban the user, and/or dismiss.

```typescript theme={null}
await sublay.spaces.handleSpaceChatReport({
  spaceId: "spc_abc123",
  reportId: "rpt_abc123",
  actions: ["remove-message", "ban-user"],
  messageId: "msg_xyz",
  userId: "usr_offender",
  reason: "Repeated harassment",
  actingUserId: "usr_mod123",
});
```

<ParamField type="string" />

<ParamField type="string" />

<ParamField type="(&#x22;remove-message&#x22; | &#x22;ban-user&#x22; | &#x22;dismiss&#x22;)[]">
  `dismiss` cannot be combined with the other actions.
</ParamField>

<ParamField type="string">Required when actions include `remove-message`.</ParamField>
<ParamField type="string">The user to ban (target); required when actions include `ban-user`.</ParamField>

<ParamField type="string" />

<ParamField type="string">Stored as the report's resolution note.</ParamField>
<ParamField type="string">Acting moderator, for attribution.</ParamField>

**Returns** — `Promise<{ message: string; code: string }>`


# Collections
Source: https://docs.sublay.io/v7/node-sdk/collections

Organize a user's saved entities into a tree of collections from your server

The `collections` module manages a user's saved-content collections. Every user has a single **root collection**, under which they can nest sub-collections and into which they can save entities.

<Note>
  Collections are always scoped to a specific user. Pass that user's Sublay ID as
  `userId` on every call — your service key performs the operation on behalf of
  that named user.
</Note>

***

### fetchRootCollection

Fetches a user's root collection, creating it on first access if it does not yet exist.

```typescript theme={null}
const root = await sublay.collections.fetchRootCollection({
  userId: "usr_abc123",
});
```

<ParamField type="string">
  The Sublay user ID whose root collection to fetch.
</ParamField>

**Returns** — `Promise<Collection>`

***

### fetchSubCollections

Fetches the direct child collections nested under a given collection.

```typescript theme={null}
const subCollections = await sublay.collections.fetchSubCollections({
  collectionId: "col_root123",
  userId: "usr_abc123",
});
```

<ParamField type="string">
  The parent collection ID.
</ParamField>

<ParamField type="string">
  The Sublay user ID who owns the collection.
</ParamField>

**Returns** — `Promise<Collection[]>`

***

### createNewCollection

Creates a new sub-collection under an existing parent collection.

```typescript theme={null}
const collection = await sublay.collections.createNewCollection({
  collectionId: "col_root123",
  collectionName: "Recipes",
  userId: "usr_abc123",
});
```

<ParamField type="string">
  The parent collection under which to create the sub-collection.
</ParamField>

<ParamField type="string">
  The name of the new collection.
</ParamField>

<ParamField type="string">
  The Sublay user ID who will own the collection.
</ParamField>

**Returns** — `Promise<Collection>`

***

### fetchCollectionEntities

Fetches a paginated list of entities saved in a collection.

```typescript theme={null}
const { data, pagination } = await sublay.collections.fetchCollectionEntities({
  collectionId: "col_xyz789",
  userId: "usr_abc123",
  sortBy: "added",
  page: 1,
  limit: 20,
});
```

<ParamField type="string">
  The collection ID.
</ParamField>

<ParamField type="string">
  The Sublay user ID who owns the collection.
</ParamField>

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Defaults to `20`.
</ParamField>

<ParamField type="string">
  Sort order: `"new"`, `"added"` (when saved), `"top"`, or `"hot"`.
</ParamField>

<ParamField type="string">
  Sort direction: `"asc"` or `"desc"`.
</ParamField>

<ParamField type="string">
  Comma-separated list of associations to populate (e.g. `"user"`).
</ParamField>

**Returns** — `Promise<PaginatedResponse<Entity>>`

***

### addEntityToCollection

Saves an entity into a collection.

```typescript theme={null}
const collection = await sublay.collections.addEntityToCollection({
  collectionId: "col_xyz789",
  entityId: "ent_xyz789",
  userId: "usr_abc123",
});
```

<ParamField type="string">
  The collection to add the entity to.
</ParamField>

<ParamField type="string">
  The Sublay entity ID to save.
</ParamField>

<ParamField type="string">
  The Sublay user ID who owns the collection.
</ParamField>

**Returns** — `Promise<Collection>`

***

### removeEntityFromCollection

Removes an entity from a collection.

```typescript theme={null}
await sublay.collections.removeEntityFromCollection({
  collectionId: "col_xyz789",
  entityId: "ent_xyz789",
  userId: "usr_abc123",
});
```

<ParamField type="string">
  The collection to remove the entity from.
</ParamField>

<ParamField type="string">
  The Sublay entity ID to remove.
</ParamField>

<ParamField type="string">
  The Sublay user ID who owns the collection.
</ParamField>

**Returns** — `Promise<void>`

***

### updateCollection

Renames a collection.

```typescript theme={null}
const collection = await sublay.collections.updateCollection({
  collectionId: "col_xyz789",
  userId: "usr_abc123",
  name: "Favorite Recipes",
});
```

<ParamField type="string">
  The collection ID to update.
</ParamField>

<ParamField type="string">
  The Sublay user ID who owns the collection.
</ParamField>

<ParamField type="string">
  The new collection name. Must be a non-empty string.
</ParamField>

**Returns** — `Promise<Collection>`

***

### deleteCollection

Deletes a collection.

```typescript theme={null}
await sublay.collections.deleteCollection({
  collectionId: "col_xyz789",
  userId: "usr_abc123",
});
```

<ParamField type="string">
  The collection ID to delete.
</ParamField>

<ParamField type="string">
  The Sublay user ID who owns the collection.
</ParamField>

**Returns** — `Promise<void>`


# Comments
Source: https://docs.sublay.io/v7/node-sdk/comments

Create, fetch, update, delete comments, and manage reactions from your server

The `comments` module provides full server-side control over comments on entities. Use it to seed content, build moderation pipelines, or integrate comment data into your backend logic.

***

### createComment

Creates a new comment on an entity.

```typescript theme={null}
const comment = await sublay.comments.createComment({
  entityId: "ent_xyz789",
  userId: "usr_abc123",
  content: "Great post!",
});
```

<ParamField type="string">
  The Sublay entity ID to comment on.
</ParamField>

<ParamField type="string">
  The Sublay user ID of the comment author.
</ParamField>

<ParamField type="string">
  The comment text content.
</ParamField>

<ParamField type="string">
  Your application's identifier for this comment.
</ParamField>

<ParamField type="object">
  A GIF to attach to the comment (`GifData`), or `null`.
</ParamField>

<ParamField type="array">
  User mentions embedded in the comment.
</ParamField>

<ParamField type="string">
  The Sublay comment ID of the parent, for creating a reply.
</ParamField>

<ParamField type="string">
  A comment being directly quoted or referenced.
</ParamField>

<ParamField type="array">
  File or media attachments on the comment.
</ParamField>

<ParamField type="object">
  Arbitrary metadata attached to the comment.
</ParamField>

<ParamField type="Date">
  A `Date` used to backdate the comment's creation time.
</ParamField>

<ParamField type="Date">
  A `Date` used to backdate the comment's last update time.
</ParamField>

**Returns** — `Promise<Comment>`

***

### fetchComment

Fetches a single comment by its Sublay ID.

```typescript theme={null}
const comment = await sublay.comments.fetchComment({ commentId: "cmt_abc123" });
```

<ParamField type="string">
  The Sublay comment ID.
</ParamField>

<ParamField type="string">
  Comma-separated list of associations to populate.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<Comment>`

***

### fetchCommentByForeignId

Fetches a comment by your application's own identifier.

```typescript theme={null}
const comment = await sublay.comments.fetchCommentByForeignId({
  foreignId: "my-comment-id-99",
});
```

<ParamField type="string">
  Your application's comment identifier.
</ParamField>

<ParamField type="string">
  Comma-separated list of associations to populate.
</ParamField>

**Returns** — `Promise<Comment>`

***

### updateComment

Updates the content of an existing comment.

```typescript theme={null}
const comment = await sublay.comments.updateComment({
  commentId: "cmt_abc123",
  content: "Edited comment text",
});
```

<ParamField type="string">
  The Sublay comment ID to update.
</ParamField>

<ParamField type="string">
  The new comment text.
</ParamField>

**Returns** — `Promise<Comment>`

***

### deleteComment

Permanently deletes a comment.

```typescript theme={null}
await sublay.comments.deleteComment({ commentId: "cmt_abc123" });
```

<ParamField type="string">
  The Sublay comment ID to delete.
</ParamField>

**Returns** — `Promise<void>`

***

### fetchManyComments

Fetches a paginated list of comments on an entity. Supports top-level and reply-level fetching.

```typescript theme={null}
const { data, pagination } = await sublay.comments.fetchManyComments({
  entityId: "ent_xyz789",
  sortBy: "top",
  page: 1,
  limit: 20,
});
```

<ParamField type="string">
  The Sublay entity ID to fetch comments for.
</ParamField>

<ParamField type="string">
  Filter to comments authored by a specific user.
</ParamField>

<ParamField type="string">
  When provided, fetches replies to this specific comment ID instead of top-level comments.
</ParamField>

<ParamField type="string">
  Filter comments by source ID.
</ParamField>

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Defaults to `20`.
</ParamField>

<ParamField type="string">
  Sort order: `"createdAt"` (newest first; honors `sortDir`), `"top"` (highest scored), or `"controversial"`. `"new"` (createdAt DESC) and `"old"` (createdAt ASC) are deprecated aliases for `"createdAt"` (removed in v8) — the server still accepts them but responds with a deprecation header.
</ParamField>

<ParamField type="string">
  Comma-separated list of associations to populate.
</ParamField>

<ParamField type="&#x22;exclude&#x22; | &#x22;include-outbound-blocked&#x22;">
  How to treat comments authored by users the viewer is [block-edged](/sdk/moderation/overview#blocking) with. `"exclude"` (default) hides them; `"include-outbound-blocked"` re-includes only the viewer's own outbound-blocked authors — never content from users who blocked the viewer. No effect without the `moderation` bundle.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<PaginatedResponse<Comment>>`

***

### addReaction

Adds a reaction from a user to a comment.

```typescript theme={null}
const reaction = await sublay.comments.addReaction({
  commentId: "cmt_abc123",
  userId: "usr_abc123",
  reactionType: "like",
});
```

<ParamField type="string">
  The Sublay comment ID.
</ParamField>

<ParamField type="string">
  The Sublay user ID of the reactor.
</ParamField>

<ParamField type="ReactionType">
  One of: `"upvote"`, `"downvote"`, `"like"`, `"love"`, `"wow"`, `"sad"`, `"angry"`, `"funny"`.
</ParamField>

**Returns** — `Promise<Reaction>`

***

### removeReaction

Removes a user's existing reaction from a comment.

```typescript theme={null}
await sublay.comments.removeReaction({
  commentId: "cmt_abc123",
  userId: "usr_abc123",
});
```

<ParamField type="string">
  The Sublay comment ID.
</ParamField>

<ParamField type="string">
  The Sublay user ID whose reaction to remove.
</ParamField>

**Returns** — `Promise<void>`

***

### fetchReactions

Fetches a paginated list of reactions on a comment, optionally filtered by reaction type.

```typescript theme={null}
const { data, pagination } = await sublay.comments.fetchReactions({
  commentId: "cmt_abc123",
  reactionType: "upvote",
  page: 1,
  limit: 20,
});
```

<ParamField type="string">
  The Sublay comment ID.
</ParamField>

<ParamField type="ReactionType">
  Filter to a specific reaction type.
</ParamField>

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Defaults to `20`.
</ParamField>

<ParamField type="string">
  Sort direction: `"asc"` or `"desc"`.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<PaginatedResponse<Reaction>>`

***

### getUserReaction

Checks what reaction (if any) a specific user has left on a comment.

```typescript theme={null}
const { reactionType } = await sublay.comments.getUserReaction({
  commentId: "cmt_abc123",
  userId: "usr_abc123",
});
// reactionType is "like" | "upvote" | ... | null
```

<ParamField type="string">
  The Sublay comment ID.
</ParamField>

<ParamField type="string">
  The Sublay user ID to check.
</ParamField>

**Returns** — `Promise<{ reactionType: ReactionType | null }>`


# Connections
Source: https://docs.sublay.io/v7/node-sdk/connections

Query and respond to a user's mutual connections from your server

The `connections` module reads and manages a user's mutual connections (bidirectional relationships, similar to "friends"). Use it to list established connections, inspect pending requests, and accept, decline, or remove connections.

<Note>
  Every function acts on behalf of a named user. Pass that user's Sublay ID as
  `userId` — your service key performs the operation as that user.
</Note>

<Tip>
  To **send** a connection request, check a connection's status, or remove a
  connection by the other user's ID, use the nested routes on the
  [`users`](/v7/node-sdk/users) module (`requestConnection`,
  `fetchConnectionStatus`, `removeConnectionByUserId`), which take an
  `actingUserId`.
</Tip>

***

### fetchConnections

Fetches a paginated list of a user's established (mutual) connections.

```typescript theme={null}
const { data, pagination } = await sublay.connections.fetchConnections({
  userId: "usr_abc123",
  page: 1,
  limit: 20,
});
```

<ParamField type="string">
  The Sublay user ID whose connections to fetch.
</ParamField>

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Defaults to `20`.
</ParamField>

<ParamField type="string">
  Optional search term. Filters the list to connections whose connected user's username or name contains this text (case-insensitive). When omitted, no filtering is applied.
</ParamField>

<ParamField type="string">
  Restricts which field `query` matches against — `username` or `name`. When omitted, `query` matches either field.
</ParamField>

**Returns** — `Promise<PaginatedResponse<EstablishedConnection>>`

***

### fetchConnectionsCount

Returns the number of established connections for a user.

```typescript theme={null}
const { count } = await sublay.connections.fetchConnectionsCount({
  userId: "usr_abc123",
});
```

<ParamField type="string">
  The Sublay user ID.
</ParamField>

**Returns** — `Promise<{ count: number }>`

***

### fetchSentPendingConnections

Returns a paginated list of connection requests the user has sent that are still pending.

```typescript theme={null}
const { data, pagination } =
  await sublay.connections.fetchSentPendingConnections({
    userId: "usr_abc123",
    page: 1,
    limit: 20,
  });
```

<ParamField type="string">
  The Sublay user ID whose sent requests to fetch.
</ParamField>

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Defaults to `20`.
</ParamField>

**Returns** — `Promise<PaginatedResponse<PendingConnection>>`

***

### fetchReceivedPendingConnections

Returns a paginated list of pending connection requests the user has received.

```typescript theme={null}
const { data, pagination } =
  await sublay.connections.fetchReceivedPendingConnections({
    userId: "usr_abc123",
    page: 1,
    limit: 20,
  });
```

<ParamField type="string">
  The Sublay user ID whose received requests to fetch.
</ParamField>

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Defaults to `20`.
</ParamField>

**Returns** — `Promise<PaginatedResponse<PendingConnection>>`

***

### acceptConnection

Accepts a pending connection request received by the user.

```typescript theme={null}
const result = await sublay.connections.acceptConnection({
  connectionId: "con_xyz789",
  userId: "usr_abc123",
});
```

<ParamField type="string">
  The ID of the pending connection request to accept.
</ParamField>

<ParamField type="string">
  The Sublay user ID accepting the request (the recipient).
</ParamField>

**Returns** — `Promise<ConnectionActionResponse>` — `{ id, status, createdAt?, respondedAt? }`

***

### declineConnection

Declines a pending connection request received by the user.

```typescript theme={null}
const result = await sublay.connections.declineConnection({
  connectionId: "con_xyz789",
  userId: "usr_abc123",
});
```

<ParamField type="string">
  The ID of the pending connection request to decline.
</ParamField>

<ParamField type="string">
  The Sublay user ID declining the request (the recipient).
</ParamField>

**Returns** — `Promise<ConnectionActionResponse>` — `{ id, status, createdAt?, respondedAt? }`

***

### removeConnection

Removes an established connection (or withdraws a pending request) by its connection ID.

```typescript theme={null}
await sublay.connections.removeConnection({
  connectionId: "con_xyz789",
  userId: "usr_abc123",
});
```

<ParamField type="string">
  The connection ID to remove.
</ParamField>

<ParamField type="string">
  The Sublay user ID on whose behalf the connection is removed.
</ParamField>

**Returns** — `Promise<void>`


# Entities
Source: https://docs.sublay.io/v7/node-sdk/entities

Create and manage content entities, reactions, drafts, and view counts from your server

<Note>
  **Requires the `entities` bundle.** A project without the entities bundle returns `403 database/tables-not-available` for entity calls. See [Bundles](/bundles).
</Note>

Entities are the central content objects in Sublay — posts, articles, products, or any item in your application that users interact with. The `entities` module gives you full server-side control over their lifecycle.

***

### createEntity

Creates a new entity.

```typescript theme={null}
const entity = await sublay.entities.createEntity({
  foreignId: "post-42",
  title: "My First Post",
  content: "Hello world",
  keywords: ["intro", "welcome"],
  userId: "usr_abc123",
  metadata: { category: "blog" },
});
```

<ParamField type="string">
  Your application's identifier for this entity. Used for idempotent lookups via `fetchEntityByForeignId`.
</ParamField>

<ParamField type="string">
  An optional secondary identifier for grouping or filtering entities.
</ParamField>

<ParamField type="string">
  The space this entity belongs to.
</ParamField>

<ParamField type="string">
  Title text for the entity.
</ParamField>

<ParamField type="string">
  Body/content text for the entity.
</ParamField>

<ParamField type="array">
  File or media attachments.
</ParamField>

<ParamField type="string[]">
  Tags or keywords used for filtering and discovery.
</ParamField>

<ParamField type="array">
  User mentions embedded in the entity.
</ParamField>

<ParamField type="object">
  Geographic coordinates `{ latitude: number; longitude: number }`.
</ParamField>

<ParamField type="object">
  Arbitrary public metadata.
</ParamField>

<ParamField type="string">
  The Sublay user ID to set as the entity's author.
</ParamField>

<ParamField type="boolean">
  The entity's own NSFW flag. Defaults to `false`. Effective NSFW also inherits from the entity's space. See [Entity NSFW flagging](/data-models/entity#nsfw-flagging).
</ParamField>

<ParamField type="boolean">
  When `true`, the entity is created as an unpublished draft. Defaults to `false`.
</ParamField>

<ParamField type="boolean">
  When `true`, creates the entity with no author association even if `userId` is provided.
</ParamField>

<ParamField type="boolean">
  When `true`, the request fails unless a valid author user is resolved.
</ParamField>

<ParamField type="Date">
  A `Date` used to backdate the entity's creation time.
</ParamField>

<ParamField type="Date">
  A `Date` used to backdate the entity's last update time.
</ParamField>

**Returns** — `Promise<Entity>`

***

### fetchEntity

Fetches a single entity by its Sublay ID.

```typescript theme={null}
const entity = await sublay.entities.fetchEntity({ entityId: "ent_xyz789" });
```

<ParamField type="string">
  The Sublay entity ID.
</ParamField>

<ParamField type="string">
  Comma-separated list of associations to populate.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<Entity>`

***

### fetchEntityByForeignId

Fetches an entity by your application's own identifier. Optionally creates it if not found.

```typescript theme={null}
const entity = await sublay.entities.fetchEntityByForeignId({
  foreignId: "post-42",
  createIfNotFound: true,
});
```

<ParamField type="string">
  Your application's entity identifier.
</ParamField>

<ParamField type="boolean">
  When `true`, creates a stub entity if no match is found. Defaults to `false`.
</ParamField>

<ParamField type="string">
  Comma-separated list of associations to populate.
</ParamField>

**Returns** — `Promise<Entity>`

***

### fetchEntityByShortId

Fetches an entity by its short, human-readable ID (used in share URLs).

```typescript theme={null}
const entity = await sublay.entities.fetchEntityByShortId({ shortId: "abc12" });
```

<ParamField type="string">
  The entity's short ID.
</ParamField>

<ParamField type="string">
  Comma-separated list of associations to populate.
</ParamField>

**Returns** — `Promise<Entity>`

***

### fetchManyEntities

Fetches a filtered, paginated list of entities. Supports rich filtering by metadata, keywords, location, and more.

```typescript theme={null}
const { data, pagination } = await sublay.entities.fetchManyEntities({
  spaceId: "spc_abc123",
  sortBy: "hot",
  page: 1,
  limit: 20,
  metadataFilters: { includes: { category: "blog" } },
});
```

<ParamField type="string">
  Filter by source ID.
</ParamField>

<ParamField type="string">
  Filter to entities within a specific space.
</ParamField>

<ParamField type="string">
  Sort order: `"createdAt"` (chronological — honors `sortDir`), `"hot"` (trending), `"top"` (highest scored), or `"controversial"`. A `"metadata.<prop>"` value is also accepted to sort by a metadata field.
</ParamField>

<ParamField type="string">
  Sort direction: `"asc"` or `"desc"`.
</ParamField>

<ParamField type="string">
  How to interpret a metadata sort value: `"auto"`, `"numeric"`, `"text"`, `"boolean"`, or `"timestamp"`.
</ParamField>

<ParamField type="string">
  Sort by the count of a specific reaction: `"upvote"`, `"downvote"`, `"like"`, `"love"`, `"wow"`, `"sad"`, `"angry"`, or `"funny"`.
</ParamField>

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Defaults to `20`.
</ParamField>

<ParamField type="string">
  Comma-separated list of associations to populate (e.g. `"user"`).
</ParamField>

<ParamField type="string">
  Time window to restrict results to: `"hour"`, `"day"`, `"week"`, `"month"`, or `"year"`.
</ParamField>

<ParamField type="string">
  The viewing user, used to resolve `followedOnly`.
</ParamField>

<ParamField type="&#x22;true&#x22; | &#x22;false&#x22;">
  When `"true"`, returns only entities from users the given `userId` follows.
</ParamField>

<ParamField type="object">
  Filter by keyword tags: `{ includes?: string[]; doesNotInclude?: string[] }`.
</ParamField>

<ParamField type="object">
  Filter by metadata fields: `{ includes?, includesAny?, doesNotInclude?, exists?: string[], doesNotExist?: string[] }`.
</ParamField>

<ParamField type="object">
  Filter by title: `{ hasTitle?: "true" | "false"; includes?: string | string[]; doesNotInclude?: string | string[] }`.
</ParamField>

<ParamField type="object">
  Filter by content: `{ hasContent?: "true" | "false"; includes?: string | string[]; doesNotInclude?: string | string[] }`.
</ParamField>

<ParamField type="object">
  Filter by attachments: `{ hasAttachments?: "true" | "false" }`.
</ParamField>

<ParamField type="object">
  Filter within a geographic radius: `{ latitude: string; longitude: string; radius: string }`.
</ParamField>

<ParamField type="&#x22;include-all&#x22; | &#x22;exclude&#x22; | &#x22;only&#x22;">
  Filter by effective NSFW (`entity.nsfw OR its space's nsfwEffective`). `"include-all"` (default) adds no predicate; `"exclude"` drops effective-NSFW entities; `"only"` returns only them. See [Entity NSFW flagging](/data-models/entity#nsfw-flagging).
</ParamField>

<ParamField type="&#x22;exclude&#x22; | &#x22;include-outbound-blocked&#x22;">
  How to treat entities authored by users the viewer is [block-edged](/sdk/moderation/overview#blocking) with. `"exclude"` (default) hides them; `"include-outbound-blocked"` re-includes only the viewer's own outbound-blocked authors — never content from users who blocked the viewer. No effect without the `moderation` bundle.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<PaginatedResponse<Entity>>`

***

### updateEntity

Updates fields on an existing entity.

```typescript theme={null}
const entity = await sublay.entities.updateEntity({
  entityId: "ent_xyz789",
  title: "Updated Title",
  metadata: { featured: true },
});
```

<ParamField type="string">
  The Sublay entity ID to update.
</ParamField>

<ParamField type="string">
  New title.
</ParamField>

<ParamField type="string">
  New content body.
</ParamField>

<ParamField type="array">
  Updated attachments list.
</ParamField>

<ParamField type="string[]">
  Updated keywords list.
</ParamField>

<ParamField type="object">
  Updated coordinates `{ latitude: number; longitude: number }`.
</ParamField>

<ParamField type="object">
  Updated metadata. Merged with existing values.
</ParamField>

<ParamField type="array">
  Updated user mentions list.
</ParamField>

<ParamField type="boolean">
  Updated NSFW own-flag (owner / service / master). A space moderator flagging another user's entity uses `spaces.setSpaceEntityNsfw` instead. See [Entity NSFW flagging](/data-models/entity#nsfw-flagging).
</ParamField>

**Returns** — `Promise<Entity>`

***

### deleteEntity

Permanently deletes an entity and its associated data.

```typescript theme={null}
await sublay.entities.deleteEntity({ entityId: "ent_xyz789" });
```

<ParamField type="string">
  The Sublay entity ID to delete.
</ParamField>

**Returns** — `Promise<void>`

***

### incrementEntityViews

Increments the view counter on an entity. Call this when a user views content to track engagement.

```typescript theme={null}
const entity = await sublay.entities.incrementEntityViews({
  entityId: "ent_xyz789",
  count: 1,
});
```

<ParamField type="string">
  The Sublay entity ID.
</ParamField>

<ParamField type="number">
  Number to add to the view counter. Defaults to `1`.
</ParamField>

**Returns** — `Promise<Entity>`

***

### fetchDrafts

Fetches a user's unpublished draft entities.

```typescript theme={null}
const { data, pagination } = await sublay.entities.fetchDrafts({
  userId: "usr_abc123",
  page: 1,
  limit: 20,
});
```

<ParamField type="string">
  The Sublay user ID whose drafts to fetch.
</ParamField>

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Defaults to `20`.
</ParamField>

<ParamField type="string">
  Filter drafts by source ID.
</ParamField>

<ParamField type="string">
  Filter drafts to a specific space.
</ParamField>

<ParamField type="string">
  Comma-separated list of associations to populate.
</ParamField>

**Returns** — `Promise<PaginatedResponse<Entity>>`

***

### publishDraft

Publishes a draft entity, making it publicly visible.

```typescript theme={null}
const entity = await sublay.entities.publishDraft({ entityId: "ent_xyz789" });
```

<ParamField type="string">
  The Sublay entity ID of the draft to publish.
</ParamField>

**Returns** — `Promise<Entity>`

***

### fetchTopComment

Fetches the highest-scored (top) comment on an entity. Returns `null` if the entity has no comments.

```typescript theme={null}
const topComment = await sublay.entities.fetchTopComment({
  entityId: "ent_xyz789",
});
```

<ParamField type="string">
  The Sublay entity ID.
</ParamField>

**Returns** — `Promise<TopComment | null>`

***

### addReaction

Adds a reaction from a user to an entity.

```typescript theme={null}
const reaction = await sublay.entities.addReaction({
  entityId: "ent_xyz789",
  userId: "usr_abc123",
  reactionType: "like",
});
```

<ParamField type="string">
  The Sublay entity ID.
</ParamField>

<ParamField type="string">
  The Sublay user ID of the reactor.
</ParamField>

<ParamField type="ReactionType">
  One of: `"upvote"`, `"downvote"`, `"like"`, `"love"`, `"wow"`, `"sad"`, `"angry"`, `"funny"`.
</ParamField>

**Returns** — `Promise<Reaction>`

***

### removeReaction

Removes a user's existing reaction from an entity.

```typescript theme={null}
await sublay.entities.removeReaction({
  entityId: "ent_xyz789",
  userId: "usr_abc123",
});
```

<ParamField type="string">
  The Sublay entity ID.
</ParamField>

<ParamField type="string">
  The Sublay user ID whose reaction to remove.
</ParamField>

**Returns** — `Promise<void>`

***

### fetchReactions

Fetches a paginated list of reactions on an entity, optionally filtered by reaction type.

```typescript theme={null}
const { data, pagination } = await sublay.entities.fetchReactions({
  entityId: "ent_xyz789",
  reactionType: "like",
  page: 1,
  limit: 20,
});
```

<ParamField type="string">
  The Sublay entity ID.
</ParamField>

<ParamField type="ReactionType">
  Filter to a specific reaction type.
</ParamField>

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Defaults to `20`.
</ParamField>

<ParamField type="string">
  Sort direction: `"asc"` or `"desc"`.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<PaginatedResponse<Reaction>>`

***

### getUserReaction

Checks what reaction (if any) a specific user has left on an entity.

```typescript theme={null}
const { reactionType } = await sublay.entities.getUserReaction({
  entityId: "ent_xyz789",
  userId: "usr_abc123",
});
// reactionType is "like" | "upvote" | ... | null
```

<ParamField type="string">
  The Sublay entity ID.
</ParamField>

<ParamField type="string">
  The Sublay user ID to check.
</ParamField>

**Returns** — `Promise<{ reactionType: ReactionType | null }>`

***

### isEntitySaved

Checks whether a user has saved an entity to any of their collections.

```typescript theme={null}
const { isSaved } = await sublay.entities.isEntitySaved({
  entityId: "ent_xyz789",
  userId: "usr_abc123",
});
```

<ParamField type="string">
  The Sublay entity ID.
</ParamField>

<ParamField type="string">
  The Sublay user ID to check.
</ParamField>

**Returns** — `Promise<{ isSaved: boolean }>`


# Events
Source: https://docs.sublay.io/v7/node-sdk/events

Create and manage events, RSVPs, hosts, and invites from the server

The `events` module covers the full events surface: creating and editing events, the RSVP lifecycle, host and invite management, and the guest list. It maps directly to the [Events API](/api-reference/events/create-event).

Because the Node SDK authenticates with a **service key** (it acts as the whole project, not a single end user), most write functions take an explicit `userId` naming the user the action is performed as. For host- and invite-management functions, `userId` is instead the **target** user (the host/invitee), and the action is authorized as the project.

<Note>
  **Image upload caveat.** The Node SDK does not support inline cover/gallery
  upload on `createEvent`/`updateEvent` yet. Create the event first, then attach
  images with [`sublay.storage.uploadImage`](/v7/node-sdk/storage) using its
  `eventId` parameter. (The browser [JS SDK](/v7/js-sdk/events) and the
  [React SDK](/sdk/events/overview) do support inline upload.)
</Note>

Requires the `events` bundle. Space-scoping needs the `spaces` bundle; images need `files-images`; notifications need `notifications`.

***

### createEvent

Creates an event. The `userId` you pass becomes the creator and is auto-added to `hostIds`. Returns the event with inline `rsvpCounts`.

```typescript theme={null}
const event = await sublay.events.createEvent({
  userId: "usr_abc123",
  title: "Launch Party",
  type: "physical",
  startTime: "2026-09-01T18:00:00.000Z",
  endTime: "2026-09-01T22:00:00.000Z",
  timezone: "America/New_York",
  venueName: "The Loft",
  address: "123 Main St, New York, NY",
  location: { latitude: 40.7128, longitude: -74.006 },
  capacity: 100,
  visibility: "public",
});
```

<ParamField type="string">Event title. 1–300 characters.</ParamField>
<ParamField type="string">ISO datetime when the event starts.</ParamField>

<ParamField type="&#x22;online&#x22; | &#x22;physical&#x22; | &#x22;hybrid&#x22;">
  Event format. `online` requires `url`; `physical` requires `address` or `location`; `hybrid` requires both.
</ParamField>

<ParamField type="string">
  The user to create the event as (creator + first host). With a service key this may be any user.
</ParamField>

<ParamField type="string">Optional description.</ParamField>
<ParamField type="string">Optional ISO end datetime.</ParamField>
<ParamField type="string">Optional IANA timezone.</ParamField>
<ParamField type="string">Join/stream URL.</ParamField>
<ParamField type="string">Venue name.</ParamField>
<ParamField type="string">Street address.</ParamField>
<ParamField type="{ latitude: number; longitude: number }">Coordinates for proximity search.</ParamField>
<ParamField type="string">Scope the event to a space. Required when `visibility` is `"members"`.</ParamField>
<ParamField type="&#x22;public&#x22; | &#x22;members&#x22; | &#x22;invite&#x22;">Defaults to `"public"`.</ParamField>
<ParamField type="number">Max `going` RSVPs. Omit for unlimited.</ParamField>
<ParamField type="boolean">Allow `"maybe"` RSVPs. Defaults to `true`.</ParamField>
<ParamField type="boolean">Expose the named guest list to non-hosts. Defaults to `true`.</ParamField>
<ParamField type="string[]">Additional host user IDs (the creator is always added).</ParamField>
<ParamField type="object">Arbitrary key-value data. Up to 1 MB.</ParamField>

**Returns** — `Promise<Event>`

***

### fetchEvent

Fetches a single event by ID. Pass `userId` to resolve visibility for that user and to populate `userRsvp` (with the `userRsvp` include).

```typescript theme={null}
const event = await sublay.events.fetchEvent({
  eventId: "evt_abc123",
  include: "user,space,files,userRsvp",
  userId: "usr_abc123",
});
```

<ParamField type="string">The event ID.</ParamField>
<ParamField type="string">Comma-separated associations: `"user"`, `"space"`, `"files"`, `"userRsvp"`.</ParamField>
<ParamField type="string">The requester id, for visibility resolution and `userRsvp` enrichment.</ParamField>

**Returns** — `Promise<Event>`

***

### fetchManyEvents

Lists events with visibility enforced, plus filtering, sorting, geo, and free-text search. Pass `userId` to resolve member/invite/host visibility and to use the `myRsvp` filter.

```typescript theme={null}
const { data, pagination } = await sublay.events.fetchManyEvents({
  timeWindow: "upcoming",
  sortBy: "startTime",
  sortDir: "asc",
  type: "physical",
  page: 1,
  limit: 20,
  userId: "usr_abc123",
  include: "user,userRsvp",
});
```

<ParamField type="number">Page number (1-indexed). Defaults to `1`.</ParamField>
<ParamField type="number">Results per page. Capped at `100`.</ParamField>
<ParamField type="&#x22;startTime&#x22; | &#x22;going&#x22;">Sort field. Defaults to `"startTime"`.</ParamField>
<ParamField type="&#x22;asc&#x22; | &#x22;desc&#x22;">Sort direction. Defaults to `"asc"`.</ParamField>
<ParamField type="&#x22;upcoming&#x22; | &#x22;ongoing&#x22; | &#x22;past&#x22;">Derived time window.</ParamField>
<ParamField type="string">ISO datetime lower bound on `startTime`.</ParamField>
<ParamField type="string">ISO datetime upper bound on `startTime`.</ParamField>
<ParamField type="string">Restrict to one space.</ParamField>
<ParamField type="string">Only events this user hosts.</ParamField>
<ParamField type="&#x22;online&#x22; | &#x22;physical&#x22; | &#x22;hybrid&#x22;">Filter by type.</ParamField>
<ParamField type="&#x22;active&#x22; | &#x22;cancelled&#x22;">Defaults to `"active"`.</ParamField>
<ParamField type="string">Comma-separated statuses the requester RSVP'd with, e.g. `"going,maybe"`. Requires `userId`.</ParamField>
<ParamField type="{ latitude: string; longitude: string; radius: string }">Proximity filter (radius in meters).</ParamField>
<ParamField type="{ hasTitle?; includes?; doesNotInclude? }">Free-text filter on `title`.</ParamField>
<ParamField type="{ hasDescription?; includes?; doesNotInclude? }">Free-text filter on `description`.</ParamField>
<ParamField type="string">Comma-separated associations.</ParamField>
<ParamField type="string">The requester id (visibility + `myRsvp` + `userRsvp`).</ParamField>

**Returns** — `Promise<PaginatedResponse<Event>>`

***

### updateEvent

Edits an event's mutable fields. Host-only at the API level; with a service key the call is authorized as the project. `hostIds`, `status`, and `spaceId` are not editable here.

```typescript theme={null}
const event = await sublay.events.updateEvent({
  eventId: "evt_abc123",
  capacity: 150,
  description: "Now with more space!",
});
```

<ParamField type="string">The event ID.</ParamField>
<ParamField type="string">New title.</ParamField>
<ParamField type="string">New description.</ParamField>
<ParamField type="string">New ISO start datetime.</ParamField>
<ParamField type="string">New ISO end datetime.</ParamField>
<ParamField type="string">New timezone.</ParamField>
<ParamField type="&#x22;online&#x22; | &#x22;physical&#x22; | &#x22;hybrid&#x22;">New type (re-validates location fields).</ParamField>
<ParamField type="string">New URL.</ParamField>
<ParamField type="string">New venue name.</ParamField>
<ParamField type="string">New address.</ParamField>
<ParamField type="{ latitude: number; longitude: number }">New coordinates.</ParamField>
<ParamField type="&#x22;public&#x22; | &#x22;members&#x22; | &#x22;invite&#x22;">New visibility.</ParamField>
<ParamField type="number">New capacity.</ParamField>
<ParamField type="boolean">Allow `"maybe"` RSVPs.</ParamField>
<ParamField type="boolean">Expose the guest list.</ParamField>
<ParamField type="object">New metadata.</ParamField>

**Returns** — `Promise<Event>`

***

### cancelEvent

Cancels an event (sets `status: "cancelled"`). The event stays fetchable but rejects new RSVPs.

```typescript theme={null}
const event = await sublay.events.cancelEvent({ eventId: "evt_abc123" });
```

<ParamField type="string">The event ID.</ParamField>

**Returns** — `Promise<Event>`

***

### deleteEvent

Permanently (or soft-, per the project's `eventDeletion` settings) deletes an event and cleans up its RSVPs and invites.

```typescript theme={null}
await sublay.events.deleteEvent({ eventId: "evt_abc123" });
```

<ParamField type="string">The event ID.</ParamField>

**Returns** — `Promise<void>`

***

### setRsvp

Sets or changes a user's RSVP. Transitions into `going` are capacity-checked.

```typescript theme={null}
const event = await sublay.events.setRsvp({
  eventId: "evt_abc123",
  status: "going",
  userId: "usr_abc123",
});
```

<ParamField type="string">The event ID.</ParamField>
<ParamField type="&#x22;going&#x22; | &#x22;maybe&#x22; | &#x22;not_going&#x22;">The RSVP response.</ParamField>
<ParamField type="string">The user to RSVP as. With a service key this may be any user.</ParamField>

**Returns** — `Promise<Event>` (with refreshed `rsvpCounts`)

***

### withdrawRsvp

Removes a user's RSVP. Idempotent.

```typescript theme={null}
const event = await sublay.events.withdrawRsvp({
  eventId: "evt_abc123",
  userId: "usr_abc123",
});
```

<ParamField type="string">The event ID.</ParamField>
<ParamField type="string">The user to withdraw. With a service key this may be any user.</ParamField>

**Returns** — `Promise<Event>`

***

### addHost

Grants a user host privileges. The `userId` is the **target** host; the action is authorized as the project.

```typescript theme={null}
const event = await sublay.events.addHost({
  eventId: "evt_abc123",
  userId: "usr_cohost",
});
```

<ParamField type="string">The event ID.</ParamField>
<ParamField type="string">The user to grant host on the event.</ParamField>

**Returns** — `Promise<Event>`

***

### removeHost

Revokes a user's host privileges. Rejected if it would leave the event with no hosts.

```typescript theme={null}
const event = await sublay.events.removeHost({
  eventId: "evt_abc123",
  userId: "usr_cohost",
});
```

<ParamField type="string">The event ID.</ParamField>
<ParamField type="string">The host to remove.</ParamField>

**Returns** — `Promise<Event>`

***

### addInvite

Invites a user to the event. Idempotent. The `userId` is the **target** invitee.

```typescript theme={null}
const event = await sublay.events.addInvite({
  eventId: "evt_abc123",
  userId: "usr_guest",
});
```

<ParamField type="string">The event ID.</ParamField>
<ParamField type="string">The user to invite (userId only — never a foreign ID).</ParamField>

**Returns** — `Promise<Event>`

***

### removeInvite

Removes a user's invite, revoking their access and dropping their RSVP.

```typescript theme={null}
const event = await sublay.events.removeInvite({
  eventId: "evt_abc123",
  userId: "usr_guest",
});
```

<ParamField type="string">The event ID.</ParamField>
<ParamField type="string">The invitee to remove.</ParamField>

**Returns** — `Promise<Event>`

***

### fetchInvitees

Host-only invitee (guest) list. Returns paginated [EventInvite](/data-models/event-invite) records with the invited user populated.

```typescript theme={null}
const { data, pagination } = await sublay.events.fetchInvitees({
  eventId: "evt_abc123",
  page: 1,
  limit: 20,
});
```

<ParamField type="string">The event ID.</ParamField>
<ParamField type="number">Page number (1-indexed).</ParamField>
<ParamField type="number">Results per page. Capped at `100`.</ParamField>

**Returns** — `Promise<PaginatedResponse<EventInvite>>`

***

### fetchEventRsvps

Named RSVP (guest) list. Returns paginated [EventRsvp](/data-models/event-rsvp) records with the user populated. Visible to hosts always, to any viewer when `guestListVisible` is `true`, or to service keys. RSVP counts themselves are public via the event's `rsvpCounts`.

```typescript theme={null}
const { data, pagination } = await sublay.events.fetchEventRsvps({
  eventId: "evt_abc123",
  status: "going,maybe",
  page: 1,
  limit: 20,
});
```

<ParamField type="string">The event ID.</ParamField>
<ParamField type="string">Comma-separated statuses to filter by, e.g. `"going,maybe"`. Omit for all.</ParamField>
<ParamField type="number">Page number (1-indexed).</ParamField>
<ParamField type="number">Results per page. Capped at `100`.</ParamField>

**Returns** — `Promise<PaginatedResponse<EventRsvp>>`

***

## Attaching images

Create the event, then upload a cover or gallery image and associate it with `eventId`:

```typescript theme={null}
import { readFile } from "node:fs/promises";

const event = await sublay.events.createEvent({
  userId: "usr_abc123",
  title: "Launch Party",
  type: "online",
  url: "https://meet.example.com/launch",
  startTime: "2026-09-01T18:00:00.000Z",
});

const buffer = await readFile("./cover.jpg");
await sublay.storage.uploadImage({
  file: new Uint8Array(buffer),
  filename: "cover.jpg",
  mimeType: "image/jpeg",
  imageOptions: { mode: "original-aspect", sizes: { full: 1600 }, format: "webp" },
  eventId: event.id,
  userId: "usr_abc123",
});
```

<Note>
  Uploading via `storage.uploadImage` attaches a gallery image (a `File` with the
  event's `eventId`). Setting it as the event's single cover (`coverImageId`) is
  done by the inline-upload path, which the Node SDK does not yet expose.
</Note>


# Follows
Source: https://docs.sublay.io/v7/node-sdk/follows

Read a user's follow graph and remove follows by ID from your server

The `follows` module reads a user's follow graph — the users they follow and the users following them — and removes follow relationships by ID.

<Note>
  Every function acts on behalf of a named user. Pass that user's Sublay ID as
  `userId` — the returned graph and counts are from that user's perspective.
</Note>

<Tip>
  To **create** a follow (or unfollow by target user ID, or check follow status),
  use the nested routes on the [`users`](/v7/node-sdk/users) module
  (`createFollow`, `deleteFollow`, `fetchFollowStatus`), which take an
  `actingUserId`.
</Tip>

***

### fetchFollowing

Returns a paginated list of the follow records for users the given user follows.

```typescript theme={null}
const { data, pagination } = await sublay.follows.fetchFollowing({
  userId: "usr_abc123",
  page: 1,
  limit: 20,
});
```

<ParamField type="string">
  The Sublay user ID whose following list to fetch.
</ParamField>

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Defaults to `20`.
</ParamField>

<ParamField type="string">
  Optional search term. Filters the list to users whose username or name contains this text (case-insensitive). When omitted, no filtering is applied.
</ParamField>

<ParamField type="string">
  Restricts which field `query` matches against — `username` or `name`. When omitted, `query` matches either field.
</ParamField>

**Returns** — `Promise<PaginatedResponse<Follow>>`

***

### fetchFollowers

Returns a paginated list of the follow records for users that follow the given user.

```typescript theme={null}
const { data, pagination } = await sublay.follows.fetchFollowers({
  userId: "usr_abc123",
  page: 1,
  limit: 20,
});
```

<ParamField type="string">
  The Sublay user ID whose followers list to fetch.
</ParamField>

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Defaults to `20`.
</ParamField>

<ParamField type="string">
  Optional search term. Filters the list to users whose username or name contains this text (case-insensitive). When omitted, no filtering is applied.
</ParamField>

<ParamField type="string">
  Restricts which field `query` matches against — `username` or `name`. When omitted, `query` matches either field.
</ParamField>

**Returns** — `Promise<PaginatedResponse<Follow>>`

***

### fetchFollowingCount

Returns the number of users the given user follows.

```typescript theme={null}
const { count } = await sublay.follows.fetchFollowingCount({
  userId: "usr_abc123",
});
```

<ParamField type="string">
  The Sublay user ID.
</ParamField>

**Returns** — `Promise<{ count: number }>`

***

### fetchFollowersCount

Returns the number of users following the given user.

```typescript theme={null}
const { count } = await sublay.follows.fetchFollowersCount({
  userId: "usr_abc123",
});
```

<ParamField type="string">
  The Sublay user ID.
</ParamField>

**Returns** — `Promise<{ count: number }>`

***

### deleteFollow

Deletes a follow relationship by its follow record ID.

```typescript theme={null}
await sublay.follows.deleteFollow({
  followId: "fol_xyz789",
  userId: "usr_abc123",
});
```

<ParamField type="string">
  The ID of the follow record to delete.
</ParamField>

<ParamField type="string">
  The Sublay user ID on whose behalf the follow is removed (must be the follower).
</ParamField>

**Returns** — `Promise<void>`


# Node.js SDK
Source: https://docs.sublay.io/v7/node-sdk/overview

Server-side SDK for Sublay — use in backend APIs, server actions, webhooks, and scheduled jobs

The `@sublay/node` SDK gives you full programmatic access to the Sublay API from any Node.js environment. It is designed for **server-side use only** — backend endpoints, Next.js server actions, webhook handlers, cron jobs, and scripts.

<Note>
  This SDK requires a **secret API key** and must never be used in client-side
  code or shipped to the browser.
</Note>

## Installation

```bash theme={null}
npm install @sublay/node
```

## Initialization

Create a single `SublayClient` instance at startup and reuse it throughout your application.

```typescript theme={null}
import { SublayClient } from "@sublay/node";

const sublay = await SublayClient.init({
  projectId: process.env.SUBLAY_PROJECT_ID!,
  apiKey: process.env.SUBLAY_API_KEY!,
});
```

### Configuration

<ParamField type="string">
  Your Sublay project ID, found in the dashboard under **Settings → General**.
</ParamField>

<ParamField type="string">
  Your secret API key from the dashboard. Keep this in an environment variable —
  never commit it to source control.
</ParamField>

<ParamField type="boolean">
  Set to `true` when making internal/admin requests that bypass standard project
  authorization. Defaults to `false`.
</ParamField>

## Modules

Once initialized, all functionality is accessed through module namespaces on the client:

```typescript theme={null}
sublay.auth              // Authentication — sign up, sign in, tokens, passwords
sublay.users             // User profiles, follow/connection actions
sublay.entities          // Content entities — CRUD, reactions, drafts
sublay.comments          // Comments — CRUD, reactions
sublay.collections       // Saved-content collections
sublay.follows           // Follow graph — followers, following, counts
sublay.connections       // Mutual connections and requests
sublay.spaces            // Spaces — management, members, moderation, rules
sublay.events            // Events — RSVPs, hosts, invites, guest list
sublay.chat              // Conversations, messages, members, reactions, read state
sublay.search            // Search and AI Q&A
sublay.reports           // Content reports and the moderation queue
sublay.appNotifications  // In-app notification feed
sublay.storage           // File and image uploads, read, delete
```

## Acting on behalf of a user

Your service key authenticates as the project, not as any single end user. So functions that operate **on a user's behalf** take an explicit `userId` — the named user the action is performed as (saving to a collection, reading a notification feed, filing a report, listing connections).

A few routes — on the `users` module (following someone, requesting a connection) and on `chat` (`createDirectConversation`, `addMember`, `removeMember`, `changeMemberRole`) — act on one user toward another. There the **target** is `userId` and the **actor** is passed separately as `actingUserId`.

<Note>
  `oauth` is intentionally not exposed by this SDK (it's a browser redirect flow).
</Note>

<CardGroup>
  <Card title="Auth" icon="lock" href="/v7/node-sdk/auth">
    Sign up, sign in, token management, password reset
  </Card>

  <Card title="Users" icon="user" href="/v7/node-sdk/users">
    Fetch, update and delete profiles, follow and connection actions
  </Card>

  <Card title="Entities" icon="file" href="/v7/node-sdk/entities">
    Create and manage content, reactions, drafts
  </Card>

  <Card title="Comments" icon="comment" href="/v7/node-sdk/comments">
    Create and manage comments, reactions
  </Card>

  <Card title="Collections" icon="folder" href="/v7/node-sdk/collections">
    Organize a user's saved entities into collections
  </Card>

  <Card title="Follows" icon="user-plus" href="/v7/node-sdk/follows">
    Read a user's follow graph and counts
  </Card>

  <Card title="Connections" icon="link" href="/v7/node-sdk/connections">
    Mutual connections, pending requests, accept/decline
  </Card>

  <Card title="Spaces" icon="layer-group" href="/v7/node-sdk/spaces">
    Space CRUD, navigation, slug management
  </Card>

  <Card title="Space Members" icon="users" href="/v7/node-sdk/spaces-members">
    Membership, roles, approvals, bans
  </Card>

  <Card title="Space Moderation" icon="shield" href="/v7/node-sdk/spaces-moderation">
    Reports, content moderation, rules
  </Card>

  <Card title="Chat" icon="message" href="/v7/node-sdk/chat">
    Conversations, messages, members, reactions, read state
  </Card>

  <Card title="Search" icon="magnifying-glass" href="/v7/node-sdk/search">
    Full-text search and AI-powered Q\&A
  </Card>

  <Card title="Reports" icon="flag" href="/v7/node-sdk/reports">
    File content reports and read the moderation queue
  </Card>

  <Card title="App Notifications" icon="bell" href="/v7/node-sdk/app-notifications">
    Read and mark a user's in-app notifications
  </Card>

  <Card title="Storage" icon="upload" href="/v7/node-sdk/storage">
    Upload, fetch, and delete files and images
  </Card>
</CardGroup>

## Paginated Responses

Functions that return lists use a shared `PaginatedResponse<T>` shape:

```typescript theme={null}
{
  data: T[];
  pagination: {
    page: number;
    pageSize: number;
    totalPages: number;
    totalItems: number;
    hasMore: boolean;
  };
}
```

Pass `page` and `limit` to any list function to control pagination.


# Push Notifications
Source: https://docs.sublay.io/v7/node-sdk/push-notifications

Send push notifications to your users' registered devices from your backend

The `push` module lets your backend fan a notification out to every registered device belonging to one or more users — across iOS (APNs), Android (FCM), and Web Push — in a single call.

<Note>
  Requires the `push` bundle and configured provider credentials (APNs, FCM, or Web Push) in the project dashboard. See [Push Notifications](/push-notifications) for the full setup guide.
</Note>

***

### send

Sends a push notification to all registered devices for the given user IDs. Dispatches to APNs, FCM, and Web Push in parallel.

```typescript theme={null}
const result = await sublay.push.send({
  userIds: ["usr_abc123", "usr_def456"],
  title: "New message",
  body: "You have a new message from Alice.",
  data: { conversationId: "conv_xyz789" },
  sound: "notification.wav",
  channelId: "messages",
  badge: 3,
  tag: "conv_xyz789",
});
```

<ParamField type="string[]">
  Sublay user IDs to notify. Maximum 100 per call.
</ParamField>

<ParamField type="string">
  Notification title shown on the device.
</ParamField>

<ParamField type="string">
  Notification body text.
</ParamField>

<ParamField type="Record<string, any>">
  Optional key-value payload forwarded to the app alongside the notification. Use for deep links, entity IDs, or any context your app needs when the user taps.

  **`recipientUserId` is reserved.** Sublay stamps every dispatched copy with the id of the account it is for, so a device signed into several accounts can tell which one a notification belongs to. A value you set under that key is overwritten — an account-routing key has to be trustworthy.
</ParamField>

<Note>
  **One notification per account, not per device.** A physical device can be bound to several accounts at once. If two of the `userIds` are signed in on the same device, that device receives two notifications — one per account, each carrying its own `recipientUserId`.
</Note>

#### Rich payload fields

All optional. Each maps to whichever platform(s) support it and is silently ignored elsewhere (e.g. `subtitle`/`threadId` are iOS-only, `channelId` is Android-only). See [Rich notification payloads](/push-notifications#rich-notification-payloads) for the platform setup each one needs.

<ParamField type="string">
  Sound file to play. **iOS:** APNs `sound`. **Android:** on 8+ the sound is owned by the notification channel — pair this with `channelId` and create that channel client-side with the sound set. **Web:** forwarded to your service worker.
</ParamField>

<ParamField type="number">
  iOS app-icon badge count (APNs `badge`). No Android equivalent. Your backend supplies the number — Sublay does not track per-user unread counts.
</ParamField>

<ParamField type="string">
  Android notification channel id (FCM). The channel must be created client-side; on Android 8+ it governs sound, importance, and vibration.
</ParamField>

<ParamField type="&#x22;high&#x22; | &#x22;normal&#x22;">
  Delivery priority. `high` (the default when omitted) wakes the device for time-sensitive pushes; `normal` is power-considerate. Maps to APNs `apns-priority` and FCM `android.priority`.
</ParamField>

<ParamField type="string">
  iOS subtitle line shown under the title (APNs `alert.subtitle`).
</ParamField>

<ParamField type="string">
  Rich/big-picture image URL. Works out of the box on **Android** (FCM) and **Web**. On **iOS** it additionally requires a [Notification Service Extension](https://developer.apple.com/documentation/usernotifications/unnotificationserviceextension) in your app; the URL is forwarded in the payload and `mutable-content` is set automatically.
</ParamField>

<ParamField type="string">
  Display-replace key so notifications collapse in the UI instead of stacking (FCM `android.notification.tag`, Web `tag`). Use a per-conversation value to keep one entry per thread. Scoped per recipient, like `collapseId` below.
</ParamField>

<ParamField type="string">
  Transport-level collapse identifier (APNs `apns-collapse-id`, FCM `collapse_key`) — a newer push supersedes an undelivered one with the same id **for the same account**.

  Both keys are scoped to the recipient before they reach the provider: two accounts signed in on one physical device share a single transport destination, so the server appends a short digest of the recipient's id and each account collapses only against itself. That means the device receives a different string than you sent — client code reading the delivered `tag` must match on a prefix rather than on equality, or carry its own key in `data`, which is passed through untouched. An over-length `collapseId` is folded into a fixed-width digest rather than refused by APNs — see [the endpoint reference](/api-reference/push-notifications/send).
</ParamField>

<ParamField type="string">
  iOS notification grouping (APNs `thread-id`).
</ParamField>

<ParamField type="number">
  Time-to-live in **seconds** for offline devices (APNs `apns-expiration`, FCM `android.ttl`). After this window the provider stops retrying.
</ParamField>

<ParamField type="boolean">
  iOS `mutable-content` flag, letting your Notification Service Extension modify the payload (e.g. attach `imageUrl`). Set implicitly when `imageUrl` is provided.
</ParamField>

**Returns** — `Promise<SendPushResult>`

```typescript theme={null}
interface SendPushResult {
  results: Record<string, PushDeviceResult[]>;
}

interface PushDeviceResult {
  platform: string;   // "ios" | "android" | "web"
  success: boolean;
  reason?: string;    // present when success is false
}
```

Every requested `userId` is present in `results` — users with no registered devices get an empty array. Device tokens permanently rejected by the upstream provider are automatically removed; you don't need a separate cleanup step. A dead token is dead for the whole device, so removal unbinds **every** account registered on it, including accounts outside this call.

**Example response:**

```json theme={null}
{
  "results": {
    "usr_abc123": [
      { "platform": "ios", "success": true },
      { "platform": "web", "success": true }
    ],
    "usr_def456": [],
    "usr_ghi789": [
      { "platform": "android", "success": false, "reason": "credentials_not_configured" }
    ]
  }
}
```

Common `reason` values when `success` is `false`:

| Reason                       | Meaning                                                               |
| ---------------------------- | --------------------------------------------------------------------- |
| `credentials_not_configured` | No provider credentials are configured (or enabled) for this platform |
| Provider error codes         | APNs, FCM, or Web Push returned a delivery error                      |

***

## Notification preferences

Read and update a user's per-type push preferences — the set of event types they've disabled for push. See [Notification Preferences & Mute](/notification-preferences) for the model and the full event palette.

<Note>
  These endpoints are **per-user**. The Node SDK authenticates with a service key, so — exactly like the other per-user operations — you name the user with an explicit `userId` and the SDK acts on that user's behalf. (End-user-token clients, such as the React hooks and the browser JS SDK, act on the signed-in user and omit `userId`.)
</Note>

### getNotificationPreferences

Reads a user's disabled push types. Returns an empty array (all-on) when no preferences are set.

```typescript theme={null}
const { disabledTypes } = await sublay.push.getNotificationPreferences({
  userId: "usr_abc123",
});
```

<ParamField type="string">
  The user whose preferences to read.
</ParamField>

**Returns** — `Promise<NotificationPreferences>`

```typescript theme={null}
interface NotificationPreferences {
  disabledTypes: PushEventType[]; // e.g. ["new-follow", "message"]
}
```

***

### updateNotificationPreferences

Replaces a user's disabled-types set (upsert). Send the **complete** set you want stored, not a delta; only valid event type names are accepted.

```typescript theme={null}
import { PUSH_EVENT_TYPES } from "@sublay/node";

await sublay.push.updateNotificationPreferences({
  disabledTypes: ["comment-mention", "message"],
  userId: "usr_abc123",
});
```

<ParamField type="PushEventType[]">
  The complete set of event types to disable for push. Values must be from `PUSH_EVENT_TYPES` (see the [event palette](/notification-preferences#the-event-palette)); unknown names are rejected. Pass `[]` to re-enable everything.
</ParamField>

<ParamField type="string">
  The user whose preferences to write.
</ParamField>

**Returns** — `Promise<NotificationPreferences>` (the stored, deduplicated set).

***

## Conversation mute

Setting or clearing a conversation mute lives on the **`chat`** module (it's a `/chat/...` route): [`chat.muteConversation`](/node-sdk/chat#muteconversation). Like the preference endpoints it is per-user — name the acting user with `userId` — and takes a duration **choice**, never a timestamp.


# Reports
Source: https://docs.sublay.io/v7/node-sdk/reports

File content reports on behalf of a user and read the moderated report queue from your server

The `reports` module lets a user report an entity, comment, or chat message, and lets moderators read the queue of reports they're responsible for.

<Note>
  Both functions act on behalf of a named user. Pass that user's Sublay ID as
  `userId` — for `createReport` this is the reporter; for `fetchModeratedReports`
  it is the moderator whose queue is returned.
</Note>

***

### createReport

Files a report against an entity, comment, or chat message on behalf of a user. If the same user has already reported the same target, the existing report is updated rather than duplicated.

```typescript theme={null}
const result = await sublay.reports.createReport({
  userId: "usr_abc123",
  targetType: "comment",
  targetId: "cmt_abc123",
  reason: "spam",
  details: "Posting the same link repeatedly.",
});
```

<ParamField type="string">
  The Sublay user ID filing the report (the reporter).
</ParamField>

<ParamField type="string">
  What is being reported: `"entity"`, `"comment"`, or `"message"`.
</ParamField>

<ParamField type="string">
  The Sublay ID of the entity, comment, or chat message being reported.
</ParamField>

<ParamField type="ReportReason">
  One of `spam`, `inappropriateContent`, `harassment`, `misinformation`,
  `hateSpeech`, `violence`, `illegalActivity`, `selfHarm`, `other`. The API
  rejects anything else — use `other` plus `details` for the rest.
</ParamField>

<ParamField type="string">
  Optional free-text details about the report.
</ParamField>

<Note>
  Reporting a chat message uses `targetType: "message"` with the **message id**
  as `targetId` — the conversation is resolved server-side. Reports on space
  conversations reach space moderators; reports on DMs and group chats are
  project-level and appear only in the Sublay dashboard.
</Note>

**Returns** — `Promise<CreateReportResponse>`

```typescript theme={null}
{
  message: string;
  code: "report/created" | "report/updated" | "report/already-reported";
}
```

***

### fetchModeratedReports

Returns a paginated list of reports in the spaces the user moderates. Each report is aggregated across all users who reported the same target, and is populated with the target content and space.

```typescript theme={null}
const { data, pagination } = await sublay.reports.fetchModeratedReports({
  userId: "usr_mod123",
  status: "pending",
  targetType: "entity",
  sortBy: "new",
  page: 1,
  limit: 20,
});
```

<ParamField type="string">
  The Sublay user ID of the moderator whose queue to fetch.
</ParamField>

<ParamField type="string">
  Filter to reports within a specific space.
</ParamField>

<ParamField type="string">
  Filter by target type: `"entity"`, `"comment"`, or `"message"`. Message
  reports appear in this queue only for space conversations — DM and group
  reports are project-level and surface in the dashboard.
</ParamField>

<ParamField type="string">
  Filter by report status: `"pending"`, `"on-hold"`, `"escalated"`, `"dismissed"`, or `"actioned"`.
</ParamField>

<ParamField type="string">
  Sort order: `"new"` (most recent first) or `"old"` (oldest first).
</ParamField>

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Defaults to `20`.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<PaginatedResponse<Report>>`

<Note>
  To act on a report (remove content, ban the author, or dismiss it), use
  `handleEntityReport` / `handleCommentReport` on the
  [Space Moderation](/v7/node-sdk/spaces-moderation) module.
</Note>


# Reputation
Source: https://docs.sublay.io/v7/node-sdk/reputation

Transfer, mint, and list reputation grants from the server

The `reputation` module moves reputation deliberately: **transfers** between two users, **mints** that create reputation from nothing (or destroy it), and reads of the grant history. It maps directly to the [Reputation Grants API](/api-reference/reputation-grants/create-reputation-grant).

Because the Node SDK authenticates with a **service key** (it acts as the whole project, not a single end user), `createGrant` takes an explicit `actingUserId` naming the sender. This is the *mediated transfer* path: it behaves exactly like a user-initiated grant — same bucket routing, same balance check — but it lets your backend enforce its own rules first (caps, cooldowns, daily limits, eligibility), which Sublay deliberately does not impose.

Two things a service key does **not** get you here:

* **Mediated transfers still respect the sender's balance.** Only `mintGrant` can create reputation or drive a bucket below zero.
* **Negative grants are not readable through `listGrants`.** The `amount > 0` filter applies to every caller, service keys included. Read them from the [dashboard grant-history route](/api-reference/reputation-grants/fetch-user-grant-history).

Requires the `reputation` bundle. A `chat-message` target additionally needs the `chat` bundle, and a `spaceId` needs the `spaces` bundle. `createGrant` and `mintGrant` validate `spaceId` identically: an ID naming no space is rejected with `404 reputation-grant/space-not-found` before anything moves, and naming a space on a project without `spaces` is rejected with `403 database/tables-not-available`.

***

### createGrant

Transfers reputation from one user to another — the amount leaves the sender's bucket and lands in the recipient's bucket for the same space. Nothing is created.

Mediated transfers skip the project's user-grants switch and ignore block relationships between the two parties.

```typescript theme={null}
const grant = await sublay.reputation.createGrant({
  actingUserId: "usr_abc123",
  recipientId: "usr_def456",
  amount: 50,
  spaceId: "spc_789",
  note: "Bounty payout",
  targetType: "comment",
  targetId: "cmt_012",
});
```

<ParamField type="string">
  The **sender** — the user reputation is debited from. Spelled `actingUserId` rather than `userId` because the body already names a target user (`recipientId`).
</ParamField>

<ParamField type="string">The user credited. Must differ from `actingUserId`.</ParamField>

<ParamField type="number">
  Whole number from `1` to `2147483647` (the signed 32-bit maximum). Never zero, negative, or fractional — use `mintGrant` to create or destroy reputation. It can never exceed what the sender holds in the source bucket.
</ParamField>

<ParamField type="string | null">
  The bucket both legs move in. Omitted or `null` = the project-general bucket. Reputation never crosses between the general bucket and a space bucket. Validated: an unknown space is rejected with `404 reputation-grant/space-not-found`.
</ParamField>

<ParamField type="string | null">Free-text note. Trimmed, up to 2000 characters.</ParamField>
<ParamField type="object">Arbitrary key-value data. Up to 1 MB. Omit when unused.</ParamField>

<ParamField type="&#x22;entity&#x22; | &#x22;comment&#x22; | &#x22;chat-message&#x22;">
  What the grant is for. Supplied together with `targetId`. An annotation only — it never determines which bucket is used, and need not be authored by the recipient.
</ParamField>

<ParamField type="string">The rewarded record's ID. Supplied together with `targetType`, and must exist.</ParamField>

**Returns** — `Promise<ReputationGrant>` with `sourceType: "user"`.

Throws `409 reputation-grant/insufficient-reputation` when the sender's bucket is short — nothing moves; that is also the answer when the named space is real but the sender holds no funded bucket in it. A mediated transfer is still checked against the sender's suspension and, for a `chat-message` target, against the sender's active membership of that conversation. A grant is **not idempotent**: a retried call moves the points a second time.

***

### mintGrant

Creates reputation from nothing and credits a user. There is no sender and nothing is debited; the grant is written with a `null` `senderId` and `sourceType: "app"`.

A **negative** amount destroys reputation instead — the moderation clawback, decay sweep, or correction path. It is the only operation permitted to drive a bucket below zero, and it is entirely silent: no notification, no socket broadcast, and invisible on every public read surface.

```typescript theme={null}
// Contest payout
await sublay.reputation.mintGrant({
  recipientId: "usr_def456",
  amount: 500,
  note: "Hackathon winner",
});

// Reversing a mistaken grant
await sublay.reputation.mintGrant({
  recipientId: "usr_def456",
  amount: -500,
  note: "Reversal: duplicate payout",
});
```

<ParamField type="string">The user credited — or, with a negative amount, debited.</ParamField>

<ParamField type="number">
  Any **non-zero** whole number in the signed 32-bit range. Negatives destroy reputation.
</ParamField>

<ParamField type="string | null">
  The bucket credited/debited. Omitted or `null` = the project-general bucket. Validated: an unknown space is rejected with `404 reputation-grant/space-not-found`.
</ParamField>

<ParamField type="string | null">Free-text note. Trimmed, up to 2000 characters.</ParamField>
<ParamField type="object">Arbitrary key-value data. Up to 1 MB. Omit when unused.</ParamField>
<ParamField type="&#x22;entity&#x22; | &#x22;comment&#x22; | &#x22;chat-message&#x22;">What the grant is for. Supplied together with `targetId`.</ParamField>
<ParamField type="string">The rewarded record's ID. Supplied together with `targetType`, and must exist.</ParamField>

**Returns** — `Promise<ReputationGrant>` with `sourceType: "app"`.

<Note>
  There is no counterpart in [`@sublay/js`](/v7/js-sdk/reputation) — minting is service/master-key only, and a user token can never reach the route.
</Note>

***

### listGrants

Lists grants. Exactly one filter shape per request — by recipient, by sender, or by target. The shapes are mutually exclusive and are not AND-ed; supplying none or combining two is a `400`.

```typescript theme={null}
const { data, pagination, summary } = await sublay.reputation.listGrants({
  targetType: "entity",
  targetId: "ent_abc123",
  include: "user",
  limit: 25,
});

console.log(summary?.total, "points from", summary?.count, "people");
```

<ParamField type="string">What this user received.</ParamField>
<ParamField type="string">What this user sent.</ParamField>
<ParamField type="&#x22;entity&#x22; | &#x22;comment&#x22; | &#x22;chat-message&#x22;">Who rewarded this item. Supplied together with `targetId`.</ParamField>
<ParamField type="string">The rewarded record's ID. Supplied together with `targetType`.</ParamField>
<ParamField type="number">Page number (1-indexed). Defaults to `1`.</ParamField>
<ParamField type="number">Page size. Defaults to `20`; the maximum is `100`. A larger value is rejected with `400 reputation-grant/invalid-query` rather than clamped.</ParamField>

<ParamField type="string">
  Comma-separated associations. Only `"user"` is supported — it hydrates both the sender and the recipient.
</ParamField>

<ParamField type="object">
  Opt-in per-user space reputation on the hydrated users. `{ spaceId: "context" }` scores each user against that grant's own space. See [Reputation](/data-models/reputation#reading-space-scoped-reputation).
</ParamField>

**Returns** — `Promise<{ data: ReputationGrant[]; pagination; summary? }>`. The `summary` block (`{ total, count, viewerTotal }`) is returned **only** on the target filter shape.

<Note>
  **Grants on chat messages are private to their conversation — and a service key is exempt from that.** For a user token, every shape asks whether that user can see the underlying message and withholds the grant if they cannot. A service key answers to neither gate: the target shape returns its rows unconditionally, and the `recipientId` / `senderId` shapes apply no membership predicate to it at all, so a backend can enumerate every grant it minted, including grants on messages moderation has removed. It is the app's own backend, already trusted to mint grants and to read every conversation. It holds no viewer identity, so `summary.viewerTotal` is always `0`.
</Note>

<Warning>
  **A service key sees no negative grants here.** The `amount > 0` filter is baked into the query for every caller, so this is not the route for auditing moderation deductions — use [Fetch User Grant History](/api-reference/reputation-grants/fetch-user-grant-history), which requires `x-sublay-project-id` alongside your key.
</Warning>

***

## Reading totals inline

For per-item totals, don't page through this module — ask the read that already returns the item. Entities, comments and chat messages all accept a `"grants"` token in their `include` string (combine it with others, e.g. `"files,grants"`). Each item then carries `grants: { total, count, viewerTotal }`. See [GrantSummary](/data-models/reputation-grant#grantsummary).

## See Also

* [ReputationGrant data model](/data-models/reputation-grant)
* [Create Reputation Grant API](/api-reference/reputation-grants/create-reputation-grant)
* [Mint Reputation Grant API](/api-reference/reputation-grants/mint-reputation-grant)
* [JS SDK reputation module](/v7/js-sdk/reputation)


# Search
Source: https://docs.sublay.io/v7/node-sdk/search

Full-text search across content, users, and spaces, plus AI-powered Q&A

The `search` module provides server-side access to Sublay's search and AI capabilities. Use it to build search APIs, power recommendation engines, or answer natural-language questions about your content.

***

### searchContent

Searches entities by full-text query, optionally scoped to a space.

```typescript theme={null}
const { data, pagination } = await sublay.search.searchContent({
  query: "getting started guide",
  spaceId: "spc_abc123",
  sourceTypes: ["entity", "comment"],
  limit: 10,
});
```

<ParamField type="string">
  The search query string.
</ParamField>

<ParamField type="string[]">
  Which content types to search: any of `"entity"`, `"comment"`, `"message"`.
</ParamField>

<ParamField type="string">
  Scope the search to a specific space.
</ParamField>

<ParamField type="boolean">
  Only applies with `spaceId`. When `true`, the search also covers every space nested under it — the whole subtree at any depth — not just the named space. Ignored without `spaceId`.
</ParamField>

<ParamField type="string">
  Scope the search to a specific conversation.
</ParamField>

<ParamField type="number">
  Maximum number of results to return.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<PaginatedResponse<Entity>>`

***

### searchUsers

Searches for users by name or username.

```typescript theme={null}
const { data, pagination } = await sublay.search.searchUsers({
  query: "alice",
  limit: 10,
});
```

<ParamField type="string">
  The search query string.
</ParamField>

<ParamField type="number">
  Maximum number of results to return.
</ParamField>

**Returns** — `Promise<PaginatedResponse<User>>`

***

### searchSpaces

Searches for spaces by name or description.

```typescript theme={null}
const { data, pagination } = await sublay.search.searchSpaces({
  query: "photography",
  limit: 10,
});
```

<ParamField type="string">
  The search query string.
</ParamField>

<ParamField type="number">
  Maximum number of results to return.
</ParamField>

**Returns** — `Promise<PaginatedResponse<Space>>`

***

### askContent

Asks a natural-language question about your content and returns an AI-generated answer with source references.

<Note>
  This feature requires semantic search to be enabled for your project. See the [Semantic Search & AI](/v7/semantic-search-ai) guide for setup instructions.
</Note>

```typescript theme={null}
const { answer, sources } = await sublay.search.askContent({
  query: "What are the best practices for error handling?",
  spaceId: "spc_abc123",
});

// answer: "Based on the content in this space, best practices include..."
// sources: [{ entityId: "ent_xyz", title: "Error Handling Guide" }, ...]
```

<ParamField type="string">
  The natural-language question to answer.
</ParamField>

<ParamField type="string[]">
  Which content types to draw from: any of `"entity"`, `"comment"`, `"message"`.
</ParamField>

<ParamField type="string">
  Scope the search to content within a specific space.
</ParamField>

<ParamField type="boolean">
  Only applies with `spaceId`. When `true`, the context lookup also covers every space nested under it — the whole subtree at any depth — so you can ask across a community and all of its channels at once. Ignored without `spaceId`.
</ParamField>

<ParamField type="string">
  Scope the search to a specific conversation.
</ParamField>

<ParamField type="number">
  Maximum number of sources to draw from.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<{ answer: string; sources?: Array<{ entityId: string; title: string | null }> }>`

***

### matchUsers

Matches people by **activity-derived interest facets**, in `passive` mode (against a given user's own facets) or `directed` mode (against a free-text topic). See the [Interest Matching](/v7/interest-matching) guide for setup and the model.

<Note>
  Requires a paid plan, the `ai-search` and `interest-matching` bundles, and `interestMatching.enabled` on the project.
</Note>

```typescript theme={null}
const { results } = await sublay.search.matchUsers({
  mode: "directed",
  query: "biotech",
  limit: 10,
});

// results: [{ user, score, matchedFacets: [{ similarity, candidateFacet, askerFacet?, sampleContent? }] }]
```

<ParamField type="string">
  `"passive"` or `"directed"`.
</ParamField>

<ParamField type="string">
  The topic to match against. Required in `directed` mode; rejected in `passive` mode.
</ParamField>

<ParamField type="number">
  Maximum number of matched users. Maximum `50`.
</ParamField>

<ParamField type="string">
  Restrict candidates to users active in this space.
</ParamField>

<ParamField type="boolean">
  With `spaceId`, also include users active in the space's subtree.
</ParamField>

<ParamField type="boolean">
  Request illustrative sample content per matched facet. Only honored when the project has `interestMatching.exposeSampleContent` on; otherwise returns `403 match/sample-content-disabled`.
</ParamField>

<ParamField type="boolean">
  Exclude the asker from results.
</ParamField>

**Returns** — `Promise<{ results: UserMatchResult[] }>` (the `{ results }` envelope, ordered by descending `score`).


# Spaces
Source: https://docs.sublay.io/v7/node-sdk/spaces

Create and manage spaces, navigate hierarchies, and look up spaces by slug or short ID

The `spaces` module covers core space lifecycle management: creating spaces, fetching them by various identifiers, updating settings, navigating parent-child hierarchies, and checking slug availability.

For membership management see [Space Members](/v7/node-sdk/spaces-members), and for moderation and rules see [Space Moderation](/v7/node-sdk/spaces-moderation).

***

### createSpace

Creates a new space.

```typescript theme={null}
const space = await sublay.spaces.createSpace({
  userId: "usr_abc123",
  name: "Photography",
  slug: "photography",
  description: "A community for photographers",
  postingPermission: "members",
});
```

<ParamField type="string">
  The Sublay user ID of the space creator, who becomes the initial admin.
</ParamField>

<ParamField type="string">
  Display name for the space.
</ParamField>

<ParamField type="string">
  URL-friendly identifier. Must be unique within the project. Generated from `name` if omitted.
</ParamField>

<ParamField type="string">
  Short description of the space.
</ParamField>

<ParamField type="string">
  Who can read content: `"anyone"` (default) or `"members"`.
</ParamField>

<ParamField type="string">
  Who can post content: `"anyone"`, `"members"` (default), or `"admins"`.
</ParamField>

<ParamField type="string">
  Listing/discoverability: `"public"` (default), `"unlisted"`, or `"private"`. Independent of `readingPermission` (which governs content). `"unlisted"` hides the space from discovery and search but keeps it reachable by direct link; `"private"` currently behaves like `"unlisted"`.
</ParamField>

<ParamField type="boolean">
  When `true`, join requests must be manually approved. Defaults to `false`.
</ParamField>

<ParamField type="boolean">
  The space's own NSFW flag. Defaults to `false`. A space created under an NSFW parent is effectively NSFW regardless of this value. See [Space NSFW flagging](/data-models/space#nsfw-flagging).
</ParamField>

<ParamField type="string">
  Makes this space a child of the specified parent space.
</ParamField>

<ParamField type="object">
  Arbitrary metadata attached to the space.
</ParamField>

**Returns** — `Promise<Space>`

***

### fetchSpace

Fetches a space by its Sublay ID, including member counts and permission details.

```typescript theme={null}
const space = await sublay.spaces.fetchSpace({ spaceId: "spc_abc123" });
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

**Returns** — `Promise<SpaceDetailed>`

***

### fetchManySpaces

Fetches a paginated list of top-level spaces, with optional text search.

```typescript theme={null}
const { data, pagination } = await sublay.spaces.fetchManySpaces({
  page: 1,
  limit: 20,
  searchName: "photo",
  sortBy: "members",
});
```

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Defaults to `20`.
</ParamField>

<ParamField type="string">
  Sort order: `"alphabetical"`, `"newest"`, or `"members"`.
</ParamField>

<ParamField type="string">
  Filter spaces whose name matches the query.
</ParamField>

<ParamField type="string">
  Filter spaces whose slug matches the query.
</ParamField>

<ParamField type="string">
  Filter spaces whose description matches the query.
</ParamField>

<ParamField type="string">
  Filter spaces matching the query across name, slug, or description.
</ParamField>

<ParamField type="&#x22;true&#x22;">
  When `"true"`, returns only spaces the requesting context is a member of.
</ParamField>

<ParamField type="string | &#x22;null&#x22;">
  Filter to children of a specific space, or pass `"null"` for top-level spaces only.
</ParamField>

<ParamField type="&#x22;include-all&#x22; | &#x22;exclude&#x22; | &#x22;only&#x22;">
  Filter by each space's `nsfwEffective` (own flag OR any ancestor). `"include-all"` (default) adds no predicate; `"exclude"` drops effective-NSFW spaces; `"only"` returns only them. `"only"` may return an NSFW child whose safe parent is omitted. See [Space NSFW flagging](/data-models/space#nsfw-flagging).
</ParamField>

<ParamField type="string">
  Comma-separated list of associations to populate.
</ParamField>

**Returns** — `Promise<PaginatedResponse<Space>>`

***

### fetchSpaceBySlug

Fetches a space by its unique slug.

```typescript theme={null}
const space = await sublay.spaces.fetchSpaceBySlug({ slug: "photography" });
```

<ParamField type="string">
  The space's URL slug.
</ParamField>

**Returns** — `Promise<SpaceDetailed>`

***

### fetchSpaceByShortId

Fetches a space by its short, human-readable ID (used in share URLs).

```typescript theme={null}
const space = await sublay.spaces.fetchSpaceByShortId({ shortId: "ph3x9" });
```

<ParamField type="string">
  The space's short ID.
</ParamField>

**Returns** — `Promise<SpaceDetailed>`

***

### fetchUserSpaces

Fetches the spaces a specific user is a member of.

```typescript theme={null}
const result = await sublay.spaces.fetchUserSpaces({
  userId: "usr_abc123",
  page: 1,
  limit: 20,
});
```

<ParamField type="string">
  The Sublay user ID.
</ParamField>

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Defaults to `20`.
</ParamField>

<ParamField type="string">
  Sort order: `"alphabetical"`, `"newest"`, or `"members"`.
</ParamField>

<ParamField type="string">
  Filter by the user's role in the space. A single role or comma-separated list, e.g. `"admin,moderator"`.
</ParamField>

<ParamField type="string">
  Membership status to list: `"active"` (default), `"pending"`, or `"banned"`. Use `"pending"` to find join requests still awaiting approval.
</ParamField>

<ParamField type="&#x22;true&#x22; | &#x22;false&#x22;">
  When `"true"`, returns the full set of spaces rather than only the paginated page.
</ParamField>

<ParamField type="string">
  Comma-separated list of associations to populate.
</ParamField>

**Returns** — `Promise<UserSpacesResponse>`

***

### fetchMutualSpaces

Fetches the spaces shared between two users — the spaces both are active members of.

```typescript theme={null}
const result = await sublay.spaces.fetchMutualSpaces({
  userId: "usr_other",       // the other user
  actingUserId: "usr_self",  // the user to act as (service key required)
  page: 1,
  limit: 20,
});
```

<ParamField type="string">
  The other user's Sublay ID. Mutual spaces are computed between this user and `actingUserId`.
</ParamField>

<ParamField type="string">
  The user to act as. Because the SDK authenticates with a service key, you must name the acting user explicitly.
</ParamField>

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Max `100`. Defaults to `20`.
</ParamField>

<ParamField type="string">
  Comma-separated list of associations to populate (e.g. `"files"`).
</ParamField>

**Returns** — `Promise<PaginatedResponse<Space>>`

***

### updateSpace

Updates settings on an existing space.

```typescript theme={null}
const space = await sublay.spaces.updateSpace({
  spaceId: "spc_abc123",
  name: "Photography Community",
  postingPermission: "admins",
  requireJoinApproval: true,
});
```

<ParamField type="string">
  The Sublay space ID to update.
</ParamField>

<ParamField type="string">
  New display name.
</ParamField>

<ParamField type="string">
  New slug. Must be unique.
</ParamField>

<ParamField type="string">
  New description.
</ParamField>

<ParamField type="string">
  Updated reading permission: `"anyone"` or `"members"`.
</ParamField>

<ParamField type="string">
  Updated posting permission: `"anyone"`, `"members"`, or `"admins"`.
</ParamField>

<ParamField type="string">
  Updated visibility: `"public"`, `"unlisted"`, or `"private"`. Controls listing/discoverability, independent of `readingPermission`.
</ParamField>

<ParamField type="boolean">
  Updated NSFW own-flag. Toggling it recomputes this space's effective NSFW and cascades it top-down to every descendant space (and, live, to their entities). See [Space NSFW flagging](/data-models/space#nsfw-flagging).
</ParamField>

<ParamField type="object">
  Updated metadata. Merged with existing values.
</ParamField>

**Returns** — `Promise<Space>`

***

### deleteSpace

Permanently deletes a space and all its content.

```typescript theme={null}
const result = await sublay.spaces.deleteSpace({ spaceId: "spc_abc123" });
```

<ParamField type="string">
  The Sublay space ID to delete.
</ParamField>

**Returns** — `Promise<DeleteSpaceResponse>`

***

### checkSlugAvailability

Checks whether a slug is available for use.

```typescript theme={null}
const { available } = await sublay.spaces.checkSlugAvailability({
  slug: "photography",
});
```

<ParamField type="string">
  The slug to check.
</ParamField>

**Returns** — `Promise<{ available: boolean }>`

***

### fetchChildSpaces

Fetches the direct child spaces of a given parent space.

```typescript theme={null}
const { data, pagination } = await sublay.spaces.fetchChildSpaces({
  spaceId: "spc_abc123",
  page: 1,
  limit: 20,
});
```

<ParamField type="string">
  The parent Sublay space ID.
</ParamField>

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Defaults to `20`.
</ParamField>

<ParamField type="string">
  Sort order: `"alphabetical"`, `"newest"`, or `"members"`.
</ParamField>

<ParamField type="string">
  Comma-separated list of associations to populate.
</ParamField>

**Returns** — `Promise<PaginatedResponse<Space>>`

***

### fetchSpaceBreadcrumb

Returns the full ancestor chain from the root down to the specified space. Useful for rendering breadcrumb navigation.

```typescript theme={null}
const breadcrumb = await sublay.spaces.fetchSpaceBreadcrumb({
  spaceId: "spc_abc123",
});
// [{ id: "root", name: "Root" }, { id: "spc_parent", name: "Parent" }, { id: "spc_abc123", name: "Photography" }]
```

<ParamField type="string">
  The Sublay space ID to get the breadcrumb for.
</ParamField>

**Returns** — `Promise<SpaceBreadcrumb>`


# Space Members
Source: https://docs.sublay.io/v7/node-sdk/spaces-members

Manage space membership — joining, leaving, approvals, role assignments, and bans

The `spaces` module includes a full set of membership management functions. Use these to build admin tools, automate onboarding flows, or enforce membership policies server-side.

***

### joinSpace

Adds a user to a space. If the space requires approval (`requireJoinApproval: true`), the membership is created in a pending state.

```typescript theme={null}
const result = await sublay.spaces.joinSpace({
  spaceId: "spc_abc123",
  userId: "usr_abc123",
});
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

<ParamField type="string">
  The Sublay user ID to add.
</ParamField>

**Returns** — `Promise<JoinSpaceResponse>`

***

### leaveSpace

Removes a user from a space.

```typescript theme={null}
const result = await sublay.spaces.leaveSpace({
  spaceId: "spc_abc123",
  userId: "usr_abc123",
});
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

<ParamField type="string">
  The Sublay user ID to remove.
</ParamField>

**Returns** — `Promise<LeaveSpaceResponse>`

***

### checkMyMembership

Returns the membership status of a user in a space.

```typescript theme={null}
const result = await sublay.spaces.checkMyMembership({
  spaceId: "spc_abc123",
  userId: "usr_abc123",
});
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

<ParamField type="string">
  The Sublay user ID to check.
</ParamField>

**Returns** — `Promise<CheckMyMembershipResponse>`

***

### fetchSpaceMembers

Returns a paginated list of approved members in a space.

```typescript theme={null}
const result = await sublay.spaces.fetchSpaceMembers({
  spaceId: "spc_abc123",
  page: 1,
  limit: 20,
});
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Defaults to `20`.
</ParamField>

<ParamField type="string">
  Filter by role: `"admin"`, `"moderator"`, or `"member"`.
</ParamField>

<ParamField type="string">
  Filter by membership status: `"pending"`, `"active"`, `"banned"`, or `"rejected"`.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<SpaceMembersResponse>`

***

### fetchSpaceTeam

Returns the admin and moderator members of a space (the "team").

```typescript theme={null}
const result = await sublay.spaces.fetchSpaceTeam({ spaceId: "spc_abc123" });
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<SpaceTeamResponse>`

***

### updateMemberRole

Updates a member's role within a space.

```typescript theme={null}
const result = await sublay.spaces.updateMemberRole({
  spaceId: "spc_abc123",
  memberId: "mem_xyz789",
  role: "moderator",
});
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

<ParamField type="string">
  The Sublay space member ID (not the user ID).
</ParamField>

<ParamField type="string">
  The new role to assign: `"admin"`, `"moderator"`, or `"member"`.
</ParamField>

**Returns** — `Promise<UpdateMemberRoleResponse>`

***

### approveMembership

Approves a pending membership request. Only relevant when the space has `requireJoinApproval: true`.

```typescript theme={null}
const result = await sublay.spaces.approveMembership({
  spaceId: "spc_abc123",
  memberId: "mem_xyz789",
});
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

<ParamField type="string">
  The Sublay space member ID of the pending member.
</ParamField>

**Returns** — `Promise<ApproveMemberResponse>`

***

### declineMembership

Declines and removes a pending membership request.

```typescript theme={null}
const result = await sublay.spaces.declineMembership({
  spaceId: "spc_abc123",
  memberId: "mem_xyz789",
});
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

<ParamField type="string">
  The Sublay space member ID of the pending member.
</ParamField>

**Returns** — `Promise<DeclineMemberResponse>`

***

### banMember

Bans a member from a space, preventing them from rejoining.

```typescript theme={null}
const result = await sublay.spaces.banMember({
  spaceId: "spc_abc123",
  memberId: "mem_xyz789",
});
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

<ParamField type="string">
  The Sublay space member ID to ban.
</ParamField>

**Returns** — `Promise<BanMemberResponse>`

***

### unbanMember

Removes a ban, allowing the user to rejoin the space.

```typescript theme={null}
const result = await sublay.spaces.unbanMember({
  spaceId: "spc_abc123",
  memberId: "mem_xyz789",
});
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

<ParamField type="string">
  The Sublay space member ID to unban.
</ParamField>

**Returns** — `Promise<UnbanMemberResponse>`


# Space Moderation
Source: https://docs.sublay.io/v7/node-sdk/spaces-moderation

Handle reports, moderate content, and manage community rules

This page covers the moderation and administrative functions on the `spaces` module: report handling, content moderation actions, and community rules management.

***

## Reports

### handleEntityReport

Resolves a report filed against an entity in a space by applying one or more moderation actions.

```typescript theme={null}
const result = await sublay.spaces.handleEntityReport({
  spaceId: "spc_abc123",
  reportId: "rpt_xyz789",
  entityId: "ent_xyz789",
  actions: ["remove-entity", "ban-user"],
  reason: "Repeated spam",
});
```

<ParamField type="string">
  The Sublay space ID where the report was filed.
</ParamField>

<ParamField type="string">
  The Sublay report ID.
</ParamField>

<ParamField type="string">
  The Sublay entity ID the report targets.
</ParamField>

<ParamField type="string[]">
  One or more actions to apply: `"remove-entity"`, `"ban-user"`, and/or `"dismiss"`.
</ParamField>

<ParamField type="string">
  Optional moderator summary of the resolution.
</ParamField>

<ParamField type="string">
  Optional reason, stored for audit purposes.
</ParamField>

<ParamField type="string">
  The Sublay user ID of the moderator performing the action.
</ParamField>

**Returns** — `Promise<HandleReportResponse>`

***

### handleCommentReport

Resolves a report filed against a comment in a space by applying one or more moderation actions.

```typescript theme={null}
const result = await sublay.spaces.handleCommentReport({
  spaceId: "spc_abc123",
  reportId: "rpt_abc456",
  commentId: "cmt_abc123",
  actions: ["dismiss"],
});
```

<ParamField type="string">
  The Sublay space ID where the report was filed.
</ParamField>

<ParamField type="string">
  The Sublay report ID.
</ParamField>

<ParamField type="string">
  The Sublay comment ID the report targets.
</ParamField>

<ParamField type="string[]">
  One or more actions to apply: `"remove-comment"`, `"ban-user"`, and/or `"dismiss"`.
</ParamField>

<ParamField type="string">
  Optional moderator summary of the resolution.
</ParamField>

<ParamField type="string">
  Optional reason, stored for audit purposes.
</ParamField>

<ParamField type="string">
  The Sublay user ID of the moderator performing the action.
</ParamField>

**Returns** — `Promise<HandleReportResponse>`

***

<Note>
  Chat message reports are handled by **`spaces.handleSpaceChatReport`**, which
  is documented with the other space-conversation functions in
  [Chat → Space conversations](/node-sdk/chat#space-conversations). Reports on
  DM and group conversations are project-level and are resolved in the Sublay
  dashboard, not through this SDK.
</Note>

***

## Content Moderation

### moderateSpaceEntity

Approves or removes an entity within a space.

```typescript theme={null}
const result = await sublay.spaces.moderateSpaceEntity({
  spaceId: "spc_abc123",
  entityId: "ent_xyz789",
  action: "remove",
  reason: "Violates community guidelines",
});
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

<ParamField type="string">
  The Sublay entity ID to moderate.
</ParamField>

<ParamField type="string">
  `"approve"` — makes the entity visible, or `"remove"` — hides/removes it from the space.
</ParamField>

<ParamField type="string">
  Optional reason for the moderation action, stored for audit purposes.
</ParamField>

**Returns** — `Promise<ModerationResponse>`

***

### setSpaceEntityNsfw

Sets the NSFW own-flag on an entity within a space — including other users' entities. This is a separate axis from `moderateSpaceEntity`: it **labels** the entity (`nsfw`), it does not approve/remove it. Requires the acting user to be an admin or moderator of the space.

```typescript theme={null}
const result = await sublay.spaces.setSpaceEntityNsfw({
  spaceId: "spc_abc123",
  entityId: "ent_xyz789",
  nsfw: true,
});
```

<ParamField type="string">
  The Sublay space ID containing the entity.
</ParamField>

<ParamField type="string">
  The Sublay entity ID to flag or unflag.
</ParamField>

<ParamField type="boolean">
  The NSFW own-flag to set on the entity.
</ParamField>

**Returns** — `Promise<{ message: string; nsfw: boolean }>`

***

### moderateSpaceComment

Approves or removes a comment within a space.

```typescript theme={null}
const result = await sublay.spaces.moderateSpaceComment({
  spaceId: "spc_abc123",
  commentId: "cmt_abc123",
  action: "approve",
});
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

<ParamField type="string">
  The Sublay comment ID to moderate.
</ParamField>

<ParamField type="string">
  `"approve"` or `"remove"`.
</ParamField>

<ParamField type="string">
  Optional reason for the moderation action.
</ParamField>

**Returns** — `Promise<ModerationResponse>`

***

## Rules

Rules are community guidelines displayed to members. They are ordered and each consists of a title and optional description.

### fetchManyRules

Fetches all rules for a space.

```typescript theme={null}
const result = await sublay.spaces.fetchManyRules({ spaceId: "spc_abc123" });
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

**Returns** — `Promise<FetchManyRulesResponse>`

***

### fetchRule

Fetches a single rule by its ID.

```typescript theme={null}
const rule = await sublay.spaces.fetchRule({
  spaceId: "spc_abc123",
  ruleId: "rul_xyz789",
});
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

<ParamField type="string">
  The Sublay rule ID.
</ParamField>

**Returns** — `Promise<Rule>`

***

### createRule

Creates a new rule for a space.

```typescript theme={null}
const rule = await sublay.spaces.createRule({
  spaceId: "spc_abc123",
  title: "Be respectful",
  description: "Treat all members with respect and courtesy.",
});
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

<ParamField type="string">
  Short title for the rule.
</ParamField>

<ParamField type="string">
  Extended explanation of the rule.
</ParamField>

**Returns** — `Promise<Rule>`

***

### updateRule

Updates an existing rule's title or description.

```typescript theme={null}
const rule = await sublay.spaces.updateRule({
  spaceId: "spc_abc123",
  ruleId: "rul_xyz789",
  title: "Be respectful and kind",
  description: "Updated description.",
});
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

<ParamField type="string">
  The Sublay rule ID to update.
</ParamField>

<ParamField type="string">
  New title.
</ParamField>

<ParamField type="string">
  New description.
</ParamField>

**Returns** — `Promise<Rule>`

***

### deleteRule

Deletes a rule from a space.

```typescript theme={null}
const result = await sublay.spaces.deleteRule({
  spaceId: "spc_abc123",
  ruleId: "rul_xyz789",
});
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

<ParamField type="string">
  The Sublay rule ID to delete.
</ParamField>

**Returns** — `Promise<DeleteRuleResponse>`

***

### reorderRules

Sets the display order of all rules for a space by providing an ordered array of rule IDs.

```typescript theme={null}
const rules = await sublay.spaces.reorderRules({
  spaceId: "spc_abc123",
  ruleIds: ["rul_first", "rul_second", "rul_third"],
});
```

<ParamField type="string">
  The Sublay space ID.
</ParamField>

<ParamField type="string[]">
  Complete ordered array of all rule IDs for the space.
</ParamField>

**Returns** — `Promise<Rule[]>` — the full list of rules in their new order.


# Storage
Source: https://docs.sublay.io/v7/node-sdk/storage

Upload, retrieve, and delete files and images from your server

The `storage` module uploads files and images to managed cloud storage and returns proxy URLs, plus reads and deletes existing files. Uploads are sent as `multipart/form-data` — pass the file bytes as a `Uint8Array` or a `Blob`.

<Note>
  Uploads can be attributed to a user by passing that user's Sublay ID as `userId` —
  your service key performs the upload on behalf of that named user. Omit `userId`
  for a **backend/project-owned** file (no owning user).
</Note>

<Warning>
  **Access model.** Reads (`getFile`) are project-scoped — reachable for any file
  in your project. **Deletes are owner-or-service:** your service key may delete
  any file, but the same call made with an end-user token only succeeds for files
  that user owns. Backend-owned files (`userId` unset) are deletable only with a
  service/master key.
</Warning>

***

### uploadFile

Uploads a generic file (PDF, video, document, …) without server-side processing. The file type is inferred from the MIME type.

```typescript theme={null}
import { readFile } from "node:fs/promises";

const buffer = await readFile("./report.pdf");

const file = await sublay.storage.uploadFile({
  file: new Uint8Array(buffer),
  filename: "report.pdf",
  mimeType: "application/pdf",
  pathParts: ["documents", "usr_abc123"],
  userId: "usr_abc123",
});
```

<ParamField type="Uint8Array | Blob">
  The file bytes to upload. Maximum 50 MB.
</ParamField>

<ParamField type="string[]">
  Storage path segments. The file is stored under the joined path with a UUID
  sub-folder appended, e.g. `["documents", "usr_abc123"]` →
  `documents/usr_abc123/<uuid>/<filename>`.
</ParamField>

<ParamField type="string">
  Name to store the file under. Defaults to `"upload"`.
</ParamField>

<ParamField type="string">
  MIME type used when wrapping a `Uint8Array`. Defaults to
  `"application/octet-stream"`. Ignored when `file` is already a `Blob`.
</ParamField>

<ParamField type="number">
  Display order when a record has multiple attachments. Defaults to `0`.
</ParamField>

<ParamField type="object">
  Custom key-value data stored alongside the file record.
</ParamField>

<ParamField type="string">
  Associates the file with an entity for cascade deletion. Only one of
  `entityId` / `commentId` / `spaceId` may be set.
</ParamField>

<ParamField type="string">
  Associates the file with a comment for cascade deletion.
</ParamField>

<ParamField type="string">
  Associates the file with a space.
</ParamField>

<ParamField type="string">
  Attribute the upload to a user. Omit for a backend/project-owned file.
</ParamField>

**Returns** — `Promise<File>`

***

### uploadImage

Uploads an image, processes it with Sharp, and stores the original plus all requested variants. The `imageOptions` object is a discriminated union on `mode` — the shape of the other fields depends on the mode you pick.

```typescript theme={null}
import { readFile } from "node:fs/promises";

const buffer = await readFile("./avatar.png");

const file = await sublay.storage.uploadImage({
  file: new Uint8Array(buffer),
  filename: "avatar.png",
  mimeType: "image/png",
  imageOptions: {
    mode: "exact-dimensions",
    dimensions: {
      thumbnail: { width: 64, height: 64 },
      card: { width: 400, height: 300 },
    },
    format: "webp",
    quality: 85,
  },
  pathParts: ["avatars", "usr_abc123"],
  userId: "usr_abc123",
});
```

<ParamField type="Uint8Array | Blob">
  The image bytes. Must be a valid image format recognized by Sharp. Maximum 50 MB.
</ParamField>

<ParamField type="ImageOptions">
  Image-processing configuration — a discriminated union on `mode`. The supported
  modes and their required fields:

  | `mode`                      | Required fields                                    | Notes                                                        |
  | --------------------------- | -------------------------------------------------- | ------------------------------------------------------------ |
  | `exact-dimensions`          | `dimensions` (`{ [variant]: { width, height } }`)  | Fixed-size crops.                                            |
  | `aspect-ratio-width-based`  | `aspectRatio`, `widths` (`{ [variant]: number }`)  | Heights computed from the ratio.                             |
  | `aspect-ratio-height-based` | `aspectRatio`, `heights` (`{ [variant]: number }`) | Widths computed from the ratio.                              |
  | `original-aspect`           | `sizes` (`{ [variant]: number }`)                  | Preserves source ratio; `fit` limited to `inside`/`outside`. |
  | `multi-aspect-ratio`        | `aspectRatios` (`{ width, height }[]`), `sizes`    | 1–10 aspect ratios.                                          |

  All modes also accept optional `quality` (1–100), `format` (`webp` | `jpeg` |
  `png` | `original`), `stripExif` (boolean), and `fit` (`cover` | `contain` |
  `inside` | `outside`). Dimension/size values are 50–10000.
</ParamField>

<ParamField type="string">
  Name to store the image under. Defaults to `"upload"`.
</ParamField>

<ParamField type="string">
  MIME type used when wrapping a `Uint8Array`. Ignored when `file` is a `Blob`.
</ParamField>

<ParamField type="string[]">
  Storage path segments. Defaults to `["images", "<fileId>"]`.
</ParamField>

<ParamField type="string">
  Associates the image with an entity. Only one of `entityId` / `commentId` /
  `spaceId` / `eventId` may be set.
</ParamField>

<ParamField type="string">
  Associates the image with a comment.
</ParamField>

<ParamField type="string">
  Associates the image with a space.
</ParamField>

<ParamField type="string">
  Associates the image with an event. Use this to attach a cover or gallery image
  to an event created via `sublay.events.createEvent` (the Node SDK does not
  support inline event image upload). See the [Events module](/v7/node-sdk/events).
</ParamField>

<ParamField type="string">
  Attribute the upload to a user. Omit for a backend/project-owned file.
</ParamField>

**Returns** — `Promise<File>` (the `image` field carries the generated `variants`).

***

### getFile

Fetches a file's metadata and proxy URLs by ID. For images, the `image` extension (variants, processing details) is included. Reads are project-scoped.

```typescript theme={null}
const file = await sublay.storage.getFile({
  fileId: "fil_abc123",
});
```

<ParamField type="string">
  The UUID of the file to retrieve.
</ParamField>

**Returns** — `Promise<File>`

***

### deleteFile

Deletes a file record and removes all associated storage objects (for images, every generated variant too).

```typescript theme={null}
await sublay.storage.deleteFile({
  fileId: "fil_abc123",
});
```

<ParamField type="string">
  The UUID of the file to delete.
</ParamField>

**Returns** — `Promise<void>`

<Note>
  With a service key this deletes any file in the project. The same call from an
  end-user token only succeeds when that user owns the file (otherwise `403`).
</Note>


# Tables — Rows
Source: https://docs.sublay.io/v7/node-sdk/tables

Read and write custom-table rows from your server with the client.table(name) accessor

Custom tables let you provision your own database tables alongside Sublay's built-in models. The `client.table(name)` accessor gives you full row-level access to a custom table from your server. For an overview of the feature — the `custom_` naming model, managed columns, and soft-delete — see [Custom Tables](/v7/custom-tables). To **create** tables and columns, see [Tables — Management](/v7/node-sdk/tables-management).

<Note>
  `client.table(name)` is a **callable accessor**, not a flat module namespace —
  it closes over the table name and returns the row-operation object. You can
  type the rows by passing a generic: `client.table<EventRow>("Events")`.
</Note>

```typescript theme={null}
interface EventRow {
  id: string;
  name: string;
  capacity: number;
  createdAt: string;
}

const events = sublay.table<EventRow>("Events");
const { data } = await events.find({ limit: 20 });
```

The `name` you pass is the **logical** table name — Sublay applies the `custom_` prefix for you.

***

### find

Fetches a filtered, sorted, paginated page of rows. Returns the shared `{ data, pagination }` envelope.

```typescript theme={null}
const { data, pagination } = await sublay.table<EventRow>("Events").find({
  page: 1,
  limit: 20,
  sortBy: "createdAt",
  sortDir: "desc",
  filters: [
    { column: "capacity", operator: "gte", value: 100 },
    { column: "name", operator: "contains", value: "summit" },
  ],
});
```

<ParamField type="number">
  Page number (1-indexed).
</ParamField>

<ParamField type="number">
  Rows per page.
</ParamField>

<ParamField type="string">
  Column to sort by. Validated against the table's real columns. Defaults to
  `createdAt` (descending) on a table with timestamps, otherwise `id`.
</ParamField>

<ParamField type="&#x22;asc&#x22; | &#x22;desc&#x22;">
  Sort direction.
</ParamField>

<ParamField type="DbFilter[]">
  An array of `{ column, operator, value }` clauses, **AND-combined**. Operators:
  `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `contains`, `like`, `isNull`.
  Serialized to a JSON query parameter for you.
</ParamField>

<ParamField type="boolean">
  On a paranoid table, set `true` to include soft-deleted rows. Defaults to
  `false`.
</ParamField>

**Returns** — `Promise<PaginatedResponse<T>>`

***

### findOne

Fetches a single row by its `id`. Throws (axios `404`) if the row doesn't exist or has been soft-deleted.

```typescript theme={null}
const event = await sublay.table<EventRow>("Events").findOne("a1b2c3d4-...");
```

<ParamField type="string">
  The row's `id` (UUID).
</ParamField>

**Returns** — `Promise<T>`

***

### create

Inserts a single row. Managed columns (`id`, `createdAt`, `updatedAt`, `deletedAt`) are rejected from the body — they are set by the server.

```typescript theme={null}
const event = await sublay.table<EventRow>("Events").create({
  name: "Launch Summit",
  capacity: 250,
});
```

<ParamField type="Partial<T>">
  The column values for the new row.
</ParamField>

**Returns** — `Promise<T>`

***

### bulkCreate

Inserts many rows in one call. Capped at **100 rows** per request.

```typescript theme={null}
const rows = await sublay.table<EventRow>("Events").bulkCreate([
  { name: "Workshop A", capacity: 40 },
  { name: "Workshop B", capacity: 40 },
]);
```

<ParamField type="Partial<T>[]">
  The rows to insert (max 100).
</ParamField>

**Returns** — `Promise<T[]>`

***

### update

Updates a row by `id`. On a table with timestamps, `updatedAt` is bumped automatically. Managed columns are rejected from the body.

```typescript theme={null}
const event = await sublay.table<EventRow>("Events").update("a1b2c3d4-...", {
  capacity: 300,
});
```

<ParamField type="string">
  The row's `id`.
</ParamField>

<ParamField type="Partial<T>">
  The column values to change.
</ParamField>

**Returns** — `Promise<T>`

***

### delete

Deletes a row by `id`. On a **paranoid** table this is a soft delete (sets `deletedAt`); pass `force: true` to hard-delete. On a non-paranoid table it is always a hard delete.

```typescript theme={null}
// Soft delete on a paranoid table
await sublay.table("Events").delete("a1b2c3d4-...");

// Hard delete
await sublay.table("Events").delete("a1b2c3d4-...", { force: true });
```

<ParamField type="string">
  The row's `id`.
</ParamField>

<ParamField type="boolean">
  When `true`, hard-deletes a paranoid row instead of soft-deleting it.
</ParamField>

**Returns** — `Promise<{ deleted: boolean; soft: boolean }>` — `soft` is `true` when the row was soft-deleted.

***

### bulkDelete

Deletes many rows by an id list and/or a `filters` predicate (at least one is required). Paranoid-aware (soft by default, `force` to hard-delete) and capped at the bulk limit.

```typescript theme={null}
// By id list
await sublay.table("Events").bulkDelete({ rowIds: ["id-1", "id-2"] });

// By predicate
await sublay.table("Events").bulkDelete({
  filters: [{ column: "capacity", operator: "lt", value: 10 }],
  force: true,
});
```

<ParamField type="string[]">
  Rows to delete by `id`.
</ParamField>

<ParamField type="DbFilter[]">
  A predicate selecting rows to delete (same shape as `find`'s `filters`).
</ParamField>

<ParamField type="boolean">
  When `true`, hard-deletes matched paranoid rows.
</ParamField>

**Returns** — `Promise<{ deletedCount: number; soft: boolean }>`

***

### restore

Clears `deletedAt` on a soft-deleted row, bringing it back. Only valid on a **paranoid** table.

```typescript theme={null}
const event = await sublay.table<EventRow>("Events").restore("a1b2c3d4-...");
```

<ParamField type="string">
  The soft-deleted row's `id`.
</ParamField>

**Returns** — `Promise<T>`

***

<Warning>
  Row CRUD on the `/db` surface is currently **open** — identity is captured but
  not enforced. See the [security note](/v7/custom-tables#security-open-row-crud)
  on the overview page before storing access-controlled data in custom tables.
</Warning>


# Tables — Management
Source: https://docs.sublay.io/v7/node-sdk/tables-management

Create and drop custom tables and columns from your server with the client.tables module

The `tables` module manages the **schema** of your custom tables — creating and dropping tables, and adding and dropping columns. For reading and writing rows, see [Tables — Rows](/v7/node-sdk/tables). For the feature overview, see [Custom Tables](/v7/custom-tables).

<Note>
  Table management is **service-key only**, so it lives in the server-side
  `@sublay/node` SDK only — the browser [`@sublay/js`](/v7/js-sdk/overview) SDK
  and the React `useTable` hook are row-only. The same operations are also
  available in the [dashboard data editor](/v7/custom-tables#the-dashboard-data-editor).
</Note>

All names you pass are **logical** — Sublay applies the `custom_` prefix for you.

***

### createTable

Creates a custom table with the given columns and managed-column flags.

```typescript theme={null}
await sublay.tables.createTable({
  tableName: "Events",
  timestamps: true,
  paranoid: true,
  columns: [
    { columnName: "name", dataType: "text", nullable: false },
    { columnName: "capacity", dataType: "integer", nullable: true, defaultValue: "0" },
    { columnName: "startsAt", dataType: "timestamp", nullable: true },
    { columnName: "metadata", dataType: "json", nullable: true },
  ],
});
```

<ParamField type="string">
  The logical table name (max 56 characters — 63 minus the `custom_` prefix).
  Sublay stores it as `custom_<tableName>`.
</ParamField>

<ParamField type="CustomColumnDefinition[]">
  The developer columns to create. Each is `{ columnName, dataType, nullable, defaultValue? }`.
  `dataType` is one of `text`, `integer`, `float`, `decimal`, `boolean`, `date`,
  `timestamp`, `uuid`, `json`. A column may not be named `id`, `createdAt`,
  `updatedAt`, or `deletedAt` (reserved managed columns).
</ParamField>

<ParamField type="boolean">
  Emit `createdAt` / `updatedAt`. Defaults to `true`.
</ParamField>

<ParamField type="boolean">
  Emit `deletedAt` and enable soft delete. **Requires `timestamps`.** Defaults to
  `false`.
</ParamField>

**Returns** — `Promise<{ table: string }>` — the physical (`custom_*`) table name.

<Info>
  Errors are returned with a `database/*` code: `database/reserved-column` (a
  column shadows a managed name), `database/name-too-long` (over 56 chars),
  `database/table-limit-reached` (100 tables), `database/column-limit-reached`
  (100 columns).
</Info>

***

### addColumn

Adds a column to an existing custom table.

```typescript theme={null}
await sublay.tables.addColumn({
  tableName: "Events",
  columnName: "venue",
  dataType: "text",
  nullable: true,
});
```

<ParamField type="string">
  The logical table name.
</ParamField>

<ParamField type="string">
  The new column's name (may not be a reserved managed name).
</ParamField>

<ParamField type="CustomColumnType">
  One of `text`, `integer`, `float`, `decimal`, `boolean`, `date`, `timestamp`,
  `uuid`, `json`.
</ParamField>

<ParamField type="boolean">
  Whether the column accepts `null`.
</ParamField>

<ParamField type="string | null">
  Optional default literal, validated against `dataType`.
</ParamField>

**Returns** — `Promise<{ added: string }>`

***

### dropColumn

Drops a column from a custom table. Managed columns (`id`, `createdAt`, `updatedAt`, `deletedAt`) cannot be dropped.

```typescript theme={null}
await sublay.tables.dropColumn({ tableName: "Events", columnName: "venue" });
```

<ParamField type="string">
  The logical table name.
</ParamField>

<ParamField type="string">
  The column to drop.
</ParamField>

**Returns** — `Promise<{ dropped: string }>`

***

### dropTable

Drops a custom table and all of its rows. This is irreversible.

```typescript theme={null}
await sublay.tables.dropTable({ tableName: "Events" });
```

<ParamField type="string">
  The logical table name.
</ParamField>

**Returns** — `Promise<{ dropped: string }>`


# Users
Source: https://docs.sublay.io/v7/node-sdk/users

Fetch, update and delete user profiles, check usernames, and query follow and connection graphs

The `users` module provides server-side access to user profiles, social graph data (follows and connections), and username availability. All operations use your project API key and do not require a user access token.

***

### fetchUserById

Fetches a user profile by their internal Sublay user ID.

```typescript theme={null}
const user = await sublay.users.fetchUserById({ userId: "usr_abc123" });
```

<ParamField type="string">
  The Sublay user ID.
</ParamField>

<ParamField type="string">
  Comma-separated list of associations to populate.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<User>`

***

### fetchUserByForeignId

Fetches a user profile by your application's own user identifier. Optionally creates the user if not found.

```typescript theme={null}
const user = await sublay.users.fetchUserByForeignId({
  foreignId: "external-user-42",
  createIfNotFound: true,
  name: "Bob Smith",
  username: "bob",
});
```

<ParamField type="string">
  Your application's user identifier.
</ParamField>

<ParamField type="boolean">
  When `true`, creates the user with the provided profile fields if no match is found. Defaults to `false`.
</ParamField>

<ParamField type="string">
  Display name — used only when creating a new user.
</ParamField>

<ParamField type="string">
  Username — used only when creating a new user.
</ParamField>

<ParamField type="string">
  Avatar URL — used only when creating a new user.
</ParamField>

<ParamField type="string">
  Bio text — used only when creating a new user.
</ParamField>

<ParamField type="object">
  Public metadata — used only when creating a new user.
</ParamField>

<ParamField type="object">
  Secure metadata (not exposed to the client) — used only when creating a new user.
</ParamField>

<ParamField type="string">
  Comma-separated list of associations to populate.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<User>`

***

### fetchUserByUsername

Fetches a user profile by their username.

```typescript theme={null}
const user = await sublay.users.fetchUserByUsername({ username: "alice" });
```

<ParamField type="string">
  The user's unique username.
</ParamField>

<ParamField type="string">
  Comma-separated list of associations to populate.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<User>`

***

### updateUser

Updates a user's profile fields.

```typescript theme={null}
const updatedUser = await sublay.users.updateUser({
  userId: "usr_abc123",
  name: "Alice Updated",
  bio: "New bio",
  avatar: "https://cdn.example.com/avatar.jpg",
  location: { latitude: 37.7749, longitude: -122.4194 },
});
```

<ParamField type="string">
  The Sublay user ID to update.
</ParamField>

<ParamField type="string">
  New display name.
</ParamField>

<ParamField type="string">
  New username. Must be available.
</ParamField>

<ParamField type="string">
  New bio text.
</ParamField>

<ParamField type="string">
  New avatar URL.
</ParamField>

<ParamField type="object">
  Updated public metadata. Merged with existing metadata.
</ParamField>

<ParamField type="object">
  Updated secure metadata (not exposed in public responses). Merged with existing values.
</ParamField>

<ParamField type="string">
  ISO 8601 date string for the user's birthdate.
</ParamField>

<ParamField type="object">
  Geographic location `{ latitude: number; longitude: number }`.
</ParamField>

**Returns** — `Promise<UserFull>`

***

### deleteUser

Permanently deletes a user and cascades cleanup across all of their related data — reactions, files, follows, connections, notifications, collections, reports, and mentions are removed, and their entities and comments are stripped of authored content. This mirrors the full-cascade delete performed from the dashboard.

<Warning>
  This is a hard, irreversible delete — the user and their related data cannot be recovered.
</Warning>

```typescript theme={null}
await sublay.users.deleteUser({ userId: "usr_abc123" });
```

<ParamField type="string">
  The Sublay user ID to delete.
</ParamField>

**Returns** — `Promise<void>`

***

### fetchUserSuggestions

Returns users whose name or username matches a partial query string. Useful for mention autocomplete on the server.

```typescript theme={null}
const users = await sublay.users.fetchUserSuggestions({ query: "ali" });
```

<ParamField type="string">
  Partial name or username to search for.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<User[]>`

***

### checkUsernameAvailability

Checks whether a username is available for registration.

```typescript theme={null}
const { available } = await sublay.users.checkUsernameAvailability({
  username: "alice",
});
```

<ParamField type="string">
  The username to check.
</ParamField>

**Returns** — `Promise<{ available: boolean }>`

***

### fetchFollowersByUserId

Returns a paginated list of users following the specified user.

```typescript theme={null}
const { data, pagination } = await sublay.users.fetchFollowersByUserId({
  userId: "usr_abc123",
  page: 1,
  limit: 20,
});
```

<ParamField type="string">
  The Sublay user ID.
</ParamField>

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Defaults to `20`.
</ParamField>

<ParamField type="string">
  Optional search term. Filters the list to users whose username or name contains this text (case-insensitive). When omitted, no filtering is applied.
</ParamField>

<ParamField type="string">
  Restricts which field `query` matches against — `username` or `name`. When omitted, `query` matches either field.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<PaginatedResponse<User>>`

***

### fetchFollowersCountByUserId

Returns the total number of followers for a user.

```typescript theme={null}
const { count } = await sublay.users.fetchFollowersCountByUserId({
  userId: "usr_abc123",
});
```

<ParamField type="string">
  The Sublay user ID.
</ParamField>

**Returns** — `Promise<{ count: number }>`

***

### fetchFollowingByUserId

Returns a paginated list of users that the specified user is following.

```typescript theme={null}
const { data, pagination } = await sublay.users.fetchFollowingByUserId({
  userId: "usr_abc123",
  page: 1,
  limit: 20,
});
```

<ParamField type="string">
  The Sublay user ID.
</ParamField>

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Defaults to `20`.
</ParamField>

<ParamField type="string">
  Optional search term. Filters the list to users whose username or name contains this text (case-insensitive). When omitted, no filtering is applied.
</ParamField>

<ParamField type="string">
  Restricts which field `query` matches against — `username` or `name`. When omitted, `query` matches either field.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<PaginatedResponse<User>>`

***

### fetchFollowingCountByUserId

Returns the number of users the specified user is following.

```typescript theme={null}
const { count } = await sublay.users.fetchFollowingCountByUserId({
  userId: "usr_abc123",
});
```

<ParamField type="string">
  The Sublay user ID.
</ParamField>

**Returns** — `Promise<{ count: number }>`

***

### fetchConnectionsByUserId

Returns a paginated list of established mutual connections for a user.

```typescript theme={null}
const { data, pagination } = await sublay.users.fetchConnectionsByUserId({
  userId: "usr_abc123",
  page: 1,
  limit: 20,
});
```

<ParamField type="string">
  The Sublay user ID.
</ParamField>

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Defaults to `20`.
</ParamField>

<ParamField type="string">
  Optional search term. Filters the list to connections whose connected user's username or name contains this text (case-insensitive). When omitted, no filtering is applied.
</ParamField>

<ParamField type="string">
  Restricts which field `query` matches against — `username` or `name`. When omitted, `query` matches either field.
</ParamField>

<SpaceReputationParams />

**Returns** — `Promise<PaginatedResponse<EstablishedConnection>>`

***

### fetchConnectionsCountByUserId

Returns the number of established connections for a user.

```typescript theme={null}
const { count } = await sublay.users.fetchConnectionsCountByUserId({
  userId: "usr_abc123",
});
```

<ParamField type="string">
  The Sublay user ID.
</ParamField>

**Returns** — `Promise<{ count: number }>`

***

## Acting on a user's follows and connections

The functions above are read-only queries about a target user. The functions below **perform an action** on behalf of one user toward another. Because a service key isn't tied to a single user, these routes take both:

* `userId` — the **target** of the action (the user being followed, connected with, etc.), taken from the request path.
* `actingUserId` — the **actor** performing it (the follower, the requester, the user whose perspective a status is from).

<Note>
  Listing and managing the acting user's own follow/connection graph by record ID
  lives on the dedicated [`follows`](/v7/node-sdk/follows) and
  [`connections`](/v7/node-sdk/connections) modules.
</Note>

***

### createFollow

Makes one user follow another.

```typescript theme={null}
const follow = await sublay.users.createFollow({
  userId: "usr_target",
  actingUserId: "usr_follower",
});
```

<ParamField type="string">
  The user being followed (the target).
</ParamField>

<ParamField type="string">
  The user performing the follow (the follower).
</ParamField>

**Returns** — `Promise<Follow>`

***

### deleteFollow

Makes one user unfollow another.

```typescript theme={null}
await sublay.users.deleteFollow({
  userId: "usr_target",
  actingUserId: "usr_follower",
});
```

<ParamField type="string">
  The user being unfollowed (the target).
</ParamField>

<ParamField type="string">
  The user performing the unfollow (the follower).
</ParamField>

**Returns** — `Promise<void>`

***

### fetchFollowStatus

Checks whether the acting user follows the target user.

```typescript theme={null}
const { isFollowing, followId } = await sublay.users.fetchFollowStatus({
  userId: "usr_target",
  actingUserId: "usr_viewer",
});
```

<ParamField type="string">
  The user whose follow relationship is being checked (the target).
</ParamField>

<ParamField type="string">
  The user whose perspective the status is from.
</ParamField>

**Returns** — `Promise<{ isFollowing: boolean; followId?: string }>`

***

### requestConnection

Sends a connection request from the acting user to the target user.

```typescript theme={null}
const connection = await sublay.users.requestConnection({
  userId: "usr_target",
  actingUserId: "usr_requester",
  message: "Let's connect!",
});
```

<ParamField type="string">
  The user the connection is requested with (the target).
</ParamField>

<ParamField type="string">
  The user sending the request (the requester).
</ParamField>

<ParamField type="string">
  Optional message to include with the request.
</ParamField>

**Returns** — `Promise<ConnectionRequestResponse>` — the created/pending connection.

***

### fetchConnectionStatus

Returns the connection status between the acting user and the target user.

```typescript theme={null}
const status = await sublay.users.fetchConnectionStatus({
  userId: "usr_target",
  actingUserId: "usr_viewer",
});
// status.status is "none" | "pending" | "connected" | "declined"
```

<ParamField type="string">
  The other user in the connection (the target).
</ParamField>

<ParamField type="string">
  The user whose perspective the status is from.
</ParamField>

**Returns** — `Promise<ConnectionStatusResponse>` — a discriminated union on `status`: `"none"`, `"pending"` (with `type` and `connectionId`), `"connected"`, or `"declined"`.

***

### removeConnectionByUserId

Removes the connection between the acting user and the target user — withdrawing a sent request, declining a received one, or disconnecting an established connection, depending on the current state.

```typescript theme={null}
const result = await sublay.users.removeConnectionByUserId({
  userId: "usr_target",
  actingUserId: "usr_viewer",
});
// result.action is "withdraw" | "disconnect" | "decline"
```

<ParamField type="string">
  The other user in the connection (the target).
</ParamField>

<ParamField type="string">
  The user withdrawing, declining, or disconnecting.
</ParamField>

**Returns** — `Promise<RemoveConnectionByUserIdResponse>`

## Acting on a user's blocks

User-to-user **blocking** is part of the trust & safety [moderation bundle](/sdk/moderation/overview#blocking). These functions require that bundle; a project without it returns `403 database/tables-not-available`. Each acts on behalf of one user (the blocker) — pass that user's ID as `actingUserId`.

<Note>
  Blocking severs interaction between two users across every Sublay surface and is **non-disclosing** — the blocked user is never notified. See [Moderation — Blocking](/sdk/moderation/overview#blocking) for the full enforcement behavior.
</Note>

***

### createBlock

Blocks one user on behalf of another. On a new block, existing follows and connections between the pair are torn down (both directions) in one transaction. Idempotent — re-blocking succeeds. Self-block is rejected.

```typescript theme={null}
const block = await sublay.users.createBlock({
  userId: "usr_target",
  actingUserId: "usr_blocker",
});
```

<ParamField type="string">
  The user being blocked (the target).
</ParamField>

<ParamField type="string">
  The user performing the block (the blocker).
</ParamField>

**Returns** — `Promise<Block>` — `{ id, blockerId, blockedId, createdAt }`.

***

### deleteBlock

Removes a block on behalf of the blocker. Idempotent; restores nothing.

```typescript theme={null}
await sublay.users.deleteBlock({
  userId: "usr_target",
  actingUserId: "usr_blocker",
});
```

<ParamField type="string">
  The user being unblocked (the target).
</ParamField>

<ParamField type="string">
  The user performing the unblock (the blocker).
</ParamField>

**Returns** — `Promise<void>`

***

### fetchBlockStatus

Checks whether the acting user blocks the target user. **Outbound-only** — it never reveals whether the target has blocked the acting user.

```typescript theme={null}
const { blocked, blockId } = await sublay.users.fetchBlockStatus({
  userId: "usr_target",
  actingUserId: "usr_blocker",
});
```

<ParamField type="string">
  The user whose block relationship is being checked (the target).
</ParamField>

<ParamField type="string">
  The user whose outbound perspective the status is from (the blocker).
</ParamField>

**Returns** — `Promise<{ blocked: boolean; blockId?: string; createdAt?: string }>`

***

### fetchBlockedUsers

Returns a paginated list of the users the acting user has blocked (their outbound blocks), each row carrying a public profile summary. This block list is **private** to the blocker.

```typescript theme={null}
const { data, pagination } = await sublay.users.fetchBlockedUsers({
  actingUserId: "usr_blocker",
  page: 1,
  limit: 20,
});
```

<ParamField type="string">
  The user whose own block list to read (the blocker).
</ParamField>

<ParamField type="number">
  Page number (1-indexed). Defaults to `1`.
</ParamField>

<ParamField type="number">
  Results per page. Defaults to `20`. Max `100`.
</ParamField>

**Returns** — `Promise<PaginatedResponse<BlockedUser>>`, where each `BlockedUser` is `{ id, blockedUser, createdAt }`.


# Workspaces
Source: https://docs.sublay.io/v7/node-sdk/workspaces

Full server-side workspace surface — CRUD, membership, invitations, and authority-as-a-service

The `workspaces` module is the developer's **authorization-server SDK** for the [Workspaces bundle](/data-models/workspace). It exposes the full surface: workspace CRUD, membership management, the invitation lifecycle, and the service-key **authority read** you use to make your own app-level decisions.

<Note>
  **Requires the `workspaces` bundle.** See [Bundles](/bundles) to install it. Because this is a **service-key** SDK, every call **accepts** an `actingUserId` — the user the action is performed **as** (the service key can [act as any user](/node-sdk/overview)). Whether it is required or optional is **per route** — see the notes below. For `fetchWorkspaceAuthority`, `actingUserId` is the user whose standing is resolved.
</Note>

<Note>
  **This SDK is not required in order to manage workspaces.** All 21 endpoints are equally available to a browser or mobile app through the [`@sublay/core` hooks](/sdk/workspaces/overview) and [`@sublay/js`](/js-sdk/workspaces), acting as the signed-in user and subject to the same ownership / capability / rank rules. What the node SDK adds is the acting-user field `actingUserId` — performing an action **as some other named user** — which only a service/master key may do.
</Note>

<Warning>
  **Naming an `actingUserId` means *being* that user.** It is not a hint or an
  audit tag — it **binds**. Every check the named user would face runs: the
  capability gate, the owner-only gate, the rank guard, no-escalation, and the
  roster/standing fencing. If that user would be refused, so are you. Omitting
  `actingUserId` is the only unbounded mode — that request is the *app itself*,
  not a person — and it exists only on the routes that have an unbounded path at
  all (see the two notes below).

  So an unrestricted backend action should be performed **as the workspace
  owner**, not by omitting the actor: the owner resolves the full capability
  vocabulary and apex rank, and the resulting webhooks carry that user id rather
  than nothing. Treat that id as a *claim*, not proof — a key may name any UUID,
  and `ownerId` is not a foreign key, so a deleted owner's id still resolves
  owner authority. Two consequences bite first-time integrators —
  [`acceptWorkspaceInvite`](#acceptworkspaceinvite) requires the invite to be
  actually addressed to the named user *and* that user's email to be verified,
  and a rank tier cannot grow itself (see
  [`createWorkspaceInvite`](#createworkspaceinvite)). Full rule:
  [Acting on behalf of a user](/sdk/workspaces/overview#acting-on-behalf-of-a-user).
</Warning>

<Note>
  **On many routes the actor is required, not optional.** These ten routes have
  **no unbounded path on the server** — their result belongs to a specific
  person, so a key must name one:

  `createWorkspace`, `fetchManyWorkspaces`, `fetchMyWorkspaceInvites`,
  `fetchWorkspaceAuthority`, `acceptWorkspaceInvite`, `declineWorkspaceInvite`,
  `leaveWorkspace`, `updateWorkspaceMember`, `removeWorkspaceMember`,
  `removeWorkspaceMemberFromSubtree`.

  Omitting `actingUserId` on any of them is a `400 workspace/missing-user-id`,
  never a bypass. `actingUserId` is typed **required** on all ten.
</Note>

<Note>
  **Four more are typed required *here* even though the REST endpoint allows
  omission.** `updateWorkspace`, `updateWorkspaceInheritFlag`, `deleteWorkspace`
  and `transferWorkspaceOwnership` are guard-only routes: over REST, a key that
  omits `actingUserId` runs as the app itself and passes the owner-only gate
  unbounded. This SDK nevertheless declares `actingUserId` **required** on all
  four, so TypeScript will not let you omit it.

  That is an SDK-level guardrail, not a different server rule — these are the
  four most destructive owner-only calls (`deleteWorkspace` cascades the whole
  subtree), and every one of them is better off carrying a user id. If you
  genuinely need the unbounded path on one of them, call the
  [REST endpoint](/api-reference/workspaces/delete-workspace) directly; the
  server accepts it.

  On the remaining seven — `fetchWorkspace`, `fetchWorkspaceMembers`,
  `fetchWorkspaceMemberStanding`, `createWorkspaceInvite`,
  `fetchWorkspaceInvites`, `revokeWorkspaceInvite`, `resendWorkspaceInvite` —
  `actingUserId` is optional in both the SDK and the API, and omitting it runs
  unbounded.
</Note>

<Warning>
  **Absent, not falsy — and undeclared fields are refused, not ignored.**
  `actingUserId: ""` or `null` is a `400`, not a fall-through to the app-itself
  mode, so `actingUserId: user?.id ?? ""` fails loudly rather than quietly
  acquiring full authority.

  Every workspaces endpoint also declares its fields exactly, and refuses any
  top-level field it does not declare — in the body and in the query string
  alike, for every caller — with
  `{ "error": "Unrecognized key: \"onBehalfOf\"", "code": "workspace/invalid-body" }`
  (plural `Unrecognized keys: "a", "b"` for two or more, and
  `workspace/invalid-query` when the offender was in the query string). So
  `onBehalfOf`, `impersonate` and `acting_user_id` all fail at the wire rather
  than being dropped on the way to an unbounded call. A `userId` anywhere in a
  body or query is refused with a message of its own — the sole exception is the
  invitee in `createWorkspaceInvite`'s **body**, and even there a query
  `?userId=` is refused like everywhere else. A non-UUID id in a path is a
  `400 workspace/invalid-params` rather than a `500`. Full list with the
  reasoning: [Shapes the server rejects](/sdk/workspaces/overview#shapes-the-server-rejects).

  One of those rules cannot bite you through this SDK: a body whose content-type
  no parser reads is refused on the unbounded path, and this SDK serializes every
  body it sends as `application/json`. It is a hazard for hand-rolled `fetch()`
  calls, not for `sublay.workspaces.*`.
</Warning>

<Warning>
  **Pass only the documented fields — the props object is sent whole.**
  `createWorkspace` and its siblings hand your object straight to the request
  body, so a convenience spread carries whatever else it holds into the request,
  and the endpoint refuses it:

  ```typescript theme={null}
  // ❌ 400 — `slug` and `plan` are not fields of this endpoint.
  await sublay.workspaces.createWorkspace({ ...orgTemplate, actingUserId });

  // ✅ Name the fields.
  await sublay.workspaces.createWorkspace({
    actingUserId,
    name: orgTemplate.name,
    metadata: { slug: orgTemplate.slug, plan: orgTemplate.plan },
  });
  ```

  Your own data belongs in `metadata`, which is opaque to Sublay and accepts any
  JSON. Strictness governs **top-level** keys only, so nothing inside `metadata`
  is inspected.
</Warning>

Read the concepts first: [capabilities vs permissions](/data-models/workspace-member#the-two-arrays-capabilities-vs-permissions), [rank](/data-models/workspace-member#rank-semantics), [reach & ownership](/data-models/workspace#reach-and-the-wall-door-rule), and the [identity-matched, no-token invite model](/data-models/workspace-invitation#acceptance-model).

***

## Workspace lifecycle

### createWorkspace

```typescript theme={null}
const workspace = await sublay.workspaces.createWorkspace({
  actingUserId: "usr_owner",      // becomes the owner
  name: "Acme Inc",
  parentWorkspaceId: null,        // omit/null → root; set → child
});
```

Root creation requires the acting user to have a **verified email**. Child creation requires the `create-sub-workspace` capability on the parent; the creator becomes the child's owner.

<Warning>
  **A service key does NOT bypass the verified-email gate.** The `actingUserId` you act as must itself be verified, or the call returns `403 workspace/email-not-verified`. This matches `acceptWorkspaceInvite` and `transferWorkspaceOwnership` — all three doors into ownership check it, so **every** workspace owner has a confirmed email. A key lets you act *as* a user; it does not make that user verified.
</Warning>

<ParamField type="string">The user the workspace is created as (becomes the owner).</ParamField>
<ParamField type="string">Display name (1–100 characters).</ParamField>
<ParamField type="object">Opaque developer data.</ParamField>
<ParamField type="string">Parent for child creation; absent/`null` → root.</ParamField>

### fetchWorkspace

```typescript theme={null}
const workspace = await sublay.workspaces.fetchWorkspace({
  workspaceId: "ws_abc",
  include: "memberCount",
});
```

<ParamField type="string">The workspace UUID.</ParamField>
<ParamField type="string">Comma-separated include flags, sent as a query param. `memberCount` adds the workspace's direct member count; omit it and the field is absent. An unrecognized flag value is ignored.</ParamField>
<ParamField type="string">Optional — the user to act as. Sent as a query param. Visibility resolves against them, so a key acting as someone with no relation to this workspace gets that user's `404`. Omit to read as the app itself.</ParamField>

### fetchManyWorkspaces

Lists a user's direct-membership + owned workspaces (paginated).

```typescript theme={null}
const { data, pagination } = await sublay.workspaces.fetchManyWorkspaces({
  actingUserId: "usr_owner",
  page: 1,
  limit: 20,
  include: "memberCount", // each row gains a `memberCount`
});
```

<ParamField type="string">The user whose workspaces to list.</ParamField>

<ParamField type="number" />

<ParamField type="number" />

<ParamField type="string">Comma-separated include flags, sent as a query param. `memberCount` adds a `memberCount` to **every row** — the workspace's direct member count, resolved in one grouped query over the returned page rather than one request per row. Omit it and the field is absent from each row.</ParamField>

### updateWorkspace

```typescript theme={null}
await sublay.workspaces.updateWorkspace({
  workspaceId: "ws_abc",
  actingUserId: "usr_editor",
  name: "Acme Corp",
});
```

Edits name/metadata (gated by `edit-workspace` or owner). Does **not** flip the inherit flag.

<ParamField type="string" />

<ParamField type="string">The user to act as — must hold `edit-workspace` on this workspace, or own it. Required by this SDK's types; the [REST endpoint](/api-reference/workspaces/update-workspace) also accepts it omitted (runs unbounded).</ParamField>

<ParamField type="string" />

<ParamField type="object" />

### updateWorkspaceInheritFlag

```typescript theme={null}
await sublay.workspaces.updateWorkspaceInheritFlag({
  workspaceId: "ws_child",
  actingUserId: "usr_owner",
  inheritsFromParent: true,
});
```

Owner-only in both directions; subject to the enforced-default lock.

<ParamField type="string" />

<ParamField type="string">The user to act as — must own this workspace or an ancestor. Required by this SDK's types; the [REST endpoint](/api-reference/workspaces/update-inherit-flag) also accepts it omitted (runs unbounded).</ParamField>

<ParamField type="boolean" />

### deleteWorkspace

```typescript theme={null}
const { message } = await sublay.workspaces.deleteWorkspace({
  workspaceId: "ws_abc",
  actingUserId: "usr_owner",
});
```

Owner-only; cascades the subtree and fires `workspace.deleted` per deleted workspace — and **no** `workspace.member.removed` events for the memberships it tears down (see [Webhooks](/sdk/workspaces/webhooks)).

<ParamField type="string" />

<ParamField type="string">The user to act as — must own this workspace or an ancestor. This call cascade-deletes the whole subtree, so name the owner deliberately. Required by this SDK's types; the [REST endpoint](/api-reference/workspaces/delete-workspace) also accepts it omitted (runs unbounded) — which is precisely why the type does not.</ParamField>

### transferWorkspaceOwnership

```typescript theme={null}
const workspace = await sublay.workspaces.transferWorkspaceOwnership({
  workspaceId: "ws_abc",
  actingUserId: "usr_owner",            // must own this workspace or an ancestor
  newOwnerId: "usr_new",                // must be verified
  previousOwnerDisposition: "demote",
  previousOwnerRank: 0,
});
```

<ParamField type="string" />

<ParamField type="string">The user to act as — must own this workspace or an ancestor. Required by this SDK's types; the [REST endpoint](/api-reference/workspaces/transfer-ownership) also accepts it omitted (runs unbounded).</ParamField>
<ParamField type="string">The new owner (any verified user).</ParamField>
<ParamField type="string">`"demote"` or `"remove"`. Defaults to `"remove"` when omitted.</ParamField>
<ParamField type="number">On demote, the ex-owner's rank (absolute only). Defaults to **one rung below the acting user's anchor** — `0` when the actor is apex (an owner or ancestor owner with no member row here, which is the usual case), or one below their own row when the named `actingUserId` sits in this workspace's ladder. (A key naming nobody also anchors at apex, but this SDK requires `actingUserId` here, so that shape is only reachable over REST.)</ParamField>

<ParamField type="string[]" />

***

## Membership

### fetchWorkspaceMembers

Returns the [unified roster](/api-reference/workspaces/members/list-members) (`WorkspaceRosterResponse`), or `WorkspaceRosterCountsResponse` when `countOnly` is set.

<Note>
  The roster fences the authority-bearing reason fields (`rank`, `relativeRank`, `capabilities`, `permissions`) from callers who cannot manage people on the workspace — **per node**, so with `include=descendants` each `descendant-member` reason is judged against the acting user's resolved standing on *that* descendant, and authority over the parent does not unfence a **sealed** child. A service key acting as **itself** is never fenced — it always sees them. Pass `actingUserId` and the fence evaluates against **that user** instead, so a key acting as a plain member receives the same partial roster that member would. The SDK types mark the four fields optional for that reason.

  A `member` reason carries both rank coordinates: absolute `rank`, and `relativeRank` — that member's position as an offset from **the caller**, meaning the acting user when you name one. `descendant-member` reasons carry `rank` only, since their ranks belong to another node's ladder.
</Note>

```typescript theme={null}
const roster = await sublay.workspaces.fetchWorkspaceMembers({
  workspaceId: "ws_abc",
  include: "ancestorOwners,descendants",
});

const counts = await sublay.workspaces.fetchWorkspaceMembers({
  workspaceId: "ws_abc",
  countOnly: true,
});
```

<ParamField type="string" />

<ParamField type="string">`ancestorOwners`, `reachHolders`, `descendants`.</ParamField>

<ParamField type="boolean" />

<ParamField type="string">Optional — the user to act as. Sent as a query param. Roster visibility and the authority-field fence both evaluate against them. Omit to read as the app itself (unfenced).</ParamField>

### fetchWorkspaceMemberStanding

```typescript theme={null}
const standing = await sublay.workspaces.fetchWorkspaceMemberStanding({
  workspaceId: "ws_abc",
  targetUserId: "usr_pat",
});
```

<ParamField type="string" />

<ParamField type="string">The user whose standing to read.</ParamField>
<ParamField type="string">Optional — the user to act as. Sent as a query param. Roster visibility and the authority-field fence both evaluate against them (and a caller always sees their **own** access, so `actingUserId === targetUserId` is never fenced). Omit to read as the app itself.</ParamField>

Returns `WorkspaceMemberStanding`. On its `user` field **only `id` is guaranteed** (`WorkspaceStandingUser`): the server returns the full user record when the user row still exists and falls back to `{ id }` alone when it does not — a deleted user with a lingering membership row is a reachable case. Read the rest defensively (`standing.user.username ?? "Deleted user"`).

`reasons` is an array of structured `{ type, viaWorkspaceId? }` entries — the same shape a roster entry's `reasons` carries — so you learn not just the kind of standing but which ancestor grants it. `capabilities` / `permissions` / `rank` / `relativeRank` are typed **optional** because the server omits them for callers who cannot manage people (`relativeRank` is fenced with `rank` — it is `rank` minus an anchor the caller already knows). A service key acting as **itself** is never fenced, so on a call with no `actingUserId` they are always present; pass one and the fence evaluates against that user, who may well not see them.

### updateWorkspaceMember

```typescript theme={null}
await sublay.workspaces.updateWorkspaceMember({
  workspaceId: "ws_abc",
  targetUserId: "usr_pat",
  actingUserId: "usr_admin",
  capabilities: ["view", "invite"],
  rank: 3,
});
```

Powerful fields require `edit-member-access` + rank rules + no-escalation; cosmetic fields require `edit-member-profile`.

Rank moves in **either coordinate** — `rank` (absolute) or `relativeRank` (an offset from `actingUserId`), never both. Omitting both means **rank unchanged**. See [choosing a rank](/sdk/workspaces/overview#choosing-a-rank).

<ParamField type="string" />

<ParamField type="string">The member being edited (path).</ParamField>
<ParamField type="string">The acting user (body). Required by the **server** here, not just by the types: this route has no unbounded path, so omitting it is a `400 workspace/missing-user-id`. Every gate — both capability tiers, the rank guard, the assign rule, no-escalation — runs against this user. Act as the owner for an unrestricted edit.</ParamField>

<ParamField type="string[]" />

<ParamField type="string[]" />

<ParamField type="number">Absolute. Mutually exclusive with `relativeRank`; omit both to leave rank unchanged.</ParamField>
<ParamField type="number">An offset from the **acting user** — `1` = one rung below them. Must be `>= 1`. Anchored on their member row on this workspace if they hold one, apex otherwise, so a key acting as the owner resolves `relativeRank: 1` to rank `0`. Resolved to an absolute rank at write time and frozen. No default.</ParamField>

<ParamField type="string" />

<ParamField type="object" />

### removeWorkspaceMember

```typescript theme={null}
await sublay.workspaces.removeWorkspaceMember({
  workspaceId: "ws_abc",
  targetUserId: "usr_pat",
  actingUserId: "usr_admin",
});
```

Requires `remove-member` (rank-bounded); sole-owner protected.

<ParamField type="string" />

<ParamField type="string">The member to remove.</ParamField>
<ParamField type="string">The acting user.</ParamField>

### leaveWorkspace

```typescript theme={null}
await sublay.workspaces.leaveWorkspace({ workspaceId: "ws_abc", actingUserId: "usr_pat" });
```

Removes the given user's own membership on this node only.

<ParamField type="string" />

<ParamField type="string">The user leaving.</ParamField>

### removeWorkspaceMemberFromSubtree

```typescript theme={null}
const result = await sublay.workspaces.removeWorkspaceMemberFromSubtree({
  workspaceId: "ws_root",
  targetUserId: "usr_pat",
  actingUserId: "usr_admin",
});
// result: { removedCount, removed, skippedCount, skipped }

if (result.skippedCount > 0) {
  // NOT fully offboarded — memberships survived in branches the ACTING user
  // (`actingUserId`) cannot reach. `id`/`name` are null where they have no standing.
  console.warn("Still a member of", result.skippedCount, "workspace(s):", result.skipped);
}
```

Blocks with `409 workspace/owns-descendants` (and a report) if the target owns any descendant workspace.

<Note>
  **`skippedCount` reflects the acting user, not the key.** The sweep is partial for a **non-owner** actor, and `actingUserId` is **required** on this call — a key always names someone, and is bound by their reach and their per-node rank. Name a non-owner admin and you can get a partial sweep, exactly as that admin would; name the owner for the god-path that clears every descendant. Always assert on `skippedCount` rather than assuming `removedCount` means the user is fully offboarded.
</Note>

<ParamField type="string" />

<ParamField type="string">The user to offboard.</ParamField>
<ParamField type="string">The acting user.</ParamField>

***

## Invitations

### createWorkspaceInvite

```typescript theme={null}
const invite = await sublay.workspaces.createWorkspaceInvite({
  workspaceId: "ws_abc",
  email: "pat@example.com",   // OR userId / username
  capabilities: ["view"],
  permissions: ["deploy"],
  // One rung below the inviter. Omitting both rank fields means exactly this.
  relativeRank: 1,
});
```

Requires the `invite` capability. Here `userId`/`username` (if used) address the invite **target**; the **inviter** is `actingUserId`, or the app itself when you omit it. Email matching against existing accounts is **case-insensitive**.

The invited grant is floored by the inviter's own standing: no-escalation on `capabilities`/`permissions`, and a rank strictly below the inviter's own. Both floors are skipped for an owner, and for a key naming nobody.

The invited rank is named in **either coordinate** — `rank` (absolute) or `relativeRank` (an offset from the inviter) — and they are mutually exclusive. Supplying **neither** applies `relativeRank: 1`, one rung below the inviter, which is well defined for every actor shape (a key naming nobody anchors at apex, so its default lands on rank `0`) and by construction never trips the rank floor.

<Note>
  **A tier cannot grow itself.** Acting as a rank-5 manager with a direct member row you can invite rank 6, 7, 8… but **never another rank 5**, and no ranked member clears the floor for rank 0. The floor binds only an inviter with a **direct member row** on the workspace — an owner or ancestor owner, a reach-holder with no direct row, and a key naming nobody all skip it entirely. If your product has a server-driven "add a manager" action, act as the owner for it. See [Acting on behalf of a user](/sdk/workspaces/overview#acting-on-behalf-of-a-user).
</Note>

<Warning>
  **The project must have `workspaces.inviteAcceptUrl` configured**, or this call fails with `409 workspace/missing-invite-accept-url` and persists nothing. It has no default, and a service key does not exempt you. Applies even when the invitee already has an account. See [Project settings](/sdk/workspaces/overview#project-settings).
</Warning>

<ParamField type="string" />

<ParamField type="string">One of `email`/`userId`/`username`.</ParamField>
<ParamField type="string">Invite target user id.</ParamField>
<ParamField type="string">Invite target username.</ParamField>

<ParamField type="string[]" />

<ParamField type="string[]" />

<ParamField type="number">Absolute. **Not required** — mutually exclusive with `relativeRank`, and omitting both applies the `relativeRank: 1` default.</ParamField>
<ParamField type="number">An offset from the inviter — `1` = one rung below them. Must be `>= 1`. Anchored on the inviter's member row on this workspace if they hold one, apex otherwise. A **snapshot**: resolved to an absolute rank here and frozen, so a later promotion or demotion of the inviter does not move the pending invite. Note the collision caveat, which is at its sharpest here: a key acting as **itself** (no `actingUserId`) has no member row, so it anchors at **apex** and the default mints **rank 0** — the most senior rung — for every invitee. A backend invite flow that wants people at the *bottom* of the ladder must name an absolute `rank`, or name an `actingUserId` who actually sits in the ladder. For an in-ladder inviter the default instead puts a whole cohort on one rung, where equals cannot manage each other. See [choosing a rank](/sdk/workspaces/overview#choosing-a-rank).</ParamField>

<ParamField type="string" />

<ParamField type="string">Optional — the **inviter** to act as. The no-escalation and rank floors run against their standing. Omit to invite as the app itself (unbounded; `invitedBy` then falls back to the workspace owner). Distinct from `userId`, which is the invitee.</ParamField>

### fetchWorkspaceInvites

```typescript theme={null}
const { data } = await sublay.workspaces.fetchWorkspaceInvites({ workspaceId: "ws_abc" });
```

The workspace's **outbox** — the live pending invites *it has issued*. Requires `invite` (or owner). Not to be confused with [`fetchMyWorkspaceInvites`](#fetchmyworkspaceinvites), which is one user's **inbox** of invites addressed *to them* across every workspace.

<ParamField type="string" />

<ParamField type="string">Optional — the user to act as. Sent as a query param. `invite` (or ownership) is required *of them*. Omit to read as the app itself.</ParamField>

### revokeWorkspaceInvite

```typescript theme={null}
await sublay.workspaces.revokeWorkspaceInvite({ workspaceId: "ws_abc", inviteId: "inv_1" });
```

<ParamField type="string" />

<ParamField type="string" />

<ParamField type="string">Optional — the user to act as. `invite` (or ownership) is required *of them*. Omit to act as the app itself.</ParamField>

### resendWorkspaceInvite

```typescript theme={null}
const invite = await sublay.workspaces.resendWorkspaceInvite({ workspaceId: "ws_abc", inviteId: "inv_1" });
```

Refreshes a lapsed pending invite (14-day expiry) and resends the email. Terminal invites → `409`. Returns the refreshed `WorkspaceInvitation`, carrying the new `expiresAt`. Like `createWorkspaceInvite`, it requires [`workspaces.inviteAcceptUrl`](/sdk/workspaces/overview#project-settings) on the project → otherwise `409 workspace/missing-invite-accept-url` with `expiresAt` untouched.

<ParamField type="string" />

<ParamField type="string" />

<ParamField type="string">Optional — the user to act as. `invite` (or ownership) is required *of them*. Omit to act as the app itself.</ParamField>

### acceptWorkspaceInvite

```typescript theme={null}
const { workspaceId } = await sublay.workspaces.acceptWorkspaceInvite({
  inviteId: "inv_1",
  actingUserId: "usr_pat", // must BE the target and be verified
});
```

Identity-matched + verified-email. Idempotent when already a member/owner.

<ParamField type="string" />

<ParamField type="string">The accepting user (must be the target and verified).</ParamField>

### declineWorkspaceInvite

```typescript theme={null}
await sublay.workspaces.declineWorkspaceInvite({ inviteId: "inv_1", actingUserId: "usr_pat" });
```

Identity-matched + verified-email — the same gate as accept, so an unverified squatter on someone else's address cannot burn their invite. A service key does **not** bypass it: the `actingUserId` you act as must itself be verified, or the call returns `403 workspace/email-not-verified`.

### fetchMyWorkspaceInvites

```typescript theme={null}
const { data } = await sublay.workspaces.fetchMyWorkspaceInvites({ actingUserId: "usr_pat" });
```

The user's **inbox** — their live pending invites addressed *to them* across every workspace (matched by `userId`). The per-workspace **outbox** counterpart is [`fetchWorkspaceInvites`](#fetchworkspaceinvites).

***

## Authority-as-a-service

### fetchWorkspaceAuthority

The **service-key authority read** — the crux of the server-side surface. Resolve any user's standing on a workspace, then run your own permission check with a one-line `.includes()`.

```typescript theme={null}
const authority = await sublay.workspaces.fetchWorkspaceAuthority({
  workspaceId: "ws_abc",
  actingUserId: "usr_pat",   // the user to act as; their standing is resolved
});

// { reasons: [{ type, viaWorkspaceId? }], capabilities, permissions, rank }
if (authority.permissions.includes("deploy")) {
  // your app allows the action
}
```

<ParamField type="string" />

<ParamField type="string">The acting user whose resolved standing to read.</ParamField>

`reasons` entries carry `viaWorkspaceId` on `ancestor-owner` / `reach-holder`, naming the ancestor responsible — so when a user has authority you did not expect, you can tell exactly which node to go fix. `capabilities` is the fully-resolved set, and **`view` is implied by every other capability**: any user with standing carries it, while a user with no relation at all comes back with `reasons: []` and an empty capability set. There is no `relativeRank` on this read — it is an offset from the caller, and here the caller is the subject, so `rank` is the coordinate it reports.

Sublay never consumes your opaque `permissions` — there is deliberately no `?permission=` check or `can()` helper.