Bem Calls API

openapi: 3.2.0
info:
  title: Bem Calls API
  version: 1.0.0
  description: 'The Calls API provides a unified interface for invoking both **Workflows** and **Functions**.


    Use this API when you want to:

    - Execute a complete workflow that chains multiple functions together

    - Call a single function directly without defining a workflow

    - Submit batch requests with multiple inputs in a single API call

    - Track execution status using call reference IDs


    **Key Difference**: Calls vs Function Calls

    - **Calls API** (`/v3/calls`): High-level API for invoking workflows or functions by name/ID. Supports batch processing and workflow orchestration.

    - **Function Calls API** (`/v3/functions/{functionName}/call`): Direct function invocation with function-type-specific arguments. Better for granular control over individual function calls.'
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: Calls
  description: 'The Calls API provides a unified interface for invoking both **Workflows** and **Functions**.


    Use this API when you want to:

    - Execute a complete workflow that chains multiple functions together

    - Call a single function directly without defining a workflow

    - Submit batch requests with multiple inputs in a single API call

    - Track execution status using call reference IDs


    **Key Difference**: Calls vs Function Calls

    - **Calls API** (`/v3/calls`): High-level API for invoking workflows or functions by name/ID. Supports batch processing and workflow orchestration.

    - **Function Calls API** (`/v3/functions/{functionName}/call`): Direct function invocation with function-type-specific arguments. Better for granular control over individual function calls.'
