# The Chatfuel API > The mental model behind the GraphQL API a generated app talks to — the hierarchy every operation traverses, the two automation surfaces that are not the same thing, and why the schema ships as a file. Page: https://sdk.chatfuel.com/docs/reference/chatfuel-api Markdown: https://sdk.chatfuel.com/docs/reference/chatfuel-api.md The supergraph has thirteen root query fields, so you reach almost everything by traversing `bot(id:)` and `currentUser` rather than by asking for an entity by its own name. ## The hierarchy [#the-hierarchy] | Level | What it is | How you reach it | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | | `UserAccount` | The Chatfuel login the token belongs to. | `currentUser` | | `Workspace` | The billing container. It holds bots and carries a `botsLimit`. | `currentUser.workspaces`, `currentUser.workspace(id:)` | | `Bot` | One Chatfuel project. Almost every field in the schema hangs off it, and almost every argument list opens with a `botID`. | `bot(id: BotID!)`, `Workspace.bots` | | `ContactScope` | One connected channel. The interface carries an id and nothing else; five types implement it — web widget, WhatsApp phone, Instagram account, TikTok account, Facebook page. | `bot.contactScopes` | | `Contact` | A person inside one scope. | `bot.contactsConnection` | | `Conversation` | The thread with that contact. | `bot.conversation(conversationID:)`, `Contact.conversation` | `Conversation.id` is the contact's id: the backend's primary key for a conversation is `Conversation.ContactID`, exposed as an alias on `id`. Every `conversationID` argument in the schema takes a contact id, and there is no separate conversation identity to look up. ## Automations and Flows are two different surfaces [#automations-and-flows-are-two-different-surfaces] | | Automations | Flows | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | What it configures | How the AI behaves. | Scripted logic on a canvas. | | The chain | `Bot → FuelyAutomation → FuelySetting` | `Bot → Flow → Block → BlockElement` | | Scoping | One base automation per scope, plus custom ones. A scope is a channel and an entry point together — `InstagramPostComments`, `WhatsAppClickFromAds`, `FacebookDirectMessages` — and a setting can inherit from another automation in the same bot. | Per flow. Blocks carry canvas positions and are joined by `Connection`s; a flow names its `startingPointBlock` and its `entryPoints`. | | Typing | `FuelySetting` is an interface with one concrete type per setting. | Strongly typed per plugin. There are no JSON configs. | | Real time | `fuelyAutomationUpdated(botID:)`. | None. The `Subscription` type carries no flow or block field, so you reconcile from mutation results. | ## Everything sendable branches on platform [#everything-sendable-branches-on-platform] ```graphql enum Platform { widget facebook instagram whatsapp tiktok } ``` Message types, send mutations and some fields exist per platform, so you branch on `Conversation.platform` or on `__typename` before you read a message. Field names are disambiguated per platform for the same reason — see [the traps](/docs/reference/chatfuel-api/traps). ## One endpoint per environment, not per account [#one-endpoint-per-environment-not-per-account] Production is `https://panel.chatfuel.com/graphql` for every account; the `botID` inside the operation selects the project. The addresses, the header, the socket and the rate limit are on [transport and auth](/docs/reference/chatfuel-api/transport-auth). ## The schema is a file, not an introspection query [#the-schema-is-a-file-not-an-introspection-query] Introspection is disabled in production, so the bundled SDL is the schema. The SDK carries it at `schema/schema.graphql` — a copy of the Chatfuel dashboard's own schema with billing, Albato, A/B-experiment and debug surfaces dropped, along with every field, argument and union member that referred to a dropped name. `scripts/refresh-schema.ts` reproduces that copy and writes the source commit into the file's header. Codegen reads that file, the operation validator builds from it, and a byte-identical copy ships inside the `chatfuel-core` skill your coding agent reads, so grepping any of the three answers the same question. ## The rest of this section [#the-rest-of-this-section] | Page | What it holds | | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Transport and auth](/docs/reference/chatfuel-api/transport-auth) | The three endpoints, how the token travels on each, what the token is and what it may do, the WebSocket client's behaviour, and 25 requests per second. | | [Errors](/docs/reference/chatfuel-api/errors) | The envelope, the `DefinedErrorCode` family, and the four rules that catch people. | | [Pagination](/docs/reference/chatfuel-api/pagination) | Relay cursors with per-connection scalars, the direction flip on message history, and the connections that take pagination arguments and ignore them. | | [Files and tasks](/docs/reference/chatfuel-api/files-and-tasks) | REST upload then `FileID`, the `File` lifecycle, and `Task` progress tracking. | | [Traps](/docs/reference/chatfuel-api/traps) | The cross-domain sharp edges, in full. |