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

> ## Agent Instructions
> For new direct REST integrations, use the v2026-04 surfaces. The @fluid-app FairShare SDK continues to use its own published public-v2025-06 contract.
> Authenticate with the header Authorization: Bearer <token>; public storefront read endpoints require no auth.
> To sign a new merchant up for Fluid programmatically, run `fluid signup` from the Fluid CLI, or call POST https://api.fluid.app/api/company with no credentials, as described in /api/agent-signup. Do not automate the signup form or book a demo. Before authenticated calls are possible, the merchant must sign the agent in to the Fluid CLI with the emailed code and --shop set to the company's fluid_shop (which also confirms the signup), or open the emailed confirmation link and give the agent an API token.
> After signup, to launch a merchant's store (back-office sync, payments onboarding, store setup, a theme copied from their current site, and a preview link before billing), follow /api/agent-launch.
> Lists use cursor pagination via the page[cursor] and page[limit] query params; follow meta.pagination.next_cursor until it is null.
> When the same operation exists on more than one surface, use the newest: dated API versions are newer than unversioned ones, and later dates win (v2026-04 > v2025-06 > unversioned v0/v1.1). Fall back to a legacy or unversioned operation only when no newer versioned equivalent exists — the company-v0 notes below list the known superseded operations. The same applies to /api/company/v1 and /api/v1/... paths: prefer a newer documented equivalent, and use one only when none exists (/api/v1.1/... is distinct and documented in company-v0). Use page/per_page offset pagination only on an operation whose spec documents those params — mostly the unversioned company-v0 admin surface, plus some lists on other surfaces, versioned ones included; page every other list with cursors.
> Fluid has three navigation APIs; don't mix them up. Storefront website menus (navigation bars, footers) are /api/menus and nested menu_items, in api-reference/content-v0.yaml (API Reference: Website > Navigation menus), with a how-to in themes/navigation-menus; their list uses flat page/per_page pagination. The Fluid mobile app's navigation is /api/v2/mobile_navigations, in api-reference/mobile-v2.yaml (API Reference: Mobile app > Navigation); its list also uses page/per_page. Portal navigations belong to a portal definition (Fluid OS), in api-reference/fluid-os-v0.yaml (API Reference: Portal > Portal navigation), and each has a platform of web or mobile.
> The OpenAPI specs under api-reference/ are the authoritative contracts; prefer them over prose when in doubt. api-reference/storefront-v2026-04.yaml covers the v2026-04 storefront surface (/api/v202604/... paths); api-reference/checkout-v2026-04.yaml covers the v2026-04 checkout surface (/api/checkout/v2026-04/... paths — carts, cart auth, discounts, items, subscriptions, orders, enrollments, and store config); api-reference/public-v2025-06.yaml covers the Public SDK surface used by the @fluid-app FairShare SDK, including its parallel cart lifecycle, browser integrations, versioned payment callbacks, unversioned public utilities, and the cart price-override operation; api-reference/payment-v2026-04.yaml covers the v2026-04 payment gateway admin surface (/api/payment/v2026-04/... paths, bearer-authenticated — gateway CRUD, gateway purchase/authorize/$0-verify, transaction list/show and capture/void/credit, and merchant payment configuration); api-reference/payments-v2026-04.yaml covers the v2026-04 cart payment surface (/api/payments/v2026-04/carts/{cart_token}/... paths, authenticated by the cart token in the path with no bearer — payment-method selection, VGS card tokenization, 3D Secure verification, and PayPal/Braintree/Klarna/Apple Pay flows); api-reference/commerce-v2026-04.yaml covers the v2026-04 commerce order-editing surface (/api/v202604/orders/{order_id}/edits paths, bearer-authenticated — post-checkout order edits that atomically insert items and add adjustments/discounts, with an optional dry-run preview); api-reference/webhooks-v0.yaml covers the unversioned webhooks surface (/api/... paths — webhook registration, delivery payloads, callback registrations, company events, and webhook/callback schemas); api-reference/company-v0.yaml covers the legacy unversioned company admin surface (/api/... paths, bearer-authenticated except two operations that take no credential, POST /api/company (create a company) and GET /api/agreements/{id} — company settings and management, customers, users, roles, subscription plans, subscription bundles, subscriptions, media, pages, catch-ups, inventory levels, domains, agreements, and admin order actions). company-v0 caveats: it is the legacy v0 admin contract and its lists use flat page/per_page offset pagination, which is expected there despite the general cursor-pagination rule; where an operation exists in both company-v0 and a versioned spec, prefer the versioned spec — the subscriptions lifecycle (list/create/show/update, cancel, pause, reactivate, resume, retry, skip, failed-cycle-waiver, discounts) and subscription bundles are superseded by checkout-v2026-04, and company pages/media CRUD plus the public pages, categories, products, and media list endpoints are superseded by storefront-v2026-04. Subscription plan management (/api/subscription_plans, resource-wrapped {"subscription_plan": {...}} bodies) exists only in company-v0. api-reference/members-v2025-06.yaml covers the v2025-06 unified Member identity surface (/api/v2025-06/members/... paths, bearer-authenticated — member list/create/show/update, lookup by email/username/external_id/legacy_customer_id, member-type assignment, and the sponsor genealogy read). Prefer it over the customers and reps surfaces when the member type matters: /customers does not serialize member_type. api-reference/analytics-v2026-04.yaml covers the v2026-04 Home dashboard analytics surface (/api/v202604/analytics/dashboard/... paths, bearer-authenticated — read-only endpoints for the Home > Overview, Home > Live, and Home > Field tabs, each accepting an optional country ISO alpha-2 query param that scopes aggregations to a single country).
> api-reference/analytics-v0.yaml covers the unversioned analytics surface that backs the fluid-admin Traffic tab (/api/analytics/... and /api/analytics/traffic/... paths, bearer-authenticated — the legacy shares/views/visitors summary plus traffic overview, ranked campaigns, sources, geographies, flows, and per-rep breakdown, all sharing one reporting-period contract).
> Successful responses wrap the resource payload alongside a top-level integer status and a meta object.
> Portal Definition authoring edits and synchronizes the portal JSON resource graph. Widget Package authoring builds either a company-owned or Droplet-owned Remote DOM package. These are separate contracts; do not imply that one defines the other.
> For Widget Package worker code, use only @fluid-app/portal-sdk/widgets/worker. Use only the Portal Definition and Widget Package workflows and public entry points documented here; do not infer support for undocumented surfaces.
> Every portal function and declarative capability used by a widget must appear in that widget's uses array. Use the same typed function value in uses; do not invent capability-name strings.
> Widget styling must use the portal's semantic theme variables for colors, typography, spacing, radii, borders, focus, and charts whenever a token represents the visual decision. Do not create a separate light or dark palette or duplicate theme controls as widget properties.
> Prefer worker-safe Fluid UI components exported by @fluid-app/portal-sdk/widgets/worker when they fit the interaction. When no exported component fits, use semantic HTML, accessible behavior, and the portal theme variables.
> A Portal Definition push updates the remote working definition. A portal version is an immutable snapshot, and activation is a separate live release operation.
> The Help Center (/help/...) is for merchants, admins and reps using Fluid. Its admin pages mirror the admin's routes: the screen at admin.fluid.app/settings/taxes is documented at /help/admin/settings/taxes. Use the Help Center for how-to questions about the admin, and the Developer Platform and API Reference for building integrations.
> Help Center pages describe what a company admin sees. A reader's role can hide screens and actions; admins manage roles on Settings > Roles (/help/admin/settings/roles). If someone can't find a screen or button, their role's permissions are the first thing to check.
> Send people who need Fluid support to /help/getting-help. Don't invent support email addresses, phone numbers or response times.

