Kumospace Spaces API

openapi: 3.2.0
info:
  title: '@kumo/api Account Spaces API'
  contact: {}
servers:
- url: /
tags:
- name: Spaces
paths:
  /v1/spaces:
    get:
      operationId: GetSpacesByOwner
      responses:
        '200':
          description: A paginated list of spaces.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse_ApiSpace-or-ApiSpacePublicInfo_'
      description: Get spaces owned by the user.  For now, users can only have a single space.
      summary: Get the user's spaces.
      tags:
      - Spaces
      security:
      - firebase: []
      parameters:
      - description: If true, also returns spaces the user is a member of.
        in: query
        name: members
        required: false
        schema:
          type: boolean
      - in: query
        name: excludeDemo
        required: false
        schema:
          type: boolean
      - in: query
        name: emailDomain
        required: false
        schema:
          type: boolean
    post:
      operationId: CreateSpace
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                properties:
                  uid:
                    type: string
                required:
                - uid
                type: object
      description: 'Creates a new space.  Spaces must have a globally unique name, and each

        user can only own one space.'
      summary: Create a space.
      tags:
      - Spaces
      security:
      - firebase: []
      parameters: []
      requestBody:
        description: The space.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiCreateSpaceRequest'
              description: The space.
  /v1/spaces/{name}:
    get:
      operationId: GetSpaceByName
      responses:
        '200':
          description: The space.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSpace'
      description: 'Get a space by name.  Only returns a space if the user has permission to

        join.'
      summary: Get a space by name.
      tags:
      - Spaces
      security:
      - firebase: []
      parameters:
      - description: The name of the space.
        in: path
        name: name
        required: true
        schema:
          type: string
      - in: header
        name: Password
        required: false
        schema:
          type: string
      - in: header
        name: InviteToken
        required: false
        schema:
          type: string
    put:
      operationId: UpdateSpace
      responses:
        '204':
          description: No content
      description: 'Updates an existing space.  Can only be called by the owner of the space.

        Any fields that are not sent will be preserved.'
      summary: Update a space.
      tags:
      - Spaces
      security:
      - firebase: []
      parameters:
      - description: The name of the space.
        in: path
        name: name
        required: true
        schema:
          type: string
      requestBody:
        description: New properties for the space.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiUpdateSpaceRequest'
              description: New properties for the space.
    delete:
      operationId: DeleteSpace
      responses:
        '204':
          description: No content
      description: 'Deletes a space.  Can only be called by the owner of the space.  This

        method will return success even if the space does not exist.'
      summary: Delete a space.
      tags:
      - Spaces
      security:
      - firebase: []
      parameters:
      - description: The name of the space.
        in: path
        name: name
        required: true
        schema:
          type: string
  /v1/spaces/{name}/publicInfo:
    get:
      operationId: GetSpacePublicInfoByName
      responses:
        '200':
          description: Public information about the space.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSpacePublicInfo'
      description: Get public information about a space.
      summary: Get public information about a space
      tags:
      - Spaces
      security:
      - firebase: []
      parameters:
      - description: The name of the space.
        in: path
        name: name
        required: true
        schema:
          type: string
  /v1/spaces/{name}/chatConfig:
    get:
      operationId: GetSpaceChatConfigByName
      responses:
        '200':
          description: The space's chat config
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiChatConfig'
      description: 'Get a space''s chat config.  Only returns chat info if the user has permission

        to access the space.'
      summary: Get a space's chat config
      tags:
      - Spaces
      security:
      - firebase: []
      parameters:
      - description: The name of the space.
        in: path
        name: name
        required: true
        schema:
          type: string
  /v1/spaces/{name}/channels:
    get:
      operationId: GetSpaceUserChannels
      responses:
        '200':
          description: The space's chat channels
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ApiChatConfigChannel'
                type: array
      description: Get a space's chat channels
      summary: Get a space's chat channels
      tags:
      - Spaces
      security:
      - firebase: []
      parameters:
      - description: The name of the space.
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: if true, only returns channels with unread messages
        in: query
        name: withUnreadMessagesOnly
        required: false
        schema:
          type: boolean
  /v1/spaces/{name}/customChannels:
    get:
      operationId: GetSpaceCustomChannels
      responses:
        '200':
          description: All space's public channels and only the space's private channels a user belongs to.
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/SendbirdChannel'
                type: array
      description: 'Get a space''s custom channels. Returns all space''s public channels and only the

        space''s private channels a user belongs to.'
      summary: Get a space's custom channels
      tags:
      - Spaces
      security:
      - firebase: []
      parameters:
      - description: The name of the space.
        in: path
        name: name
        required: true
        schema:
          type: string
      - in: query
        name: includeArchived
        required: false
        schema:
          type: boolean
  /v1/spaces/{name}/home:
    put:
      operationId: UpdateHome
      responses:
        '204':
          description: No content
      description: Creates or updates a user's spawn home for a space
      summary: Update a user's spawn home.
      tags:
      - Spaces
      security:
      - firebase: []
      parameters:
      - description: The space name.
        in: path
        name: name
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiUpdateHomeRequest'
    delete:
      operationId: DeleteHome
      responses:
        '204':
          description: No content
      description: Deletes an existing user's spawn home for a space
      summary: Delete a user's spawn home.
      tags:
      - Spaces
      security:
      - firebase: []
      parameters:
      - description: The space name.
        in: path
        name: name
        required: true
        schema:
          type: string
  /v1/spaces/{name}/trial:
    put:
      operationId: StartInternalFreeTrial
      responses:
        '204':
          description: No content
      description: Starts an internal free trial if the space never got one or a stripe free trial
      summary: Start a free trial if space never got one
      tags:
      - Spaces
      security:
      - firebase: []
      parameters:
      - description: The space name.
        in: path
        name: name
        required: true
        schema:
          type: string
    get:
      operationId: GetFreeTrialInfo
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                properties:
                  hasHadFreeTrial:
                    type: boolean
                required:
                - hasHadFreeTrial
                type: object
      description: Retrieves free trial info
      summary: Retrieves free trial info
      tags:
      - Spaces
      security:
      - firebase: []
      parameters:
      - description: The space name
        in: path
        name: name
        required: true
        schema:
          type: string
  /v1/spaces/{name}/addMemberLink/{addMemberLinkId}:
    get:
      operationId: GetAddMemberLink
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddMemberLink'
      description: Retrieves an Add Member Link for a space
      summary: Start a free trial if space never got one
      tags:
      - Spaces
      security:
      - firebase: []
      parameters:
      - description: The space name.
        in: path
        name: name
        required: true
        schema:
          type: string
      - description: The ID of the link to retrieve
        in: path
        name: addMemberLinkId
        required: true
        schema:
          type: string
  /v1/spaces/{name}/prospected:
    put:
      operationId: SetProspected
      responses:
        '204':
          description: No content
      description: 'Set a space as already prospected by Sales Team.

        Can only be called by verified Kumospace users.'
      summary: Set a space as already prospected by Sales Team.
      tags:
      - Spaces
      security:
      - firebase: []
      parameters:
      - description: The space name.
        in: path
        name: name
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiUpdateProspectStatusRequest'
  /v1/spaces/{name}/ownerEmail:
    get:
      operationId: GetSpaceOwnerEmail
      responses:
        '200':
          description: The space owner's email.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiGetSpaceOwnerEmailResponse'
      description: Returns the space owner's email
      summary: Get a space owner's email.
      tags:
      - Spaces
      security:
      - firebase: []
      parameters:
      - description: The name of the space.
        in: path
        name: name
        required: true
        schema:
          type: string
  /v1/spaces/{name}/defaultChannels:
    put:
      operationId: UpdateDefaultChannels
      responses:
        '204':
          description: No content
      description: 'Updates a space''s default channels. When a guest is promoted

        to member, they are added to all the space''s default channels'
      summary: Updates a custom channel's settings
      tags:
      - Spaces
      security:
      - firebase: []
      parameters:
      - in: path
        name: name
        required: true
        schema:
          type: string
      requestBody:
        description: Body of the request
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiUpdateDefaultChannelsRequest'
              description: Body of the request
  /v1/spaces/{spaceName}/can-schedule-demo:
    get:
      operationId: GetCanSpaceScheduleDemo
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiGetCanSpaceScheduleDemoResponse'
      summary: 'Uses onboarding intake forms to determine if the space

        is a small company or not.'
      tags:
      - Spaces
      security:
      - firebase: []
      parameters:
      - in: path
        name: spaceName
        required: true
        schema:
          type: string
