Flow API reference
The Platform-owned /api/flow/v1 surface — catalog, connections, auth, runtime, policies, activity — pinned to flow-contracts v2.
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.
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.
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):
curl -sS -b session.cookie https://platform.upcube.ai/api/flow/v1/connectionsAuth 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):
curl -sS -b session.cookie https://platform.upcube.ai/api/flow/v1/connections/conn_gone