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, and for moderation, rules, and digest configuration see Space Moderation.

---

createSpace

Creates a new space.

const space = await sublay.spaces.createSpace({
  name: "Photography",
  slug: "photography",
  description: "A community for photographers",
  postingPermission: "members",
});

name · string · required

Display name for the space.

slug · string

URL-friendly identifier. Must be unique within the project. Generated from name if omitted.

description · string

Short description of the space.

readingPermission · string

Who can read content: "anyone" or "members".

postingPermission · string

Who can post content: "anyone", "members", or "admins".

requireJoinApproval · boolean

When true, join requests must be manually approved.

parentSpaceId · string

Makes this space a child of the specified parent space.

metadata · Record<string, any>

Arbitrary metadata attached to the space.

Returns — Promise<Space>

---

fetchSpace

Fetches a single space, including detailed information, by its ID.

const space = await sublay.spaces.fetchSpace({ spaceId: "spc_abc123" });

spaceId · string · required

The Sublay space ID.

Returns — Promise<SpaceDetailed>

---

fetchManySpaces

Fetches a paginated, filterable list of spaces.

const { data, pagination } = await sublay.spaces.fetchManySpaces({
  sortBy: "members",
  parentSpaceId: "null",
  limit: 20,
});

page · number

The page number to fetch.

limit · number

The number of spaces to return per page.

sortBy · string

Sort order: "alphabetical", "newest", or "members".

searchSlug · string

Filter by matching slug.

searchName · string

Filter by matching name.

searchDescription · string

Filter by matching description.

searchAny · string

Filter by matching across slug, name, and description.

memberOf · string

Pass "true" to return only spaces you belong to.

parentSpaceId · string

Filter by parent space. Pass "null" for top-level spaces.

include · string

Comma-separated related resources to include in the response.

Returns — Promise<PaginatedResponse<Space>>

---

fetchSpaceBySlug

Fetches a detailed space by its slug.

const space = await sublay.spaces.fetchSpaceBySlug({ slug: "photography" });

slug · string · required

The space slug.

Returns — Promise<SpaceDetailed>

---

fetchSpaceByShortId

Fetches a detailed space by its short ID.

const space = await sublay.spaces.fetchSpaceByShortId({ shortId: "a1b2c3" });

shortId · string · required

The space short ID.

Returns — Promise<SpaceDetailed>

---

fetchUserSpaces

Fetches the spaces the logged-in user belongs to.

const userSpaces = await sublay.spaces.fetchUserSpaces({
  role: "admin,moderator",
  sortBy: "newest",
});

page · number

The page number to fetch.

limit · number

The number of spaces to return per page.

sortBy · string

Sort order: "alphabetical", "newest", or "members".

include · string

Comma-separated related resources to include in the response.

role · string

Filter by role. A single role or a comma-separated list, e.g. "admin,moderator".

all · string

Pass "true" or "false".

Returns — Promise<UserSpacesResponse>

---

fetchMutualSpaces

Fetches the spaces the logged-in user shares with another user — the spaces both are active members of.

const mutual = await sublay.spaces.fetchMutualSpaces({
  userId: "usr_other",
  page: 1,
  limit: 20,
});

userId · string · required

The other user’s ID. Mutual spaces are computed between this user and the logged-in user.

page · number

The page number to fetch.

limit · number

The number of spaces to return per page. Max 100.

include · string

Comma-separated related resources to include (e.g. "files").

Returns — Promise<PaginatedResponse<Space>>

---

updateSpace

Updates a space’s settings.

const space = await sublay.spaces.updateSpace({
  spaceId: "spc_abc123",
  description: "An updated description",
  postingPermission: "admins",
});

spaceId · string · required

The Sublay space ID.

name · string

New display name for the space.

slug · string

New URL-friendly identifier.

description · string

New description of the space.

readingPermission · string

Who can read content: "anyone" or "members".

postingPermission · string

Who can post content: "anyone", "members", or "admins".

metadata · Record<string, any>

Arbitrary metadata attached to the space.

Returns — Promise<Space>

---

deleteSpace

Deletes a space.

const result = await sublay.spaces.deleteSpace({ spaceId: "spc_abc123" });

spaceId · string · required

The Sublay space ID.

Returns — Promise<DeleteSpaceResponse>

---

checkSlugAvailability

Checks whether a space slug is available.

const { available } = await sublay.spaces.checkSlugAvailability({
  slug: "photography",
});

slug · string · required

The slug to check.

Returns — Promise<{ available: boolean }>

---

fetchChildSpaces

Fetches a paginated list of child spaces under a parent.

const { data, pagination } = await sublay.spaces.fetchChildSpaces({
  spaceId: "spc_abc123",
  sortBy: "alphabetical",
});

spaceId · string · required

The parent space ID.

page · number

The page number to fetch.

limit · number

The number of spaces to return per page.

sortBy · string

Sort order: "alphabetical", "newest", or "members".

include · string

Comma-separated related resources to include in the response.

Returns — Promise<PaginatedResponse<Space>>

---

fetchSpaceBreadcrumb

Fetches the ancestor breadcrumb chain for a space.

const breadcrumb = await sublay.spaces.fetchSpaceBreadcrumb({
  spaceId: "spc_abc123",
});

spaceId · string · required

The Sublay space ID.

Returns — Promise<SpaceBreadcrumb>

---

getSpaceConversation

Gets the chat conversation object associated with a space.

const conversation = await sublay.spaces.getSpaceConversation({
  spaceId: "spc_abc123",
});

spaceId · string · required

The Sublay space ID.

Returns — Promise<Conversation>

Space chat messages are sent and read via the chat module.