> ## 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. # Read company health > Each area's latest check and the company's state across the areas returned. Reads stored checks only. Needs `company_settings.view`, and each area's own permissions; areas you cannot see are left out. Naming one in `areas[]`, or having none left, answers 403. ## OpenAPI ````yaml /api-reference/company-health-v2026-10.yaml get /api/company/v2026-10/health openapi: 3.1.0 info: title: Fluid Company API v2026-10 — Health version: 2026-10 description: >- Your company's health on v2026-10: one call that says which parts of your store need attention, so a person or a bot knows where to look first. ## Authentication Send a company admin credential as `Authorization: Bearer `: an admin session token or an API token for your company. Every endpoint needs the `company_settings.view` permission. Droplet installation tokens are refused. Each area also needs the permissions its own data sits behind: `droplets.view` for `droplets`; `droplets.view`, `orders.view` and `members.view` for `connect`; `orders.view` for `tax`, `shipping` and `fulfillment`; `subscriptions.view` for `subscriptions`; `payment_accounts.view` and `reports.view` for `payments`; `orders.view` and `reports.view` for `checkout`; `mist.code` for `mist_apps`; `application_themes.view` and `application_themes.update` for `themes`; `members.view`, `company_admins.view` and `developer.view` for `auth`; `orders.view` for `fairshare`. An area you cannot see is left out of the response and of the overall `state`. Naming one, or having none left to return, answers 403. ## How health is computed Fluid checks each area on a schedule: hourly, and every six hours for `fulfillment`. It stores one row per check, so these endpoints only read; they never run a check. An area with no check yet, or whose last check is older than it should be, reads `unknown` (`stale: true` for the second, keeping its last findings and metrics). States, from best to worst: `idle` (nothing to check, such as no Connect integration), `healthy`, `unknown`, `degraded`, `failing`. The overall `state` is the worst state among the areas returned, ignoring `idle`; it is `idle` only when every area is. A finding names what is wrong with counts and category codes, never error text or record ids, and `next_step` names the call that holds the detail. ## Being told about changes Subscribe a company webhook to resource `company_health`, event `changed`, or give a bot the `company_health.changed` trigger. It fires when an area's state changes. The payload names no area or state: read `GET /health` and compare each area's `state` with its `previous_state`. ## Responses Every response wraps the resource under its own key with `status` and `meta`. Errors use the same envelope with `error.message` and `error.details`. A 401 is a bare `{ "message": … }`. contact: email: support@fluid.app license: name: Proprietary identifier: LicenseRef-Proprietary servers: - url: https://api.fluid.app description: Production API server security: [] tags: - name: company_health description: Your company's health per area, and each area's history. x-fluid-section: Analytics paths: /api/company/v2026-10/health: get: tags: - company_health summary: Read company health description: >- Each area's latest check and the company's state across the areas returned. Reads stored checks only. Needs `company_settings.view`, and each area's own permissions; areas you cannot see are left out. Naming one in `areas[]`, or having none left, answers 403. operationId: companyHealth parameters: - name: areas[] in: query required: false description: Only these areas. Omit for every area you can see. schema: type: array items: $ref: '#/components/schemas/HealthArea' style: form explode: true responses: '200': description: The company's health. content: application/json: schema: $ref: '#/components/schemas/CompanyHealthResponse' example: company_health: state: degraded generated_at: '2026-10-24T15:32:08Z' areas: - area: connect state: degraded previous_state: healthy observed_at: '2026-10-24T15:07:12Z' stale: false metrics: integrations: 1 connected: 1 findings: - code: connect.tier_below severity: degraded summary: >- Exigo sync success is below its healthy tier; most failures are validation. subject: type: connect_integration uuid: drp_1mjyysle6csm9eb2q2wmffucoetres7cy next_step: method: GET path: >- /api/company/v2026-10/connect/integrations/drp_1mjyysle6csm9eb2q2wmffucoetres7cy/status - area: tax state: healthy previous_state: healthy observed_at: '2026-10-24T15:07:09Z' stale: false metrics: orders: 412 zero_tax_orders: 18 zero_tax_share: 0.044 findings: [] status: 200 meta: request_uuid: 7e2c9b41-3f8a-4d15-b6e0-9a4c21d7f583 timestamp: '2026-10-24T15:32:08Z' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '422': $ref: '#/components/responses/InvalidParameters' security: - bearer_auth: [] components: schemas: HealthArea: type: string description: An area key. enum: - droplets - connect - payments - checkout - tax - shipping - fulfillment - subscriptions - mist_apps - themes - auth - fairshare CompanyHealthResponse: type: object required: - company_health - status - meta properties: company_health: $ref: '#/components/schemas/CompanyHealth' status: type: integer meta: $ref: '#/components/schemas/Meta' CompanyHealth: type: object required: - state - generated_at - areas properties: state: $ref: '#/components/schemas/HealthState' generated_at: type: string format: date-time areas: type: array items: $ref: '#/components/schemas/HealthAreaResult' Meta: type: object description: >- Response metadata included on every response body. A refused droplet installation token's 403 names the request `request_id` rather than `request_uuid`. required: - timestamp properties: request_uuid: type: - string - 'null' request_id: type: - string - 'null' timestamp: type: string format: date-time UnauthorizedError: type: object description: Bare 401 body, a single `message` string, not the error envelope. required: - message properties: message: type: string example: Invalid credentials. ForbiddenError: description: >- Bare 403 body, `{ error }` when a permission is missing or `{ message }` when the credential is not company-admin tier. oneOf: - type: object required: - error properties: error: type: string example: Not authorized. - type: object required: - message properties: message: type: string example: Not authorized. ErrorResponse: type: object required: - error - status - meta properties: error: type: object required: - message properties: message: type: string details: type: object additionalProperties: true status: type: integer meta: $ref: '#/components/schemas/Meta' HealthState: type: string description: >- An area's or the company's state, from best to worst `idle`, `healthy`, `unknown`, `degraded`, `failing`. enum: - idle - healthy - unknown - degraded - failing HealthAreaResult: type: object required: - area - state - previous_state - observed_at - stale - metrics - findings properties: area: $ref: '#/components/schemas/HealthArea' state: $ref: '#/components/schemas/HealthState' previous_state: description: >- The state of the check before the latest one; null for an area's first check. oneOf: - $ref: '#/components/schemas/HealthState' - type: 'null' observed_at: type: - string - 'null' format: date-time description: >- When the latest check ran; null when the area has not been checked yet. stale: type: boolean description: >- True when the latest check is older than the area allows, so `state` reads `unknown`. metrics: type: object description: >- The area's figures from its latest check, such as `orders` and `zero_tax_share` for `tax`. Present for every state. additionalProperties: true findings: type: array items: $ref: '#/components/schemas/HealthFinding' HealthFinding: type: object description: >- One thing a check found wrong. Counts and category codes only, never error text or record ids. required: - code - severity - summary properties: code: type: string description: '`.`, such as `connect.tier_attention`.' example: connect.tier_attention severity: type: string enum: - unknown - degraded - failing summary: type: string description: A sentence a person or bot can relay. subject: type: object description: What the finding is about, when it is one thing. required: - type - uuid properties: type: type: string example: connect_integration uuid: type: string count: type: integer next_step: type: object description: The documented call that holds the detail. required: - method - path properties: method: type: string example: GET path: type: string responses: Unauthorized: description: >- Missing or invalid bearer token. The body is a bare `{ message }`, not the error envelope. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' example: message: Invalid credentials. Forbidden: description: >- Not a company admin with `company_settings.view` (bare body), a droplet installation token, or an area you cannot see (the error envelope). content: application/json: schema: oneOf: - $ref: '#/components/schemas/ForbiddenError' - $ref: '#/components/schemas/ErrorResponse' example: error: message: You do not have permission to read this health area details: {} status: 403 meta: request_uuid: 7e2c9b41-3f8a-4d15-b6e0-9a4c21d7f583 timestamp: '2026-10-24T15:32:08Z' InvalidParameters: description: An unknown area key, or a query parameter out of range. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: message: Invalid parameters details: area: - >- must be one of: droplets, connect, tax, shipping, fulfillment, subscriptions status: 422 meta: request_uuid: 7e2c9b41-3f8a-4d15-b6e0-9a4c21d7f583 timestamp: '2026-10-24T15:32:08Z' securitySchemes: bearer_auth: type: http scheme: bearer description: >- A company admin credential for your company. Droplet installation tokens are refused. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.