Space

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, avatar and banner images, and an optional digest/newsletter webhook. 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[].

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 below.
`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.

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.

Visibility can be set on create and update, 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.

​Space

​SpaceDetailed

​SpacePreview

​SpaceMemberPermissions

​Visibility

​Related

Space

SpaceDetailed

SpacePreview

SpaceMemberPermissions

Visibility

Related