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. For files, an optional tags field labels each file, aligned positionally by index.
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, jfif, jpeg, json, m4a, mp3, mov, mp4, pdf, png, pptx, text, wav, webp, xls, xlsx, xml. jfif (and jpg) are normalized to jpeg.

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.

metadata?object

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

input*

Input file(s) for the workflow. Use nested flags to specify a single file or batch:

Single file: --input.single-file '{"inputContent": "@file.pdf", "inputType": "pdf"}' Batch files: --input.batch-files '{"inputs": [{"inputContent": "@a.pdf", "inputType": "pdf"}]}'

The @path/to/file syntax reads and base64-encodes the file automatically. Provide exactly one of singleFile or batchFiles.

bucket?string

Optional bucket NAME that entities extracted by the workflow's parse function(s) land in. Resolution precedence: this call-level bucket > the parse function's configured defaultBucket > the account+environment default bucket. A non-existent bucket name returns 400, but only when the workflow contains a parse function; on a parse-free workflow it is ignored.

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",
    "callType": "workflow",
    "status": "pending",
    "createdAt": "2019-08-24T14:15:22Z",
    "finishedAt": "2019-08-24T14:15:22Z",
    "workflowID": "string",
    "workflowName": "string",
    "workflowVersionNum": 0,
    "functionID": "string",
    "functionName": "string",
    "functionType": "transform",
    "functionVersionNum": 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",
        "kind": "string"
      }
    ],
    "input": {
      "singleFile": {
        "inputType": "string",
        "s3URL": "string"
      },
      "batchFiles": {
        "inputs": [
          {
            "inputType": "string",
            "itemReferenceID": "string",
            "tag": "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`