Flatfile subpackage_sheets API

openapi: 3.1.0
info:
  title: API Reference subpackage_accounts subpackage_sheets API
  version: 1.0.0
servers:
- url: https://api.x.flatfile.com/v1
tags:
- name: subpackage_sheets
paths:
  /sheets:
    get:
      operationId: list
      summary: List sheets
      description: Returns sheets in a workbook
      tags:
      - subpackage_sheets
      parameters:
      - name: workbookId
        in: query
        description: ID of workbook
        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_sheets:ListSheetsResponse'
  /sheets/{sheetId}:
    get:
      operationId: get
      summary: Get a sheet
      description: Returns a sheet in a workbook
      tags:
      - subpackage_sheets
      parameters:
      - name: sheetId
        in: path
        description: ID of sheet
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:SheetId'
      - 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_sheets:SheetResponse'
    delete:
      operationId: delete
      summary: Delete a sheet
      description: Deletes a specific sheet from a workbook
      tags:
      - subpackage_sheets
      parameters:
      - name: sheetId
        in: path
        description: ID of sheet
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:SheetId'
      - 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-sheet
      summary: Update a sheet
      description: Updates Sheet
      tags:
      - subpackage_sheets
      parameters:
      - name: sheetId
        in: path
        description: ID of sheet
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:SheetId'
      - 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_sheets:SheetResponse'
        '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_sheets:SheetUpdateRequest'
  /sheets/{sheetId}/duplicate:
    post:
      operationId: duplicate-sheet
      summary: Duplicate a sheet
      description: Creates a copy of a sheet including all its data within the same workbook
      tags:
      - subpackage_sheets
      parameters:
      - name: sheetId
        in: path
        description: ID of sheet to duplicate
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:SheetId'
      - 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_sheets:SheetResponse'
        '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:
              type: object
              properties:
                name:
                  type: string
                  description: Custom name for the duplicated sheet. Defaults to "Copy of [original name]"
                slug:
                  type: string
                  description: Custom slug for the duplicated sheet. Defaults to "[original slug]-copy-[timestamp]"
  /sheets/{sheetId}/validate:
    post:
      operationId: validate
      summary: Validate a sheet
      description: Trigger data hooks and validation to run on a sheet
      tags:
      - subpackage_sheets
      parameters:
      - name: sheetId
        in: path
        description: ID of sheet
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:SheetId'
      - 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'
  /sheets/{sheetId}/download:
    get:
      operationId: get-records-as-csv
      summary: Download records as a CSV file
      description: Returns records from a sheet in a workbook as a csv file
      tags:
      - subpackage_sheets
      parameters:
      - name: sheetId
        in: path
        description: ID of sheet
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:SheetId'
      - name: versionId
        in: query
        description: Deprecated, use `sinceCommitId` instead.
        required: false
        schema:
          type: string
      - name: commitId
        in: query
        description: Returns records that were changed in that version  in that version and only those records.
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:CommitId'
      - name: sinceVersionId
        in: query
        description: Deprecated, use `sinceCommitId` instead.
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:VersionId'
      - name: sinceCommitId
        in: query
        description: Returns records that were changed in that version in addition to any records from versions after that version.
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:CommitId'
      - name: sortField
        in: query
        description: The field to sort the data on.
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:SortField'
      - name: sortDirection
        in: query
        description: Sort direction - asc (ascending) or desc (descending)
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:SortDirection'
      - name: filter
        in: query
        description: Options to filter records
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:Filter'
      - name: filterField
        in: query
        description: The field to filter the data on.
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:FilterField'
      - name: searchValue
        in: query
        description: The value to search for data on.
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:SearchValue'
      - name: searchField
        in: query
        description: The field to search for data on.
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:SearchField'
      - name: ids
        in: query
        description: The Record Ids param (ids) is a list of record ids that can be passed to several record endpoints allowing the user to identify specific records to INCLUDE in the query, or specific records to EXCLUDE, depending on whether or not filters are being applied. When passing a query param that filters the record dataset, such as 'searchValue', or a 'filter' of 'valid' | 'error' | 'all', the 'ids' param will EXCLUDE those records from the filtered results. For basic queries that do not filter the dataset, passing record ids in the 'ids' param will limit the dataset to INCLUDE just those specific records
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:RecordId'
      - 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/octet-stream:
              schema:
                type: string
                format: binary
  /sheets/{sheetId}/counts:
    get:
      operationId: get-record-counts
      summary: Get record counts
      description: Returns counts of records from a sheet
      tags:
      - subpackage_sheets
      parameters:
      - name: sheetId
        in: path
        description: ID of sheet
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:SheetId'
      - name: versionId
        in: query
        description: Returns records that were changed in that version and only those records.
        required: false
        schema:
          type: string
      - name: sinceVersionId
        in: query
        description: Deprecated, use `sinceCommitId` instead.
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:VersionId'
      - name: commitId
        in: query
        description: Returns records that were changed in that version in addition to any records from versions after that version.
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:CommitId'
      - name: sinceCommitId
        in: query
        description: Listing a commit ID here will return all records since the specified commit.
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:CommitId'
      - name: filter
        in: query
        description: Options to filter records
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:Filter'
      - name: filterField
        in: query
        description: The field to filter the data on.
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:FilterField'
      - name: searchValue
        in: query
        description: The value to search for data on.
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:SearchValue'
      - name: searchField
        in: query
        description: The field to search for data on.
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:SearchField'
      - name: byField
        in: query
        description: If true, the counts for each field will also be returned
        required: false
        schema:
          type: boolean
      - name: q
        in: query
        description: An FFQL query used to filter the result set to be counted
        required: false
        schema:
          type: string
      - 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_sheets:RecordCountsResponse'
  /sheets/{sheetId}/calculations:
    get:
      operationId: get-calculations
      summary: List calculations
      description: Returns all calculations for a sheet
      tags:
      - subpackage_sheets
      parameters:
      - name: sheetId
        in: path
        description: ID of sheet
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:SheetId'
      - name: versionId
        in: query
        description: Returns records that were changed in that version and only those records.
        required: false
        schema:
          type: string
      - name: sinceVersionId
        in: query
        description: Deprecated, use `sinceCommitId` instead.
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:VersionId'
      - name: commitId
        in: query
        description: Returns records that were changed in that version in addition to any records from versions after that version.
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:CommitId'
      - name: sinceCommitId
        in: query
        description: Listing a commit ID here will return all records since the specified commit.
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:CommitId'
      - name: filter
        in: query
        description: Options to filter records
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:Filter'
      - name: filterField
        in: query
        description: The field to filter the data on.
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:FilterField'
      - name: searchValue
        in: query
        description: The value to search for data on.
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:SearchValue'
      - name: searchField
        in: query
        description: The field to search for data on.
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:SearchField'
      - name: byField
        in: query
        description: If true, the counts for each field will also be returned
        required: false
        schema:
          type: boolean
      - name: q
        in: query
        description: An FFQL query used to filter the result set to be counted
        required: false
        schema:
          type: string
      - 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_sheets:ListCalculationsResponse'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:Errors'
  /sheets/{sheetId}/commits:
    get:
      operationId: get-sheet-commits
      summary: Get commit versions for a sheet
      description: Returns the commit versions for a sheet
      tags:
      - subpackage_sheets
      parameters:
      - name: sheetId
        in: path
        description: ID of sheet
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:SheetId'
      - 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'
  /sheets/{sheetId}/lock:
    post:
      operationId: lock-sheet
      summary: Lock a sheet
      description: Locks a sheet
      tags:
      - subpackage_sheets
      parameters:
      - name: sheetId
        in: path
        description: ID of sheet
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:SheetId'
      - 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'
  /sheets/{sheetId}/unlock:
    post:
      operationId: unlock-sheet
      summary: Unlock a sheet
      description: Removes a lock from a sheet
      tags:
      - subpackage_sheets
      parameters:
      - name: sheetId
        in: path
        description: ID of sheet
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:SheetId'
      - 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'
  /sheets/{sheetId}/cells:
    get:
      operationId: get-cell-values
      summary: Get record cells by field
      description: Returns record cell values grouped by all fields in the sheet
      tags:
      - subpackage_sheets
      parameters:
      - name: sheetId
        in: path
        description: ID of sheet
        required: true
        schema:
          $ref: '#/components/schemas/type_commons:SheetId'
      - name: fieldKey
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_sheets:FieldKey'
      - name: sortField
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:SortField'
      - name: sortDirection
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:SortDirection'
      - name: filter
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:Filter'
      - name: filterField
        in: query
        description: Name of field by which to filter records
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:FilterField'
      - name: pageSize
        in: query
        description: Number of records to return in a page (default 1000 if pageNumber included)
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:PageSize'
      - name: pageNumber
        in: query
        description: Based on pageSize, which page of records to return
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:PageNumber'
      - name: distinct
        in: query
        description: Must be set to true
        required: true
        schema:
          $ref: '#/components/schemas/type_sheets:Distinct'
      - name: includeCounts
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_sheets:IncludeCounts'
      - name: searchValue
        in: query
        description: A value to find for a given field in a sheet. Wrap the value in "" for exact match
        required: false
        schema:
          $ref: '#/components/schemas/type_commons:SearchValue'
      - name: q
        in: query
        description: An FFQL query used to filter the records to be queried
        required: false
        schema:
          type: string
      - 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_sheets:CellsResponse'
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_records:ValidationSource:
      type: string
      enum:
      - required-constraint
      - unique-constraint
      - custom-logic
      - unlinked
      - invalid-option
      - is-artifact
      title: ValidationSource
    type_sheets:CellsResponseData:
      type: object
      additionalProperties:
        type: array
        items:
          $ref: '#/components/schemas/type_sheets:CellValueWithCounts'
      description: Cell values grouped by field key
      title: CellsResponseData
    type_records:ValidationType:
      type: string
      enum:
      - error
      - warn
      - info
      title: ValidationType
    type_commits:Commit:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/type_commons:CommitId'
        sheetId:
          $ref: '#/components/schemas/type_commons:SheetId'
        createdBy:
          type: string
          description: The actor (user or system) who created the commit
        completedBy:
          type: string
          description: The actor (user or system) who completed the commit
        createdAt:
          type: string
          format: date-time
          description: The time the commit was created
        completedAt:
          type: string
          format: date-time
          description: The time the commit was acknowledged
      required:
      - id
      - sheetId
      - createdBy
      - createdAt
      description: A commit version
      title: Commit
    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_commons:Filter:
      type: string
      enum:
      - valid
      - error
      - all
      - none
      description: Options to filter records
      title: Filter
    type_commons:ActionMessage:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type_commons:ActionMessageType'
        content:
          type: string
      required:
      - type
      - content
      title: ActionMessage
    type_property:StringConfig:
      type: object
      properties:
        size:
          $ref: '#/components/schemas/type_property:StringConfigOptions'
      required:
      - size
      title: StringConfig
    type_sheets:RecordCountsResponseData:
      type: object
      properties:
        counts:
          $ref: '#/components/schemas/type_records:RecordCounts'
        success:
          type: boolean
      required:
      - counts
      - success
      title: RecordCountsResponseData
    type_sheets:Distinct:
      type: boolean
      description: When true, excludes duplicate values
      title: Distinct
    type_commons:ActionConstraint:
      oneOf:
      - type: object
        properties:
          type:
            type: string
            enum:
            - hasAllValid
            description: 'Discriminator value: hasAllValid'
          ignoreSelection:
            type: boolean
        required:
        - type
      - type: object
        properties:
          type:
            type: string
            enum:
            - hasSelection
            description: 'Discriminator value: hasSelection'
        required:
        - type
      - type: object
        properties:
          type:
            type: string
            enum:
            - hasData
            description: 'Discriminator value: hasData'
        required:
        - type
      - type: object
        properties:
          type:
            type: string
            enum:
            - hasColumnEnabled
            description: 'Discriminator value: hasColumnEnabled'
        required:
        - type
      discriminator:
        propertyName: type
      title: ActionConstraint
    type_commons:ActionMount:
      oneOf:
      - type: object
        properties:
          type:
            type: string
            enum:
            - sheet
            description: 'Discriminator value: sheet'
          slugs:
            type: array
            items:
              type: string
        required:
        - type
      - type: object
        properties:
          type:
            type: string
            enum:
            - workbook
            description: 'Discriminator value: workbook'
          slugs:
            type: array
            items:
              type: string
        required:
        - type
      - type: object
        properties:
          type:
            type: string
            enum:
            - field
            description: 'Discriminator value: field'
          keys:
            type: array
            items:
              type: string
        required:
        - type
      - type: object
        properties:
          type:
            type: string
            enum:
            - document
            description: 'Discriminator value: document'
        required:
        - type
      - type: object
        properties:
          type:
            type: string
            enum:
            - file
            description: 'Discriminator value: file'
        required:
        - type
      discriminator:
        propertyName: type
      title: ActionMount
    type_commons:InputEnumPropertyOption:
      type: object
      properties:
        label:
          type: string
          description: A visual label for this option, defaults to value if not provided
        description:
          type: string
          description: A short description for this option
        color:
          type: string
          description: An optional color to assign this option
        icon:
          type: string
          description: A reference pointer to a previously registered icon
        meta:
          type: object
          additionalProperties:
            description: Any type
          description: An arbitrary JSON object to be associated with this option and made available to hooks
        value:
          description: The value or ID of this option. This value will be sent in egress. The type is a string | integer | boolean.
      required:
      - value
      title: InputEnumPropertyOption
    type_commits:ListCommitsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/type_commits:Commit'
      required:
      - data
      title: ListCommitsResponse
    type_commons:SortDirection:
      type: string
      enum:
      - asc
      - desc
      description: Sort direction - asc (ascending) or desc (descending)
      title: SortDirection
    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: 'Discriminat

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