Flatfile subpackage_events API

openapi: 3.2.0
info:
  title: Reference subpackage_accounts Subpackage Events API
  version: 1.0.0
servers:
- url: https://api.x.flatfile.com/v1
tags:
- name: subpackage_events
paths:
  /events:
    get:
      operationId: list
      summary: List events
      description: Event topics that the Flatfile Platform emits.
      tags:
      - subpackage_events
      parameters:
      - name: environmentId
        in: query
        description: Filter by environment
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_EnvironmentId'
      - name: spaceId
        in: query
        description: Filter by space
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_SpaceId'
      - name: domain
        in: query
        description: Filter by event domain
        required: false
        schema:
          type: string
      - name: topic
        in: query
        description: Filter by event topic
        required: false
        schema:
          type: string
      - name: since
        in: query
        description: Filter by event timestamp
        required: false
        schema:
          type: string
          format: date-time
      - name: pageSize
        in: query
        description: Number of results to return in a page (default 10)
        required: false
        schema:
          type: integer
      - name: pageNumber
        in: query
        description: Based on pageSize, which page of results to return
        required: false
        schema:
          type: integer
      - name: includeAcknowledged
        in: query
        description: Include acknowledged events
        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_events_ListAllEventsResponse'
    post:
      operationId: create
      summary: Create an event
      tags:
      - subpackage_events
      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_events_EventResponse'
        '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_events_CreateEventConfig'
  /events/{eventId}:
    get:
      operationId: get
      summary: Get an event
      tags:
      - subpackage_events
      parameters:
      - name: eventId
        in: path
        description: The event id
        required: true
        schema:
          $ref: '#/components/schemas/type_commons_EventId'
      - 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_events_EventResponse'
  /events/{eventId}/ack:
    post:
      operationId: ack
      summary: Acknowledge an event
      tags:
      - subpackage_events
      parameters:
      - name: eventId
        in: path
        description: The event id
        required: true
        schema:
          $ref: '#/components/schemas/type_commons_EventId'
      - 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'
  /subscription:
    get:
      operationId: get-event-token
      summary: Get subscription credentials
      description: Get a token which can be used to subscribe to events for this space
      tags:
      - subpackage_events
      parameters:
      - name: scope
        in: query
        description: The resource ID of the event stream (space or environment id)
        required: false
        schema:
          type: string
      - name: spaceId
        in: query
        description: The space ID of the event stream
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_SpaceId'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      - name: X-Disable-Hooks
        in: header
        required: true
        schema:
          type: string
          enum:
          - 'true'
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_spaces_EventTokenResponse'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_Errors'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_Errors'
components:
  schemas:
    type_events_Origin:
      type: object
      properties:
        id:
          type: string
        slug:
          type: string
      description: The origin resource of the event
      title: Origin
    type_commons_SpaceId:
      type: string
      description: Space ID
      title: SpaceId
    type_commons_Error:
      type: object
      properties:
        key:
          type: string
        message:
          type: string
      required:
      - message
      title: Error
    type_commons_CommitId:
      type: string
      description: Commit ID
      title: CommitId
    type_commons_AppId:
      type: string
      description: App ID
      title: AppId
    type_commons_ThreadId:
      type: string
      description: Thread ID
      title: ThreadId
    type_events_EventResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/type_events_Event'
      required:
      - data
      title: EventResponse
    type_events_Context:
      type: object
      properties:
        namespaces:
          type: array
          items:
            type: string
          description: The namespaces of the event
        slugs:
          $ref: '#/components/schemas/type_events_EventContextSlugs'
          description: The slugs of related resources
        actionName:
          $ref: '#/components/schemas/type_events_ActionName'
        accountId:
          $ref: '#/components/schemas/type_commons_AccountId'
        environmentId:
          $ref: '#/components/schemas/type_commons_EnvironmentId'
        spaceId:
          $ref: '#/components/schemas/type_commons_SpaceId'
        workbookId:
          $ref: '#/components/schemas/type_commons_WorkbookId'
        sheetId:
          $ref: '#/components/schemas/type_commons_SheetId'
        sheetSlug:
          $ref: '#/components/schemas/type_events_SheetSlug'
        snapshotId:
          $ref: '#/components/schemas/type_commons_SnapshotId'
        versionId:
          $ref: '#/components/schemas/type_commons_VersionId'
          description: Deprecated, use `commitId` instead.
        commitId:
          $ref: '#/components/schemas/type_commons_CommitId'
        jobId:
          $ref: '#/components/schemas/type_commons_JobId'
        programId:
          $ref: '#/components/schemas/type_commons_ProgramId'
        fileId:
          $ref: '#/components/schemas/type_commons_FileId'
        documentId:
          $ref: '#/components/schemas/type_commons_DocumentId'
        precedingEventId:
          $ref: '#/components/schemas/type_commons_EventId'
        actorId:
          type: string
          description: Can be a UserId, GuestId, or AgentId
        appId:
          $ref: '#/components/schemas/type_commons_AppId'
        actionId:
          $ref: '#/components/schemas/type_commons_ActionId'
        dataClipId:
          $ref: '#/components/schemas/type_commons_DataClipId'
        threadId:
          $ref: '#/components/schemas/type_commons_ThreadId'
        filters:
          type: object
          additionalProperties:
            type: string
        entityId:
          type: string
      required:
      - accountId
      - environmentId
      description: The context of the event
      title: Context
    type_commons_VersionId:
      type: string
      description: Version ID
      title: VersionId
    type_commons_EventId:
      type: string
      description: Event ID
      title: EventId
    type_commons_ActionId:
      type: string
      description: Action ID
      title: ActionId
    type_events_ListAllEventsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/type_events_Event'
      required:
      - data
      title: ListAllEventsResponse
    type_commons_DocumentId:
      type: string
      description: Document ID
      title: DocumentId
    type_events_EventContextSlugs:
      type: object
      properties:
        space:
          type: string
          description: The slug of the space
        workbook:
          type: string
          description: The slug of the workbook
        sheet:
          type: string
          description: The slug of the sheet
      title: EventContextSlugs
    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_commons_SuccessData:
      type: object
      properties:
        success:
          type: boolean
      required:
      - success
      title: SuccessData
    type_commons_SnapshotId:
      type: string
      description: Snapshot ID
      title: SnapshotId
    type_commons_Errors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/type_commons_Error'
      required:
      - errors
      title: Errors
    type_events_Domain:
      type: string
      enum:
      - file
      - space
      - workbook
      - flag
      - job
      - document
      - sheet
      - program
      - secret
      - cron
      - environment
      - data-clip
      - canvas
      - canvas-area
      - thread
      description: The domain of the event
      title: Domain
    type_commons_FileId:
      type: string
      description: File ID
      title: FileId
    type_commons_DataClipId:
      type: string
      description: Data Clip ID
      title: DataClipId
    type_commons_WorkbookId:
      type: string
      description: Workbook ID
      title: WorkbookId
    type_events_CreateEventConfig:
      type: object
      properties:
        domain:
          $ref: '#/components/schemas/type_events_Domain'
          description: The domain of the event
        context:
          $ref: '#/components/schemas/type_events_Context'
          description: The context of the event
        attributes:
          $ref: '#/components/schemas/type_events_EventAttributes'
          description: The attributes of the event
        callbackUrl:
          type: string
          description: The callback url to acknowledge the event
        dataUrl:
          type: string
          description: The url to retrieve the data associated with the event
        target:
          type: string
        origin:
          $ref: '#/components/schemas/type_events_Origin'
        namespaces:
          type: array
          items:
            type: string
        topic:
          $ref: '#/components/schemas/type_events_EventTopic'
        payload:
          type: object
          additionalProperties:
            description: Any type
        deletedAt:
          type: string
          format: date-time
          description: Date the event was deleted
      required:
      - domain
      - context
      - topic
      - payload
      description: Properties used to create a new event
      title: CreateEventConfig
    type_commons_ProgramId:
      type: string
      description: Mapping Program ID
      title: ProgramId
    type_events_Event:
      oneOf:
      - type: object
        properties:
          topic:
            type: string
            enum:
            - agent:created
            description: 'Discriminator value: agent:created'
          domain:
            $ref: '#/components/schemas/type_events_Domain'
            description: The domain of the event
          context:
            $ref: '#/components/schemas/type_events_Context'
            description: The context of the event
          attributes:
            $ref: '#/components/schemas/type_events_EventAttributes'
            description: The attributes of the event
          callbackUrl:
            type: string
            description: The callback url to acknowledge the event
          dataUrl:
            type: string
            description: The url to retrieve the data associated with the event
          target:
            type: string
          origin:
            $ref: '#/components/schemas/type_events_Origin'
          namespaces:
            type: array
            items:
              type: string
          id:
            $ref: '#/components/schemas/type_commons_EventId'
          createdAt:
            type: string
            format: date-time
            description: Date the event was created
          deletedAt:
            type: string
            format: date-time
            description: Date the event was deleted
          acknowledgedAt:
            type: string
            format: date-time
            description: Date the event was acknowledged
          acknowledgedBy:
            type: string
            description: The actor (user or system) who acknowledged the event
          payload:
            type: object
            additionalProperties:
              description: Any type
        required:
        - topic
        - domain
        - context
        - id
        - createdAt
        - payload
      - type: object
        properties:
          topic:
            type: string
            enum:
            - agent:updated
            description: 'Discriminator value: agent:updated'
          domain:
            $ref: '#/components/schemas/type_events_Domain'
            description: The domain of the event
          context:
            $ref: '#/components/schemas/type_events_Context'
            description: The context of the event
          attributes:
            $ref: '#/components/schemas/type_events_EventAttributes'
            description: The attributes of the event
          callbackUrl:
            type: string
            description: The callback url to acknowledge the event
          dataUrl:
            type: string
            description: The url to retrieve the data associated with the event
          target:
            type: string
          origin:
            $ref: '#/components/schemas/type_events_Origin'
          namespaces:
            type: array
            items:
              type: string
          id:
            $ref: '#/components/schemas/type_commons_EventId'
          createdAt:
            type: string
            format: date-time
            description: Date the event was created
          deletedAt:
            type: string
            format: date-time
            description: Date the event was deleted
          acknowledgedAt:
            type: string
            format: date-time
            description: Date the event was acknowledged
          acknowledgedBy:
            type: string
            description: The actor (user or system) who acknowledged the event
          payload:
            type: object
            additionalProperties:
              description: Any type
        required:
        - topic
        - domain
        - context
        - id
        - createdAt
        - payload
      - type: object
        properties:
          topic:
            type: string
            enum:
            - agent:deleted
            description: 'Discriminator value: agent:deleted'
          domain:
            $ref: '#/components/schemas/type_events_Domain'
            description: The domain of the event
          context:
            $ref: '#/components/schemas/type_events_Context'
            description: The context of the event
          attributes:
            $ref: '#/components/schemas/type_events_EventAttributes'
            description: The attributes of the event
          callbackUrl:
            type: string
            description: The callback url to acknowledge the event
          dataUrl:
            type: string
            description: The url to retrieve the data associated with the event
          target:
            type: string
          origin:
            $ref: '#/components/schemas/type_events_Origin'
          namespaces:
            type: array
            items:
              type: string
          id:
            $ref: '#/components/schemas/type_commons_EventId'
          createdAt:
            type: string
            format: date-time
            description: Date the event was created
          deletedAt:
            type: string
            format: date-time
            description: Date the event was deleted
          acknowledgedAt:
            type: string
            format: date-time
            description: Date the event was acknowledged
          acknowledgedBy:
            type: string
            description: The actor (user or system) who acknowledged the event
          payload:
            type: object
            additionalProperties:
              description: Any type
        required:
        - topic
        - domain
        - context
        - id
        - createdAt
        - payload
      - type: object
        properties:
          topic:
            type: string
            enum:
            - space:created
            description: 'Discriminator value: space:created'
          domain:
            $ref: '#/components/schemas/type_events_Domain'
            description: The domain of the event
          context:
            $ref: '#/components/schemas/type_events_Context'
            description: The context of the event
          attributes:
            $ref: '#/components/schemas/type_events_EventAttributes'
            description: The attributes of the event
          callbackUrl:
            type: string
            description: The callback url to acknowledge the event
          dataUrl:
            type: string
            description: The url to retrieve the data associated with the event
          target:
            type: string
          origin:
            $ref: '#/components/schemas/type_events_Origin'
          namespaces:
            type: array
            items:
              type: string
          id:
            $ref: '#/components/schemas/type_commons_EventId'
          createdAt:
            type: string
            format: date-time
            description: Date the event was created
          deletedAt:
            type: string
            format: date-time
            description: Date the event was deleted
          acknowledgedAt:
            type: string
            format: date-time
            description: Date the event was acknowledged
          acknowledgedBy:
            type: string
            description: The actor (user or system) who acknowledged the event
          payload:
            type: object
            additionalProperties:
              description: Any type
        required:
        - topic
        - domain
        - context
        - id
        - createdAt
        - payload
      - type: object
        properties:
          topic:
            type: string
            enum:
            - space:updated
            description: 'Discriminator value: space:updated'
          domain:
            $ref: '#/components/schemas/type_events_Domain'
            description: The domain of the event
          context:
            $ref: '#/components/schemas/type_events_Context'
            description: The context of the event
          attributes:
            $ref: '#/components/schemas/type_events_EventAttributes'
            description: The attributes of the event
          callbackUrl:
            type: string
            description: The callback url to acknowledge the event
          dataUrl:
            type: string
            description: The url to retrieve the data associated with the event
          target:
            type: string
          origin:
            $ref: '#/components/schemas/type_events_Origin'
          namespaces:
            type: array
            items:
              type: string
          id:
            $ref: '#/components/schemas/type_commons_EventId'
          createdAt:
            type: string
            format: date-time
            description: Date the event was created
          deletedAt:
            type: string
            format: date-time
            description: Date the event was deleted
          acknowledgedAt:
            type: string
            format: date-time
            description: Date the event was acknowledged
          acknowledgedBy:
            type: string
            description: The actor (user or system) who acknowledged the event
          payload:
            type: object
            additionalProperties:
              description: Any type
        required:
        - topic
        - domain
        - context
        - id
        - createdAt
        - payload
      - type: object
        properties:
          topic:
            type: string
            enum:
            - space:deleted
            description: 'Discriminator value: space:deleted'
          domain:
            $ref: '#/components/schemas/type_events_Domain'
            description: The domain of the event
          context:
            $ref: '#/components/schemas/type_events_Context'
            description: The context of the event
          attributes:
            $ref: '#/components/schemas/type_events_EventAttributes'
            description: The attributes of the event
          callbackUrl:
            type: string
            description: The callback url to acknowledge the event
          dataUrl:
            type: string
            description: The url to retrieve the data associated with the event
          target:
            type: string
          origin:
            $ref: '#/components/schemas/type_events_Origin'
          namespaces:
            type: array
            items:
              type: string
          id:
            $ref: '#/components/schemas/type_commons_EventId'
          createdAt:
            type: string
            format: date-time
            description: Date the event was created
          deletedAt:
            type: string
            format: date-time
            description: Date the event was deleted
          acknowledgedAt:
            type: string
            format: date-time
            description: Date the event was acknowledged
          acknowledgedBy:
            type: string
            description: The actor (user or system) who acknowledged the event
          payload:
            type: object
            additionalProperties:
              description: Any type
        required:
        - topic
        - domain
        - context
        - id
        - createdAt
        - payload
      - type: object
        properties:
          topic:
            type: string
            enum:
            - space:archived
            description: 'Discriminator value: space:archived'
          domain:
            $ref: '#/components/schemas/type_events_Domain'
            description: The domain of the event
          context:
            $ref: '#/components/schemas/type_events_Context'
            description: The context of the event
          attributes:
            $ref: '#/components/schemas/type_events_EventAttributes'
            description: The attributes of the event
          callbackUrl:
            type: string
            description: The callback url to acknowledge the event
          dataUrl:
            type: string
            description: The url to retrieve the data associated with the event
          target:
            type: string
          origin:
            $ref: '#/components/schemas/type_events_Origin'
          namespaces:
            type: array
            items:
              type: string
          id:
            $ref: '#/components/schemas/type_commons_EventId'
          createdAt:
            type: string
            format: date-time
            description: Date the event was created
          deletedAt:
            type: string
            format: date-time
            description: Date the event was deleted
          acknowledgedAt:
            type: string
            format: date-time
            description: Date the event was acknowledged
          acknowledgedBy:
            type: string
            description: The actor (user or system) who acknowledged the event
          payload:
            type: object
            additionalProperties:
              description: Any type
        required:
        - topic
        - domain
        - context
        - id
        - createdAt
        - payload
      - type: object
        properties:
          topic:
            type: string
            enum:
            - space:expired
            description: 'Discriminator value: space:expired'
          domain:
            $ref: '#/components/schemas/type_events_Domain'
            description: The domain of the event
          context:
            $ref: '#/components/schemas/type_events_Context'
            description: The context of the event
          attributes:
            $ref: '#/components/schemas/type_events_EventAttributes'
            description: The attributes of the event
          callbackUrl:
            type: string
            description: The callback url to acknowledge the event
          dataUrl:
            type: string
            description: The url to retrieve the data associated with the event
          target:
            type: string
          origin:
            $ref: '#/components/schemas/type_events_Origin'
          namespaces:
            type: array
            items:
              type: string
          id:
            $ref: '#/components/schemas/type_commons_EventId'
          createdAt:
            type: string
            format: date-time
            description: Date the event was created
          deletedAt:
            type: string
            format: date-time
            description: Date the event was deleted
          acknowledgedAt:
            type: string
            format: date-time
            description: Date the event was acknowledged
          acknowledgedBy:
            type: string
            description: The actor (user or system) who acknowledged the event
          payload:
            type: object
            additionalProperties:
              description: Any type
        required:
        - topic
        - domain
        - context
        - id
        - createdAt
        - payload
      - type: object
        properties:
          topic:
            type: string
            enum:
            - space:guestAdded
            description: 'Discriminator value: space:guestAdded'
          domain:
            $ref: '#/components/schemas/type_events_Domain'
            description: The domain of the event
          context:
            $ref: '#/components/schemas/type_events_Context'
            description: The context of the event
          attributes:
            $ref: '#/components/schemas/type_events_EventAttributes'
            description: The attributes of the event
          callbackUrl:
            type: string
            description: The callback url to acknowledge the event
          dataUrl:
            type: string
            description: The url to retrieve the data associated with the event
          target:
            type: string
          origin:
            $ref: '#/components/schemas/type_events_Origin'
          namespaces:
            type: array
            items:
              type: string
          id:
            $ref: '#/components/schemas/type_commons_EventId'
          createdAt:
            type: string
            format: date-time
            description: Date the event was created
          deletedAt:
            type: string
            format: date-time
            description: Date the event was deleted
          acknowledgedAt:
            type: string
            format: date-time
            description: Date the event was acknowledged
          acknowledgedBy:
            type: string
            description: The actor (user or system) who acknowledged the event
          payload:
            type: object
            additionalProperties:
              description: Any type
        required:
        - topic
        - domain
        - context
        - id
        - createdAt
        - payload
      - type: object
        properties:
          topic:
            type: string
            enum:
            - space:guestRemoved
            description: 'Discriminator value: space:guestRemoved'
          domain:
            $ref: '#/components/schemas/type_events_Domain'
            description: The domain of the event
          context:
            $ref: '#/components/schemas/type_events_Context'
            description: The context of the event
          attributes:
            $ref: '#/components/schemas/type_events_EventAttributes'
            description: The attributes of the event
          callbackUrl:
            type: string
            description: The callback url to acknowledge the event
          dataUrl:
            type: string
            description: The url to retrieve the data associated with the event
          target:
            type: string
          origin:
            $ref: '#/components/schemas/type_events_Origin'
          namespaces:
            type: array
            items:
              type: string
          id:
            $ref: '#/components/schemas/type_commons_EventId'
          createdAt:
            type: string
            format: date-time
            description: Date the event was created
          deletedAt:
            type: string
            format: date-time
            description: Date the event was deleted
          acknowledgedAt:
            type: string
            format: date-time
            description: Date the event was acknowledged
          acknowledgedBy:
            type: string
            description: The actor (user or system) who acknowledged the event
          payload:
            type: object
            additionalProperties:
              description: Any type
        required:
        - topic
        - domain
        - context
        - id
        - createdAt
        - payload
      - type: object
        properties:
          topic:
            type: string
            enum:
            - document:created
     

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