Flatfile subpackage_jobs API

openapi: 3.2.0
info:
  title: Reference subpackage_accounts Subpackage Jobs API
  version: 1.0.0
servers:
- url: https://api.x.flatfile.com/v1
tags:
- name: subpackage_jobs
paths:
  /jobs:
    get:
      operationId: list
      summary: List jobs
      tags:
      - subpackage_jobs
      parameters:
      - name: environmentId
        in: query
        description: When provided, only jobs for the given environment will be returned
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_EnvironmentId'
      - name: spaceId
        in: query
        description: When provided, only jobs for the given space will be returned
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_SpaceId'
      - name: workbookId
        in: query
        description: When provided, only jobs for the given workbook will be returned
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_WorkbookId'
      - name: fileId
        in: query
        description: When provided, only jobs for the given file will be returned
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_FileId'
      - name: parentId
        in: query
        description: When provided, only jobs that are parts of the given job will be returned
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_JobId'
      - name: pageSize
        in: query
        description: Number of jobs to return in a page (default 20)
        required: false
        schema:
          type: integer
      - name: pageNumber
        in: query
        description: Based on pageSize, which page of jobs to return
        required: false
        schema:
          type: integer
      - name: sortDirection
        in: query
        description: Sort direction - asc (ascending) or desc (descending)
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_SortDirection'
      - name: excludeChildJobs
        in: query
        description: When true, only top-level jobs will be returned unless a parentId is specified
        required: false
        schema:
          type: boolean
      - name: source
        in: query
        description: When provided, only jobs with the given source will be returned
        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_jobs_ListJobsResponse'
    post:
      operationId: create
      summary: Create a job
      tags:
      - subpackage_jobs
      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_jobs_JobResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_jobs_JobConfig'
  /jobs/{jobId}:
    get:
      operationId: get
      summary: Get a job
      tags:
      - subpackage_jobs
      parameters:
      - name: jobId
        in: path
        description: The id of the job to return
        required: true
        schema:
          $ref: '#/components/schemas/type_commons_JobId'
      - 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_jobs_JobResponse'
    patch:
      operationId: update
      summary: Update a job
      tags:
      - subpackage_jobs
      parameters:
      - name: jobId
        in: path
        description: The id of the job to patch
        required: true
        schema:
          $ref: '#/components/schemas/type_commons_JobId'
      - 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_jobs_JobResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_jobs_JobUpdate'
    delete:
      operationId: delete
      summary: Delete a job
      tags:
      - subpackage_jobs
      parameters:
      - name: jobId
        in: path
        description: The id of the job to delete
        required: true
        schema:
          $ref: '#/components/schemas/type_commons_JobId'
      - 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'
  /jobs/{jobId}/execute:
    post:
      operationId: execute
      summary: Execute a job
      description: Execute a job and return the job
      tags:
      - subpackage_jobs
      parameters:
      - name: jobId
        in: path
        description: ID of job to return
        required: true
        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_commons_Success'
  /jobs/{jobId}/plan:
    get:
      operationId: get-execution-plan
      summary: Get a job's execution plan
      description: Returns a single job's execution plan
      tags:
      - subpackage_jobs
      parameters:
      - name: jobId
        in: path
        description: ID of job to return
        required: true
        schema:
          $ref: '#/components/schemas/type_commons_JobId'
      - 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_jobs_JobPlanResponse'
    put:
      operationId: update-execution-plan
      summary: Replace a job's plan
      description: Update a job's entire execution plan
      tags:
      - subpackage_jobs
      parameters:
      - name: jobId
        in: path
        description: ID of job to return
        required: true
        schema:
          $ref: '#/components/schemas/type_commons_JobId'
      - 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_jobs_JobPlanResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_jobs_JobExecutionPlanRequest'
    patch:
      operationId: update-execution-plan-fields
      summary: Update a job's plan
      description: Update one or more individual fields on a job's execution plan
      tags:
      - subpackage_jobs
      parameters:
      - name: jobId
        in: path
        description: ID of job to return
        required: true
        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_jobs_JobPlanResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_jobs_JobExecutionPlanConfigRequest'
  /jobs/{jobId}/ack:
    post:
      operationId: ack
      summary: Acknowledge a job
      description: Acknowledge a job and return the job
      tags:
      - subpackage_jobs
      parameters:
      - name: jobId
        in: path
        description: ID of job to return
        required: true
        schema:
          $ref: '#/components/schemas/type_commons_JobId'
      - 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_jobs_JobResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_jobs_JobAckDetails'
  /jobs/{jobId}/outcome/ack:
    post:
      operationId: ack-outcome
      summary: Acknowledge a job outcome
      description: Acknowledge a job outcome and return the job
      tags:
      - subpackage_jobs
      parameters:
      - name: jobId
        in: path
        description: ID of job to return
        required: true
        schema:
          $ref: '#/components/schemas/type_commons_JobId'
      - 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_jobs_JobResponse'
  /jobs/{jobId}/complete:
    post:
      operationId: complete
      summary: Complete a job
      description: Complete a job and return the job
      tags:
      - subpackage_jobs
      parameters:
      - name: jobId
        in: path
        description: ID of job to return
        required: true
        schema:
          $ref: '#/components/schemas/type_commons_JobId'
      - 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_jobs_JobResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_jobs_JobCompleteDetails'
  /jobs/{jobId}/fail:
    post:
      operationId: fail
      summary: Fail a job
      description: Fail a job and return the job
      tags:
      - subpackage_jobs
      parameters:
      - name: jobId
        in: path
        description: ID of job to return
        required: true
        schema:
          $ref: '#/components/schemas/type_commons_JobId'
      - 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_jobs_JobResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_jobs_JobCompleteDetails'
  /jobs/{jobId}/cancel:
    post:
      operationId: cancel
      summary: Cancel a job
      description: Cancel a job and return the job
      tags:
      - subpackage_jobs
      parameters:
      - name: jobId
        in: path
        description: ID of job to return
        required: true
        schema:
          $ref: '#/components/schemas/type_commons_JobId'
      - 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_jobs_JobResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_jobs_JobCancelDetails'
  /jobs/{jobId}/retry:
    post:
      operationId: retry
      summary: Retry a failed job
      description: Retry a failt job and return the job
      tags:
      - subpackage_jobs
      parameters:
      - name: jobId
        in: path
        description: ID of job to return
        required: true
        schema:
          $ref: '#/components/schemas/type_commons_JobId'
      - 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_jobs_JobResponse'
  /jobs/preview-mutation:
    post:
      operationId: preview-mutation
      summary: Preview a mutation
      description: Preview the results of a mutation
      tags:
      - subpackage_jobs
      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_records_DiffRecordsResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_jobs_MutateJobConfig'
  /jobs/{jobId}/split:
    post:
      operationId: split
      summary: Split a job
      description: Split a job and return the job
      tags:
      - subpackage_jobs
      parameters:
      - name: jobId
        in: path
        description: ID of job to return
        required: true
        schema:
          $ref: '#/components/schemas/type_commons_JobId'
      - 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_jobs_JobResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_jobs_JobSplitDetails'
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_commons_SpaceId:
      type: string
      description: Space ID
      title: SpaceId
    type_jobs_JobOutcomeTrigger:
      oneOf:
      - $ref: '#/components/schemas/type_jobs_JobOutcomeTriggerType'
      - $ref: '#/components/schemas/type_jobs_JobOutcomeTriggerDetails'
      title: JobOutcomeTrigger
    type_jobs_ListJobsResponse:
      type: object
      properties:
        pagination:
          $ref: '#/components/schemas/type_commons_Pagination'
        data:
          type: array
          items:
            $ref: '#/components/schemas/type_jobs_Job'
      required:
      - data
      title: ListJobsResponse
    type_jobs_JobPartsArray:
      type: array
      items:
        type: object
        additionalProperties:
          description: Any type
      description: Data for each of the job parts
      title: JobPartsArray
    type_property_NumberConfig:
      type: object
      properties:
        decimalPlaces:
          type: integer
          description: Number of decimal places to round data to
      title: NumberConfig
    type_commons_AppId:
      type: string
      description: App ID
      title: AppId
    type_commons_VersionId:
      type: string
      description: Version ID
      title: VersionId
    type_jobs_Certainty:
      type: string
      enum:
      - absolute
      - strong
      - moderate
      - weak
      title: Certainty
    type_jobs_AgentPromotionJobConfig:
      type: object
      properties:
        targetEnvironmentId:
          $ref: '#/components/schemas/type_commons_EnvironmentId'
          description: The environment ID where the agent should be promoted
        spaceId:
          $ref: '#/components/schemas/type_commons_SpaceId'
          description: The space ID where the agent is being promoted from
      required:
      - targetEnvironmentId
      - spaceId
      description: The configuration for an agent promotion job
      title: AgentPromotionJobConfig
    type_jobs_JobCancelDetails:
      type: object
      properties:
        info:
          type: string
      description: Info about the reason the job was canceled
      title: JobCancelDetails
    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_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_commons_ActorId:
      type: string
      description: Actor ID
      title: ActorId
    type_jobs_RunRunbookJobConfig:
      type: object
      properties:
        sourceSheetId:
          $ref: '#/components/schemas/type_commons_SheetId'
        runbookId:
          $ref: '#/components/schemas/type_commons_RunbookId'
      required:
      - sourceSheetId
      - runbookId
      title: RunRunbookJobConfig
    type_property_StringConfig:
      type: object
      properties:
        size:
          $ref: '#/components/schemas/type_property_StringConfigOptions'
      required:
      - size
      title: StringConfig
    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_jobs_EnumValue:
      oneOf:
      - type: string
      - type: integer
      - type: boolean
      title: EnumValue
    type_commons_SortField:
      type: string
      description: Name of field by which to sort records
      title: SortField
    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_jobs_AiRuleCreationJobConfig:
      type: object
      properties:
        label:
          type: string
          description: Display name for the rule to be created
        prompt:
          type: string
          description: The natural language description of the rule to be created
        sheetId:
          $ref: '#/components/schemas/type_commons_SheetId'
          description: The ID of the sheet containing the field to create/update the rule for
        fieldKey:
          type: string
          description: The key of the field to create/update the rule for
        index:
          type: integer
          description: To edit an existing rule, provide the index of the constraint in the constraints array for the field and that constraint will be replaced.
      required:
      - prompt
      - sheetId
      - fieldKey
      description: Configuration for AI-powered rule creation jobs that generate or replace field constraints
      title: AiRuleCreationJobConfig
    type_commons_Pagination:
      type: object
      properties:
        currentPage:
          type: integer
          description: current page of results
        pageCount:
          type: integer
          description: total number of pages of results
        totalCount:
          type: integer
          description: total available results
      required:
      - currentPage
      - pageCount
      - totalCount
      description: pagination info
      title: Pagination
    type_jobs_FlagMutationConfig:
      type: object
      properties:
        type:
          type: string
          enum:
          - flag
          description: The type of mutation (always "flag")
        operation:
          $ref: '#/components/schemas/type_flags_FlagOperation'
          description: The operation to perform
        flag:
          $ref: '#/components/schemas/type_jobs_FlagMutationConfigData'
          description: The flag data for the operation
        flags:
          type: array
          items:
            type: string
          description: Array of flag slugs for delete operation
      required:
      - type
      - operation
      - flag
      description: Configuration for flag mutation operations
      title: FlagMutationConfig
    type_jobs_JobOutcomeNext:
      oneOf:
      - type: object
        properties:
          type:
            type: string
            enum:
            - id
            description: 'Discriminator value: id'
          id:
            type: string
          label:
            type: string
          path:
            type: string
          query:
            type: string
        required:
        - type
        - id
      - type: object
        properties:
          type:
            type: string
            enum:
            - url
            description: 'Discriminator value: url'
          url:
            type: string
          label:
            type: string
          replace:
            type: boolean
            description: Whether to replace the current tab or iframe when navigating to the url. Defaults to false.
        required:
        - type
        - url
      - type: object
        properties:
          type:
            type: string
            enum:
            - download
            description: 'Discriminator value: download'
          url:
            type: string
          label:
            type: string
          fileName:
            type: string
        required:
        - type
        - url
      - type: object
        properties:
          type:
            type: string
            enum:
            - files
            description: 'Discriminator value: files'
          files:
            type: array
            items:
              $ref: '#/components/schemas/type_jobs_JobOutcomeNextFileObject'
          label:
            type: string
        required:
        - type
        - files
      - type: object
        properties:
          type:
            type: string
            enum:
            - wait
            description: 'Discriminator value: wait'
          fade:
            type: boolean
          confetti:
            type: boolean
        required:
        - type
      - type: object
        properties:
          type:
            type: string
            enum:
            - snapshot
            description: 'Discriminator value: snapshot'
          snapshotId:
            type: string
          sheetId:
            type: string
        required:
        - type
        - snapshotId
        - sheetId
      - type: object
        properties:
          type:
            type: string
            enum:
            - retry
            description: 'Discriminator value: retry'
          label:
            type: string
        required:
        - type
      - type: object
        properties:
          type:
            type: string
            enum:
            - view
            description: 'Discriminator value: view'
          sheetId:
            type: string
          hiddenColumns:
            type: array
            items:
              type: string
            description: An array of field keys from the sheet
          label:
            type: string
        required:
        - type
        - sheetId
        - hiddenColumns
      - type: object
        properties:
          type:
            type: string
            enum:
            - clearFilters
            description: 'Discriminator value: clearFilters'
          label:
            type: string
          sheetIds:
            type: array
            items:
              type: string
        required:
        - type
      discriminator:
        propertyName: type
      title: JobOutcomeNext
    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:
       

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