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

---

createSpace

Creates a new space.

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

userId · string · required

The Sublay user ID of the space creator, who becomes the initial admin.

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" (default) or "members".

postingPermission · string

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

requireJoinApproval · boolean

When true, join requests must be manually approved. Defaults to false.

parentSpaceId · string

Makes this space a child of the specified parent space.

metadata · object

Arbitrary metadata attached to the space.

Returns — Promise<Space>

---

fetchSpace

Fetches a space by its Sublay ID, including member counts and permission details.

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

spaceId · string · required

The Sublay space ID.

Returns — Promise<SpaceDetailed>

---

fetchManySpaces

Fetches a paginated list of top-level spaces, with optional text search.

const { data, pagination } = await sublay.spaces.fetchManySpaces({
  page: 1,
  limit: 20,
  searchName: "photo",
  sortBy: "members",
});

page · number

Page number (1-indexed). Defaults to 1.

limit · number

Results per page. Defaults to 20.

sortBy · string

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

searchName · string

Filter spaces whose name matches the query.

searchSlug · string

Filter spaces whose slug matches the query.

searchDescription · string

Filter spaces whose description matches the query.

searchAny · string

Filter spaces matching the query across name, slug, or description.

memberOf · "true"

When "true", returns only spaces the requesting context is a member of.

parentSpaceId · string | "null"

Filter to children of a specific space, or pass "null" for top-level spaces only.

include · string

Comma-separated list of associations to populate.

Returns — Promise<PaginatedResponse<Space>>

---

fetchSpaceBySlug

Fetches a space by its unique slug.

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

slug · string · required

The space’s URL slug.

Returns — Promise<SpaceDetailed>

---

fetchSpaceByShortId

Fetches a space by its short, human-readable ID (used in share URLs).

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

shortId · string · required

The space’s short ID.

Returns — Promise<SpaceDetailed>

---

fetchUserSpaces

Fetches the spaces a specific user is a member of.

const result = await sublay.spaces.fetchUserSpaces({
  userId: "usr_abc123",
  page: 1,
  limit: 20,
});

userId · string · required

The Sublay user ID.

page · number

Page number (1-indexed). Defaults to 1.

limit · number

Results per page. Defaults to 20.

sortBy · string

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

role · string

Filter by the user’s role in the space. A single role or comma-separated list, e.g. "admin,moderator".

all · "true" | "false"

When "true", returns the full set of spaces rather than only the paginated page.

include · string

Comma-separated list of associations to populate.

Returns — Promise<UserSpacesResponse>

---

fetchMutualSpaces

Fetches the spaces shared between two users — the spaces both are active members of.

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

userId · string · required

The other user’s Sublay ID. Mutual spaces are computed between this user and actingUserId.

actingUserId · string · required

The user to act as. Because the SDK authenticates with a service key, you must name the acting user explicitly.

page · number

Page number (1-indexed). Defaults to 1.

limit · number

Results per page. Max 100. Defaults to 20.

include · string

Comma-separated list of associations to populate (e.g. "files").

Returns — Promise<PaginatedResponse<Space>>

---

updateSpace

Updates settings on an existing space.

const space = await sublay.spaces.updateSpace({
  spaceId: "spc_abc123",
  name: "Photography Community",
  postingPermission: "admins",
  requireJoinApproval: true,
});

spaceId · string · required

The Sublay space ID to update.

name · string

New display name.

slug · string

New slug. Must be unique.

description · string

New description.

readingPermission · string

Updated reading permission: "anyone" or "members".

postingPermission · string

Updated posting permission: "anyone", "members", or "admins".

metadata · object

Updated metadata. Merged with existing values.

Returns — Promise<Space>

---

deleteSpace

Permanently deletes a space and all its content.

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

spaceId · string · required

The Sublay space ID to delete.

Returns — Promise<DeleteSpaceResponse>

---

checkSlugAvailability

Checks whether a slug is available for use.

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

slug · string · required

The slug to check.

Returns — Promise<{ available: boolean }>

---

fetchChildSpaces

Fetches the direct child spaces of a given parent space.

const { data, pagination } = await sublay.spaces.fetchChildSpaces({
  spaceId: "spc_abc123",
  page: 1,
  limit: 20,
});

spaceId · string · required

The parent Sublay space ID.

page · number

Page number (1-indexed). Defaults to 1.

limit · number

Results per page. Defaults to 20.

sortBy · string

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

include · string

Comma-separated list of associations to populate.

Returns — Promise<PaginatedResponse<Space>>

---

fetchSpaceBreadcrumb

Returns the full ancestor chain from the root down to the specified space. Useful for rendering breadcrumb navigation.

const breadcrumb = await sublay.spaces.fetchSpaceBreadcrumb({
  spaceId: "spc_abc123",
});
// [{ id: "root", name: "Root" }, { id: "spc_parent", name: "Parent" }, { id: "spc_abc123", name: "Photography" }]

spaceId · string · required

The Sublay space ID to get the breadcrumb for.

Returns — Promise<SpaceBreadcrumb>