> ## 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.
> 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 (send the built folder's 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; the MCP server has no tools for logs, traffic, env vars or converting to an App, so use the fluid sites CLI for those.
> 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.

# Company sites on the storefront

> List your company's sites on the public storefront, manage them with the company API, and learn how their SEO, the active switch and a moderator's take-down work.

A company site is a [Site](https://docs.fluid.app/sites/overview.md) that your company owns, such as a launch microsite or a landing page. Besides opening at its own address, a company site is a storefront resource: it has the same common fields, lifecycle, SEO, metafields and countries as a page or a product, a public catalog, and company endpoints to manage it.

Member-owned sites aren't storefront resources. They stay on the [Member API](https://docs.fluid.app/api/member-sites.md) and are never listed in the public catalog. A member's public sites are listed on their own page instead, at `/<credit>/sites` on your store domain, and by [a member's public sites](https://docs.fluid.app/api-reference/member-sites/a-members-public-sites.md) request.

The site's pages still come from the build you publish with the Fluid CLI. See [Publish a Site](https://docs.fluid.app/sites/publishing.md). The fields on this page describe the site on the storefront.

## List your sites on the storefront

`GET /api/v202604/sites` lists your live company sites. A site is live when it's company-owned, public, switched on, not taken down, and published, or scheduled with its time passed. Call it on the store's own host, with no token:

```bash theme={null}
curl "https://acme.fluid.app/api/v202604/sites?filter[country]=US&page[limit]=10"
```

The list takes the same controls as every storefront list: `q`, `sort`, `lang`, `filter[country]`, `filter[language]`, `page[cursor]` and `page[limit]`. See [Find and create resources](https://docs.fluid.app/storefront/find-and-create.md).

`GET /api/v202604/sites/{slug}` looks up one site:

```bash theme={null}
curl "https://acme.fluid.app/api/v202604/sites/spring-launch"
```

A public draft or scheduled site still resolves by slug, with `seo.indexable` set to `false`. A private, archived, switched-off, taken-down or member-owned site returns `404`. See [Visibility, drafts, and scheduling](https://docs.fluid.app/storefront/visibility.md).

While Sites are off for your company, the list is empty and every lookup returns `404`.

See [Public Sites catalog](https://docs.fluid.app/api-reference/sites/public-sites-catalog.md) and [Public Site by slug](https://docs.fluid.app/api-reference/sites/public-site-by-slug.md) for the parameters and the response.

## Manage your sites

Manage company sites at `/api/v202604/company/sites` on `https://api.fluid.app`. Reads need a Bearer token with `storefront.view`. Creating, changing and deleting a site needs a signed-in admin's token with `storefront.update`: a company API token on its own can't change a site.

Writes wrap the body in a `site` key:

```bash theme={null}
curl -X POST "https://api.fluid.app/api/v202604/company/sites" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "site": {
      "title": "Spring Launch",
      "slug": "spring-launch",
      "description": "Meet the new spring line and the people behind it.",
      "visibility": "public",
      "status": "draft",
      "country_isos": ["US", "CA"],
      "search_engine_optimizer_attributes": {
        "title": "Spring Launch | Acme Wellness"
      }
    }
  }'
```

A site takes the same common fields as a page or a product: `title`, `slug`, `description`, `image_url`, `active`, `status`, `publish_at`, SEO, metafields and countries. `status` is `draft`, `scheduled`, `published` or `archived`. `visibility` stays a site's own field: `public` lets anyone open the site, and `private` limits it to the people its shares admit.

A few things differ from pages:

* **The slug is the site's address.** Leave `slug` blank on create and Fluid proposes one from the title. Renaming a site never changes its slug.
* **Shares mean share-link statistics.** `GET /api/v202604/company/sites/{id}/shares` returns the visits that came through the site's tracked share links, as it does for a page. Who may open a private site is set through the [Member Sites APIs](https://docs.fluid.app/api/member-sites.md).
* **Scans run on every save.** Each create and update queues a Lighthouse scan and a compliance scan. Read the results at `/api/v202604/company/sites/{id}/lighthouse` and `/api/v202604/company/sites/{id}/compliance`.

The company list leaves out archived sites unless you ask for them with `filter[status]`. It also takes `filter[active]`, and `filter[slug]` for one exact slug. Member-owned sites never appear in it.

In the Fluid admin, a company site's screen has a **Storefront** card for the same fields: **Active**, **Publish at**, the search engine title, description and indexing, and **Archive** or **Restore**.

See the [Sites reference](https://docs.fluid.app/api-reference/sites/company-sites-index.md) for every company request, its fields and its responses.

## SEO and the page head

You don't have to write SEO tags in your site. Search engines and link previews read the storefront page around your site, and Fluid writes its head for you: the title, the description, the preview image, the Open Graph tags, a Twitter card, and the canonical link.

Each value comes from the first source that has one:

1. The page's own entry in your site's `config/meta.json`: `routeMeta`, then `pages`, for the page's exact path.
2. The site's SEO settings, which you write with `search_engine_optimizer_attributes`.
3. The `default` in your site's `config/meta.json`.
4. The site's own `title`, `description` and `image_url`.
5. Your store's defaults.

Fluid picks each value on its own, so a page that names only a title in `config/meta.json` still gets the site's description and image. The SEO settings win over the `default` in `config/meta.json`, so what an admin sets shows on every page your code doesn't name. See [SEO and indexing](https://docs.fluid.app/sites/seo.md) and [SEO for storefront resources](https://docs.fluid.app/storefront/seo.md).

A site's `canonical_url` is `/home/sites/<slug>` on your store domain, such as `https://acme.fluid.app/home/sites/spring-launch`, like every storefront resource. It takes the visitor to the site. In the page head, a page other than the site's home adds its own path to that address for the canonical link, such as `/home/sites/spring-launch/events`. Your store's `sitemap-sites.xml` lists the live company sites at those addresses.

Search engines may index a site only when it's a live, public, switched-on company site, its SEO settings have `indexable: true`, and your storefront allows indexing. A new site starts with indexing off, so turn it on when the site is ready. Every other site, every member's site, and every refusal or sign-in page tells search engines not to index it. `config/meta.json` can't turn indexing on.

## Link members to their sites

`/account` on your store domain, such as `https://acme.fluid.app/account`, takes a member to their sites. Use it in a menu, an email or a text. It needs no rep in the address.

* A visitor who isn't signed in is asked to sign in, then comes back to `/account`.
* A member with one site goes straight to it.
* A member with several sites sees them all as tiles. The site they chose as home comes first.
* A member with no site yet sees a short message saying so.

The page lists only sites the member can open now. Each one is a company site shared with them, a site they built, or a site another member shared with them. `/account` works only on a store that has Sites turned on.

## Switch a site off

`active` is a site's on/off switch, separate from `status` and from `visibility`. Set `"active": false` to take a site off the storefront without unpublishing it:

* Its owner and your company's admins can still open it.
* A guest is asked to sign in, and any other member sees not found.
* It leaves the public catalog, and its public lookup returns `404`.

Set `"active": true` to bring it back.

## When a site is taken down

A company admin can take any site down, a company site or a member's: **Take down** on the site's screen in the Fluid admin, or the [take-down request](https://docs.fluid.app/api-reference/member-sites/take-a-member-site-down.md) of the company member-site API. Both take an optional reason, at most 1000 characters. The request sends it as `reason`.

A take-down is separate from the site's `status`. While a site is down:

* Its address no longer opens it, and it's in no public catalog or lookup.
* Its owner can't publish it, schedule it, switch it on or make it public. Each of those changes is refused with `422`.
* Its owner can still edit it, such as its title, description, SEO and metafields, and can move it to draft or archive it, so they can fix what led to the take-down.

The owner is told once, in Flow: a direct message from Fluid that names the site and gives the reason. For a company site, your company's admins get the message. The reason also shows on the site. Your admins see it on the site's screen in the Fluid admin, as `taken_down_reason` on the v2026-10 company member-site API, and as `suspension_reason`, with `suspended_at`, on the v2026-04 company endpoints. A member who owns the site sees it as `taken_down_reason` when they read their site through the Member API. The public endpoints never show it.

Only a company admin can bring a site back, with **Bring back** in the Fluid admin or the [reinstate request](https://docs.fluid.app/api-reference/member-sites/bring-back-a-member-site-that-was-taken-down.md) of the company member-site API. Nothing the owner writes lifts a take-down.

The v2026-10 member-site APIs keep their own field names: a site's slug is its `handle`, its title is its `name`, and a site that's down has the status `taken_down`.

## Next steps

* [Sites](https://docs.fluid.app/sites/overview.md) — what a Site is, its address and who can open it.
* [Visibility, drafts, and scheduling](https://docs.fluid.app/storefront/visibility.md) — the lifecycle every storefront resource shares.
* [SEO for storefront resources](https://docs.fluid.app/storefront/seo.md) — the `seo` object and its fallbacks.
* [Metafields](https://docs.fluid.app/storefront/metafields.md) and [Country availability](https://docs.fluid.app/storefront/country-availability.md) — the same on a site as on a page.


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