Call a Workflow

Invoke a workflow.

Submit the input file as either a multipart form request or a JSON request with base64-encoded file content. The workflow name is derived from the URL path.

Input Formats

Multipart form (multipart/form-data): attach the file directly via the file or files fields. Set wait in the form body to control synchronous behaviour.
JSON (application/json): base64-encode the file content and set it in input.singleFile.inputContent or input.batchFiles.inputs[*].inputContent. Pass wait=true as a query parameter to control synchronous behaviour.

By default the call is created asynchronously and this endpoint returns 202 Accepted immediately with a pending call object. Set wait to true to block until the call completes (up to 30 seconds):

On success: returns 200 OK with the completed call, outputs populated
On failure: returns 500 Internal Server Error with the call and an error message
On timeout: returns 202 Accepted with the still-running call

Tracking

Poll GET /v3/calls/{callID} to check status, or configure a webhook subscription to receive events when the call finishes.

CLI Usage

Use @path/to/file inside JSON string values to embed file contents automatically. Binary files (PDF, images, audio) are base64-encoded; text files are embedded as strings.

Single file (synchronous):

bem workflows call \
  --workflow-name my-workflow \
  --input.single-file '{"inputContent": "@invoice.pdf", "inputType": "pdf"}' \
  --wait

Single file (asynchronous, returns callID immediately):

bem workflows call \
  --workflow-name my-workflow \
  --input.single-file '{"inputContent": "@invoice.pdf", "inputType": "pdf"}'

Batch files:

bem workflows call \
  --workflow-name my-workflow \
  --input.batch-files '{"inputs": [{"inputContent": "@a.pdf", "inputType": "pdf"}, {"inputContent": "@b.png", "inputType": "png"}]}'

Alternative: pass the full --input flag as JSON:

bem workflows call \
  --workflow-name my-workflow \
  --input '{"singleFile": {"inputContent": "@invoice.pdf", "inputType": "pdf"}}' \
  --wait

Important: --wait is a boolean flag. Use --wait or --wait=true. Do not use --wait true (with a space) — the true will be parsed as an unexpected positional argument.

Supported inputType values: csv, docx, email, heic, heif, html, jpeg, json, m4a, mp3, pdf, png, text, wav, webp, xls, xlsx, xml.

Authorization

API Key

x-api-key<token>

Authenticate using API Key in request header

In: header

Path Parameters

workflowName*string

The name of the workflow to invoke.

Query Parameters

wait?boolean

Block until the call completes (up to 30 seconds) and return the finished call object. Default: false. This is a boolean flag — use --wait or --wait=true, not --wait true.

Request Body

TypeScript Definitions

Use the request body type in TypeScript.

callReferenceID?string

Your reference ID for tracking this call.

wait?string

Block until the call completes (up to 30 seconds) and return the finished call object. Default: false. This is a boolean flag — use --wait or --wait=true, not --wait true.

metadata?string

Arbitrary JSON object (serialized as a string) attached to this call. Stored on the call record and injected into transformedContent under the reserved _metadata key (alongside referenceID). Must be a valid JSON object string. Maximum size: 4 KB.

Example: {"customer_id": "cust_123", "test_flag": true}

file?unknown

Single input file (for extract, classify, and split functions).

files?array<>

Multiple input files (for join functions).

Response Body

`application/json`

curl -X POST "https://api.bem.ai/v3/workflows/string/call" \  -H "Content-Type: application/json" \  -d '{    "input": {}  }'

{
  "call": {
    "callID": "string",
    "status": "pending",
    "createdAt": "2019-08-24T14:15:22Z",
    "finishedAt": "2019-08-24T14:15:22Z",
    "workflowID": "string",
    "workflowName": "string",
    "workflowVersionNum": 0,
    "callReferenceID": "string",
    "outputs": [
      {
        "functionCallTryNumber": 0,
        "eventID": "string",
        "createdAt": "2019-08-24T14:15:22Z",
        "referenceID": "string",
        "inboundEmail": {
          "to": "string",
          "deliveredTo": "string",
          "from": "string",
          "subject": "string"
        },
        "metadata": {
          "durationFunctionToEventSeconds": 0
        },
        "eventType": "transform",
        "functionCallID": "string",
        "functionID": "string",
        "functionName": "string",
        "functionVersionNum": 0,
        "callID": "string",
        "workflowID": "string",
        "workflowName": "string",
        "workflowVersionNum": 0,
        "pipelineID": "string",
        "publishedAt": "2019-08-24T14:15:22Z",
        "lastPublishErrorAt": "string",
        "inputType": "csv",
        "transformationID": "string",
        "s3URL": "string",
        "inputs": [
          {
            "inputType": "string",
            "inputContent": "string",
            "jsonInputContent": {},
            "s3URL": "string"
          }
        ],
        "transformedContent": {},
        "correctedContent": {
          "output": [
            {}
          ]
        },
        "invalidProperties": [
          "string"
        ],
        "metrics": {
          "metrics": {
            "accuracy": 0,
            "precision": 0,
            "recall": 0,
            "f1Score": 0
          },
          "differences": [
            {
              "category": "string",
              "correctedVal": null,
              "extractedVal": null,
              "jsonPointer": "string"
            }
          ]
        },
        "orderMatching": true,
        "isRegression": true,
        "itemOffset": 0,
        "itemCount": 0,
        "fieldConfidences": {},
        "avgConfidence": 0.1
      }
    ],
    "errors": [
      {
        "functionCallTryNumber": 0,
        "eventID": "string",
        "createdAt": "2019-08-24T14:15:22Z",
        "referenceID": "string",
        "inboundEmail": {
          "to": "string",
          "deliveredTo": "string",
          "from": "string",
          "subject": "string"
        },
        "metadata": {
          "durationFunctionToEventSeconds": 0
        },
        "eventType": "error",
        "functionCallID": "string",
        "functionID": "string",
        "functionName": "string",
        "functionVersionNum": 0,
        "callID": "string",
        "workflowID": "string",
        "workflowName": "string",
        "workflowVersionNum": 0,
        "message": "string"
      }
    ],
    "input": {
      "singleFile": {
        "inputType": "string",
        "s3URL": "string"
      },
      "batchFiles": {
        "inputs": [
          {
            "inputType": "string",
            "itemReferenceID": "string",
            "s3URL": "string"
          }
        ]
      }
    },
    "url": "string",
    "traceUrl": "string"
  },
  "error": "string"
}

Call a Workflow

Input Formats

Synchronous vs Asynchronous

Tracking

CLI Usage

Authorization

Path Parameters

Query Parameters

Request Body

Response Body

`application/json`

See also

Call a Workflow

200application/json

`application/json`