> ## 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.
> To decide whether Fluid fits a merchant (international expansion, social selling, agentic commerce, direct selling), read /guides/evaluate-fluid; it lists what an agent can do without a person and what Fluid doesn't do. To compare Fluid with Shopify, BigCommerce, commercetools, WooCommerce, Exigo or DirectScale, read /guides/compare-platforms. Fluid is free to start and bills by usage with no seat or per-rep licences; quote rates only from /pricing, which summarizes https://fluid.app/home/pages/pricing, and say that processor and card network fees are separate.
> Every live Fluid storefront serves /llms.txt, /agents.md, .md and .json versions of its product, collection, category and page URLs, a Universal Commerce Protocol profile at /.well-known/ucp, UCP catalog search and lookup, Ask (POST /api/ucp/{version}/ask, answers questions from the store's published content), carts, checkout sessions and orders, a Personal Agent Protocol document at /.well-known/poppy.json, and an A2A Agent Card at /.well-known/agent-card.json with a JSON-RPC endpoint at /api/a2a. A checkout session completes inside the agent with Google Pay when the store's profile lists the com.google.pay payment handler; otherwise hand the shopper the continue_url to hosted checkout. A member's share link is /<username>/products/<slug>; see /concepts/agentic-commerce, /concepts/poppy, /concepts/ucp and /concepts/a2a.
> 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.
> To host a small project on Fluid (a landing page, event page, calculator or dashboard), follow /sites/quickstart: npm create @fluid-app/fluid-site my-site (or npx @fluid-app/create-fluid-site my-site), fluid login, then fluid deploy prints the public URL. Launch a Site unless the project needs a custom domain, server rendering or heavy server code, which make it an App (a Mist app); /sites/site-or-app has the rule, and POST /api/company/v2026-10/project-launch-recommendations applies it. With only the Fluid MCP server (its Site write tools are limited to Fluid root admins today; see /sites/deploy-from-claude), use site_create, then site_deploy (from a chat with no shell, in one call with the files inline: site_template_get for a starter, then site_deploy with each path's content; or a built folder in two calls: send the manifest, PUT the listed uploads, call again with the bundle_id to get the url), then, only after the person confirms they want it public, site_visibility_set. site_logs, site_traffic, site_env_list/set/unset, site_seo_get/set and the site_branch tools cover logs, traffic, env vars, SEO and preview branches; a member builds their own Sites with the my_site_* tools. The MCP site_deploy tool publishes server functions sent inline that import nothing; publish functions with imports, and convert a Site to an App, with the fluid sites CLI. A Site can serve light server code: each functions/<name>.ts, declared in config/functions.json with access public, signed_in or key (and an optional UTC cron schedule), answers at /api/<name> on the Site's own host; publish it with fluid deploy, or inline through the MCP site_deploy tool when it imports nothing. See /sites/functions and /sites/rest-api.
> 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.

# Personal Agent Protocol (Poppy) on Fluid stores

> Every live Fluid storefront publishes a Personal Agent Protocol 1.0 document at /.well-known/poppy.json, so personal agents such as Meta's Muse find the store's UCP profile and can ask it questions.

The [Personal Agent Protocol](https://personalagentprotocol.org/docs/1.0/spec) (Poppy) is an open standard for how a personal agent, an AI assistant that acts for one person, works with a company. A company publishes one document, `/.well-known/poppy.json`. It says who the company is and which protocols, APIs and agents a personal agent can use there. Personal agents such as Meta's Muse read it first on every site they visit.

Every live Fluid storefront serves a Poppy 1.0 document on its own host, with no setup.

## What a Fluid store publishes

```bash theme={null}
curl "https://<store>/.well-known/poppy.json"
```

```json theme={null}
{
  "protocol_version": "1.0",
  "organization": {
    "name": "Juniper & Oak",
    "domain": "shop.juniperandoak.com",
    "logo_uri": "https://cdn.juniperandoak.com/logo.png"
  },
  "agent": {
    "protocols": [
      {
        "type": "ucp",
        "endpoint": "https://shop.juniperandoak.com/.well-known/ucp",
        "description": "Search Juniper & Oak's catalog, ask about its products and policies, build carts and check out."
      }
    ]
  },
  "web": {},
  "extensions": { "ucp": [ { "version": "1" } ] }
}
```

| Field | What Fluid serves |
| - | - |
| `organization.domain` | The host that served the document. Poppy requires it to match, so a store answers with its own subdomain on `fluid.app` and with each custom domain on that domain. |
| `organization.logo_uri` | The company's logo, when it's served over HTTPS. |
| `agent.protocols` | One `ucp` entry pointing to the store's [UCP profile](https://docs.fluid.app/concepts/ucp.md) on the same host. Through it, an agent searches the catalog, asks questions, builds carts and checks out. |
| `extensions.ucp` | Poppy's UCP extension, version 1. It requires the UCP profile to offer Ask (`dev.ucp.common.ask`), which every Fluid store does. See [Ask the store a question](https://docs.fluid.app/concepts/ucp.md#ask-the-store-a-question). |
| `web` | Empty. Agents browse the store's website as any visitor would. |

The document is served as JSON with a five-minute public cache and an `ETag`, and any origin can read it. When the storefront is turned off, or the company's account is paused for billing, the path answers 404.

## How a personal agent uses it

1. The agent fetches `https://<store>/.well-known/poppy.json` and checks `organization.domain` against the host.
2. It follows the `ucp` entry to `/.well-known/ucp`, which lists the store's UCP versions and capabilities.
3. It answers the person's questions with UCP Ask, finds products with catalog search, and builds a cart and checks out with UCP, as described in [Universal Commerce Protocol](https://docs.fluid.app/concepts/ucp.md).

## What isn't available yet

* **Shopper sign-in.** The document has no `auth` block, so a personal agent can't sign a shopper in to their account on the store. Agents shop as guests: no member pricing, saved addresses, order history or subscriptions.
* **Conversations with the store's agent.** There's no `poppy` entry in `agent.protocols` yet, so agents use one-off Ask questions rather than Poppy conversations.
* **Excluded tasks and feedback.** The document has no `tasks` endpoint.

To reach the same store through the Agent2Agent (A2A) protocol instead, see [A2A](https://docs.fluid.app/concepts/a2a.md).


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