# ChatFood Flow API

> Flow.API is the control plane of ChatFood: it connects Facebook Messenger, Instagram Direct and Telegram pages, stores conversation flows (a JSON "script" of routes and nodes executed by the ChatFood bot), segments leads, schedules broadcasts and journeys, and exposes delivery metrics. This file is the entry point for AI agents and automations that want to build flows, trigger broadcasts or read results through the HTTP API.

Base URL: https://api.chatfood.app. The public API is versioned in the path: every route is under `/v1` (for example `GET /v1/pages`), in lower case with hyphens. Every request and response is JSON in camelCase; errors are `application/problem+json`. Enums are serialized as integers. Lists take `limit`, `cursor` and `sort` and answer `{items, nextCursor}` (plus `total` when the list counts its filter). `PUT` replaces a resource; `PATCH` changes only the fields sent, and an explicit `null` clears an optional field. Authenticate with an API token (`Authorization: Bearer cf_live_...` or `X-Api-Key: cf_live_...`) created by a logged-in user at `POST /v1/api-tokens` with scopes such as `broadcasts:write` or `metrics:read`, or with the 18-hour user JWT from `POST /Auth`. Full details, payload contracts and the flow script specification are in the full guide below.

## Docs

- [Full guide for agents (llms-full.txt)](https://api.chatfood.app/llms-full.txt): authentication, multi-account model, pages and providers, the complete flow script JSON contract (routes, node types, buttons, variables, awaitReply, ConversationSettings, per-provider support), flow lifecycle, broadcasts, journeys, leads and tags, metrics (GraphQL), errors and limits.
- [Agent manifest (agent.json)](https://api.chatfood.app/.well-known/agent.json): machine-readable summary of authentication, capabilities and the endpoints behind each capability.
- [OpenAPI 3 for API tokens](https://api.chatfood.app/swagger/agents/swagger.json): only the `/v1` routes a token can call, each with `x-required-scope`. Generated with the same rule the server enforces; start here.
- [API reference](https://api.chatfood.app/docs) and [Postman collection](https://api.chatfood.app/docs/postman.json): built from the same document.
- [OpenAPI 3 document](https://api.chatfood.app/swagger/v1/swagger.json): for user sessions. It still lists the routes that existed before `/v1`, marked deprecated with their successor; do not use them.
- [GraphQL endpoint](https://api.chatfood.app/graphql): read-only analytics (`dashboard`, `flowMetrics`, `leadFunnel`, `broadcastCalendar`, `profileCalendar`, `analytics`, `websiteMetrics`). Introspection is enabled. No mutations: every write goes through REST.

## Quick start

- Authenticate: `POST /Auth` with `{"username": "<email>", "password": "<password>"}` returns `{"token": "<jwt>"}`. Then create a long-lived credential: `POST /v1/api-tokens` with `{"name": "my agent", "scopes": ["flows:write", "broadcasts:write", "metrics:read"], "accountId": "<optional account guid>", "expiresAt": "<optional ISO date>"}`. The `token` field of the response (`cf_live_...`) is shown once; store it and send it as `Authorization: Bearer cf_live_...`. A route outside the token scopes answers `403` naming the missing scope.
- Discover scope: `GET /v1/me` (who am I, which accounts, which permissions in each), `GET /v1/accounts`, `GET /v1/pages?fields=connectedApps` (pages with ids and provider). Pages are always addressed by their GUID. When the credential reaches more than one account, pass `?accountId=`.
- Build a flow: `POST /v1/schemas?accountId=<guid>` with `name`, `provider` (1 Facebook, 2 Instagram, 3 Telegram), `channelTrigger`, `pageIds`, `messageTriggers`, and `script` (a JSON string; see the script contract in the full guide). Publish with `PATCH /v1/schemas/{schemaId}` and `{"status": 1}`.
- Send a broadcast: `POST /v1/broadcasts` with `schemaId` (must be published), `pageIds`, `type` (5 Automatic is the safe default on Meta, 6 All on Telegram), optional `tags`, `recencyFilter`, `scheduledTo` (page-local wall clock) or `isImmediate: true`. Track it with `GET /v1/broadcasts/{broadcastId}` and `GET /v1/broadcasts/{broadcastId}/executions`.
- Read results: GraphQL `dashboard` / `flowMetrics(schemaId: ...)` or REST `GET /v1/schemas/{schemaId}/metrics?broadcastId=...`, `GET /v1/alerts/summary`, `GET /v1/alerts`.
- Register a conversion dataset: `POST /v1/meta/datasets?accountId=` with `name`, `metaDatasetId`, `accessToken`, `appliesToAllPages` or `categoryIds` (scope `pixels:write`).
- Ready to paste curl recipes for these tasks are in section 16 of the full guide.

## Limits and errors

- 120 requests per minute per token; over it, `429` with `Retry-After` (wait and continue).
- `401`: token missing, expired or revoked (stop, ask for a new one). `403` with a scope in `detail`: ask for that scope. `403` without one: resource of another account. `400`: fix the payload.
- Least privilege, one token per account with an expiry, never log the token, confirm with a human before writes that reach leads. Details in sections 17 and 18 of the full guide.

## Optional

- [Repository docs: broadcast pipeline](https://github.com/GrowChat/Flow.API/blob/main/docs/BROADCAST_SYSTEM_ANALYSIS.md)
- [Repository docs: utility templates](https://github.com/GrowChat/Flow.API/blob/main/docs/UTILITY_TEMPLATE_SYSTEM.md)
- [Repository docs: profiles (leads)](https://github.com/GrowChat/Flow.API/blob/main/docs/PROFILE_SYSTEM.md)
- [Repository docs: delayed messages](https://github.com/GrowChat/Flow.API/blob/main/docs/DELAY_SYSTEM.md)