Skip to main content
The Flowy API lets you run flows, the reusable tools you publish from a canvas, programmatically. With it you can:
  • List the flows in your workspace
  • Read a flow’s inputs and outputs so you know what to send
  • Start a run with your own inputs
  • Poll a run and download its results: images, video, audio, and more
A flow is a canvas you’ve turned into a reusable tool by marking its input and output nodes. Anyone can fill in the inputs and run it. Learn more in Concepts.
The app calls these flows; the REST resource underneath is still /v1/apps (a name it kept from before the rename). GET /v1/apps, POST /v1/apps/{appId}/runs, and so on all refer to flows: the endpoints themselves aren’t renamed.

​
Base URL

All API requests are made to the following base URL:
Copy your exact base URL, and create keys, from Settings → API keys in the app. These docs use $FLOWY_API for the base URL and $FLOWY_KEY for your key.

​
Authentication

Authenticate every request by sending your API key as a Bearer token in the Authorization header:
Today you create secret keys (flowy_…) for your server. See Authentication to create one and Permissions to scope it to exactly what it needs.
Browser-safe publishable keys (flowy_pk_…), locked to an allowlist of domains, are coming soon.
Your secret key carries the privileges of its scopes. Keep it server-side and never commit it or expose it in client code. Every run is billed to the key’s own workspace, so a leaked key can only ever spend your balance, never another workspace’s.

​
Error handling

The Flowy API uses conventional HTTP status codes to indicate success or failure, and returns a human-readable message on every error:
A 2xx means success, a 4xx means the request was rejected (and usually tells you how to fix it), and a 5xx means something went wrong on our end. See Errors for the full list, and Rate limits for the 429 and the X-RateLimit-* headers.

​
SDKs

There’s no official SDK yet, but the API is described by an OpenAPI 3 document (served publicly, no key required). Use it to generate a typed client in your language of choice, or import the API into Postman or Insomnia.

​
Next steps

Create an API key

Mint, scope, and revoke keys from your workspace settings.

Authentication

Send your key as a Bearer token on every request.

Permissions

Scope a key to exactly what it needs: read flows, read runs, start runs.

Run a flow

The end-to-end path: list flows, start a run, poll for the result.

Rate limits

Per-minute limits, the X-RateLimit-* headers, and backing off on 429.

Errors

Every status code the API returns, and how to fix each one.
Last modified on August 29, 2026