openapi: 3.1.0
info:
  title: Bem Buckets Errors 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: Errors
  description: 'Retrieve terminal error events from workflow calls.


    Errors are events produced by function steps that failed during processing. A single workflow

    call may produce multiple error events if several steps fail independently.


    Errors and outputs from the same call are not mutually exclusive: a partially-completed

    workflow may have both.


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

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


        Returns error events produced by failed function calls within workflow executions.

        Non-error output events are excluded; use `GET /v3/outputs` to retrieve those.


        ## 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 errors 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: referenceIDSubstring
        in: query
        required: false
        description: Case-insensitive substring match against `referenceID`.
        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/ListErrorsResponseV3'
      tags:
      - Errors
  /v3/errors/{eventID}:
    get:
      operationId: v3-get-error
      summary: Get an Error
      description: '**Retrieve a single error event by ID.**


        Returns `404` if the event does not exist or if it is not an error event

        (use `GET /v3/outputs/{eventID}` for non-error events).'
      parameters:
      - name: eventID
        in: path
        required: true
        description: The unique identifier of the error event.
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEventResponseV3'
      tags:
      - Errors
components:
  schemas:
    ListErrorsResponseV3:
      type: object
      required:
      - errors
      - totalCount
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorEvent'
          description: Array of terminal error events.
        totalCount:
          type: integer
          description: The total number of results available.
    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
    ErrorEventResponseV3:
      type: object
      required:
      - error
      properties:
        error:
          allOf:
          - $ref: '#/components/schemas/ErrorEvent'
          description: The 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.
  securitySchemes:
    API Key:
      type: apiKey
      in: header
      name: x-api-key
      description: Authenticate using API Key in request header