Bem Outputs API

openapi: 3.2.0
info:
  title: Bem Outputs API
  version: 1.0.0
  description: 'Retrieve terminal non-error output events from workflow calls.


    Outputs are events produced by successful terminal function steps — steps that completed

    without errors and did not spawn further downstream function calls. A single workflow call

    may produce multiple outputs (e.g. from a split-then-transform pipeline).


    Outputs and errors from the same call are not mutually exclusive: a partially-completed

    workflow may have both.


    Use `GET /v3/outputs` to list outputs across calls, or `GET /v3/outputs/{eventID}` to

    retrieve a specific output. To get outputs scoped to a single call, filter by `callIDs`.'
servers:
- url: https://api.bem.ai
  description: US Region API
  variables: {}
- url: https://api.eu1.bem.ai
  description: EU Region API
  variables: {}
security:
- API Key: []
tags:
- name: Outputs
  description: 'Retrieve terminal non-error output events from workflow calls.


    Outputs are events produced by successful terminal function steps — steps that completed

    without errors and did not spawn further downstream function calls. A single workflow call

    may produce multiple outputs (e.g. from a split-then-transform pipeline).


    Outputs and errors from the same call are not mutually exclusive: a partially-completed

    workflow may have both.


    Use `GET /v3/outputs` to list outputs across calls, or `GET /v3/outputs/{eventID}` to

    retrieve a specific output. To get outputs scoped to a single call, filter by `callIDs`.'
paths:
  /v3/outputs:
    get:
      operationId: v3-list-outputs
      summary: List Outputs
      description: '**List terminal non-error output events.**


        Returns events that represent successful terminal outputs — primary events

        (non-split-collection) that did not trigger any downstream function calls.

        Error events are excluded; use `GET /v3/errors` to retrieve those.


        ## Intermediate Events


        By default, intermediate events (those that spawned a downstream function call in a

        multi-step workflow) are excluded. Pass `includeIntermediate=true` to include them.


        ## Filtering


        Filter by call, workflow, function, or reference ID. Multiple filters are ANDed together.'
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      - name: callIDs
        in: query
        required: false
        description: Filter to outputs from specific calls.
        schema:
          type: array
          items:
            type: string
          minItems: 1
        explode: false
      - name: workflowIDs
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
          minItems: 1
        explode: false
      - name: workflowNames
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
          minItems: 1
        explode: false
      - name: functionIDs
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
          minItems: 1
        explode: false
      - name: functionNames
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
          minItems: 1
        explode: false
      - name: referenceIDs
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
          minItems: 1
        explode: false
      - name: eventIDs
        in: query
        required: false
        description: Filter to specific output events by their event IDs (KSUIDs).
        schema:
          type: array
          items:
            type: string
          minItems: 1
        explode: false
      - name: eventTypes
        in: query
        required: false
        description: Filter to specific non-error output event types, e.g. `classify` or `extract`.
        schema:
          type: array
          items:
            type: string
          minItems: 1
        explode: false
      - name: transformationIDs
        in: query
        required: false
        description: 'Filter by legacy transformation IDs. Provided for backwards compatibility

          with clients migrating from `/v1-beta/transformations`.'
        schema:
          type: array
          items:
            type: string
          minItems: 1
        explode: false
      - name: functionVersionNums
        in: query
        required: false
        description: Filter to specific function version numbers.
        schema:
          type: array
          items:
            type: integer
          minItems: 1
        explode: false
      - name: referenceIDSubstring
        in: query
        required: false
        description: Case-insensitive substring match against `referenceID`.
        schema:
          type: string
        explode: false
      - name: isLabelled
        in: query
        required: false
        description: 'If `true`, only outputs with a corrected (labelled) payload.

          If `false`, only outputs that are not labelled. If omitted, no filter is applied.'
        schema:
          type: boolean
      - name: isRegression
        in: query
        required: false
        description: 'If `true`, only regression-marked outputs. If `false`, only non-regression outputs.

          If omitted, no filter is applied.


          Note: clients migrating from `/v1-beta/transformations` should pass `isRegression=false`

          explicitly to preserve the legacy default (regressions hidden unless explicitly requested).'
        schema:
          type: boolean
      - name: includeIntermediate
        in: query
        required: false
        description: 'When `true`, includes intermediate events (those that spawned a downstream function call).

          Default: `false`.'
        schema:
          type: boolean
      - name: sortOrder
        in: query
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
      - name: startingAfter
        in: query
        required: false
        schema:
          type: string
      - name: endingBefore
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListOutputsResponseV3'
      tags:
      - Outputs
  /v3/outputs/{eventID}:
    get:
      operationId: v3-get-output
      summary: Get an Output
      description: '**Retrieve a single output event by ID.**


        Fetches any non-error event by its `eventID`. Returns `404` if the event does not exist

        or if it is an error event (use `GET /v3/errors/{eventID}` for those).'
      parameters:
      - name: eventID
        in: path
        required: true
        description: The unique identifier of the output event.
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutputResponseV3'
      tags:
      - Outputs
