Skip to main content
POST
Executes a flow by uploading files and triggering the configured workflow steps.

Usage Notes

  • Files are uploaded as multipart/form-data
  • File field names must match the flow’s configuration
  • Required files must be provided or the request will fail
  • The flow executes asynchronously - use the returned ID to check status
  • Use metadata to include custom data that will be preserved in the flow run

Request

string
required
The ID of the flow to run
file
File(s) to upload. The field name must match the key defined in the flow’s file_input_config.file_fields. For fields that accept multiple files, append an index starting at 1 (e.g., attachments_1, attachments_2).
string
Optional name for the flow run. This is useful for identifying flow runs in the TableFlow UI.
string
JSON string containing metadata for a specific file. Replace {file_key} with the file field key (e.g., purchase_order_metadata). This metadata is associated with the individual file’s extraction.
string
Optional extraction guidance for a specific file. Replace {file_key} with the file field key (e.g., purchase_order_guidance). Use this to provide hints to the AI about the document structure or specific values to look for in that particular file.
string
JSON string containing metadata for the entire flow run. This metadata will be included in all flow run responses and webhooks.

Response

string
required
The unique identifier for the flow run
string
required
The ID of the flow being executed
string
required
The workspace ID
string
required
Current status of the flow run: processing, review, completed, or failed
array
required
History of status changes
string
Error message if the flow run failed
object
Custom metadata provided when running the flow
string
required
How the flow was triggered: api or manual
number
required
Unix timestamp when the flow run started
number
Unix timestamp when the flow run completed
number
required
Duration of the flow run in milliseconds
number
required
Unix timestamp when the flow run was created
number
required
Unix timestamp when the flow run was last updated