Skip to main content

Batch endpoint

The Batch endpoint accepts several files in a single HTTP call. Zparse runs your workflow once per uploaded file, so a batch of ten files produces ten independent executions from one request.

Use it when a source system exports a set of documents at once — a nightly drop of invoices, a folder of product images, a multi-file export — and you would otherwise have to loop and call the File endpoint once per file.

Pre-requisite​

Your workflow must be configured with a Batch: Files endpoint function node. This node acts as the entry point and generates the unique URL you publish to.

Configuration​

See platform reference: How to configure the Batch endpoint

Usage​

Call the given url from your own http client using a POST request, repeating the files part once per file.

files (form files)required

The files you want to send. Repeat the part for each file — the part name is files, plural, unlike the single File endpoint. The whole request is limited to 2000 MB.

Authorization (header)

If private workflow: Configured access key. Cf: How to handle Authentication.

X-ZPARSE-IO-ATTR (header)

Optional header you can use to provide additional context to your call.

X-ZPARSE-IO-AUTH (header)

Optional header you can use to check extra security.


Example using Curl:
curl https://api.zparse.io/workflow/e/mf/xxx/yyy \
  -H 'Authorization: {ACCESS_KEY}' \
  -H 'X-ZPARSE-IO-ATTR: {CUSTOM_ATTR}' \
  -H 'X-ZPARSE-IO-AUTH: {CUSTOM_AUTH}' \
  -XPOST \
  -F "files=@/path/to/invoice-1.pdf" \
  -F "files=@/path/to/invoice-2.pdf" \
  -F "files=@/path/to/invoice-3.pdf"
Example in python:
def publish_files(file_paths, secret_key):
    headers = {
        'Authorization': secret_key,
    }

    files = [
        ('files', (path, open(path, 'rb'), 'application/octet-stream'))
        for path in file_paths
    ]
    return requests.post('https://api.zparse.io/workflow/e/mf/xxx/yyy', files=files, headers=headers)
One execution per file

The workflow is executed once for every file in the batch. Each execution receives a single file on the File connector along with its own Filename, and produces its own entry in the monitoring timeline.

Response​

Unlike the single File endpoint, a batch runs asynchronously by default — sending a hundred files should not hold an HTTP connection open. An authenticated call receives the execution tracker as JSON, an anonymous call an empty 200, and processing continues in the background.

Follow the run and collect what your responder produced from Workflow Monitoring — with one tracker step per file, since each file is its own execution.

Add ?mode=Play to the url to run synchronously instead, in which case the response is produced inline by the responder you wired on your function. Keep in mind that a synchronous batch is bound by the server-side execution timeout.