Flatfile subpackage_spaces API

openapi: 3.2.0
info:
  title: 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_JSONPatchOperation:
      type: object
      properties:
        op:
          $ref: '#/components/schemas/type_spaces_JSONPatchOperationType'
        from:
          type: string
        path:
          type: string
        value:
          description: Any type
      required:
      - op
      title: JSONPatchOperation
    type_commons_SpaceId:
      type: string
      description: Space ID
      title: SpaceId
    type_commons_Error:
      type: object
      properties:
        key:
          type: string
        message:
          type: string
      required:
      - message
      title: Error
    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_commons_AppId:
      type: string
      description: App ID
      title: AppId
    type_commons_Action:
      type: object
      properties:
        slug:
          type: string
          description: '**This is deprecated. Use `operation` instead.**'
        operation:
          type: string
          description: This will become the job operation that is triggered
        mode:
          $ref: '#/components/schemas/type_commons_ActionMode'
          description: Foreground and toolbarBlocking action mode will prevent interacting with the resource until complete
        tooltip:
          type: string
          description: A tooltip that appears when hovering the action button
        messages:
          type: array
          items:
            $ref: '#/components/schemas/type_commons_ActionMessage'
        type:
          type: string
          description: '**This is deprecated.**'
        description:
          type: string
          description: The text that appears in the dialog after the action is clicked.
        schedule:
          $ref: '#/components/schemas/type_commons_ActionSchedule'
          description: Determines if the action should happen on a regular cadence.
        primary:
          type: boolean
          description: A primary action will be more visibly present, whether in Sheet or Workbook.
        confirm:
          type: boolean
          description: Whether to show a modal to confirm the action
        icon:
          type: string
          description: Icon will work on primary actions. It will only accept an already existing Flatfile design system icon.
        requireAllValid:
          type: boolean
          description: '**This is deprecated. Use `constraints` instead.**'
        requireSelection:
          type: boolean
          description: '**This is deprecated. Use `constraints` instead.**'
        inputForm:
          $ref: '#/components/schemas/type_commons_InputForm'
          description: Adds an input form for this action after it is clicked.
        constraints:
          type: array
          items:
            $ref: '#/components/schemas/type_commons_ActionConstraint'
          description: A limitation or restriction on the action.
        mount:
          $ref: '#/components/schemas/type_commons_ActionMount'
        guide:
          $ref: '#/components/schemas/type_commons_Guide'
        guardrail:
          $ref: '#/components/schemas/type_commons_Guardrail'
        createdFrom:
          $ref: '#/components/schemas/type_commons_ActionId'
          description: The action that this action was cloned from
        lastPropagatedAt:
          type: string
          format: date-time
          description: The last time this action was propagated to a workbook
        deletedAt:
          type: string
          format: date-time
          description: The time this action was deleted
        invalidConditionalMessaging:
          type: boolean
          description: When enabled, shows dynamic confirmation messages based on record validation status instead of the 

# --- 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