components:
  schemas:
    SendBirdUser:
      properties:
        start_at:
          type: number
          format: double
        end_at:
          type: number
          format: double
        description:
          type: string
        is_created:
          type: boolean
        is_shadow_blocked:
          type: boolean
        is_hide_me_from_friends:
          type: boolean
        locale:
          type: string
        local:
          type: string
        phone_number:
          type: string
        created_at:
          type: number
          format: double
        profile_url:
          type: string
        preferred_languages:
          items:
            type: string
          type: array
        session_tokens:
          items:
            type: string
          type: array
        discovery_keys:
          items:
            type: string
          type: array
        nickname:
          type: string
        last_seen_at:
          type: number
          format: double
        is_active:
          type: boolean
        has_ever_logged_in:
          type: boolean
        access_token:
          type: string
        is_online:
          type: boolean
        require_auth_for_profile_image:
          type: boolean
        user_id:
          type: string
      required:
      - user_id
      type: object
    SpawnHome:
      properties:
        roomId:
          type: string
        x:
          type: number
          format: double
        y:
          type: number
          format: double
      required:
      - roomId
      - x
      - y
      type: object
      additionalProperties: false
    ApiPrivacySettings:
      anyOf:
      - properties:
          type:
            $ref: '#/components/schemas/PrivacySettingType.public'
        required:
        - type
        type: object
      - properties:
          type:
            $ref: '#/components/schemas/PrivacySettingType.registeredUsers'
        required:
        - type
        type: object
      - properties:
          data:
            properties:
              password:
                type: string
                description: 'The password for this space.  Attendees will be prompted before

                  joining.'
                minLength: 4
            required:
            - password
            type: object
          type:
            $ref: '#/components/schemas/PrivacySettingType.password'
        required:
        - data
        - type
        type: object
      - properties:
          data:
            properties:
              allowedDomains:
                items:
                  type: string
                type: array
                maxLength: 100
            required:
            - allowedDomains
            type: object
          type:
            $ref: '#/components/schemas/PrivacySettingType.emailDomain'
        required:
        - data
        - type
        type: object
      - properties:
          data:
            properties:
              guestList:
                items:
                  type: string
                type: array
                maxLength: 2000
            required:
            - guestList
            type: object
          type:
            $ref: '#/components/schemas/PrivacySettingType.guestList'
        required:
        - data
        - type
        type: object
      - properties:
          data:
            properties:
              guestList:
                items:
                  type: string
                type: array
                maxLength: 2000
              issuerId:
                type: string
            required:
            - guestList
            - issuerId
            type: object
          type:
            $ref: '#/components/schemas/PrivacySettingType.jwt'
        required:
        - data
        - type
        type: object
      - properties:
          data:
            properties:
              guestList:
                items:
                  type: string
                type: array
                maxLength: 2000
              providerId:
                type: string
            required:
            - guestList
            - providerId
            type: object
          type:
            $ref: '#/components/schemas/PrivacySettingType.saml'
        required:
        - data
        - type
        type: object
      - properties:
          type:
            $ref: '#/components/schemas/PrivacySettingType.closed'
        required:
        - type
        type: object
      description: Privacy settings as returned by the api.
    ApiRoomFeatures:
      properties:
        zoom:
          type: boolean
        pan:
          type: boolean
        pathfinding:
          type: boolean
        map:
          type: boolean
        fog:
          type: boolean
      type: object
    SubscriptionEnvironment:
      enum:
      - test
      - dev
      - prod
      type: string
    UserRole.admin:
      enum:
      - admin
      type: string
    PrivacySettingType.closed:
      enum:
      - closed
      type: string
    RoomPrivacySettings:
      anyOf:
      - properties:
          type:
            $ref: '#/components/schemas/RoomPrivacySettingType.open'
        required:
        - type
        type: object
      - properties:
          type:
            $ref: '#/components/schemas/RoomPrivacySettingType.closed'
        required:
        - type
        type: object
    ApiUpdateDefaultChannelsRequest:
      properties:
        channelUrls:
          items:
            type: string
          type: array
      required:
      - channelUrls
      type: object
    PrivacySettingType.registeredUsers:
      enum:
      - registeredUsers
      type: string
    PaginatedResponse_ApiSpace-or-ApiSpacePublicInfo_:
      description: A page of items.  Useful for breaking up a large dataset into smaller chunks.
      properties:
        items:
          items:
            anyOf:
            - $ref: '#/components/schemas/ApiSpace'
            - $ref: '#/components/schemas/ApiSpacePublicInfo'
          type: array
          description: The page of items.
        metadata:
          properties:
            count:
              type: number
              format: double
              description: The number of items sent.
            next:
              type: string
              description: 'A pagination cursor.  If specified, there is another page of results that

                can be requested by appending this value as a query parameter called

                "next".'
          required:
          - count
          type: object
          description: 'Metadata about the page of items.  Contains a pagination cursor called

            "next" if there is another page of items.'
      required:
      - items
      - metadata
      type: object
      additionalProperties: false
    SendbirdChannel:
      properties:
        ts_message_offset:
          type: number
          format: double
        joined_ts:
          type: number
          format: double
        freeze:
          type: boolean
        metadata:
          $ref: '#/components/schemas/ChannelMetadata'
        members:
          items:
            $ref: '#/components/schemas/SendBirdUser'
          type: array
        unread_mention_count:
          type: number
          format: double
        unread_message_count:
          type: number
          format: double
        created_at:
          type: number
          format: double
        max_length_message:
          type: number
          format: double
        joined_member_count:
          type: number
          format: double
        member_count:
          type: number
          format: double
        is_super:
          type: boolean
        is_public:
          type: boolean
        is_distinct:
          type: boolean
        custom_type:
          $ref: '#/components/schemas/ChannelType'
        channel_url:
          type: string
        name:
          type: string
      required:
      - freeze
      - unread_mention_count
      - unread_message_count
      - created_at
      - max_length_message
      - joined_member_count
      - member_count
      - is_super
      - is_public
      - is_distinct
      - custom_type
      - channel_url
      - name
      type: object
    Pick_ApiPrivacySettings.type_:
      properties:
        type:
          $ref: '#/components/schemas/PrivacySettingType.public'
      required:
      - type
      type: object
      description: From T, pick a set of properties whose keys are in the union K
    ApiCreateSpaceRequest:
      description: A request to create a new space.
      properties:
        name:
          type: string
          description: A globally unique name for the space.
          minLength: 6
          maxLength: 20
          pattern: ^[0-9a-z\-_]{6,20}$
        useCase:
          allOf:
          - $ref: '#/components/schemas/UseCase'
          description: The main purpose of this space.
        createDefaultRoom:
          type: boolean
          description: Whether to create a demo room.  Defaults to false.
        defaultRoomTemplate:
          type: string
          description: 'The template to use for the default room.  Defaults to a template

            matching the request''s useCase property.'
        displayName:
          type: string
          description: An optional display name.
          minLength: 1
        privacySettings:
          $ref: '#/components/schemas/ApiPrivacySettings'
          description: Restricts user access to the space.  Defaults to public
        isDryRun:
          type: boolean
          description: If true, perform all validation, but don't actually create the space.
        isDemo:
          type: boolean
          description: If true, configure the space as a demo space
        setEmailDomain:
          type: boolean
          description: 'if true, everybody who joins the space with the same email domain as the owner

            will automatically be added as a member'
      required:
      - name
      - useCase
      type: object
      additionalProperties: false
    ChatSettings:
      allOf:
      - $ref: '#/components/schemas/Record_Exclude_Range.Range.groupDm_.boolean_'
      - properties:
          permissions:
            properties:
              manageChannel:
                properties:
                  minimumRole:
                    anyOf:
                    - $ref: '#/components/schemas/UserRole.admin'
                    - $ref: '#/components/schemas/UserRole.member'
                required:
                - minimumRole
                type: object
              createChannel:
                properties:
                  minimumRole:
                    anyOf:
                    - $ref: '#/components/schemas/UserRole.admin'
                    - $ref: '#/components/schemas/UserRole.member'
                required:
                - minimumRole
                type: object
            type: object
          undefined:
            type: boolean
        type: object
      description: Chat ranges available for Guests
    ApiGetCanSpaceScheduleDemoResponse:
      properties:
        canScheduleDemo:
          type: boolean
      required:
      - canScheduleDemo
      type: object
    ApiSpace:
      description: A consolidated space model across v1 and v2.
      properties:
        name:
          type: string
          description: The name of the space. Used as a unique identifier.
        displayName:
          type: string
          description: A user-specified description of the space.
        privacySettings:
          $ref: '#/components/schemas/ApiPrivacySettings'
          description: Privacy settings applied to the space.
        useCase:
          allOf:
          - $ref: '#/components/schemas/UseCase'
          description: Privacy setting type applied to the space.
        description:
          type: string
          description: Space description
        uid:
          type: string
          description: The ID of the space (firebase ID). Used as a unique identifier.
        version:
          type: number
          enum:
          - 1
          - 2
          - 3
          description: The version of the space.
        ownerId:
          type: string
          description: The uid of the space's owner.
        emailDomain:
          type: string
          description: The email domain that will be used to automatically add members to the space.
        emailDomains:
          items:
            type: string
          type: array
          description: List of email domains that will be used to automatically add members to the space.
        createdAt:
          type: string
          format: date-time
          description: Date the space was created
        chatSettings:
          $ref: '#/components/schemas/ChatSettings'
          description: Chat ranges allowed in this space
        rooms:
          items:
            $ref: '#/components/schemas/ApiRoom'
          type: array
          description: The rooms in this space.
        memberCount:
          type: number
          format: double
          description: The number of users given member permissions for the space.
        memberLimit:
          type: number
          format: double
          description: 'The maxmimum number of users that can be made members. If undefined,

            there is no member limit.'
        memberMinimum:
          type: number
          format: double
          description: The minimum number of users that should be billed as members.
        tier:
          $ref: '#/components/schemas/SubscriptionTier'
          description: 'The subscription tier.  If the user cancels their subscription, this

            reverts to ''free''.'
        tierNameOverride:
          type: string
          description: An override for the customer facing name for the user's subscription tier.
        subscription:
          $ref: '#/components/schemas/AutomaticStripeSubscription'
          description: Stripe subscription info, if the user is payment for an upgraded space.
        hideInviteButton:
          type: boolean
          description: Whether the "invite" button should be viewable in the space
        disableGuestPresent:
          type: boolean
          description: Whether guest's ability to present should be disabled.
        permissions:
          $ref: '#/components/schemas/ApiSpacePermissions'
          description: A mapping of permissions this space has based on its subscription.
        userRoles:
          properties: {}
          additionalProperties:
            $ref: '#/components/schemas/UserRole'
          type: object
          description: 'User roles in the space.  If a user is not in this mapping, they are a

            guest. Available only to members.'
        hipaaEnabled:
          type: boolean
          description: Whether the HIPAA compliance mode is enabled in this space
        spawnHomes:
          properties: {}
          additionalProperties:
            $ref: '#/components/schemas/SpawnHome'
          type: object
          description: 'The room''s spawn homes for each user. Each user can only have one spawnHome

            per space (rather than per room) - the idea is that they''d only have one office per space.'
        isDemo:
          type: boolean
          description: Whether the space is a demo space.
        guestLimitMs:
          type: number
          format: double
          description: 'The number of milliseconds a guest account can be active in the space per week.

            Lobby time is not counted against this limit.'
        isInternalFreeTrialActive:
          type: boolean
        internalFreeTrialScheduledExpirationMs:
          type: number
          format: double
          description: Scheduled internal free trial expiration in milliseconds
        isReverseTrial:
          type: boolean
          description: 'Wether or not this space has been created with a reverse trial.

            Reverse trials are cardless and starts when the space is created.'
        cancelledReverseTrial:
          type: boolean
          description: Indicates if a space has a cancelled reverse trial subscription.
        requireDesktopApp:
          type: boolean
          description: Requires members of this space to use the desktop app to join.
      required:
      - name
      - displayName
      - privacySettings
      - uid
      - version
      - ownerId
      - createdAt
      - chatSettings
      - rooms
      - memberCount
      - memberMinimum
      - tier
      - hideInviteButton
      - disableGuestPresent
      - permissions
      - hipaaEnabled
      type: object
      additionalProperties: false
    RoomPrivacySettingType.password:
      enum:
      - password
      type: string
    UserRole:
      description: The user's role and permissions within a space.
      enum:
      - admin
      - banned
      - cohost
      - guest
      - member
      - floorManager
      type: string
    SubscriptionTier:
      enum:
      - free
      - professional
      - business
      - enterprise
      - custom
      type: string
    PrivacySettingType.guestList:
      enum:
      - guestList
      type: string
    UserRole.member:
      enum:
      - member
      type: string
    PrivacySettingType.password:
      enum:
      - password
      type: string
    PrivacySettingType.emailDomain:
      enum:
      - emailDomain
      type: string
    ApiSpacePermissions:
      properties:
        advancedChat:
          type: boolean
        analytics:
          type: boolean
        broadcast:
          type: boolean
        presentLocalFile:
          type: boolean
        presentSecondaryCamera:
          type: boolean
        privacySettingEmailDomain:
          type: boolean
        privacySettingGuestList:
          type: boolean
        privacySettingJwt:
          type: boolean
        privacySettingSaml:
          type: boolean
        privacySettingPassword:
          type: boolean
        privacySettingPublic:
          type: boolean
        privacySettingRegisteredUsers:
          type: boolean
        privacySettingClosed:
          type: boolean
        recording:
          type: boolean
        sendbirdChat:
          type: boolean
      type: object
    BackgroundType.singleTile:
      enum:
      - singleTile
      type: string
    RoomPrivacySettingType.closed:
      enum:
      - closed
      type: string
    UseCase:
      description: How the user plans to use the space.
      enum:
      - culture
      - productivity
      - communication
      - visibility
      - engagement
      - other
      - events
      - education
      - friends
      type: string
    PrivacySettingType.jwt:
      enum:
      - jwt
      type: string
    Record_Exclude_Range.Range.groupDm_.boolean_:
      properties:
        user:
          type: boolean
        nearby:
          type: boolean
        room:
          type: boolean
        space:
          type: boolean
        custom:
          type: boolean
      type: object
      description: Construct a type with a set of properties K of type T
    ChannelType:
      type: string
      enum:
      - user
      - custom
      - group_dms
    BillingPeriod:
      enum:
      - monthly
      - annually
      type: string
    ApiChatConfigChannel:
      properties:
        user_ids:
          items:
            type: string
          type: array
        unread_mention_count:
          type: number
          format: double
        unread_message_count:
          type: number
          format: double
        custom_type:
          $ref: '#/components/schemas/ChannelType'
        channel_url:
          type: string
        name:
          type: string
      required:
      - user_ids
  

# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kumospace/refs/heads/main/openapi/kumospace-spaces-api-openapi.yml