Flatfile subpackage_workbooks API

openapi: 3.2.0
info:
  title: Reference subpackage_accounts Subpackage Workbooks API
  version: 1.0.0
servers:
- url: https://api.x.flatfile.com/v1
tags:
- name: subpackage_workbooks
paths:
  /workbooks:
    get:
      operationId: list
      summary: List workbooks
      description: Returns all workbooks matching a filter for an account or space
      tags:
      - subpackage_workbooks
      parameters:
      - name: spaceId
        in: query
        description: The associated Space ID of the Workbook.
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_SpaceId'
      - name: name
        in: query
        description: Filter by name. Precede with - to negate the filter
        required: false
        schema:
          type: string
      - name: namespace
        in: query
        description: Filter by namespace. Precede with - to negate the filter
        required: false
        schema:
          type: string
      - name: label
        in: query
        description: Filter by label. Precede with - to negate the filter
        required: false
        schema:
          type: string
      - name: treatment
        in: query
        description: Filter by treatment.
        required: false
        schema:
          type: string
      - name: includeSheets
        in: query
        description: Include sheets for the workbook (default true)
        required: false
        schema:
          type: boolean
      - name: includeCounts
        in: query
        description: Include counts for the workbook. **DEPRECATED** Counts will return 0s. Use GET /sheets/:sheetId/counts
        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_workbooks_ListWorkbooksResponse'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_Errors'
    post:
      operationId: create
      summary: Create a workbook
      description: Creates a workbook and adds it to a space
      tags:
      - subpackage_workbooks
      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_workbooks_WorkbookResponse'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_Errors'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_workbooks_CreateWorkbookConfig'
  /workbooks/{workbookId}:
    get:
      operationId: get
      summary: Get a workbook
      description: Returns a single workbook
      tags:
      - subpackage_workbooks
      parameters:
      - name: workbookId
        in: path
        description: ID of workbook to return
        required: true
        schema:
          $ref: '#/components/schemas/type_commons_WorkbookId'
      - 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_workbooks_WorkbookResponse'
        '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 workbook
      description: Deletes a workbook and all of its record data permanently
      tags:
      - subpackage_workbooks
      parameters:
      - name: workbookId
        in: path
        description: ID of workbook to delete
        required: true
        schema:
          $ref: '#/components/schemas/type_commons_WorkbookId'
      - 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 workbook
      description: "Updates a workbook\n<Note>\n  Adding a sheet to a workbook does not require the config object to be provided, however updating an existing sheet does.\n</Note>"
      tags:
      - subpackage_workbooks
      parameters:
      - name: workbookId
        in: path
        description: ID of workbook to update
        required: true
        schema:
          $ref: '#/components/schemas/type_commons_WorkbookId'
      - 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_workbooks_WorkbookResponse'
        '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_workbooks_WorkbookUpdate'
  /workbooks/{workbookId}/commits:
    get:
      operationId: get-workbook-commits
      summary: Get commits for a workbook
      description: Returns the commits for a workbook
      tags:
      - subpackage_workbooks
      parameters:
      - name: workbookId
        in: path
        description: ID of workbook
        required: true
        schema:
          $ref: '#/components/schemas/type_commons_WorkbookId'
      - name: completed
        in: query
        description: If true, only return commits that have been completed. If false, only return commits that have not been completed. If not provided, return all commits.
        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_commits_ListCommitsResponse'
