> ## 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 ; 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. # Build member sites with the APIs > Build, publish, share and oversee member sites without the CLI: the member API and the company API, which credentials each takes, the file and page APIs, and every operation in the API Reference. The [`fluid member-site` CLI](https://docs.fluid.app/member-sites/cli) is a client of two APIs. You can call them yourself to build a member site from your own code, a droplet or a script. This page covers which API to use, how to authenticate, how the file and page APIs behave, and where to find each operation. It doesn't restate request or response schemas: each operation's generated page in the API Reference holds those. > [!NOTE] > > Member sites must be turned on for your company by Fluid. Until they are, every request to either API answers `404`. To ask for them, [contact support](https://docs.fluid.app/help/getting-help.md). ## Choose the API The owner of a site decides which API builds it. | Owner | API | Base path | Credential | | - | - | - | - | | A member | The member API | `/api/member/v2026-10/sites` | The member's own token | | The company | The company API | `/api/company/v2026-10/member-sites` | A signed-in company admin | * **The member API reaches only the signed-in member's own sites.** The one exception is copying, which also reaches a published site shared with the member with `copy` permission. A site another member owns, a site in another company and a malformed id all answer `404`. A site is addressed by its public `id`, never by a numeric id. * **The company API reaches every site in the company.** An admin lists, reads, takes down, deletes and copies a member's site, and can list and restore its versions. An admin builds a company site: its files, pages and publishing. * **An admin can't change a member's site.** For a member's site, the company API's file, page and publish routes answer `403`, and its routes that create a branch or a share answer `404`. The owner builds it. The CLI follows the same rule: see [Choose the login](https://docs.fluid.app/member-sites/cli.md#choose-the-login). Send the credential as a Bearer token to `https://api.fluid.app`. ## Authenticate ### The member API The member API acts as the signed-in member. The credential alone decides which member and which company a request is about. Its credentials are the member's own: an opaque member token, a member session JWT, a portal JWT linked to a membership in that company, or a verified One Auth identity access token. See [Member APIs](https://docs.fluid.app/api/member-apis.md#credentials). ```bash theme={null} curl "https://api.fluid.app/api/member/v2026-10/sites" \ -H "Authorization: Bearer $MEMBER_TOKEN" ``` * **It refuses company, partner, public and droplet installation tokens.** It also refuses an admin credential, and a credential for a member who is also an admin of that company. That is why the CLI says a member who is an admin builds company sites only. * **It takes a bearer token only.** A request on the same-origin cookie mount is refused with `403`, even with a valid member session, because a script on your company's storefront shares that origin. * **A member session JWT and a portal JWT are read-only.** A write with either answers `403`. Use a member token to build. The credential that order and subscription emails carry is a member session JWT. It is also refused on the account menu, the shares and the share-target search. * **Any member can build.** A member needs no particular member type to own sites. ### The company API The company API takes a company admin credential. Reading needs the `application_themes.view` permission and writing needs `application_themes.update`, the permissions the theme API uses. * **A write needs a signed-in admin.** A company API token, a droplet installation token and any other credential with no user can read, and every write answers `403`. * **A company API token reads sites, pages, versions, shares, branches and the featured list.** It can't read files, which hold a site's code, and it can't preview a draft. * **A droplet installation token with the `website` scope can read** sites, pages and the featured list, and versions when its installation role grants `application_themes.view`. It is refused on files, shares and branches. * **An OAuth client token is refused on shares and branches**, whatever its scopes. See [Authentication](https://docs.fluid.app/api/authentication.md) for the token types. ### Know the order of the checks A refused credential answers `401` or `403` before anything else, so a refused credential never learns whether member sites are on. A valid credential for a company without member sites then answers `404`. A `404` can therefore mean the feature is off, the site is missing, or the site belongs to someone else. ## Build a member's site This builds a site with the member API: create it, write a layout, add a page and publish. The CLI does the same steps from a folder. ```bash theme={null} # Create the site. It starts as a private draft. curl -X POST "https://api.fluid.app/api/member/v2026-10/sites" \ -H "Authorization: Bearer $MEMBER_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Riley'\''s Shop", "visibility": "private" }' # Write a layout. $SITE_ID is the site's id from the response above. curl -X PUT "https://api.fluid.app/api/member/v2026-10/sites/$SITE_ID/files/layouts/site.liquid" \ -H "Authorization: Bearer $MEMBER_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "content": "
{{ content_for_layout }}
", "must_not_exist": true }' # Add a page and its content. curl -X POST "https://api.fluid.app/api/member/v2026-10/sites/$SITE_ID/pages" \ -H "Authorization: Bearer $MEMBER_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "slug": "/", "title": "Home", "published": true, "content": "