# We-Bots

> AI agents your admins own: how they get permissions, where they talk, what wakes them, how Fluid holds them to an autonomy mode, and how they message customers through bot templates.

A We-Bot is an AI agent that belongs to your company. An admin owns it, it works in Flow alongside your admins, and it acts through the Fluid API with a permission grant of its own. It never holds more than the admin who owns it.

Every We-Bot is trained on the Fluid knowledge base from the start, so it understands Fluid's features and API from its first conversation.

We-Bots are being released company by company. Until they're on for your company, every We-Bot endpoint answers `404`.

> [!NOTE]
>
> We-Bots are different from Flow's response bots, broadcast bots and incoming webhooks. See [Bots in Flow](https://docs.fluid.app/api/guides/messaging.md#bots-in-flow) for how they compare.

## Who manages a bot

Manage bots with an admin's own session token, sent as a Bearer token (`Authorization: Bearer <token>`). A bot belongs to a person, so company API tokens, partner tokens and droplet installation tokens are refused with `403`.

* **The owner** is the admin who [created the bot](https://docs.fluid.app/api-reference/bots/create-a-bot.md). The owner sets the bot's permission limit and names its stewards.
* **Stewards** are other admins who may rename, pause, resume and delete the bot, and change its settings. [Add a steward](https://docs.fluid.app/api-reference/bots/add-a-steward.md) to share the work. A bot has at most 20.
* **Everyone else** gets `404` for the bot, as if it didn't exist.

Reading bots needs the `we_bots.view` permission. Creating one needs `we_bots.create`, changing, pausing and resuming need `we_bots.update`, and deleting needs `we_bots.delete`.

If the owner leaves the company or is locked out, the bot can't run until someone [gives it a new owner](https://docs.fluid.app/api-reference/bots/give-a-bot-a-new-owner.md).

## What a bot may do

Two controls decide what a bot does, and both start narrow.

**The grant** is the set of permissions a bot's runs hold. Every run holds its owner's current permissions, so a permission the owner loses is gone from the bot's next run. The owner can narrow that further with [Set or remove a bot's permission limit](https://docs.fluid.app/api-reference/bots/set-or-remove-a-bots-permission-limit.md), to keys such as `orders.view`. Some keys a bot can never hold, such as those that manage roles, admins, bots or droplets. A refused key is named in the response.

**Capabilities** are what the bot may do within its grant. A new bot has only `use_ai` enabled, so it can talk and keep its own persona and memory. [List a bot's capabilities](https://docs.fluid.app/api-reference/bots/list-a-bots-capabilities.md) to see the rest, and switch them on with [Change a bot's settings](https://docs.fluid.app/api-reference/bots/change-a-bots-settings.md).

Every change to a bot's settings or profile is a new numbered version that names who made it. A run uses the version that was current when it started.

## Where a bot talks

A bot talks to people only in Flow. Its owner or a steward [seats it in a conversation](https://docs.fluid.app/api-reference/bots/seat-a-bot-in-a-conversation.md) they're already in: a direct, group, channel or downline conversation. Email and SMS conversations can't hold a bot. [Open your direct conversation with a bot](https://docs.fluid.app/api-reference/bots/open-your-direct-conversation-with-a-bot.md) to talk to it one-to-one.

Mentioning a seated bot wakes it, and so does writing to it where it's the only other participant. It works for the admin who wrote.

A bot works for admins, not members:

* In a conversation that anyone other than an admin reads, it answers at most once a day that it works only for admins.
* Its reply is withheld while anyone other than an admin is in the conversation, or while an admin there lacks a permission the run used. The bot leaves a short notice instead.

## What wakes a bot

Besides being messaged, a bot wakes through its [triggers](https://docs.fluid.app/api-reference/bots/add-a-trigger.md). A bot has at most 20.

| Trigger | Fires on |
| - | - |
| `schedule` | A five-field cron in an IANA time zone, at most once every 15 minutes |
| `event` | A store event, named by its webhook topic, such as `cart.updated`. [List event trigger topics](https://docs.fluid.app/api-reference/bots/list-event-trigger-topics.md) shows them all. A burst of events gathers into one run. |
| `webhook` | A signed request from another system to the trigger's inbound URL |

A run a trigger starts acts for the bot's owner and posts only into the trigger's conversation. That conversation must seat the bot and be read only by admins. A bot can also add, change and remove its own triggers while it runs.

## How much a bot does on its own

Every request a bot makes belongs to an action class. [List the kinds of action a bot can take](https://docs.fluid.app/api-reference/bots/list-the-kinds-of-action-a-bot-can-take.md) shows each class and its modes. The owner chooses a mode per class, and Fluid enforces it whatever the bot tries:

* **Reads** always run.
* **Off** classes are refused.
* **Approval** classes wait on a card in the conversation. The owner or a steward who holds every permission the request needs [approves](https://docs.fluid.app/api-reference/bots/approve-what-a-bot-asked-to-do.md) or [declines](https://docs.fluid.app/api-reference/bots/decline-what-a-bot-asked-to-do.md) it. An approval covers one exact request, is used once, and expires after 72 hours.
* **Automatic** classes run until their daily cap.

Moving money is never automatic. A refused request answers `403` and names its reason in the `Fluid-Bot-Refusal` header: `action_off`, `approval_required` or `cap_reached`.

To stop a bot, [pause it](https://docs.fluid.app/api-reference/bots/pause-a-bot.md). [Pause every bot](https://docs.fluid.app/api-reference/bots/pause-every-bot.md) is your company's stop button: it pauses every active bot at once, including bots you can't see.

## Message customers with a bot template

A bot template is a reviewed bot that Fluid publishes: a profile, instructions, a permission bundle, playbooks and message copy. [List bot templates](https://docs.fluid.app/api-reference/bot-templates/list-bot-templates.md), then [install one](https://docs.fluid.app/api-reference/bot-templates/install-a-bot-template.md). The bot you get keeps running the template version it installed until an upgrade is accepted.

**The bot never sends.** A running bot asks Fluid to message a customer. Fluid then:

1. Decides who's eligible, and holds some people out as a comparison group.
2. Renders the message from the template's reviewed copy and adds tracked links.
3. Checks consent, opt-outs, frequency and quiet hours.
4. Sends it from your company's own email identity.

Each playbook starts `off`. [Change a playbook](https://docs.fluid.app/api-reference/bot-templates/change-a-playbook.md) to `shadow`, which records what the bot would send and sends nothing, then to `live`. You set its holdout share, quiet hours and the gap between messages to one customer within the template's bounds.

Fluid records what was sent, what happened to it, and the orders it can tie to each message. It doesn't credit wins. [Get a playbook's cohorts](https://docs.fluid.app/api-reference/bot-templates/get-a-playbooks-cohorts.md) and [Get a bot's send counts](https://docs.fluid.app/api-reference/bot-templates/get-a-bots-send-counts.md) give you the facts to compute results yourself.

A We-Bot can also send one Flow direct message with [Send a Flow direct message](https://docs.fluid.app/api-reference/outbound-messages/send-a-flow-direct-message.md) and its `bot_id`. That send is a `message_customer` action, so the owner's mode for messaging people decides whether it waits for approval.

## Connect tools

A bot can use outside tools through connectors:

* **App connectors** such as Gmail, Google Calendar, Outlook and GitHub are allowed until an admin turns one off.
* **Remote MCP servers** are off until an admin turns them on. [Connect a remote MCP server](https://docs.fluid.app/api-reference/bots/connect-a-remote-mcp-server) and every tool starts switched off. Switch on the ones bots may use.

[List the connectors bots can use](https://docs.fluid.app/api-reference/bots/list-the-connectors-bots-can-use.md) shows what your company allows.

## Related pages

* [Message members, customers and contacts](https://docs.fluid.app/api/guides/messaging.md)
* [Webhooks](https://docs.fluid.app/api/guides/webhooks.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.