Skip to main content
POST
Create 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

name
string
Display name for the space. Must be 3–100 characters.
slug
string
Optional URL slug. Must be unique per project. Supports Unicode letters, numbers, hyphens, and underscores.
description
string
Optional description. Up to 1,000 characters.
readingPermission
string
Who can read content: "anyone" or "members". Defaults to "anyone".
postingPermission
string
Who can post entities: "anyone", "members", or "admins". Defaults to "members".
visibility
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.
requireJoinApproval
boolean
Whether new joins require approval. Defaults to true.
metadata
object
Optional arbitrary key-value data. Up to 1 MB.
parentSpaceId
string
Optional UUID of a parent space. The caller must be an admin of the parent space.
avatarFile
file
Optional avatar image. Multipart form field. Requires avatarFile.options when provided.
bannerFile
file
Optional banner image. Multipart form field. Requires bannerFile.options when provided.

Response

Returns the created Space object with membersCount, childSpacesCount, and optional file associations.

Error Responses

See also: useCreateSpace