Welcome

" }' # Publish. The request has no body. curl -X POST "https://api.fluid.app/api/member/v2026-10/sites/$SITE_ID/publish" \ -H "Authorization: Bearer $MEMBER_TOKEN" ``` A member's site opens at `/accounts/rileys-shop` once it is published and the member can open it. See [Share a member site](https://docs.fluid.app/member-sites/sharing.md). The member API's bodies are plain JSON objects, and its responses carry the record under `data`. The company API wraps its bodies and responses in a named key instead: `member_site`, `member_site_file`, `member_site_page`, `member_site_share` and so on. A company site is created with `{ "member_site": { "name": "Fall Launch", "visibility": "public" } }`. The generated page for each operation shows its exact body. ## Use the file API A site's files have theme-style paths with no subfolders: `layouts/`, `sections/`, `snippets/`, `pages/`, `assets/` and `config/`. [Pages and menus](https://docs.fluid.app/member-sites/pages-and-menus.md) and [Build pages with Liquid](https://docs.fluid.app/member-sites/templates.md#know-the-folder) describe what each holds. * **One call creates and replaces.** [Write a site file](https://docs.fluid.app/api-reference/site-files/write-a-site-file.md) takes the whole new content of the file at the path in the URL. * **Every file has a `version`.** Send it back to write the file only if it hasn't changed since you read it. Send `must_not_exist` to create a file only if the path is free. Send one of the two, not both. With neither, the write replaces whatever is there and the last write wins. A stale `version`, or a file that exists under `must_not_exist`, answers `409`, and nothing is written. * **`config/settings.json` is versioned by the settings' `lock_version`.** It moves when a page changes or when `config/menus.json` is written, so read the settings again before a versioned write. * **A page's file must exist before you write it.** Add the page first. Pages can't be removed through the file API: use [Remove a page](https://docs.fluid.app/api-reference/site-pages/remove-a-page.md). * **Writing a config file does more than save it.** `config/menus.json` replaces every menu, and `config/pages.json` adds, changes and removes pages to match it. `config/access.json` is a member site's draft declaration, and a company site refuses it. * **Assets are text only.** An asset is css, js, json, txt or html, and isn't empty. * **Layouts, sections, snippets and pages are drafts** until you publish. See [Know what is live at once](https://docs.fluid.app/member-sites/pages-and-menus.md#know-what-is-live-at-once). [List a site's files](https://docs.fluid.app/api-reference/site-files/list-a-sites-files.md) returns each file's metadata without its content, a cursor page at a time: send `page[cursor]` and `page[limit]`, and follow `meta.pagination.next_cursor` until it is `null`. A page holds 25 files by default and at most 100. A cursor works only for the site that issued it. A bad cursor answers `400` from the member API and `422` from the company API. ## Use the page API The page API changes one page and its content in one step. A site holds at most 50 pages, so the page list isn't paged. A member holds at most 25 sites, so that list isn't paged either. The company's list of sites is paged with `page[cursor]` and `page[limit]`, and filters with `filter[owner_kind]` and `filter[status]`. Send the `lock_version` you last read when you change or remove a page or a site, and the request answers `409` if it changed since. Without it the change is applied to the current record. ## Preview a draft The preview operations return a site's draft as HTML or text, so you can check a page before you publish. They take a bearer token. Only the owner sees a member's draft, and a company site's draft needs a signed-in admin. See [Preview the draft](https://docs.fluid.app/member-sites/publishing.md#preview-the-draft). ## Find every operation The generated pages hold each operation's parameters, bodies and responses. ### Sites | Task | Member API | Company API | | - | - | - | | List sites | [List the member's sites](https://docs.fluid.app/api-reference/sites/list-the-members-sites.md) | [List member sites](https://docs.fluid.app/api-reference/member-sites/list-member-sites.md) | | Create a site | [Add a site](https://docs.fluid.app/api-reference/sites/add-a-site.md) | [Create a company site](https://docs.fluid.app/api-reference/member-sites/create-a-company-site.md) | | Read a site | [Show a site](https://docs.fluid.app/api-reference/sites/show-a-site.md) | [Get a member site](https://docs.fluid.app/api-reference/member-sites/get-a-member-site.md) | | Change a site | [Change a site](https://docs.fluid.app/api-reference/sites/change-a-site.md) | [Change a member site](https://docs.fluid.app/api-reference/member-sites/change-a-member-site.md) | | Delete a site | [Delete a site](https://docs.fluid.app/api-reference/sites/delete-a-site.md) | [Delete a member site](https://docs.fluid.app/api-reference/member-sites/delete-a-member-site.md) | | Take a site down | Not available | [Take a member site down](https://docs.fluid.app/api-reference/member-sites/take-a-member-site-down.md) | | Copy a site | [Copy a site](https://docs.fluid.app/api-reference/sites/copy-a-site.md) | [Copy a member site](https://docs.fluid.app/api-reference/member-sites/copy-a-member-site.md) | ### Files, pages and preview | Task | Member API | Company API | | - | - | - | | List files | [List a site's files](https://docs.fluid.app/api-reference/site-files/list-a-sites-files.md) | [List a site's files](https://docs.fluid.app/api-reference/member-site-files/list-a-sites-files.md) | | Read a file | [Show a site file](https://docs.fluid.app/api-reference/site-files/show-a-site-file.md) | [Show a site file](https://docs.fluid.app/api-reference/member-site-files/show-a-site-file.md) | | Write a file | [Write a site file](https://docs.fluid.app/api-reference/site-files/write-a-site-file.md) | [Write a site file](https://docs.fluid.app/api-reference/member-site-files/write-a-site-file.md) | | Remove a file | [Remove a site file](https://docs.fluid.app/api-reference/site-files/remove-a-site-file.md) | [Remove a site file](https://docs.fluid.app/api-reference/member-site-files/remove-a-site-file.md) | | List pages | [List a site's pages](https://docs.fluid.app/api-reference/site-pages/list-a-sites-pages.md) | [List a site's pages](https://docs.fluid.app/api-reference/member-site-pages/list-a-sites-pages.md) | | Add a page | [Add a page](https://docs.fluid.app/api-reference/site-pages/add-a-page.md) | [Add a page](https://docs.fluid.app/api-reference/member-site-pages/add-a-page.md) | | Change a page | [Change a page](https://docs.fluid.app/api-reference/site-pages/change-a-page.md) | [Change a page](https://docs.fluid.app/api-reference/member-site-pages/change-a-page.md) | | Remove a page | [Remove a page](https://docs.fluid.app/api-reference/site-pages/remove-a-page.md) | [Remove a page](https://docs.fluid.app/api-reference/member-site-pages/remove-a-page.md) | | Preview the home page | [Preview the home page of a site's draft](https://docs.fluid.app/api-reference/site-preview/preview-the-home-page-of-a-sites-draft.md) | [Preview the home page of a company site's draft](https://docs.fluid.app/api-reference/member-site-preview/preview-the-home-page-of-a-company-sites-draft.md) | | Preview a page | [Preview a page of a site's draft](https://docs.fluid.app/api-reference/site-preview/preview-a-page-of-a-sites-draft.md) | [Preview a page of a company site's draft](https://docs.fluid.app/api-reference/member-site-preview/preview-a-page-of-a-company-sites-draft.md) | | Read a draft asset | [Read a text asset of a site's draft](https://docs.fluid.app/api-reference/site-preview/read-a-text-asset-of-a-sites-draft.md) | [Read a text asset of a company site](https://docs.fluid.app/api-reference/member-site-preview/read-a-text-asset-of-a-company-site.md) | ### Publishing, versions and branches | Task | Member API | Company API | | - | - | - | | Publish | [Publish a site](https://docs.fluid.app/api-reference/sites/publish-a-site.md) | [Publish a company site](https://docs.fluid.app/api-reference/member-sites/publish-a-company-site.md) | | List versions | [List a site's versions](https://docs.fluid.app/api-reference/sites/list-a-sites-versions.md) | [List a site's versions](https://docs.fluid.app/api-reference/member-sites/list-a-sites-versions.md) | | Restore a version | [Restore a site to a version](https://docs.fluid.app/api-reference/sites/restore-a-site-to-a-version.md) | [Restore a site to a version](https://docs.fluid.app/api-reference/member-sites/restore-a-site-to-a-version.md) | | List branches | [List a site's branches](https://docs.fluid.app/api-reference/site-branches/list-a-sites-branches.md) | [List a site's branches](https://docs.fluid.app/api-reference/member-site-branches/list-a-sites-branches.md) | | Make a branch | [Branch a site](https://docs.fluid.app/api-reference/site-branches/branch-a-site.md) | [Branch a company site](https://docs.fluid.app/api-reference/member-site-branches/branch-a-company-site.md) | | Read a branch | [Read a site's branch](https://docs.fluid.app/api-reference/site-branches/read-a-sites-branch.md) | [Read a site's branch](https://docs.fluid.app/api-reference/member-site-branches/read-a-sites-branch.md) | | Delete a branch | [Delete a site's branch](https://docs.fluid.app/api-reference/site-branches/delete-a-sites-branch.md) | [Delete a site's branch](https://docs.fluid.app/api-reference/member-site-branches/delete-a-sites-branch.md) | See [Publish, restore, copy and take down a member site](https://docs.fluid.app/member-sites/publishing.md) for how these behave. ### Shares | Task | Member API | Company API | | - | - | - | | List shares | [List a site's shares](https://docs.fluid.app/api-reference/site-shares/list-a-sites-shares.md) | [List a site's shares](https://docs.fluid.app/api-reference/member-site-shares/list-a-sites-shares.md) | | Share a site | [Share a site](https://docs.fluid.app/api-reference/site-shares/share-a-site.md) | [Share a company site](https://docs.fluid.app/api-reference/member-site-shares/share-a-company-site.md) | | Change a share's permission | [Change a share's permission](https://docs.fluid.app/api-reference/site-shares/change-a-shares-permission.md) | [Change a share's permission](https://docs.fluid.app/api-reference/member-site-shares/change-a-shares-permission.md) | | Stop sharing | [Stop sharing with an audience](https://docs.fluid.app/api-reference/site-shares/stop-sharing-with-an-audience.md) | [Delete a share](https://docs.fluid.app/api-reference/member-site-shares/delete-a-share.md) | | Find whom to share with | [Search the share targets](https://docs.fluid.app/api-reference/site-share-targets/search-the-share-targets.md) | Not available | See [Share a member site](https://docs.fluid.app/member-sites/sharing.md). ### The account menu, pins and home These belong to the signed-in member, so only the member API has them. Featuring is the company's version. | Task | Operation | | - | - | | Read the account menu | [Show the member's account menu](https://docs.fluid.app/api-reference/site-menu/show-the-members-account-menu.md) | | Remove a site from the menu | [Remove a site from the member's menu](https://docs.fluid.app/api-reference/site-removals/remove-a-site-from-the-members-menu.md) | | Restore a removed site | [Restore a removed site](https://docs.fluid.app/api-reference/site-removals/restore-a-removed-site.md) | | Pin a site | [Pin a site to the member's menu](https://docs.fluid.app/api-reference/site-pins/pin-a-site-to-the-members-menu.md) | | Unpin a site | [Unpin a site](https://docs.fluid.app/api-reference/site-pins/unpin-a-site.md) | | Order the pins | [Order the member's pins](https://docs.fluid.app/api-reference/site-pins/order-the-members-pins.md) | | Choose a home site | [Choose the member's home site](https://docs.fluid.app/api-reference/site-home/choose-the-members-home-site.md) | | Clear the home site | [Clear the member's home site](https://docs.fluid.app/api-reference/site-home/clear-the-members-home-site.md) | | List the featured sites (company) | [List the featured sites](https://docs.fluid.app/api-reference/member-site-features/list-the-featured-sites.md) | | Feature a site (company) | [Feature a site](https://docs.fluid.app/api-reference/member-site-features/feature-a-site.md) | | Stop featuring a site (company) | [Stop featuring a site](https://docs.fluid.app/api-reference/member-site-features/stop-featuring-a-site.md) | | Order the featured sites (company) | [Order the featured sites](https://docs.fluid.app/api-reference/member-site-features/order-the-featured-sites.md) | See [Member sites in the account menu](https://docs.fluid.app/member-sites/sites-home.md). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.