Flatfile subpackage_spaces API

openapi: 3.1.0
info:
  title: API Reference subpackage_accounts subpackage_spaces API
  version: 1.0.0
servers:
- url: https://api.x.flatfile.com/v1
tags:
- name: subpackage_spaces
paths:
  /spaces:
    get:
      operationId: list
      summary: List spaces
      description: Returns all spaces for an account or environment
      tags:
      - subpackage_spaces
      parameters:
      - name: environmentId
        in: query
        description: The ID of the environment.
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:EnvironmentId'
      - name: pageSize
        in: query
        description: Number of spaces to return in a page (default 10)
        required: false
        schema:
          type: integer
      - name: pageNumber
        in: query
        description: Based on pageSize, which page of records to return
        required: false
        schema:
          type: integer
      - name: app
        in: query
        description: Filter by appId
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:AppId'
      - name: search
        in: query
        description: Search query for spaces
        required: false
        schema:
          type: string
      - name: namespace
        in: query
        description: Search by namespace
        required: false
        schema:
          type: string
      - name: archived
        in: query
        description: Flag to include archived spaces
        required: false
        schema:
          type: boolean
      - name: sortField
        in: query
        description: Field to sort spaces by; requires `sortDirection` if provided.
        required: false
        schema:
          $ref: '#/components/schemas/type_spaces:GetSpacesSortField'
      - name: sortDirection
        in: query
        description: Direction of sorting; requires `sortField` if provided.
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:SortDirection'
      - name: isCollaborative
        in: query
        description: Flag for collaborative (project) spaces
        required: false
        schema:
          type: boolean
      - name: appId
        in: query
        description: (Deprecated!) Use `app` query parameter
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:AppId'
      - name: isAppTemplate
        in: query
        description: Flag for app templates
        required: false
        schema:
          type: boolean
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      - name: X-Disable-Hooks
        in: header
        required: true
        schema:
          type: string
          enum:
          - 'true'
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_spaces:ListSpacesResponse'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
    post:
      operationId: create
      summary: Create a space
      description: Creates a new space based on an existing Space Config
      tags:
      - subpackage_spaces
      parameters:
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      - name: X-Disable-Hooks
        in: header
        required: true
        schema:
          type: string
          enum:
          - 'true'
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_spaces:SpaceResponse'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_spaces:SpaceConfig'
    delete:
      operationId: bulk-delete
      summary: Delete spaces
      description: Delete multiple spaces by id
      tags:
      - subpackage_spaces
      parameters:
      - name: spaceIds
        in: query
        description: List of ids for the spaces to be deleted
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:SpaceId'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      - name: X-Disable-Hooks
        in: header
        required: true
        schema:
          type: string
          enum:
          - 'true'
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Success'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
  /spaces/{spaceId}:
    get:
      operationId: get
      summary: Get a space
      description: Returns a single space
      tags:
      - subpackage_spaces
      parameters:
      - name: spaceId
        in: path
        description: ID of space to return
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:SpaceId'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      - name: X-Disable-Hooks
        in: header
        required: true
        schema:
          type: string
          enum:
          - 'true'
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_spaces:SpaceResponse'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
    delete:
      operationId: delete
      summary: Delete a space
      description: Delete a space
      tags:
      - subpackage_spaces
      parameters:
      - name: spaceId
        in: path
        description: ID of space to delete
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:SpaceId'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      - name: X-Disable-Hooks
        in: header
        required: true
        schema:
          type: string
          enum:
          - 'true'
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Success'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
    patch:
      operationId: update
      summary: Update a space
      description: Update a space, to change the name for example
      tags:
      - subpackage_spaces
      parameters:
      - name: spaceId
        in: path
        description: ID of space to update
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:SpaceId'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      - name: X-Disable-Hooks
        in: header
        required: true
        schema:
          type: string
          enum:
          - 'true'
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_spaces:SpaceResponse'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_spaces:SpaceConfig'
  /spaces/{spaceId}/archive:
    post:
      operationId: archive-space
      summary: Archives a space
      description: Sets archivedAt timestamp on a space
      tags:
      - subpackage_spaces
      parameters:
      - name: spaceId
        in: path
        description: ID of space to archive
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:SpaceId'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      - name: X-Disable-Hooks
        in: header
        required: true
        schema:
          type: string
          enum:
          - 'true'
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Success'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
  /spaces/{spaceId}/unarchive:
    post:
      operationId: unarchive-space
      summary: Unarchives a space
      description: Sets archivedAt timestamp on a space to null
      tags:
      - subpackage_spaces
      parameters:
      - name: spaceId
        in: path
        description: ID of space to unarchive
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:SpaceId'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      - name: X-Disable-Hooks
        in: header
        required: true
        schema:
          type: string
          enum:
          - 'true'
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Success'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
  /spaces/{spaceId}/guidance:
    post:
      operationId: create-guidance
      summary: Create a new guidance
      description: Creates a new guidance
      tags:
      - subpackage_spaces
      parameters:
      - name: spaceId
        in: path
        description: ID of the space
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:SpaceId'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      - name: X-Disable-Hooks
        in: header
        required: true
        schema:
          type: string
          enum:
          - 'true'
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_spaces:GuidanceResource'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
        '403':
          description: Error response with status 403
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_spaces:GuidanceApiCreateData'
    get:
      operationId: list-guidance
      summary: List guidances
      description: Lists guidances
      tags:
      - subpackage_spaces
      parameters:
      - name: spaceId
        in: path
        description: ID of the space
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:SpaceId'
      - name: includeGuide
        in: query
        description: Include the guide with the guidance, default is false
        required: false
        schema:
          type: boolean
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      - name: X-Disable-Hooks
        in: header
        required: true
        schema:
          type: string
          enum:
          - 'true'
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_spaces:GuidanceListResponse'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
        '403':
          description: Error response with status 403
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
  /spaces/{spaceId}/guidance/{guidanceId}:
    get:
      operationId: get-guidance
      summary: Get a guidance
      description: Retrieves a guidance by its id
      tags:
      - subpackage_spaces
      parameters:
      - name: spaceId
        in: path
        description: ID of the space
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:SpaceId'
      - name: guidanceId
        in: path
        description: ID of the guidance
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:GuidanceId'
      - name: includeGuide
        in: query
        description: Include the guide with the guidance, default is false
        required: false
        schema:
          type: boolean
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      - name: X-Disable-Hooks
        in: header
        required: true
        schema:
          type: string
          enum:
          - 'true'
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_spaces:GuidanceResource'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
        '403':
          description: Error response with status 403
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
    patch:
      operationId: update-guidance
      summary: Update a guidance
      description: Updates a guidance with the given id
      tags:
      - subpackage_spaces
      parameters:
      - name: spaceId
        in: path
        description: ID of the space
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:SpaceId'
      - name: guidanceId
        in: path
        description: ID of the guidance
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:GuidanceId'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      - name: X-Disable-Hooks
        in: header
        required: true
        schema:
          type: string
          enum:
          - 'true'
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_spaces:GuidanceResource'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
        '403':
          description: Error response with status 403
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_spaces:GuidanceApiUpdateData'
    delete:
      operationId: delete-guidance
      summary: Delete a guidance
      description: Deletes a guidance by its id
      tags:
      - subpackage_spaces
      parameters:
      - name: spaceId
        in: path
        description: ID of the space
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:SpaceId'
      - name: guidanceId
        in: path
        description: ID of the guidance
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:GuidanceId'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      - name: X-Disable-Hooks
        in: header
        required: true
        schema:
          type: string
          enum:
          - 'true'
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Success'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
        '403':
          description: Error response with status 403
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
  /spaces/{spaceId}/drafts:
    post:
      operationId: create-draft
      summary: Create a draft of a space
      description: Creates a draft of a space
      tags:
      - subpackage_spaces
      parameters:
      - name: spaceId
        in: path
        description: ID of space to create draft of
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:SpaceId'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      - name: X-Disable-Hooks
        in: header
        required: true
        schema:
          type: string
          enum:
          - 'true'
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_spaces:SpaceDraftResponse'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
    get:
      operationId: list-space-drafts
      summary: List drafts for a space
      description: Lists drafts for a space
      tags:
      - subpackage_spaces
      parameters:
      - name: spaceId
        in: path
        description: ID of space to list drafts for
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:SpaceId'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      - name: X-Disable-Hooks
        in: header
        required: true
        schema:
          type: string
          enum:
          - 'true'
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_spaces:SpaceDraftListResponse'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
  /spaces/{spaceId}/drafts/{draftSpaceId}/merge:
    get:
      operationId: get-space-draft
      summary: Get a draft
      description: Gets a draft by the space id and draft space id
      tags:
      - subpackage_spaces
      parameters:
      - name: spaceId
        in: path
        description: ID of space to get draft for
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:SpaceId'
      - name: draftSpaceId
        in: path
        description: ID of draft space to get
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:SpaceId'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      - name: X-Disable-Hooks
        in: header
        required: true
        schema:
          type: string
          enum:
          - 'true'
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_spaces:SpaceDraftMergeOperationsResponse'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
    post:
      operationId: merge-draft
      summary: Merge a draft
      description: Merges a draft into a space
      tags:
      - subpackage_spaces
      parameters:
      - name: spaceId
        in: path
        description: ID of space to merge draft into
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:SpaceId'
      - name: draftSpaceId
        in: path
        description: ID of draft space to merge
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:SpaceId'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      - name: X-Disable-Hooks
        in: header
        required: true
        schema:
          type: string
          enum:
          - 'true'
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Success'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
components:
  schemas:
    type_spaces:GuidanceOptions:
      type: object
      properties:
        target:
          type: string
        trigger:
          $ref: '#/components/schemas/type_spaces:TriggerEnum'
        type:
          $ref: '#/components/schemas/type_spaces:TypeEnum'
        role:
          $ref: '#/components/schemas/type_spaces:RoleEnum'
          description: The role for which this guidance should be displayed. If not specified, guidance will be shown to both admin and guest users.
      required:
      - target
      - trigger
      - type
      title: GuidanceOptions
    type_commons:Success:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/type_commons:SuccessData'
      description: Informs whether or not a request was successful
      title: Success
    type_commons:SpaceConfigId:
      type: string
      description: Space Config ID
      title: SpaceConfigId
    type_spaces:SpaceConfig:
      type: object
      properties:
        spaceConfigId:
          $ref: '#/components/schemas/type_commons:SpaceConfigId'
        environmentId:
          $ref: '#/components/schemas/type_commons:EnvironmentId'
        primaryWorkbookId:
          $ref: '#/components/schemas/type_commons:WorkbookId'
          description: The ID of the primary workbook for the space. This should not be included in create space requests.
        metadata:
          description: Metadata for the space
        settings:
          $ref: '#/components/schemas/type_spaces:SpaceSettings'
          description: The Space settings.
        actions:
          type: array
          items:
            $ref: '#/components/schemas/type_commons:Action'
        access:
          type: array
          items:
            $ref: '#/components/schemas/type_spaces:SpaceAccess'
        autoConfigure:
          type: boolean
          description: Only used during creation - will be ignored on update
        namespace:
          type: string
        labels:
          type: array
          items:
            type: string
        translationsPath:
          type: string
        languageOverride:
          type: string
        archivedAt:
          type: string
          format: date-time
          description: Date when space was archived
        appId:
          $ref: '#/components/schemas/type_commons:AppId'
          description: The ID of the App that space is associated with
        isAppTemplate:
          type: boolean
          description: Whether the space is an app template. Only one space per app can be an app template.
        name:
          type: string
          description: The name of the space
        displayOrder:
          type: integer
          description: The display order
        guestAuthentication:
          type: array
          items:
            $ref: '#/components/schemas/type_environments:GuestAuthenticationEnum'
      description: Properties used to create a new Space
      title: SpaceConfig
    type_spaces:TypeEnum:
      type: string
      enum:
      - sidebar
      - popout
      - tooltip
      title: TypeEnum
    type_commons:Guide:
      type: object
      properties:
        content:
          type: string
          description: Markdown guidance for this action
      required:
      - content
      title: Guide
    type_spaces:ListSpacesResponse:
      type: object
      properties:
        pagination:
          $ref: '#/components/schemas/type_commons:Pagination'
        data:
          type: array
          items:
            $ref: '#/components/schemas/type_spaces:Space'
      required:
      - data
      description: List of Space objects
      title: ListSpacesResponse
    type_spaces:SpaceDraft:
      type: object
      properties:
        sourceSpaceId:
          $ref: '#/components/schemas/type_commons:SpaceId'
        draftSpaceId:
          $ref: '#/components/schemas/type_commons:SpaceId'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        mergedAt:
          type: string
          format: date-time
        deletedAt:
          type: string
          format: date-time
      required:
      - sourceSpaceId
      - draftSpaceId
      - createdAt
      - updatedAt
      title: SpaceDraft
    type_commons:InputConstraintType:
      type: string
      enum:
      - required
      title: InputConstraintType
    type_spaces:Space:
      type: object
      properties:
        spaceConfigId:
          $ref: '#/components/schemas/type_commons:SpaceConfigId'
        environmentId:
          $ref: '#/components/schemas/type_commons:EnvironmentId'
        primaryWorkbookId:
          $ref: '#/components/schemas/type_commons:WorkbookId'
          description: The ID of the primary workbook for the space. This should not be included in create space requests.
        metadata:
          description: Metadata for the space
        settings:
          $ref: '#/components/schemas/type_spaces:SpaceSettings'
          description: The Space settings.
        actions:
          type: array
          items:
            $ref: '#/components/schemas/type_commons:Action'
        access:
          type: array
          items:
            $ref: '#/components/schemas/type_spaces:SpaceAccess'
        autoConfigure:
          type: boolean
          description: Only used during creation - will be ignored on update
        namespace:
          type: string
        labels:
          type: array
          items:
            type: string
        translationsPath:
          type: string
        languageOverride:
          type: string
        archivedAt:
          type: string
          format: date-time
          description: Date when s

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