components:
  schemas:
    type_property_FieldAppearance:
      type: object
      properties:
        size:
          $ref: '#/components/schemas/type_property_FieldSize'
      description: Control the appearance of this field when it's displayed in a table or input
      title: FieldAppearance
    type_property_StringConfigOptions:
      type: string
      enum:
      - tiny
      - normal
      - medium
      - long
      description: How much text should be storeable in this field
      title: StringConfigOptions
    type_commons_SpaceId:
      type: string
      description: Space ID
      title: SpaceId
    type_workbooks_WorkbookUpdate:
      type: object
      properties:
        name:
          type: string
          description: The name of the Workbook.
        labels:
          type: array
          items:
            type: string
          description: An optional list of labels for the Workbook.
        spaceId:
          $ref: '#/components/schemas/type_commons_SpaceId'
          description: The Space Id associated with the Workbook.
        environmentId:
          $ref: '#/components/schemas/type_commons_EnvironmentId'
          description: The Environment Id associated with the Workbook.
        namespace:
          type: string
          description: The namespace of the Workbook.
        sheets:
          type: array
          items:
            $ref: '#/components/schemas/type_sheets_SheetConfigOrUpdate'
          description: Describes shape of data as well as behavior
        actions:
          type: array
          items:
            $ref: '#/components/schemas/type_commons_Action'
        metadata:
          description: Metadata for the workbook
        settings:
          $ref: '#/components/schemas/type_workbooks_WorkbookConfigSettings'
          description: The Workbook settings.
        folder:
          type: string
          description: The folder to group the workbook in
      description: The updates to be made to an existing workbook
      title: WorkbookUpdate
    type_commons_Error:
      type: object
      properties:
        key:
          type: string
        message:
          type: string
      required:
      - message
      title: Error
    type_property_EnumPropertySortBy:
      type: string
      enum:
      - label
      - value
      - ordinal
      title: EnumPropertySortBy
    type_commons_CommitId:
      type: string
      description: Commit ID
      title: CommitId
    type_property_NumberConfig:
      type: object
      properties:
        decimalPlaces:
          type: integer
          description: Number of decimal places to round data to
      title: NumberConfig
    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 static description
        validRecordsMessage:
          type: string
          description: Custom message to show when all records are valid (only used when invalidConditionalMessaging is true)
        invalidRecordsMessage:
          type: string
          description: Custom message to show when there are invalid records (only used when invalidConditionalMessaging is true)
        label:
          type: string
          description: The text on the Button itself
      required:
      - label
      title: Action
    type_records_ValidationType:
      type: string
      enum:
      - error
      - warn
      - info
      title: ValidationType
    type_workbooks_StorageStrategy:
      type: string
      enum:
      - RAINBOW_TABLES
      - CELL_HISTORY
      - HYPERCUBE
      - QUICKSTORE
      - DUCKDB
      - FOREIGNDB
      - MEMCSV
      title: StorageStrategy
    type_property_EnumPropertyConfig:
      type: object
      properties:
        allowCustom:
          type: boolean
          description: Permit the user to create new options for this specific field.
        options:
          type: array
          items:
            $ref: '#/components/schemas/type_property_EnumPropertyOption'
        sortBy:
          $ref: '#/components/schemas/type_property_EnumPropertySortBy'
          description: Sort the options by the value of this property. Defaults to `label`.
      required:
      - options
      title: EnumPropertyConfig
    type_property_RequiredConstraintConfig:
      type: object
      properties:
        message:
          type: string
          description: Custom validation message to display when the constraint fails
        level:
          $ref: '#/components/schemas/type_records_ValidationType'
          description: Validation level (error, warn, info). Defaults to error.
      title: RequiredConstraintConfig
    type_sheets_CompositeUniqueConstraintConfig:
      type: object
      properties:
        message:
          type: string
          description: Custom validation message to display when the constraint fails
        level:
          $ref: '#/components/schemas/type_records_ValidationType'
          description: Validation level (error, warn, info). Defaults to error.
      title: CompositeUniqueConstraintConfig
    type_property_ReferenceListPropertyConfig:
      type: object
      properties:
        ref:
          type: string
          description: Full path reference to a sheet configuration. Must be in the same workbook.
        key:
          type: string
          description: Key of the property to use as the reference key. Defaults to `id`
        filter:
          $ref: '#/components/schemas/type_property_ReferenceFilter'
          description: Optional filter to narrow the set of records in the reference sheet used as valid values
      required:
      - ref
      - key
      title: ReferenceListPropertyConfig
    type_workbooks_WorkbookResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/type_workbooks_Workbook'
      required:
      - data
      title: WorkbookResponse
    type_commons_InputConstraint:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_commons_InputConstraintType'
      required:
      - type
      title: InputConstraint
    type_commons_ActionId:
      type: string
      description: Action ID
      title: ActionId
    type_workbooks_WorkbookConfigSettings:
      type: object
      properties:
        trackChanges:
          type: boolean
          description: Whether to track changes for this workbook. Defaults to false. Tracking changes on a workbook allows for disabling workbook and sheet actions while data in the workbook is still being processed. You must run a recordHook listener if you enable this feature.
        noMappingRedirect:
          type: boolean
          description: When noMappingRedirect is set to true, dragging a file into a sheet will not redirect to the mapping screen. Defaults to false.
        sheetSidebarOrder:
          type: array
          items:
            $ref: '#/components/schemas/type_commons_SheetId'
          description: Used to set the order of sheets in the sidebar. Sheets that are not specified will be shown after those listed.
        autoRunAnalysis:
          type: boolean
          description: Whether to automatically run analysis on the workbook when the inlineTransform feature is enabled. Defaults to true.
      description: Settings for a workbook
      title: WorkbookConfigSettings
    type_commons_Guardrail:
      type: object
      properties:
        content:
          type: string
          description: Markdown guardrail for this action
      required:
      - content
      title: Guardrail
    type_property_BooleanPropertyConfig:
      type: object
      properties:
        allowIndeterminate:
          type: boolean
          description: Allow a neither true or false state to be stored as `null`
      required:
      - allowIndeterminate
      title: BooleanPropertyConfig
    type_sheets_SheetAccess:
      type: string
      enum:
      - '*'
      - add
      - edit
      - delete
      - import
      title: SheetAccess
    type_sheets_CompositeUniqueConstraintStrategy:
      type: string
      enum:
      - hash
      - concat
      title: CompositeUniqueConstraintStrategy
    type_commons_ActionMessageType:
      type: string
      enum:
      - error
      - info
      title: ActionMessageType
    type_property_Constraint:
      oneOf:
      - type: object
        properties:
          type:
            type: string
            enum:
            - required
            description: 'Discriminator value: required'
          config:
            $ref: '#/components/schemas/type_property_RequiredConstraintConfig'
        required:
        - type
      - type: object
        properties:
          type:
            type: string
            enum:
            - unique
            description: 'Discriminator value: unique'
          config:
            $ref: '#/components/schemas/type_property_UniqueConstraintConfig'
        required:
        - type
      - type: object
        properties:
          type:
            type: string
            enum:
            - computed
            description: 'Discriminator value: computed'
        required:
        - type
      - type: object
        properties:
          type:
            type: string
            enum:
            - external
            description: 'Discriminator value: external'
          validator:
            type: string
          description:
            type: string
            description: A full description of what this constraint configuration does
          label:
            type: string
            description: A short description of what this constraint constraint should do, example - values between 1 and 100
          config:
            description: Any type
        required:
        - type
        - validator
      - type: object
        properties:
          type:
            type: string
            enum:
            - stored
            description: 'Discriminator value: stored'
          validator:
            type: string
            description: Must match the constraint validator name.
          version:
            type: integer
            description: The version of the stored constraint to use. (Defaults to version 1.)
          description:
            type: string
            description: A full description of what this constraint configuration does
          label:
            type: string
            description: A short description of what this constraint constraint should do, example - values between 1 and 100
          config:
            description: Any type
        required:
        - type
        - validator
      discriminator:
        propertyName: type
      title: Constraint
    type_property_StringConfig:
      type: object
      properties:
        size:
          $ref: '#/components/schemas/type_property_StringConfigOptions'
      required:
      - size
      title: StringConfig
    type_property_ReferenceFilter:
      type: object
      properties:
        refField:
          type: string
          description: The field key of the reference sheet to filter with
        recordField:
          type: string
          description: The field key of the record used to filter the reference field
      required:
      - refField
      - recordField
      description: If provided, the reference filter will narrow the set of records in the reference sheet used as the set of valid values for the record. Only rows where the value in the reference sheet's refField matches the value in this record's recordField will be used.
      title: ReferenceFilter
    type_workbooks_CreateWorkbookConfig:
      type: object
      properties:
        name:
          type: string
          description: The name of the Workbook.
        labels:
          type: array
          items:
            type: string
          description: An optional list of labels for the Workbook.
        spaceId:
          $ref: '#/components/schemas/type_commons_SpaceId'
          description: Space to associate with the Workbook.
        environmentId:
          $ref: '#/components/schemas/type_commons_EnvironmentId'
          description: Environment to associate with the Workbook
        namespace:
          type: string
          description: Optional namespace to apply to the Workbook.
        sheets:
          type: array
          items:
            $ref: '#/components/schemas/type_sheets_SheetConfig'
          description: Sheets to create on the Workbook.
        actions:
          type: array
          items:
            $ref: '#/components/schemas/type_commons_Action'
          description: Actions to create on the Workbook.
        settings:
          $ref: '#/components/schemas/type_workbooks_WorkbookConfigSettings'
          description: The Workbook settings.
        metadata:
          description: Metadata for the workbook
        treatments:
          type: array
          items:
            $ref: '#/components/schemas/type_workbooks_WorkbookTreatments'
          description: Treatments for the workbook
        storageStrategy:
          $ref: '#/components/schemas/type_workbooks_StorageStrategy'
          description: Storage strategy for the workbook. Defaults to QUICKSTORE.
        folder:
          type: string
          description: The folder to group the workbook in
      required:
      - name
      description: Properties used to create a new Workbook
      title: CreateWorkbookConfig
    type_sheets_SheetConfigOrUpdate:
      type: object
      properties:
        name:
          type: string
          description: The name of your Sheet as it will appear to your end users.
        description:
          type: string
          description: A sentence or two describing the purpose of your Sheet.
        slug:
          type: string
          description: A unique identifier for your Sheet. **Required when updating a Workbook.**
        readonly:
          type: boolean
          description: A boolean specifying whether or not this sheet is read only. Read only sheets are not editable by end users.
        allowAdditionalFields:
          type: boolean
          description: Allow end users to add fields during mapping.
        mappingConfidenceThreshold:
          type: number
          format: double
          description: The minimum confidence required to automatically map a field
        access:
          type: array
          items:
            $ref: '#/components/schemas/type_sheets_SheetAccess'
          description: Control Sheet-level access for all users.
        fields:
          type: array
          items:
            $ref: '#/components/schemas/type_property_Property'
          description: Where you define your Sheet's data schema.
        actions:
          type: array
          items:
            $ref: '#/components/schemas/type_commons_Action'
          description: An array of actions that end users can perform on this Sheet.
        treatments:
          type: array
          items:
            $ref: '#/components/schemas/type_sheets_SheetTreatments'
          description: An array of treatments that define the behavior of the sheet.
        collection:
          type: string
          description: Collection in which to group the sheet
        id:
          $ref: '#/components/schemas/type_commons_SheetId'
          description: The ID of the Sheet.
        workbookId:
          $ref: '#/components/schemas/type_commons_WorkbookId'
          description: The ID of the Workbook.
        config:
          $ref: '#/components/schemas/type_sheets_SheetConfig'
          description: Describes shape of data as well as behavior.
        metadata:
          description: Useful for any contextual metadata regarding the sheet. Store any valid json
        namespace:
          type: string
          description: The scoped namespace of the Sheet.
        updatedAt:
          type: string
          format: date-time
          description: Date the sheet was last updated
        createdAt:
          type: string
          format: date-time
          description: Date the sheet was created
      title: SheetConfigOrUpdate
    type_records_RecordCounts:
      type: object
      properties:
        total:
          type: integer
        valid:
          type: integer
        error:
          type: integer
        errorsByField:
          type: object
          additionalProperties:
            type: integer
        byField:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/type_records_FieldRecordCounts'
          description: Counts for valid, error, and total records grouped by field key
      required:
      - total
      - valid
      - error
      title: RecordCounts
    type_property_Property:
      oneOf:
      - type: object
        properties:
          type:
            type: string
            enum:
            - string
            description: 'Discriminator value: string'
          key:
            type: string
          label:
            type: string
            description: User friendly field name
          description:
            type: string
            description: A short description of the field. Markdown syntax is supported.
          constraints:
            type: array
            items:
              $ref: '#/components/schemas/type_property_Constraint'
            description: A list of constraints that should be applied to this field. This is limited to a maximum of 10 constraints and all external and stored constraints must have unique validator values.
          readonly:
            type: boolean
          appearance:
            $ref: '#/components/schemas/type_property_FieldAppearance'
          actions:
            type: array
            items:
              $ref: '#/components/schemas/type_commons_Action'
            description: An array of actions that end users can perform on this Column.
          metadata:
            description: Useful for any contextual metadata regarding the schema. Store any valid json here.
          treatments:
            type: array
            items:
              type: string
            description: A unique presentation for a field in the UI.
          alternativeNames:
            type: array
            items:
              type: string
          config:
            $ref: '#/components/schemas/type_property_StringConfig'
        required:
        - type
        - key
      - type: object
        properties:
          type:
            type: string
            enum:
            - number
            description: 'Discriminator value: number'
          key:
            type: string
          label:
            type: string
            description: User friendly field name
          description:
            type: string
            description: A short description of the field. Markdown syntax is supported.
          constraints:
            type: array
            items:
              $ref: '#/components/schemas/type_property_Constraint'
            description: A list of constraints that should be applied to this field. This is limited to a maximum of 10 constraints and all external and stored constraints must have unique validator values.
          readonly:
            type: boolean
          appearance:
            $ref: '#/components/schemas/type_property_FieldAppearance'
          actions:
            type: array
            items:
              $ref: '#/components/schemas/type_commons_Action'
            description: An array of actions that end users can perform on this Column.
          metadata:
            description: Useful for any contextual metadata regarding the schema. Store any valid json here.
          treatments:
            type: array
            items:
              type: string
            description: A unique presentation for a field in the UI.
          alternativeNames:
            type: array
            items:
              type: string
          isArray:
            type: boolean
            description: Will allow multiple values and store as an array. Use enum-list type instead.
          config:
            $ref: '#/components/schemas/type_property_NumberConfig'
        required:
        - type
        - key
      - type: object
        properties:
          type:
            type: string
            enum:
            - boolean
            description: 'Discriminator value: boolean'
          key:
            type: string
          label:
            type: string
            description: User friendly field name
          description:
            type: string
            description: A short description of the field. Markdown syntax is supported.
          constraints:
            type: array
            items:
              $ref: '#/components/schemas/type_property_Constraint'
            description: A list of constraints that should be ap

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