Flatfile subpackage_workbooks API
The subpackage_workbooks API from Flatfile — 3 operation(s) for subpackage_workbooks.
OpenAPI Specification
openapi: 3.1.0
info:
title: API 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_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:Success:
type: object
properties:
data:
$ref: '#/components/schemas/type_commons:SuccessData'
description: Informs whether or not a request was successful
title: Success
type_sheets:SheetConfig:
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.
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.
metadata:
description: Useful for any contextual metadata regarding the schema. Store any valid json
constraints:
type: array
items:
$ref: '#/components/schemas/type_sheets:SheetConstraint'
description: An array of constraints 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
required:
- name
- fields
description: Describes shape of data as well as behavior
title: SheetConfig
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_commons:CommitId:
type: string
description: Commit ID
title: CommitId
type_property:EnumPropertyOption:
type: object
properties:
label:
type: string
description: A visual label for this option
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.
alternativeNames:
type: array
items:
type: string
description: Alternative names to match this enum option to
ordinal:
type: integer
description: The order of this option in the list. SortBy must be set to `ordinal` to use this.
required:
- value
title: EnumPropertyOption
type_commons:Guide:
type: object
properties:
content:
type: string
description: Markdown guidance for this action
required:
- content
title: Guide
type_property:FieldSize:
type: string
enum:
- xs
- s
- m
- l
- xl
description: The default visual sizing. This sizing may be overridden by a user
title: FieldSize
type_records:ValidationType:
type: string
enum:
- error
- warn
- info
title: ValidationType
type_commons:InputConstraintType:
type: string
enum:
- required
title: InputConstraintType
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_property:NumberConfig:
type: object
properties:
decimalPlaces:
type: integer
description: Number of decimal places to round data to
title: NumberConfig
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_commons:ActionMode:
type: string
enum:
- foreground
- background
- toolbarBlocking
description: Foreground actions will prevent interacting with the resource until complete
title: ActionMode
type_sheets:SheetConstraint:
oneOf:
- type: object
properties:
type:
type: string
enum:
- unique
description: 'Discriminator value: unique'
name:
type: string
description: The name of the constraint
fields:
type: array
items:
type: string
description: The fields that must be unique together
requiredFields:
type: array
items:
type: string
description: Fields that, when empty, will cause this unique constraint to be ignored
strategy:
$ref: '#/components/schemas/type_sheets:CompositeUniqueConstraintStrategy'
config:
$ref: '#/components/schemas/type_sheets:CompositeUniqueConstraintConfig'
description: Configuration options for the composite unique constraint
required:
- type
- name
- fields
- strategy
- type: object
properties:
type:
type: string
enum:
- external
description: 'Discriminator value: external'
validator:
type: string
fields:
type: array
items:
type: string
description: The fields that must be unique together
config:
description: Any type
required:
- type
- validator
discriminator:
propertyName: type
title: SheetConstraint
type_commons:ActionSchedule:
type: string
enum:
- weekly
- daily
- hourly
title: ActionSchedule
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_commons:ActionMessageType:
type: string
enum:
- error
- info
title: ActionMessageType
type_sheets:CompositeUniqueConstraintStrategy:
type: string
enum:
- hash
- concat
title: CompositeUniqueConstraintStrategy
type_commons:SheetId:
type: string
description: Sheet ID
title: SheetId
type_commons:ActionId:
type: string
description: Action ID
title: ActionId
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_property:StringConfigOptions:
type: string
enum:
- tiny
- normal
- medium
- long
description: How much text should be storeable in this field
title: StringConfigOptions
type_property:UniqueConstraintConfig:
type: object
properties:
caseSensitive:
type: boolean
description: Ignore casing when determining uniqueness
ignoreEmpty:
type: boolean
description: Do not flag empty values as duplicate
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: UniqueConstraintConfig
type_sheets:SheetAccess:
type: string
enum:
- '*'
- add
- edit
- delete
- import
title: SheetAccess
type_sheets:Sheet:
type: object
properties:
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.
name:
type: string
description: The name of the Sheet.
slug:
type: string
description: The slug of the Sheet.
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.
lockedBy:
type: string
description: The actor who locked 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
lockedAt:
type: string
format: date-time
description: The time the Sheet was locked.
recordCounts:
$ref: '#/components/schemas/type_records:RecordCounts'
description: The precomputed counts of records in the Sheet (may not exist).
createdFrom:
$ref: '#/components/schemas/type_commons:SheetId'
description: The sheet id of the template that was used to create this sheet
lastPropagatedAt:
type: string
format: date-time
description: The last time the sheet template configuration was propagated to 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
required:
- id
- workbookId
- name
- slug
- config
- updatedAt
- createdAt
description: A place to store tabular data
title: Sheet
type_commons:InputConstraint:
type: object
properties:
type:
$ref: '#/components/schemas/type_commons:InputConstraintType'
required:
- type
title: InputConstraint
type_commons:ActionMessage:
type: object
properties:
type:
$ref: '#/components/schemas/type_commons:ActionMessageType'
content:
type: string
required:
- type
- content
title: ActionMessage
type_commons:EnvironmentId:
type: string
description: Environment ID
title: EnvironmentId
type_commons:InputForm:
type: object
properties:
type:
$ref: '#/components/schemas/type_commons:InputFormType'
fields:
type: array
items:
$ref: '#/components/schemas/type_commons:InputField'
required:
- type
- fields
title: InputForm
type_commons:Error:
type: object
properties:
key:
type: string
message:
type: string
required:
- message
title: Error
type_property:StringConfig:
type: object
properties:
size:
$ref: '#/components/schemas/type_property:StringConfigOptions'
required:
- size
title: StringConfig
type_commons:InputField:
type: object
properties:
key:
type: string
description: Unique key for a Field.
label:
type: string
description: Visible name of a Field.
description:
type: string
description: Brief description below the name of the Field.
type:
type: string
description: Field Types inform the user interface how to sort and display data.
defaultValue:
description: Default value for a Field.
config:
$ref: '#/components/schemas/type_commons:InputConfig'
description: Additional configuration for enum Fields.
constraints:
type: array
items:
$ref: '#/components/schemas/type_commons:InputConstraint'
description: Indicate additional validations that will be applied to the Field.
required:
- key
- label
- type
title: InputField
type_commons:SuccessData:
type: object
properties:
success:
type: boolean
required:
- success
title: SuccessData
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:InputFormType:
type: string
enum:
- simple
title: InputFormType
type_commons:InputConfig:
type: object
properties:
options:
type: array
items:
$ref: '#/components/schemas/type_commons:InputEnumPropertyOption'
required:
- options
title: InputConfig
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_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: obj
# --- 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