components:
  schemas:
    SendEventS3Output:
      type: object
      required:
      - bucketName
      - key
      properties:
        bucketName:
          type: string
          description: Name of the S3 bucket the payload was written to.
        key:
          type: string
          description: Object key under which the payload was stored.
      description: Metadata returned when a Send function delivers to an S3 bucket.
    SendEventWebhookOutput:
      type: object
      required:
      - httpStatusCode
      - httpResponseBody
      properties:
        httpStatusCode:
          type: integer
          description: HTTP status code returned by the webhook endpoint.
        httpResponseBody:
          type: string
          description: Raw HTTP response body returned by the webhook endpoint.
      description: Metadata returned when a Send function delivers to a webhook.
    SendDestinationType:
      type: string
      enum:
      - webhook
      - s3
      - google_drive
      description: Destination type for a Send function.
    OutputResponseV3:
      type: object
      required:
      - output
      properties:
        output:
          allOf:
          - $ref: '#/components/schemas/EventV3'
          description: The output event. Polymorphic by `eventType`.
    ExtractEvent:
      type: object
      required:
      - eventID
      - referenceID
      - functionID
      - functionName
      - transformedContent
      - itemOffset
      - itemCount
      properties:
        functionCallTryNumber:
          type: integer
          description: The attempt number of the function call that created this event. 1 indexed.
        eventID:
          type: string
          description: Unique ID generated by bem to identify the event.
        createdAt:
          type: string
          format: date-time
          description: Timestamp indicating when the event was created.
        referenceID:
          type: string
          description: The unique ID you use internally to refer to this data point, propagated from the original function input.
        inboundEmail:
          allOf:
          - $ref: '#/components/schemas/EventInboundEmail'
          description: The inbound email that triggered this event.
        metadata:
          type: object
          properties:
            durationFunctionToEventSeconds:
              type: number
        eventType:
          type: string
          enum:
          - extract
        functionCallID:
          type: string
          description: Unique identifier of function call that this event is associated with.
        functionID:
          type: string
          description: Unique identifier of function that this event is associated with.
        functionName:
          type: string
          description: Unique name of function that this event is associated with.
        functionVersionNum:
          type: integer
          description: Version number of function that this event is associated with.
        callID:
          type: string
          description: Unique identifier of workflow call that this event is associated with.
        workflowID:
          type: string
          description: Unique identifier of workflow that this event is associated with.
        workflowName:
          type: string
          description: Name of workflow that this event is associated with.
        workflowVersionNum:
          type: integer
          description: Version number of workflow that this event is associated with.
        inputType:
          $ref: '#/components/schemas/InputType'
        transformationID:
          type: string
          description: Unique ID for each transformation output generated by bem following Segment's KSUID conventions.
        s3URL:
          anyOf:
          - type: string
          - type: 'null'
          description: Presigned S3 URL for the input content uploaded to S3.
        inputs:
          anyOf:
          - type: array
            items:
              type: object
              properties:
                inputType:
                  anyOf:
                  - type: string
                  - type: 'null'
                inputContent:
                  anyOf:
                  - type: string
                  - type: 'null'
                jsonInputContent:
                  anyOf:
                  - type: object
                    unevaluatedProperties: {}
                  - type: 'null'
                s3URL:
                  anyOf:
                  - type: string
                  - type: 'null'
          - type: 'null'
          description: Array of transformation inputs with their types and S3 URLs.
        transformedContent:
          type: object
          unevaluatedProperties: {}
          description: The transformed content of the input. The structure of this object is defined by the function configuration.
        correctedContent:
          anyOf:
          - type: object
            properties:
              output:
                type: array
                items:
                  $ref: '#/components/schemas/AnyType'
          - $ref: '#/components/schemas/AnyType'
          description: Corrected feedback provided for fine-tuning purposes.
        invalidProperties:
          type: array
          items:
            type: string
          description: List of properties that were invalid in the input.
        itemOffset:
          type: integer
          description: The offset of the first item that was transformed. Used for batch transformations to indicate which item in the batch this event corresponds to.
        itemCount:
          type: integer
          description: The number of items that were transformed. Used for batch transformations to indicate how many items were transformed.
        fieldBoundingBoxes:
          type: object
          unevaluatedProperties: {}
          description: 'Per-field bounding boxes. A JSON object mapping RFC 6901 JSON Pointer paths (e.g. `"/invoiceNumber"`,

            `"/items/0/price"`) to the document regions from which each extracted value was sourced.'
        fieldConfidences:
          type: object
          unevaluatedProperties:
            type: number
            format: float
          description: 'Per-field confidence scores. A JSON object mapping RFC 6901 JSON Pointer paths (e.g. `"/invoiceNumber"`)

            to float values in the range [0, 1] indicating the model''s confidence in each extracted field value.'
        avgConfidence:
          anyOf:
          - type: number
            format: float
          - type: 'null'
          description: Average confidence score across all extracted fields, in the range [0, 1].
      description: 'V3 event variants that do not exist in the shared `Event` union.


        `ExtractEvent` and `ClassifyEvent` are emitted only by V3-era function types

        (`extract` and `classify`). The shared `Event` union in `specs/events/models.tsp`

        predates these types and continues to describe V2 / V1-alpha responses verbatim;

        V3 response payloads add the new variants via the `EventV3` union below while

        keeping every shared variant intact for backward compatibility.'
      title: Extract Event
    AnyType:
      anyOf:
      - type: object
        unevaluatedProperties: {}
      - type: array
        items: {}
      - type: string
      - type: number
      - type: integer
      - type: boolean
      - type: 'null'
    EvaluationEvent:
      type: object
      required:
      - eventID
      - referenceID
      - functionID
      - functionName
      - transformId
      - evaluationVersion
      - result
      - status
      properties:
        functionCallTryNumber:
          type: integer
          description: The attempt number of the function call that created this event. 1 indexed.
        eventID:
          type: string
          description: Unique ID generated by bem to identify the event.
        createdAt:
          type: string
          format: date-time
          description: Timestamp indicating when the event was created.
        referenceID:
          type: string
          description: The unique ID you use internally to refer to this data point, propagated from the original function input.
        inboundEmail:
          allOf:
          - $ref: '#/components/schemas/EventInboundEmail'
          description: The inbound email that triggered this event.
        metadata:
          type: object
          properties:
            durationFunctionToEventSeconds:
              type: number
        eventType:
          type: string
          enum:
          - evaluation
        functionCallID:
          type: string
          description: Unique identifier of function call that this event is associated with.
        functionID:
          type: string
          description: Unique identifier of function that this event is associated with.
        functionName:
          type: string
          description: Unique name of function that this event is associated with.
        functionVersionNum:
          type: integer
          description: Version number of function that this event is associated with.
        callID:
          type: string
          description: Unique identifier of workflow call that this event is associated with.
        workflowID:
          type: string
          description: Unique identifier of workflow that this event is associated with.
        workflowName:
          type: string
          description: Name of workflow that this event is associated with.
        workflowVersionNum:
          type: integer
          description: Version number of workflow that this event is associated with.
        transformId:
          type: string
          description: Unique ID of the transformation that was evaluated.
        evaluationVersion:
          type: string
          description: Version identifier of the evaluation logic that produced this result.
        result:
          type: object
          unevaluatedProperties: {}
          description: 'Evaluator output. Shape depends on `evaluationVersion` and includes

            confidence scores, per-field hallucination flags, and relevance metrics.'
        status:
          type: string
          enum:
          - success
          - failed
          description: Terminal status of the evaluation run.
        errorMessage:
          type: string
          description: Failure reason populated when `status` is `failed`.
      description: 'Emitted when a function-accuracy evaluation completes for a transformation.

        Evaluations are scheduled by `POST /v3/eval` and run asynchronously; this

        event reports the terminal result.'
      title: Evaluation Event
    JoinEventItem:
      type: object
      required:
      - itemReferenceID
      - itemOffset
      - itemCount
      properties:
        itemReferenceID:
          type: string
          description: The unique ID you use internally to refer to this data point.
        itemOffset:
          type: integer
          description: The offset of the first item that was transformed. Used for batch transformations to indicate which item in the batch this event corresponds to.
        itemCount:
          type: integer
          description: The number of items that were transformed.
        s3URL:
          type: string
          description: The presigned S3 URL of the file that was joined.
    SplitCollectionEvent:
      type: object
      required:
      - eventID
      - referenceID
      - functionID
      - functionName
      - outputType
      - printPageOutput
      - semanticPageOutput
      properties:
        functionCallTryNumber:
          type: integer
          description: The attempt number of the function call that created this event. 1 indexed.
        eventID:
          type: string
          description: Unique ID generated by bem to identify the event.
        createdAt:
          type: string
          format: date-time
          description: Timestamp indicating when the event was created.
        referenceID:
          type: string
          description: The unique ID you use internally to refer to this data point, propagated from the original function input.
        inboundEmail:
          allOf:
          - $ref: '#/components/schemas/EventInboundEmail'
          description: The inbound email that triggered this event.
        metadata:
          type: object
          properties:
            durationFunctionToEventSeconds:
              type: number
        eventType:
          type: string
          enum:
          - split_collection
        functionCallID:
          type: string
          description: Unique identifier of function call that this event is associated with.
        functionID:
          type: string
          description: Unique identifier of function that this event is associated with.
        functionName:
          type: string
          description: Unique name of function that this event is associated with.
        functionVersionNum:
          type: integer
          description: Version number of function that this event is associated with.
        callID:
          type: string
          description: Unique identifier of workflow call that this event is associated with.
        workflowID:
          type: string
          description: Unique identifier of workflow that this event is associated with.
        workflowName:
          type: string
          description: Name of workflow that this event is associated with.
        workflowVersionNum:
          type: integer
          description: Version number of workflow that this event is associated with.
        outputType:
          type: string
          enum:
          - print_page
          - semantic_page
        printPageOutput:
          type: object
          properties:
            itemCount:
              type: integer
            items:
              type: array
              items:
                type: object
                properties:
                  itemReferenceID:
                    type: string
                  itemOffset:
                    type: integer
                  s3URL:
                    type: string
        semanticPageOutput:
          type: object
          properties:
            pageCount:
              type: integer
            itemCount:
              type: integer
            items:
              type: array
              items:
                type: object
                properties:
                  itemReferenceID:
                    type: string
                  itemOffset:
                    type: integer
                  itemClass:
                    type: string
                  itemClassCount:
                    type: integer
                  itemClassOffset:
                    type: integer
                  pageStart:
                    type: integer
                  pageEnd:
                    type: integer
                  s3URL:
                    type: string
      title: Split Collection Event
    SendEvent:
      type: object
      required:
      - eventID
      - referenceID
      - functionID
      - functionName
      - deliveryStatus
      - destinationType
      properties:
        functionCallTryNumber:
          type: integer
          description: The attempt number of the function call that created this event. 1 indexed.
        eventID:
          type: string
          description: Unique ID generated by bem to identify the event.
        createdAt:
          type: string
          format: date-time
          description: Timestamp indicating when the event was created.
        referenceID:
          type: string
          description: The unique ID you use internally to refer to this data point, propagated from the original function input.
        inboundEmail:
          allOf:
          - $ref: '#/components/schemas/EventInboundEmail'
          description: The inbound email that triggered this event.
        metadata:
          type: object
          properties:
            durationFunctionToEventSeconds:
              type: number
        eventType:
          type: string
          enum:
          - send
        functionCallID:
          type: string
          description: Unique identifier of function call that this event is associated with.
        functionID:
          type: string
          description: Unique identifier of function that this event is associated with.
        functionName:
          type: string
          description: Unique name of function that this event is associated with.
        functionVersionNum:
          type: integer
          description: Version number of function that this event is associated with.
        callID:
          type: string
          description: Unique identifier of workflow call that this event is associated with.
        workflowID:
          type: string
          description: Unique identifier of workflow that this event is associated with.
        workflowName:
          type: string
          description: Name of workflow that this event is associated with.
        workflowVersionNum:
          type: integer
          description: Version number of workflow that this event is associated with.
        deliveryStatus:
          allOf:
          - $ref: '#/components/schemas/SendDeliveryStatus'
          description: Whether the payload was successfully delivered or the send node was skipped.
        destinationType:
          allOf:
          - $ref: '#/components/schemas/SendDestinationType'
          description: The type of destination the payload was sent to.
        deliveredContent:
          type: object
          unevaluatedProperties: {}
          description: 'The full protocol event JSON that was delivered — identical to what subscription

            publish would deliver for the same event. For ad-hoc calls with a JSON file input,

            contains the raw input JSON. For ad-hoc calls with a binary file input, contains

            {"s3URL": "<presigned-url>"}.'
        webhookOutput:
          allOf:
          - $ref: '#/components/schemas/SendEventWebhookOutput'
          description: Populated when destinationType is "webhook".
        s3Output:
          allOf:
          - $ref: '#/components/schemas/SendEventS3Output'
          description: Populated when destinationType is "s3".
        googleDriveOutput:
          allOf:
          - $ref: '#/components/schemas/SendEventGoogleDriveOutput'
          description: Populated when destinationType is "google_drive".
      title: Send Event
    ErrorEvent:
      type: object
      required:
      - eventID
      - referenceID
      - functionID
      - functionName
      - message
      properties:
        functionCallTryNumber:
          type: integer
          description: The attempt number of the function call that created this event. 1 indexed.
        eventID:
          type: string
          description: Unique ID generated by bem to identify the event.
        createdAt:
          type: string
          format: date-time
          description: Timestamp indicating when the event was created.
        referenceID:
          type: string
          description: The unique ID you use internally to refer to this data point, propagated from the original function input.
        inboundEmail:
          allOf:
          - $ref: '#/components/schemas/EventInboundEmail'
          description: The inbound email that triggered this event.
        metadata:
          type: object
          properties:
            durationFunctionToEventSeconds:
              type: number
        eventType:
          type: string
          enum:
          - error
        functionCallID:
          type: string
          description: Unique identifier of function call that this event is associated with.
        functionID:
          type: string
          description: Unique identifier of function that this event is associated with.
        functionName:
          type: string
          description: Unique name of function that this event is associated with.
        functionVersionNum:
          type: integer
          description: Version number of function that this event is associated with.
        callID:
          type: string
          description: Unique identifier of workflow call that this event is associated with.
        workflowID:
          type: string
          description: Unique identifier of workflow that this event is associated with.
        workflowName:
          type: string
          description: Name of workflow that this event is associated with.
        workflowVersionNum:
          type: integer
          description: Version number of workflow that this event is associated with.
        message:
          type: string
          description: Error message.
        kind:
          type: string
          description: 'Open, extensible error-kind label for typed transformation errors. The

            platform emits these as plain strings and the set grows over time, so

            clients must accept unknown values. For render functions the known kinds

            are `render_source_fetch`, `render_template_fetch`,

            `render_image_unresolved`, `render_validation`, `render_exception`,

            `render_upload`, and `render_contract`. Omitted for historical events

            that pre-date the kind column and for non-transform errors.'
      title: Error Event
    EventInboundEmail:
      type: object
      required:
      - to
      - from
      - subject
      properties:
        to:
          type: string
          description: The email address of the recipient.
        deliveredTo:
          type: string
          description: The email address of the original intended recipient if the email itself was forwarded.
        from:
          type: string
          description: The email address of the sender.
        subject:
          type: string
          description: The subject of the email.
    EventV3:
      type: object
      oneOf:
      - $ref: '#/components/schemas/TransformEvent'
      - $ref: '#/components/schemas/ExtractEvent'
      - $ref: '#/components/schemas/ParseEvent'
      - $ref: '#/components/schemas/AnalyzeEvent'
      - $ref: '#/components/schemas/RouteEvent'
      - $ref: '#/components/schemas/ClassifyEvent'
      - $ref: '#/components/schemas/SplitCollectionEvent'
      - $ref: '#/components/schemas/SplitItemEvent'
      - $ref: '#/components/schemas/ErrorEvent'
      - $ref: '#/components/schemas/JoinEvent'
      - $ref: '#/components/schemas/EnrichEvent'
      - $ref: '#/components/schemas/PayloadShapingEvent'
      - $ref: '#/components/schemas/EvaluationEvent'
      - $ref: '#/components/schemas/collectionProcessingEvent'
      - $ref: '#/components/schemas/SendEvent'
      - $ref: '#/components/schemas/RenderEvent'
      discriminator:
        propertyName: eventType
        mapping:
          transform: '#/components/schemas/TransformEvent'
          extract: '#/components/schemas/ExtractEvent'
          parse: '#/components/schemas/ParseEvent'
          analyze: '#/components/schemas/AnalyzeEvent'
          route: '#/components/schemas/RouteEvent'
          classify: '#/components/schemas/ClassifyEvent'
          split_collection: '#/components/schemas/SplitCollectionEvent'
          split_item: '#/components/schemas/SplitItemEvent'
          error: '#/components/schemas/ErrorEvent'
          join: '#/components/schemas/JoinEvent'
          enrich: '#/components/schemas/EnrichEvent'
          payload_shaping: '#/components/schemas/PayloadShapingEvent'
          evaluation: '#/components/schemas/EvaluationEvent'
          collection_processing: '#/components/schemas/collectionProcessingEvent'
          send: '#/components/schemas/SendEvent'
          render: '#/components/schemas/RenderEvent'
      description: 'V3 read-side event union. Superset of the shared `Event` union: it contains

        every shared variant verbatim (backward compatible) and adds the V3-only

        `extract`, `parse`, `classify`, `analyze`, `payload_shaping`, and

        `evaluation` variants. This is also the union delivered as the body of

        outbound webhook payloads.'
    EnrichEvent:
      type: object
      required:
      - eventID
      - referenceID
      - functionID
      - functionName
      - enrichedContent
      properties:
        functionCallTryNumber:
          type: integer
          description: The attempt number of the function call that created this event. 1 indexed.
        eventID:
          type: string
          description: Unique ID generated by bem to identify the event.
        createdAt:
          type: string
          format: date-time
          description: Timestamp indicating when the event was created.
        referenceID:
          type: string
          description: The unique ID you use internally to refer to this data point, propagated from the original function input.
        inboundEmail:
          allOf:
          - $ref: '#/components/schemas/EventInbo

# --- truncated at 32 KB (71 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bem/refs/heads/main/openapi/bem-outputs-api-openapi.yml