Call a Workflow 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.

Synchronous vs Asynchronous

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.

workflowNamestring required

The name of the workflow to invoke.

waitboolean

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

callReferenceIDstring

Your reference ID for tracking this call.

metadataobject

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.

bucketstring

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

The request has succeeded.

errorstring

Error message if the call retrieval failed, or if the call itself failed when using wait=true.

v37