REST API reference
Base URL, headers, pagination, and the main Flowyn endpoints. The OpenAPI document is the complete, machine-readable contract.
Base URL and headers
https://api.flowyn.dev
Authorization: Bearer <key>
Content-Type: application/json
Idempotency-Key: <your key> # on createsOpenAPI
The OpenAPI 3 document at https://api.flowyn.dev/openapi/v1.yaml is the authoritative description of every request, response, and error. Point your client generator or coding agent at it rather than at this page.
Main endpoints
| Method | Path | Purpose |
|---|---|---|
| POST | /v1/files | Upload a file (tus) |
| GET | /v1/files/{id}/download | Download a file |
| POST | /v1/pdf/parse | Parse a PDF |
| POST | /v1/docx/parse | Parse a DOCX |
| POST | /v1/pdf/from-html | Render an HTML file to PDF |
| POST | /v1/split-pdf | Split a mixed PDF |
| POST | /v1/pdf/split | Split a PDF by page ranges |
| GET | /v1/file-jobs/{id} | Read a file job and its outputs |
| POST | /v1/jobs | Create a durable HTTP job |
| GET | /v1/jobs/{id} | Read a job |
| GET | /v1/jobs/{id}/attempts | Read a job's attempts |
| POST | /v1/jobs/{id}/cancel | Cancel a job |
| POST | /v1/schedules | Create a schedule |
| GET | /v1/schedules/{id}/occurrences | Read a schedule's occurrences |
| POST | /v1/events | Send an event |
| GET | /v1/events/{id}/attempts | Read delivery attempts |
| POST | /v1/events/{id}/replay | Replay an event |
| POST | /v1/endpoints | Create a webhook endpoint |
| POST | /v1/endpoints/{id}/test | Send a test delivery |
| POST | /v1/monitors | Create an HTTP, heartbeat, or API-check monitor |
| POST | /v1/monitors/{id}/ping | Record a heartbeat ping |
| GET | /v1/monitors/{id}/results | Read monitor results |
| GET | /v1/monitors/{id}/incidents | Read monitor incidents |
| GET | /v1/issues/{fingerprint} | Read an issue |
| POST | /v1/flags | Create a flag |
| POST | /v1/flags/evaluate | Evaluate a flag |
| POST | /v1/agents | Register an agent |
| POST | /v1/agent-runs | Record that an agent run started |
| POST | /v1/agent-runs/{id}/finish | Report a run's outcome |
| POST | /v1/agent-telemetry | Send agent spans |
| GET | /v1/agent-telemetry/{trace_id} | Read a trace and its steps |
| GET | /v1/agent-telemetry/usage | Read model usage and cost |
| POST | /v1/agent-approvals | Ask a person to decide |
| GET | /v1/agent-approvals/{id} | Read an approval decision |
| POST | /v1/provider-connections | Store an encrypted provider key |
| POST | /v1/provider-connections/{id}/test | Test a provider key |
Pagination
List endpoints accept limit and cursor. A response includes next_cursor; null means the last page.
Environments
An API key acts in its own environment. A signed-in session selects one with ?environment=test or live.