paths:
  /v3/calls:
    get:
      operationId: v3-list-calls
      summary: List Calls
      description: '**List workflow calls with filtering and pagination.**


        Returns calls created via `POST /v3/workflows/{workflowName}/call`.


        ## Filtering


        - `callIDs`: Specific call identifiers

        - `referenceIDs`: Your custom reference IDs

        - `workflowIDs` / `workflowNames`: Filter by workflow


        ## Pagination


        Use `startingAfter` and `endingBefore` cursors with a default limit of 50.'
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      - name: callIDs
        in: query
        required: false
        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: referenceIDs
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
          minItems: 1
        explode: false
      - name: statuses
        in: query
        required: false
        description: Filter by one or more statuses.
        schema:
          type: array
          items:
            type: string
            enum:
            - pending
            - running
            - completed
            - failed
          minItems: 1
        explode: false
      - name: referenceIDSubstring
        in: query
        required: false
        description: Case-insensitive substring match against `callReferenceID`.
        schema:
          type: string
        explode: false
      - 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/CallsListResponseV3'
      tags:
      - Calls
  /v3/calls/{callID}:
    get:
      operationId: v3-get-call
      summary: Get a Call
      description: '**Retrieve a workflow call by ID.**


        Returns the full call object including status, workflow details, terminal outputs,

        and terminal errors. `outputs` and `errors` are both populated once the call finishes —

        they are not mutually exclusive (a partially-completed workflow may have both).


        ## Status


        | Status | Description |

        |--------|-------------|

        | `pending` | Queued, not yet started |

        | `running` | Currently executing |

        | `completed` | All enclosed function calls finished without errors |

        | `failed` | One or more enclosed function calls produced an error event |


        Poll this endpoint or configure a webhook subscription to detect completion.'
      parameters:
      - name: callID
        in: path
        required: true
        description: The unique identifier of the call.
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallGetResponseV3'
      tags:
      - Calls
  /v3/calls/{callID}/trace:
    get:
      operationId: v3-get-call-trace
      summary: Get Call Trace
      description: '**Retrieve the full execution trace of a workflow call.**


        Returns all function calls and events emitted during the call as flat arrays.

        The DAG can be reconstructed using `FunctionCallResponseBase.sourceEventID`

        (the event that spawned each function call) and each event''s `functionCallID`

        (the function call that emitted it).


        ## Graph structure


        - A function call with no `sourceEventID` is the root.

        - An event''s `functionCallID` points to the function call that emitted it.

        - A function call''s `sourceEventID` points to the event that triggered it.

        - `workflowNodeName` identifies the DAG node; `incomingDestinationName` identifies

        the labelled outlet used to reach this call (absent for unlabelled edges and root calls).


        The trace is available as soon as the call exists and grows as execution proceeds.'
      parameters:
      - name: callID
        in: path
        required: true
        description: The unique identifier of the call.
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallTraceResponseV3'
      tags:
      - Calls
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.
    BatchFilesInputItemResponse:
      type: object
      properties:
        inputType:
          type: string
          description: Input type of the file
        itemReferenceID:
          type: string
          description: Item reference ID
        s3URL:
          type: string
          description: Presigned S3 URL for the file
    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
    BatchFilesInputResponse:
      type: object
      properties:
        inputs:
          type: array
          items:
            $ref: '#/components/schemas/BatchFilesInputItemResponse'
    AnyType:
      anyOf:
      - type: object
        unevaluatedProperties: {}
      - type: array
        items: {}
      - type: string
      - type: number
      - type: integer
      - type: boolean
      - type: 'null'
    CallV3:
      type: object
      required:
      - callID
      - createdAt
      - outputs
      - errors
      - url
      - traceUrl
      properties:
        callID:
          type: string
          description: Unique identifier of the call.
        status:
          type: string
          enum:
          - pending
          - running
          - completed
          - failed
          description: Status of call.
        createdAt:
          type: string
          format: date-time
          description: The date and time the call was created.
        finishedAt:
          type: string
          format: date-time
          description: The date and time the call finished. Only set once status is `completed` or `failed`.
        workflowID:
          type: string
          description: Unique identifier of the workflow.
        workflowName:
          type: string
          description: Name of the workflow.
        workflowVersionNum:
          type: integer
          description: Version number of the workflow.
        callReferenceID:
          type: string
          description: Your reference ID for this call, propagated from the original request.
        outputs:
          type: array
          items:
            $ref: '#/components/schemas/EventV3'
          description: 'Terminal non-error outputs of this call: primary events (non-split-collection) that did not

            trigger any downstream function calls. Workflow calls are not atomic — `outputs` and `errors`

            may both be non-empty if some enclosed function calls succeeded and others failed.


            Each element is a polymorphic event object; inspect `eventType` to determine the type.

            Retrieve individual outputs via `GET /v3/outputs/{eventID}`.'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorEvent'
          description: 'Terminal error events of this call. Workflow calls are not atomic — `errors` and `outputs`

            may both be non-empty if some enclosed function calls succeeded and others failed.


            Retrieve individual errors via `GET /v3/errors/{eventID}`.'
        input:
          allOf:
          - $ref: '#/components/schemas/FunctionCallCreateInputResponse'
          description: Input to the main function call.
        url:
          type: string
          description: 'Hint URL for retrieving this call: `GET /v3/calls/{callID}`.'
        traceUrl:
          type: string
          description: 'Hint URL for the full execution trace: `GET /v3/calls/{callID}/trace`.'
      description: 'A workflow call returned by the V3 API.


        Compared to the V2 `Call` model:

        - Terminal outputs are split into `outputs` (non-error events) and `errors` (error events)

        - `callType` and function-scoped fields are removed — V3 calls are always workflow calls

        - The deprecated `functionCalls` field is removed (use `GET /v3/calls/{callID}/trace`)

        - `url` and `traceUrl` hint fields are included for resource discovery'
    CallTrace:
      type: object
      required:
      - functionCalls
      - events
      properties:
        functionCalls:
          type: array
          items:
            $ref: '#/components/schemas/FunctionCallResponseBase'
          description: All function calls executed within this call.
        events:
          type: array
          items: {}
          description: All events emitted within this call, polymorphic by eventType.
      description: 'Full execution DAG of a call as flat arrays. Reconstruct the graph using

        FunctionCallResponseBase.sourceEventID and each event''s functionCallID.'
    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 f

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