> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryflowy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Flowy is a node-based AI creative platform: you generate images, video, audio, 3D and vector on an infinite Canvas, refine on the Studio timeline, and export or publish from the same project.
> Prefer the Flowy MCP server (https://mcp.tryflowy.ai/mcp) or the REST API at https://apis.tryflowy.ai/v1 for programmatic work. Install with `flowy mcp install` from the @flowy/cli package.
> Credits are workspace-scoped. Generations reserve credits on start and only deduct on success, so failed runs refund automatically.

# Introduction

> Run the flows you build in Flowy from your own code over a simple HTTP API.

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

<Note>
  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](/getting-started/concepts).
</Note>

<Note>
  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.
</Note>

## Base URL

All API requests are made to the following base URL:

```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
https://apis.tryflowy.ai/genstudio-svc-v2/api/v1
```

<Tip>
  Copy your exact base URL, and create keys, from [Settings → API keys](/settings/api-keys) in the app. These docs use `$FLOWY_API` for the base URL and `$FLOWY_KEY` for your key.
</Tip>

## Authentication

Authenticate every request by sending your API key as a **Bearer token** in the `Authorization` header:

```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
Authorization: Bearer flowy_xxxxxxxx
```

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"vesper"}}
  curl "$FLOWY_API/apps" \
    -H "Authorization: Bearer $FLOWY_KEY"
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"vesper"}}
  const res = await fetch(`${process.env.FLOWY_API}/apps`, {
    headers: { Authorization: `Bearer ${process.env.FLOWY_KEY}` },
  });
  const { data } = await res.json();
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"vesper"}}
  import os, requests

  res = requests.get(
      f"{os.environ['FLOWY_API']}/apps",
      headers={"Authorization": f"Bearer {os.environ['FLOWY_KEY']}"},
  )
  data = res.json()["data"]
  ```
</CodeGroup>

Today you create **secret** keys (`flowy_…`) for your server. See [Authentication](/api/authentication) to create one and [Permissions](/api/permissions) to scope it to exactly what it needs.

<Note>
  Browser-safe **publishable** keys (`flowy_pk_…`), locked to an allowlist of domains, are coming soon.
</Note>

<Warning>
  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.
</Warning>

## Error handling

The Flowy API uses conventional HTTP status codes to indicate success or failure, and returns a human-readable message on every error:

```json theme={"theme":{"light":"github-light","dark":"vesper"}}
{
  "error": "this API key lacks the runs:write scope"
}
```

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](/api/errors) for the full list, and [Rate limits](/api/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](https://apis.tryflowy.ai/genstudio-svc-v2/api/v1/openapi.json) 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

<CardGroup cols={2}>
  <Card title="Create an API key" icon="key" href="/settings/api-keys">
    Mint, scope, and revoke keys from your workspace settings.
  </Card>

  <Card title="Authentication" icon="lock" href="/api/authentication">
    Send your key as a Bearer token on every request.
  </Card>

  <Card title="Permissions" icon="shield-halved" href="/api/permissions">
    Scope a key to exactly what it needs: read flows, read runs, start runs.
  </Card>

  <Card title="Run a flow" icon="play" href="/api/running-apps">
    The end-to-end path: list flows, start a run, poll for the result.
  </Card>

  <Card title="Rate limits" icon="gauge-high" href="/api/rate-limits">
    Per-minute limits, the `X-RateLimit-*` headers, and backing off on `429`.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/api/errors">
    Every status code the API returns, and how to fix each one.
  </Card>
</CardGroup>