Requests

Base URL, content types, pagination, filtering, and field projection.

Base URL

https://api.runflow.io

All endpoints live under /v1/. The public OpenAPI spec is at docs.runflow.io/api/openapi.public.json.

Content types

Method	Content-Type	Use
GET	n/a	Read endpoints.
POST, PATCH, PUT	application/json	All mutations.
POST /v1/asset-uploads/{id}/confirmations	application/json	After uploading the file blob to the presigned URL.

Pagination

List endpoints return cursors, not page numbers. Pass pq (the cursor) and limit (page size, max 500).

curl https://api.runflow.io/v1/runs?limit=50 \
  -H "Authorization: Bearer $RUNFLOW_API_KEY"

The response includes next_pq and prev_pq. Pass from_prev=true to walk backward.

Filtering

List endpoints accept a filter expression in q:

curl 'https://api.runflow.io/v1/runs?q=status_code:succeeded%20AND%20created_at>2026-04-01' \
  -H "Authorization: Bearer $RUNFLOW_API_KEY"

Operators: =, :, >, <, >=, <=, AND, OR, NOT. String values are case-sensitive.

Field projection

Trim the response to the fields you need with fields:

curl 'https://api.runflow.io/v1/runs?fields=id,status_code,model_id' \
  -H "Authorization: Bearer $RUNFLOW_API_KEY"

Sorting

curl 'https://api.runflow.io/v1/runs?sort_by=created_at:desc' \
  -H "Authorization: Bearer $RUNFLOW_API_KEY"

Multi-field sort: sort_by=status_code:asc,created_at:desc.

Idempotency

Mutations are not idempotent by default. To retry safely, save the response of the first call and skip on duplicate.

Related

Errors

Status codes and the error envelope.

Runs

Callbacks, polling, statuses.