# Flow API reference

The Flow API (`/api/flow/v1`, served from Platform) is the control plane behind Connected Apps. Platform owns it; Chat consumes it through a delegated server-to-server transport and never reads Flow state directly.

Pinned contract: **flow-contracts v2** (18 files, sha256 release manifest). This reference describes v2 only.

:::note
The Platform API is not open for public access. Requests outside an authenticated product session answer `503 PLATFORM_CLOSED`; run the recorded fixtures below instead of calling a live host.
:::

## Auth

- Cookie session (signed-in user), or a verified delegated product reader (actor-scoped, product HMAC + user assertion).
- Unauthenticated calls fail closed. Auth failures return typed JSON codes, never HTML.
- All management responses are `private, no-store`.

:::warning
The examples below run against **recorded fixtures**, not a live host: Flow v1 is authenticated and its providers are still certifying. Fixture responses are contract-checked by the docs example gate.
:::

## Catalog

| Endpoint | Method | Purpose |
|---|---|---|
| `/api/flow/v1/catalog/apps` | GET | List apps in the catalog |
| `/api/flow/v1/catalog/apps/[slug]` | GET | One app's catalog entry |
| `/api/flow/v1/catalog/connectors/[id]` | GET | One connector's catalog entry |
| `/api/flow/v1/catalog/connectors/[id]/connect-options` | GET | Setup options for the connect sheet |

Listing states stay distinguishable: catalog-only, setup-required, partial, and certified are never collapsed into one "available".

## Connections

| Endpoint | Method | Purpose |
|---|---|---|
| `/api/flow/v1/connections` | GET | The caller's active + attention connections |
| `/api/flow/v1/connections/[id]` | GET | One connection with sibling impact |
| `/api/flow/v1/connections/[id]` | PATCH | Update one connection |
| `/api/flow/v1/connections/[id]/disconnect` | POST | Revoke the binding |
| `/api/flow/v1/connections/[id]/reconnect-start` | POST | Re-authorize or extend one connection |
| `/api/flow/v1/connections/[id]/standing-approvals` | GET, POST | List or create standing approvals |

Example (recorded fixture):

```bash exec GET fixture:flow/connections-list expect:200 schema:flow-connections
curl -sS -b session.cookie https://platform.upcube.ai/api/flow/v1/connections
```

## Auth endpoints

| Endpoint | Method | Purpose |
|---|---|---|
| `/api/flow/v1/auth/start` | POST | Start an OAuth connect flow |
| `/api/flow/v1/auth/callback` | GET | Provider OAuth callback |
| `/api/flow/v1/auth/credentials` | POST | Submit API-key / PAT credentials |
| `/api/flow/v1/auth/select` | POST | Choose account / workspace mid-flow |
| `/api/flow/v1/auth/completion` | GET | Complete the flow and land the grant |

Auth kinds: `oauth2`, `github_app_user`, `api_key`, `pat`, `service_account_jwt`, `mcp_oauth`, `basic`. Connection and grant ids are injected server-side from the path — never trusted from the client.

## Runtime

| Endpoint | Method | Purpose |
|---|---|---|
| `/api/flow/v1/runtime/resolve` | POST | Resolve tools for an invocation |
| `/api/flow/v1/runtime/invoke` | POST | Invoke a tool (may pause for approval) |
| `/api/flow/v1/runtime/resume` | POST | Resume after approval / connection / account |

Pauses are typed: `connection_required`, `reauth_required`, `scope_required`, `approval_required`, plus account choice, admin consent/policy, denial, provider outage/rate-limit, and unknown-outcome.

## Policies, requests, activity, me, events

| Endpoint | Method | Purpose |
|---|---|---|
| `/api/flow/v1/policies` | GET | Policy surface |
| `/api/flow/v1/policies/me` | GET, PUT | Caller's policy view and update |
| `/api/flow/v1/policies/rules` | POST | Create a rule |
| `/api/flow/v1/policies/rules/[id]` | DELETE | Delete one rule |
| `/api/flow/v1/policies/tenant-settings` | PUT | Tenant settings |
| `/api/flow/v1/requests` | GET, POST | Connector requests |
| `/api/flow/v1/activity` | GET | Activity trail |
| `/api/flow/v1/me` | GET | Caller view |
| `/api/flow/v1/events/[source]` | POST | Signed provider events |

Admin endpoints (`/api/flow/v1/admin/*`) are authorized-admin only and out of scope for this reference. Approvals stay at `/api/platform/approvals`.

## Errors

Closed code table (`FLOW_ERROR_CODES`, user-safe messages, no secrets in slots):

`POLICY_BLOCKED` `MISSING_SCOPE` `NEEDS_REAUTH` `ADMIN_POLICY_BLOCKED` `ACCOUNT_AMBIGUOUS` `APPROVAL_REQUIRED` `APPROVAL_MISMATCH` `APPROVAL_EXPIRED` `APPROVAL_DENIED` `RATE_LIMITED` `ROUTE_UNAVAILABLE` `PROVIDER_UNAVAILABLE` `PROVIDER_ERROR` `TIMEOUT` `UNKNOWN_OUTCOME` `TOOL_CHANGED` `TOOL_NOT_FOUND` `CONNECTION_NOT_FOUND` `CREDENTIALS_UNAVAILABLE` `FLOW_DISABLED` `CONNECTOR_DISABLED` `OUTPUT_REJECTED` `STATE_INVALID` `USER_DENIED` `SCOPE_NOT_GRANTED` `INVALID_GRANT` `SIGNATURE_INVALID` `VALIDATION_FAILED`

Example (recorded fixture):

```bash exec GET fixture:flow/connection-missing expect:404 schema:flow-error
curl -sS -b session.cookie https://platform.upcube.ai/api/flow/v1/connections/conn_gone
```

## Next steps

- [Connected Apps overview](/docs/connected-apps/overview)
- [Managing connections](/docs/connected-apps/managing-connections)
- [Model Intelligence API](/docs/api/model-intelligence)