Spaces

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 and rules 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",
});

string

required

Display name for the space.

string

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

string

Short description of the space.

string

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

string

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

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".

boolean

When true, join requests must be manually approved.

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.

string

Makes this space a child of the specified parent space.

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" });

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,
});

number

The page number to fetch.

number

The number of spaces to return per page.

string

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

string

Filter by matching slug.

string

Filter by matching name.

string

Filter by matching description.

string

Filter by matching across slug, name, and description.

string

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

string

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

"include-all" | "exclude" | "only"

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.

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" });

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" });

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",
});

number

The page number to fetch.

number

The number of spaces to return per page.

string

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

string

Comma-separated related resources to include in the response.

string

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

string

Membership status to list: "active" (default), "pending", or "banned". Use "pending" to find join requests still awaiting approval.

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,
});

string

required

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

number

The page number to fetch.

number

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

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",
});

string

required

The Sublay space ID.

string

New display name for the space.

string

New URL-friendly identifier.

string

New description of the space.

string

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

string

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

string

Updated visibility: "public", "unlisted", or "private". Controls listing/discoverability, independent of readingPermission.

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.

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" });

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",
});

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",
});

string

required

The parent space ID.

number

The page number to fetch.

number

The number of spaces to return per page.

string

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

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",
});

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",
});

string

required

The Sublay space ID.

Returns — Promise<Conversation>

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

Getting Started

Modules

createSpace

fetchSpace

fetchManySpaces

fetchSpaceBySlug

fetchSpaceByShortId

fetchUserSpaces

fetchMutualSpaces

updateSpace

deleteSpace

checkSlugAvailability

fetchChildSpaces

fetchSpaceBreadcrumb

getSpaceConversation

​createSpace

​fetchSpace

​fetchManySpaces

​fetchSpaceBySlug

​fetchSpaceByShortId

​fetchUserSpaces

​fetchMutualSpaces

​updateSpace

​deleteSpace

​checkSlugAvailability

​fetchChildSpaces

​fetchSpaceBreadcrumb

​getSpaceConversation

createSpace

fetchSpace

fetchManySpaces

fetchSpaceBySlug

fetchSpaceByShortId

fetchUserSpaces

fetchMutualSpaces

updateSpace

deleteSpace

checkSlugAvailability

fetchChildSpaces

fetchSpaceBreadcrumb

getSpaceConversation