Bem Calls API

openapi: 3.1.0
info:
  title: Bem Buckets Calls API
  version: 1.0.0
  description: "Buckets are named partitions of the knowledge graph within an\naccount+environment. Entities, mentions, and relations are scoped to a\nbucket so a single account+environment can host multiple isolated graphs\n— for example one per data source or workspace.\n\nEvery account+environment has exactly one **default** bucket, used by\nunscoped flows. The default bucket can be renamed but never deleted.\n\nUse these endpoints to create, list, fetch, rename, and delete buckets:\n\n- **`POST /v3/buckets`** creates a non-default bucket.\n- **`GET /v3/buckets`** lists buckets with cursor pagination\n  (`startingAfter` / `endingBefore` over `bucketID`).\n- **`PATCH /v3/buckets/{bucketID}`** updates `name` and/or `description`.\n- **`DELETE /v3/buckets/{bucketID}`** soft-deletes a bucket. A non-empty\n  bucket is rejected with `409 Conflict` unless `?cascade=true` is\n  passed; the default bucket can never be deleted."
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:
    FunctionCallCreateInputResponse:
      type: object
      properties:
        singleFile:
          $ref: '#/components/schemas/SingleFileInputResponse'
        batchFiles:
          $ref: '#/components/schemas/BatchFilesInputResponse'
    PayloadShapingEvent:
      type: object
      required:
      - eventID
      - referenceID
      - functionID
      - functionName
      - transformedContent
      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:
          - payload_shaping
        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.
        transformedContent:
          type: object
          unevaluatedProperties: {}
          description: 'The reshaped payload produced by applying the function''s JMESPath

            expressions to the input data.'
      description: 'Emitted by `payload_shaping` functions, which restructure JSON payloads

        using JMESPath expressions configured on the function. The shaped result

        is carried in `transformedContent`.'
      title: Payload Shaping Event
    FunctionCallResponseBase:
      type: object
      required:
      - functionCallID
      - functionID
      - functionName
      - type
      - referenceID
      - status
      - startedAt
      properties:
        functionCallID:
          type: string
          description: Unique identifier for this function call
        functionID:
          type: string
          description: ID of the function that was called
        functionName:
          type: string
          description: Name of the function that was called
        type:
          $ref: '#/components/schemas/FunctionType'
        referenceID:
          type: string
          description: User-provided reference ID for tracking
        status:
          $ref: '#/components/schemas/ActionStatus'
        functionVersionNum:
          type: integer
          description: Version number of the function
        activity:
          type: array
          items:
            type: object
            properties:
              displayName:
                type: string
              status:
                type: string
                enum:
                - pending
                - running
                - completed
                - failed
          description: Array of activity steps for this function call
        startedAt:
          type: string
          format: date-time
          description: The date and time this function call started.
        finishedAt:
          type: string
          format: date-time
          description: The date and time this function call finished. Absent while still running.
        sourceFunctionCallID:
          type: string
          description: ID of the function call that spawned this function call (for DAG reconstruction)
        sourceEventID:
          type: string
          description: ID of the event that spawned this function call (for DAG reconstruction). Nil for the root function call.
        workflowCallID:
          type: string
          description: ID of the workflow call this function call belongs to (top-level execution context)
        workflowNodeName:
          type: string
          description: Name of the workflow DAG call-site node this function call is executing. Absent for non-workflow calls and pre-migration rows.
        incomingDestinationName:
          type: string
          description: The labelled outlet on the upstream node that routed execution to this call. Absent for root calls, unlabelled edges, and pre-migration rows.
        inputType:
          type: string
          description: Input type for single file input (set when there's exactly one file input)
        s3URL:
          type: string
          description: Presigned S3 URL for single file input (set when there's exactly one file input)
        inputs:
          type: array
          items:
            $ref: '#/components/schemas/FunctionCallInputResponse'
          description: Array of all file inputs with their S3 URLs
    CallsListResponseV3:
      type: object
      properties:
        calls:
          type: array
          items:
            $ref: '#/components/schemas/CallV3'
        totalCount:
          type: integer
          description: The total number of results available.
        error:
          type: string
          description: Error message if the calls listing failed.
    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
    AnyType:
      anyOf:
      - type: object
        unevaluatedProperties: {}
      - type: array
        items: {}
      - type: string
      - type: number
      - type: integer
      - type: boolean
      - type: 'null'
    AnalyzeEvent:
      type: object
      required:
      - eventID
      - referenceID
      - functionID
      - functionName
      - transformedContent
      - invalidProperties
      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:
          - analyze
        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.
        transformationID:
          anyOf:
          - type: string
          - type: 'null'
          description: Unique ID for each transformation output generated by bem following Segment's KSUID conventions.
        transformedContent:
          type: object
          unevaluatedProperties: {}
          description: The extracted content of the input. The structure of this object is defined by the function's `outputSchema`.
        invalidProperties:
          type: array
          items:
            type: string
          description: List of properties that were invalid in the input.
        s3URL:
          anyOf:
          - type: string
          - type: 'null'
          description: Presigned S3 URL of the input file that was analyzed.
        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

            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: 'Emitted by functions of the legacy `analyze` type (the vision path predecessor of

        `extract`). Carries the extracted JSON along with per-field bounding-box metadata

        identifying the document regions each value was extracted from.'
      title: Analyze Event
    SplitItemEvent:
      type: object
      required:
      - eventID
      - referenceID
      - functionID
      - functionName
      - outputType
      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_item
        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:
            collectionReferenceID:
              type: string
            itemCount:
              type: integer
            itemOffset:
              type: integer
            s3URL:
              type: string
        semanticPageOutput:
          type: object
          properties:
            collectionReferenceID:
              type: string
            pageCount:
              type: integer
            itemCount:
              type: integer
            itemOffset:
              type: integer
            itemClass:
              type: string
            itemClassCount:
              type: integer
            itemClassOffset:
              type: integer
            pageStart:
              type: integer
            pageEnd:
              type: integer
            s3URL:
              type: string
      title: Split Item Event
    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.
    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'
    CallTraceResponseV3:
      type: object
      properties:
        trace:
          $ref: '#/components/schemas/CallTrace'
        error:
          type: string
          description: Error message if trace retrieval failed.
      description: 'Response from `GET /v3/calls/{callID}/trace`.


        Contains the full execution DAG as flat arrays of function calls and events. Reconstruct the

        graph using `FunctionCallResponseBase.sourceEventID` (the event that spawned each function call)

        and each event''s `functionCallID` (the function call that emitted it).'
    ActionStatus:
      type: string
      enum:
      - pending
      - running
      - completed
      - failed
      description: The status of the action.
    CallGetResponseV3:
      type: object
      properties:
        call:
          $ref: '#/components/schemas/CallV3'
        error:
          type: string
          description: Error message if the call retrieval failed, or if the call itself failed when using `wait=true`.
    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.
    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.
    JoinEvent:
      type: object
      required:
      - eventID
      - referenceID
      - functionID
      - functionName
      - joinType
      - transformedContent
      - invalidProperties
      - items
      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:
          - join
        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.
 

# --- 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