Bem Functions API

openapi: 3.1.0
info:
  title: Bem Buckets Functions 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: Functions
  description: 'Functions are the core building blocks of data transformation in Bem. Each function type serves a specific purpose:


    - **Extract**: Extract structured JSON data from unstructured documents (PDFs, emails, images, spreadsheets), with optional layout-aware bounding-box extraction

    - **Route**: Direct data to different processing paths based on conditions

    - **Split**: Break multi-page documents into individual pages for parallel processing

    - **Join**: Combine outputs from multiple function calls into a single result

    - **Parse**: Render documents into a navigable structure of page-aware sections, named entities, and relationships — designed to be walked by an LLM agent via the [File System API](/api/v3/file-system) (`POST /v3/fs`). Two toggles, both `true` by default: `extractEntities` controls per-document entity and relationship extraction; `linkAcrossDocuments` merges entities into one canonical record per real-world thing across the environment, populating cross-document memory.

    - **Payload Shaping**: Transform and restructure data using JMESPath expressions

    - **Enrich**: Enhance data with semantic search against collections

    - **Send**: Deliver workflow outputs to downstream destinations


    Use these endpoints to create, update, list, and manage your functions.'
paths:
  /v3/functions:
    post:
      operationId: v3-create-function
      summary: Create a Function
      description: '**Create a function.**


        The function `type` determines which configuration fields are

        required — see the `CreateFunctionV3` discriminated union and

        [Function types overview](/guide/function-types/overview) for the

        per-type contract.


        The response contains both `functionID` and `functionName`. Either is

        a stable handle you can use elsewhere; most workflows reference

        functions by `functionName` because it''s human-readable.


        ## Naming rules


        - `functionName` must be unique per environment.

        - Allowed characters: letters, digits, hyphens, and underscores.

        - Names cannot be reused after deletion within the same environment

        for at least the retention window of the previous record.


        The new function is created at `versionNum: 1`. Subsequent

        `PATCH /v3/functions/{functionName}` calls produce new versions —

        the version-1 configuration remains immutable and addressable.'
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FunctionResponseV3'
      tags:
      - Functions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFunctionV3'
    get:
      operationId: v3-list-functions
      summary: List Functions
      description: '**List functions in the current environment.**


        Returns each function''s current version. Combine filters freely —

        they AND together.


        ## Filtering


        - `functionIDs` / `functionNames`: exact-match identity filters.

        - `displayName`: case-insensitive substring match.

        - `types`: one or more of `extract`, `classify`, `split`, `join`,

        `enrich`, `payload_shaping`. Legacy `transform`, `analyze`, `route`,

        and `send` types remain readable via this filter.

        - `tags`: returns functions tagged with any of the supplied tags.

        - `workflowIDs` / `workflowNames`: returns only functions referenced

        by the named workflows. Useful for "what functions does this

        workflow depend on?" lookups.


        ## Pagination


        Cursor-based with `startingAfter` and `endingBefore` (functionIDs).

        Default limit 50, maximum 100.'
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      - 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: displayName
        in: query
        required: false
        schema:
          type: string
        explode: false
      - name: types
        in: query
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/FunctionType'
          minItems: 1
        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
      - name: tags
        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
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListFunctionsResponseV3'
      tags:
      - Functions
  /v3/functions/copy:
    post:
      operationId: v3-copy-function
      summary: Copy a Function
      description: '**Copy a function to a new name within the same environment.**


        Forks the source function''s current configuration into a brand-new

        function. The copy starts at `versionNum: 1` regardless of how many

        versions the source has — version history is not carried over.


        Useful for experimenting with schema or prompt changes against a

        stable production function without disturbing existing callers.


        The destination name must be unique in the environment. A copy does

        not migrate workflows: existing workflow nodes continue to reference

        the original function.'
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FunctionResponseV3'
        '400':
          description: The server could not understand the request due to invalid syntax.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPError'
      tags:
      - Functions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FunctionCopyRequest'
  /v3/functions/{functionName}:
    delete:
      operationId: v3-delete-function
      summary: Delete a Function
      description: '**Delete a function and every one of its versions.**


        Permanent. Running and queued calls that reference this function

        continue to completion against the version they captured at call

        time, but no new calls can target it.


        ## Before deleting


        Workflow nodes that reference this function will fail at call time

        after deletion. List workflows that reference it first:


        ```

        GET /v3/workflows?functionNames=my-function

        ```


        Update or remove those workflows, or create a replacement function

        and re-point the workflow nodes, before deleting.'
      parameters:
      - name: functionName
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: 'There is no content to send for this request, but the headers may be useful. '
      tags:
      - Functions
    get:
      operationId: v3-get-function
      summary: Get a Function
      description: '**Retrieve a function''s current version by name.**


        Returns the function record with its `currentVersionNum` and the

        configuration of that version. To inspect a historical version, use

        `GET /v3/functions/{functionName}/versions/{versionNum}`.'
      parameters:
      - name: functionName
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FunctionResponseV3'
      tags:
      - Functions
    patch:
      operationId: v3-update-function
      summary: Update a Function
      description: '**Update a function. Updates create a new version.**


        The previous version remains addressable and immutable. Workflow

        nodes that pinned the function with a `versionNum` continue to use

        the pinned version; nodes that reference the function by name with

        no version automatically pick up the new version on their next call.


        ## What you can change


        Any field allowed by the function''s type. Most commonly:

        `outputSchema` (for `extract`/`join`), `classifications` (for

        `classify`), `displayName`, and `tags`.


        ## Versioning behaviour


        - Each successful update increments `currentVersionNum` by 1.

        - `displayName`, `tags`, and `functionName` updates also create a

        new version, so the version history is a complete record of every

        change.

        - To revert, fetch the previous version and re-submit its

        configuration as a new update — versions themselves are immutable.'
      parameters:
      - name: functionName
        in: path
        required: true
        schema:
          type: string
          x-stainless-param: path_function_name
        x-stainless-param: path_function_name
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FunctionResponseV3'
      tags:
      - Functions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateFunctionV3'
  /v3/functions/{functionName}/versions:
    get:
      operationId: v3-list-function-versions
      summary: List Function Versions
      description: '**List every version of a function.**


        Returns the full version history, newest-first. Each row captures

        the configuration the function had between updates. Useful for

        audits ("when did this schema change?") and for diffing two

        versions before promoting an update to production.'
      parameters:
      - name: functionName
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListFunctionVersionsResponseV3'
      tags:
      - Functions
  /v3/functions/{functionName}/versions/{versionNum}:
    get:
      operationId: v3-get-function-version
      summary: Get a Function Version
      description: '**Retrieve a specific historical version of a function.**


        Versions are immutable. Use this endpoint to inspect what a function

        looked like at the moment a particular call was made — every event

        and transformation records the function version it ran against.'
      parameters:
      - name: functionName
        in: path
        required: true
        schema:
          type: string
      - name: versionNum
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FunctionVersionResponseV3'
      tags:
      - Functions
