Single PDF Async Generation

The POST /file/async/single endpoint generates a single PDF asynchronously from the specified design and parameters. It returns a requestId and file information immediately, so the client never has to wait for rendering.

Endpoint

• URL: https://api.re-port-flow.com/v1/file/async/single
• Method: POST
• Auth: appkey header required
• Timeout: none (async processing)
• Request body limit: 50MB (after Base64 encoding, roughly 37MB of binary data)

Example

cURL

curl -X POST https://api.re-port-flow.com/v1/file/async/single \
  -H "appkey: your-application-key" \
  -H "Content-Type: application/json" \
  -d '{
    "designId": "550e8400-e29b-41d4-a716-446655440000",
    "version": 1,
    "content": {
      "fileName": "invoice.pdf",
      "shareType": "01",
      "passcodeEnabled": false,
      "params": {
        "customerName": "John Doe",
        "invoiceNumber": "INV-2024-001",
        "amount": 10000
      }
    }
  }'

Request parameters

Field	Type	Required	Description
designId	string (UUID)	✓	Design ID
version	integer	✓	Design version
content.fileName	string	✓	File name (any character is allowed except `/ \ : * ? " < >
content.shareType	string	-	Share type on the request side is a numeric code: "01" = workspace (default), "02" = invitee, "03" = public URL. In the response, share.shareType is returned as the human-readable name (workspace / invited / public)
content.passcodeEnabled	boolean	-	Whether to enable passcode protection (default false)
content.passthrough	object	-	Arbitrary metadata that will be echoed back in files[].passthrough (e.g. { "pageId": "abc123" })
content.params	object	✓	Template parameters. The expected structure is available from the design parameter API

Response

Success (202 Accepted)

{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://api.re-port-flow.com/v1/file/download/{requestId}",
  "files": [
    {
      "fileName": "invoice.pdf",
      "fileId": "7f3d1a2b-4c5e-6f7a-8b9c-0d1e2f3a4b5c",
      "passthrough": { "pageId": "abc123" },
      "share": {
        "shareType": "workspace",
        "url": "https://app.re-port-flow.com/file/{requestId}/{fileId}",
        "passcodeEnabled": false
      }
    }
  ]
}

Field	Type	Description
requestId	string (UUID)	Request ID, used by the download endpoint
url	string (URI)	ZIP download URL
files	array	Generated files
files[].fileName	string	File name
files[].fileId	string	File ID, used by the per-file download endpoint
files[].passthrough	object	The content.passthrough value supplied on the request (only when set)
files[].share.shareType	string	Share type (workspace / invited / public)
files[].share.url	string	Sharable URL
files[].share.passcodeEnabled	boolean	Whether passcode protection is enabled
files[].share.passcode	string	Server-generated passcode (only when passcodeEnabled=true AND immediately after generation)

When to use passthrough

ReportFlow does not echo back params (the data used to render the PDF) on responses or webhooks, both for payload size and to avoid leaking business data to webhook endpoints.

If you need to know which business record a PDF corresponds to, put your own DB id (or any opaque token) into passthrough on the request. The exact value comes back on the response and the webhook unchanged.

{
  "fileName": "invoice.pdf",
  "passthrough": { "invoiceId": "INV-001", "tenantId": "acme" },
  "params": { "customerName": "John Doe", "amount": 10000 }
}

When the webhook arrives, look up your DB by invoiceId to find the record to update. params (the customer name, amount, etc.) is never sent off-server.

Errors

Errors are the same shape as the synchronous endpoint. See Single PDF Sync Generation — Errors.

Async flow

1. Client → API: send generation request
   ↓
2. API → Client: returns requestId / url / files immediately (202 Accepted)
   ↓
3. API: starts background PDF generation
   ↓
4. API: uploads the result to S3 when done
   ↓
5. Client: download the PDF via the returned `url` or
   /v1/file/download/{requestId}/{fileId}

Use cases

Case 1: background generation

Accept the user request immediately and let the rendering happen in the background.

app.post('/api/generate-report', async (req, res) => {
  const response = await axios.post(
    'https://api.re-port-flow.com/v1/file/async/single',
    {
      designId: '...',
      version: 1,
      content: { fileName: 'report.pdf', params: req.body },
    },
    { headers: { appkey: process.env.APP_KEY } },
  );

  const { requestId, url, files } = response.data;

  res.status(202).json({
    message: 'Report generation started',
    requestId,
    downloadUrl: url,
    fileId: files[0].fileId,
  });
});

Case 2: webhook notifications (recommended)

Use ReportFlow's built-in webhook to be notified when generation finishes — no polling required.

See the Webhook guide for details, including HMAC-SHA256 signature verification.

Next steps

• Multiple PDF Async Generation — generate many PDFs in one async call
• Async Workflows — best practices for high-volume generation
• File Download — how to download the generated files