POST
/
v2
/
flows
/
{id}
/
run
curl --request POST \
  --url https://api.tableflow.com/v2/flows/dk4g1tUg1uHLs8YU/run \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: multipart/form-data' \
  --form 'purchase_order=@/path/to/po.pdf' \
  --form 'invoice=@/path/to/invoice.pdf' \
  --form 'purchase_order_metadata={"po_number": "PO-123"}' \
  --form 'metadata={"customer_id": "12345"}'
{
  "id": "fr_abc123def456",
  "flow_id": "dk4g1tUg1uHLs8YU",
  "workspace_id": "uT2bJNWN75YPU95r",
  "status": "processing",
  "status_history": [
    {
      "status": "processing",
      "time": 1682366228,
      "message": "Flow started via api"
    }
  ],
  "error": null,
  "metadata": {
    "customer_id": "12345",
    "order_number": "PO-2024-001"
  },
  "trigger_method": "api",
  "start_time": 1682366228,
  "end_time": null,
  "duration": 0,
  "drive_files": {},
  "created_at": 1682366228,
  "updated_at": 1682366228
}
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

id
string
required
The ID of the flow to run
file
file
File to upload. The field name should match the key defined in the flow’s file_input_config.file_fields
file_metadata
string
JSON string containing metadata for a specific file. Use the format {file_key}_metadata where {file_key} matches the file field key.
metadata
string
JSON string containing metadata for the entire flow run. This metadata will be included in all flow run responses and webhooks.

Response

{
  "id": "fr_abc123def456",
  "flow_id": "dk4g1tUg1uHLs8YU",
  "workspace_id": "uT2bJNWN75YPU95r",
  "status": "processing",
  "status_history": [
    {
      "status": "processing",
      "time": 1682366228,
      "message": "Flow started via api"
    }
  ],
  "error": null,
  "metadata": {
    "customer_id": "12345",
    "order_number": "PO-2024-001"
  },
  "trigger_method": "api",
  "start_time": 1682366228,
  "end_time": null,
  "duration": 0,
  "drive_files": {},
  "created_at": 1682366228,
  "updated_at": 1682366228
}
curl --request POST \
  --url https://api.tableflow.com/v2/flows/dk4g1tUg1uHLs8YU/run \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: multipart/form-data' \
  --form 'purchase_order=@/path/to/po.pdf' \
  --form 'invoice=@/path/to/invoice.pdf' \
  --form 'purchase_order_metadata={"po_number": "PO-123"}' \
  --form 'metadata={"customer_id": "12345"}'
id
string
required
The unique identifier for the flow run
flow_id
string
required
The ID of the flow being executed
workspace_id
string
required
The workspace ID
status
string
required
Current status of the flow run: processing, review, completed, or failed
status_history
array
required
History of status changes
error
string
Error message if the flow run failed
metadata
object
Custom metadata provided when running the flow
trigger_method
string
required
How the flow was triggered: api or manual
start_time
number
required
Unix timestamp when the flow run started
end_time
number
Unix timestamp when the flow run completed
duration
number
required
Duration of the flow run in milliseconds
created_at
number
required
Unix timestamp when the flow run was created
updated_at
number
required
Unix timestamp when the flow run was last updated