components:
  schemas:
    EnrichFunction:
      type: object
      required:
      - functionID
      - functionName
      - versionNum
      - type
      - config
      properties:
        functionID:
          type: string
          description: Unique identifier of function.
        functionName:
          type: string
          description: Name of function. Must be UNIQUE on a per-environment basis.
        versionNum:
          type: integer
          description: Version number of function.
        usedInWorkflows:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowUsageInfo'
          description: List of workflows that use this function.
        displayName:
          type: string
          description: Display name of function. Human-readable name to help you identify the function.
        tags:
          type: array
          items:
            type: string
          description: Array of tags to categorize and organize functions.
        audit:
          allOf:
          - $ref: '#/components/schemas/FunctionAudit'
          description: Audit trail information for the function.
        type:
          type: string
          enum:
          - enrich
        config:
          $ref: '#/components/schemas/enrichConfig'
      title: Enrich Function
    ParseFunction:
      type: object
      required:
      - functionID
      - functionName
      - versionNum
      - type
      properties:
        functionID:
          type: string
          description: Unique identifier of function.
        functionName:
          type: string
          description: Name of function. Must be UNIQUE on a per-environment basis.
        versionNum:
          type: integer
          description: Version number of function.
        usedInWorkflows:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowUsageInfo'
          description: List of workflows that use this function.
        displayName:
          type: string
          description: Display name of function. Human-readable name to help you identify the function.
        tags:
          type: array
          items:
            type: string
          description: Array of tags to categorize and organize functions.
        audit:
          allOf:
          - $ref: '#/components/schemas/FunctionAudit'
          description: Audit trail information for the function.
        type:
          type: string
          enum:
          - parse
        parseConfig:
          $ref: '#/components/schemas/ParseConfig'
        extraConfig:
          $ref: '#/components/schemas/ParseExtraFunctionConfiguration'
      title: Parse Function
    FunctionCopyRequest:
      type: object
      required:
      - sourceFunctionName
      - targetFunctionName
      properties:
        sourceFunctionName:
          type: string
          description: Name of the function to copy from. Must be a valid existing function name.
        targetFunctionName:
          type: string
          description: Name for the new copied function. Must be unique within the target environment.
        targetDisplayName:
          type: string
          description: Optional display name for the copied function. If not provided, defaults to the source function's display name with " (Copy)" appended.
        targetEnvironment:
          type: string
          description: Optional environment name to copy the function to. If not provided, the function will be copied within the same environment.
        tags:
          type: array
          items:
            type: string
          description: Optional array of tags for the copied function. If not provided, defaults to the source function's tags.
      description: Request to copy an existing function with a new name and optional customizations.
    FunctionVersionV3:
      type: object
      oneOf:
      - $ref: '#/components/schemas/TransformFunctionVersion'
      - $ref: '#/components/schemas/ExtractFunctionVersion'
      - $ref: '#/components/schemas/AnalyzeFunctionVersion'
      - $ref: '#/components/schemas/ClassifyFunctionVersion'
      - $ref: '#/components/schemas/SendFunctionVersion'
      - $ref: '#/components/schemas/SplitFunctionVersion'
      - $ref: '#/components/schemas/JoinFunctionVersion'
      - $ref: '#/components/schemas/EnrichFunctionVersion'
      - $ref: '#/components/schemas/PayloadShapingFunctionVersion'
      - $ref: '#/components/schemas/ParseFunctionVersion'
      - $ref: '#/components/schemas/RenderFunctionVersion'
      discriminator:
        propertyName: type
        mapping:
          transform: '#/components/schemas/TransformFunctionVersion'
          extract: '#/components/schemas/ExtractFunctionVersion'
          analyze: '#/components/schemas/AnalyzeFunctionVersion'
          classify: '#/components/schemas/ClassifyFunctionVersion'
          send: '#/components/schemas/SendFunctionVersion'
          split: '#/components/schemas/SplitFunctionVersion'
          join: '#/components/schemas/JoinFunctionVersion'
          enrich: '#/components/schemas/EnrichFunctionVersion'
          payload_shaping: '#/components/schemas/PayloadShapingFunctionVersion'
          parse: '#/components/schemas/ParseFunctionVersion'
          render: '#/components/schemas/RenderFunctionVersion'
      description: 'V3 read-side union for function versions. Same shape as the shared

        `FunctionVersion` union but with `classify` in place of `route`.'
    PayloadShapingFunction:
      type: object
      required:
      - functionID
      - functionName
      - versionNum
      - type
      - shapingSchema
      properties:
        functionID:
          type: string
          description: Unique identifier of function.
        functionName:
          type: string
          description: Name of function. Must be UNIQUE on a per-environment basis.
        versionNum:
          type: integer
          description: Version number of function.
        usedInWorkflows:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowUsageInfo'
          description: List of workflows that use this function.
        displayName:
          type: string
          description: Display name of function. Human-readable name to help you identify the function.
        tags:
          type: array
          items:
            type: string
          description: Array of tags to categorize and organize functions.
        audit:
          allOf:
          - $ref: '#/components/schemas/FunctionAudit'
          description: Audit trail information for the function.
        type:
          type: string
          enum:
          - payload_shaping
        shapingSchema:
          type: string
          description: 'JMESPath expression that defines how to transform and customize the input payload structure.

            Payload shaping allows you to extract, reshape, and reorganize data from complex input payloads

            into a simplified, standardized output format. Use JMESPath syntax to select specific fields,

            perform calculations, and create new data structures tailored to your needs.'
      description: 'A function that transforms and customizes input payloads using JMESPath expressions.

        Payload shaping allows you to extract specific data, perform calculations, and reshape

        complex input structures into simplified, standardized output formats tailored to your

        downstream systems or business requirements.'
      title: Payload Shaping Function
    ListFunctionsResponseV3:
      type: object
      properties:
        functions:
          type: array
          items:
            $ref: '#/components/schemas/FunctionV3'
        totalCount:
          type: integer
          description: The total number of results available.
    ClassificationList:
      type: array
      items:
        type: object
        properties:
          name:
            type: string
          description:
            type: string
          isErrorFallback:
            type: boolean
          origin:
            type: object
            properties:
              email:
                type: object
                properties:
                  patterns:
                    type: array
                    items:
                      type: string
          regex:
            type: object
            properties:
              patterns:
                type: array
                items:
                  type: string
          functionID:
            type: string
          functionName:
            type: string
        required:
        - name
      description: List of classifications a classify function can produce. Shares the underlying route list shape.
    ParseConfig:
      type: object
      properties:
        extractEntities:
          type: boolean
          description: 'When true, extract named entities (people, organizations, products,

            studies, identifiers, etc.) and the relationships between them, and

            dedupe by canonical name within the document. When false, only

            `sections[]` is extracted; `entities[]` and `relationships[]` come

            back empty in the parse output. Defaults to true.'
        linkAcrossDocuments:
          type: boolean
          description: 'When true, link this document''s entities to entities seen in earlier

            documents in this environment, building one canonical record per

            real-world thing across the corpus. Visible in the Memory tab and

            queryable via `POST /v3/fs` (op=find / open / xref). Doesn''t change

            this call''s parse output. Requires `extractEntities=true`. Defaults

            to true.'
        schema:
          type: object
          unevaluatedProperties: {}
          description: 'Optional JSONSchema. When provided, each chunk performs schema-guided

            extraction. When absent, chunks perform open-ended discovery and

            return sections, entities, and relationships per the discovery

            schema.'
        defaultBucket:
          type: string
          description: 'Optional bucket NAME that parse-extracted entities land in when no

            call-level bucket is supplied. Lower precedence than a call-level bucket,

            higher than the account+environment default.'
      description: 'Per-version configuration for a Parse function.


        Parse renders document pages (PDF, image) via vision LLM and emits

        structured JSON. The two toggles below independently control entity

        extraction (a per-call output concern) and cross-document memory

        linking (an environment-wide concern).'
    FunctionAudit:
      type: object
      properties:
        functionCreatedBy:
          allOf:
          - $ref: '#/components/schemas/UserActionSummary'
          description: Information about who created the function.
        functionLastUpdatedBy:
          allOf:
          - $ref: '#/components/schemas/UserActionSummary'
          description: Information about who last updated the function.
        versionCreatedBy:
          allOf:
          - $ref: '#/components/schemas/UserActionSummary'
          description: Information about who created the current version.
    UpsertJoinFunction:
      type: object
      required:
      - type
      properties:
        functionName:
          type: string
          description: Name of function. Must be UNIQUE on a per-environment basis.
        displayName:
          type: string
          description: Display name of function. Human-readable name to help you identify the function.
        tags:
          type: array
          items:
            type: string
          description: Array of tags to categorize and organize functions.
        type:
          type: string
          enum:
          - join
        description:
          type: string
          description: Description of join function.
        joinType:
          type: string
          enum:
          - standard
          description: The type of join to perform.
        outputSchemaName:
          type: string
          description: Name of output schema object.
        outputSchema:
          type: object
          unevaluatedProperties: {}
          description: Desired output structure defined in standard JSON Schema convention.
      title: Join Function
    UpsertParseFunction:
      type: object
      required:
      - type
      properties:
        functionName:
          type: string
          description: Name of function. Must be UNIQUE on a per-environment basis.
        displayName:
          type: string
          description: Display name of function. Human-readable name to help you identify the function.
        tags:
          type: array
          items:
            type: string
          description: Array of tags to categorize and organize functions.
        type:
          type: string
          enum:
          - parse
        parseConfig:
          $ref: '#/components/schemas/ParseConfig'
        extraConfig:
          $ref: '#/components/schemas/ParseExtraFunctionConfiguration'
      title: Parse Function
    RenderFunctionVersion:
      type: object
      required:
      - functionID
      - functionName
      - versionNum
      - type
      properties:
        functionID:
          type: string
          description: Unique identifier of function.
        functionName:
          type: string
          description: Name of function. Must be UNIQUE on a per-environment basis.
        versionNum:
          type: integer
          description: Version number of function.
        usedInWorkflows:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowUsageInfo'
          description: List of workflows that use this function.
        displayName:
          type: string
          description: Display name of function. Human-readable name to help you identify the function.
        tags:
          type: array
          items:
            type: string
          description: Array of tags to categorize and organize functions.
        createdAt:
          type: string
          format: date-time
          description: The date and time the function version was created.
        audit:
          allOf:
          - $ref: '#/components/schemas/FunctionAudit'
          description: Audit trail information for the function version.
        type:
          type: string
          enum:
          - render
        renderConfig:
          $ref: '#/components/schemas/RenderConfig'
    PayloadShapingFunctionVersion:
      type: object
      required:
      - functionID
      - functionName
      - versionNum
      - type
      - shapingSchema
      properties:
        functionID:
          type: string
          description: Unique identifier of function.
        functionName:
          type: string
          description: Name of function. Must be UNIQUE on a per-environment basis.
        versionNum:
          type: integer
          description: Version number of function.
        usedInWorkflows:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowUsageInfo'
          description: List of workflows that use this function.
        displayName:
          type: string
          description: Display name of function. Human-readable name to help you identify the function.
        tags:
          type: array
          items:
            type: string
          description: Array of tags to categorize and organize functions.
        createdAt:
          type: string
          format: date-time
          description: The date and time the function version was created.
        audit:
          allOf:
          - $ref: '#/components/schemas/FunctionAudit'
          description: Audit trail information for the function version.
        type:
          type: string
          enum:
          - payload_shaping
        shapingSchema:
          type: string
          description: 'JMESPath expression that defines how to transform and customize the input payload structure.

            Payload shaping allows you to extract, reshape, and reorganize data from complex input payloads

            into a simplified, standardized output format. Use JMESPath syntax to select specific fields,

            perform calculations, and create new data structures tailored to your needs.'
      description: 'A version of a payload shaping function that transforms and customizes input payloads using JMESPath expressions.

        Payload shaping allows you to extract specific data, perform calculations, and reshape

        complex input structures into simplified, standardized output formats tailored to your

        downstream systems or business requirements.'
    RenderConfig:
      type: object
      properties:
        template:
          allOf:
          - $ref: '#/components/schemas/RenderTemplate'
          description: 'The uploaded template: its filename, a short-lived presigned download URL,

            and the placeholder/style contract derived from it. Absent on configs

            created before template capture existed.'
      description: 'Per-version configuration for a Render function.


        Render emits a `.docx` from schema-typed JSON by composing the JSON into a

        `.docx` template. The template document is stored server-side; this response

        exposes only the contract derived from it. Schema validation runs internally

        in the ML service against the bundled core schema; no customer-supplied

        schema rides this surface.'
      title: Render function configuration
    CreateClassifyFunction:
      type: object
      required:
      - functionName
      - type
      properties:
        functionName:
          type: string
          description: Name of function. Must be UNIQUE on a per-environment basis.
        displayName:
          type: string
          description: Display name of function. Human-readable name to help you identify the function.
        tags:
          type: array
          items:
            type: string
          description: Array of tags to categorize and organize functions.
        type:
          type: string
          enum:
          - classify
        description:
          type: string
          description: Description of classifier. Can be used to provide additional context on classifier's purpose and expected inputs.
        classifications:
          $ref: '#/components/schemas/ClassificationList'
      description: V3 wire form of the classify function create payload.
      title: Classify Function
    UpsertRenderFunction:
    

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