> ## 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, 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. The merchant must open the emailed sign-in link and create an API token before authenticated calls are possible. > 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 where a spec documents it — in practice the unversioned company-v0 admin surface; every versioned surface uses cursor pagination. > 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 — 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. # Troubleshoot a Mist app > Fix the common Mist app problems: a create or publish that fails, an app that crashes, database and environment variable errors, rejected webhooks, embeds that won't load, and restoring a deleted app. Start with the logs. Most problems show up there first. * **Mist desktop app**: click **Logs**. The **Production** tab shows the live app. The **Local** tab shows your computer. * **CLI**: `fluid mist logs --tail` streams the live app's build and runtime logs. You can also ask Mist, for example "Why did my app crash?". Mist reads the logs and tells you what it finds. ## Creating the app fails | What you see | What to do | | - | - | | "We couldn't finish creating your Mist right now." | This is usually temporary. Fluid has already undone the partial setup, so try again in a moment. | | A `402` status with `credits_exhausted` | Your company is out of usage credits. Buy more on [Billing](/help/admin/settings/billing), then try again. | | A `409` status with `duplicate_recent_create` | You created an app with the same name in the last few minutes. Use the app you already have, or wait 10 minutes. | | A `503` status with `admission_unavailable` | Nothing was created. Try again. | | No **Create Mist** button, or a `403` status | Your role needs the Mist permission that starts with **Create new Mist hostings**. See [Roles](/help/admin/settings/roles). | If an app shows **Failed**, it was rolled back. Create a new one. ## The app stays in provisioning An app moves to `live` once its first deployment starts. Check its state with `fluid mist show`. If it stays in `provisioning` for more than a few minutes, run `fluid mist deployments` to see whether the first deployment failed. ## A publish or build fails Open **Publish output** in Mist, or run `fluid mist logs --deployment ` with the ID from `fluid mist deployments`. Look for the first error. Run the same checks the build depends on: ```bash theme={null} npm run typecheck npm run lint npm run build ``` Fix the error, then publish again. Mist tries one fix on its own when a publish fails. For each reason Mist reports, see [If a publish fails](/help/mist/run-and-publish#if-a-publish-fails). To go back to the last version that worked, see [Roll back](/help/mist/run-and-publish#roll-back). ## The live app crashes or returns errors Open the **Production** logs, then load the failing page again. The request's error shows up as it happens. Errors your code logs with `console.error` show up there too. If a change works locally but not live, check what differs in production: * **Data.** Production has its own database. Rows you created locally aren't there. * **Environment variables.** A variable in your `.env.local` must also be set on the app. See [Add your own environment variables](/mist-apps/hosting#add-your-own-environment-variables). * **Embedding.** A page that works on its own can still be blocked inside Fluid. See [The embed won't load](#the-embed-wont-load). If the first request after a quiet period is slow, check the app's **Compute** setting. **Standard serverless** sleeps between requests, so the first request waits for the app to start. **Fluid Compute** keeps it warm. See [Compute](/mist-apps/hosting#compute). ## Database errors Open `/api/health` on the app. It returns `{"db":"ok"}` when the database answers, or a `503` with the error. | Error | Cause and fix | | - | - | | `DATABASE_URL is not set` | The app ran in production mode outside Mist hosting, for example with `npm start` on your computer. Use `npm run dev` locally. | | `relation "…" does not exist` | The table hasn't been created yet. Add it to `ensureSchema()` and call it before the query. See [Add a table](/mist-apps/starter-template#add-a-table). | To start your local database over, stop the app and delete the `local.db` folder. It's created again on the next `npm run dev`. You can browse the app's local and production data in Mist, read-only. See [Databases](/help/mist/databases). ## Environment variable problems | Problem | Fix | | - | - | | A new value doesn't take effect | Variables apply on the next deployment. Publish again, or run `fluid mist push`. | | "…is managed by Fluid" or "…is managed by Mist" | Fluid sets that variable for you. Use a different name for your own. See [Environment variables Fluid sets](/mist-apps/hosting#environment-variables-fluid-sets). | | A droplet variable, such as `FLUID_DROPLET_UUID`, is missing | The app has no droplet. [Add a droplet integration point](/mist-apps/integration-points#add-an-integration-point). | | A value is missing locally | Fluid doesn't send encrypted values back. Add it to `.env.local` yourself. | ## Webhooks are rejected The template's webhook route returns these errors. Find the message in the production logs. | Status and message | Cause and fix | | - | - | | `500` "Webhook authentication not configured" | The app has no `FLUID_WEBHOOK_AUTH_TOKEN`, so it can't check lifecycle webhooks. Add a droplet integration point, which sets it. | | `401` "Missing X-Fluid-Signature header" | The request wasn't signed. Fluid signs every webhook, so the request didn't come from Fluid. | | `401` "Webhook timestamp too old" | The webhook is more than five minutes old, or it was replayed. Check that your server's clock is correct. | | `401` "Invalid signature" | Your code changed the body before the check, or used the wrong secret. Verify the raw body, exactly as received. | | `401` "No active company for fluid\_shop" | The company hasn't installed the droplet, or the install didn't finish. Check that `droplet.installed` reached the app. | | `202` with `"handled": false` | The webhook was accepted, but no handler is registered for it. Register one in `lib/handlers/index.ts`. | If installs never reach the app, run `fluid mist droplet repair`. It fixes the droplet's embed and lifecycle webhook URLs when they don't match the app. Every webhook the app receives is saved in its `webhooks` table, with any error. Query it in [Databases](/help/mist/databases) to see what arrived. ## The embed won't load | What you see | Cause and fix | | - | - | | The frame is blank, and the browser console mentions `frame-ancestors` | The page that frames your app isn't on `fluid.app`. Add its domain to `FLUID_FRAME_ANCESTORS` in `proxy.ts`. See [Frame the app inside Fluid](/mist-apps/integration-points#frame-the-app-inside-fluid). | | "Open this in Fluid" | The page is wrapped in `` and was opened directly. Open it from Fluid. | | "Fluid installation context not found" | The request had no valid installation reference, or the installation isn't active. Make sure your client code sends it with `fluidInstallationFetch()`. | | "Viewer identity unavailable. Reload this page from Fluid." | The session token was missing, expired or couldn't be checked. Reload the page from Fluid. Locally this is expected, because the session-token variables exist only in production. | | "This Mist has no public URL yet" | The app is still being set up. Wait until it's live, then add the integration point. | Verifying a viewer also needs the `settings` scope on the droplet installation. Without it, the store lookup is refused and the page returns `401`. ## A custom domain doesn't work See [Connect a custom domain](/mist-apps/domains#troubleshooting). ## Restore a deleted app A deleted app is kept for 15 days. Until then, you can restore it with its code, database and settings intact. ```bash theme={null} fluid mist restore 3bed85 ``` You can also use [Cancel a pending teardown](/api-reference/mists/cancel-a-pending-teardown-within-the-15-day-grace-window) in the API. The Mist desktop app doesn't have a restore button yet. After 15 days, Fluid permanently deletes the app's repository, database and hosting. It can't be restored. ## Get help If you're still stuck, contact Fluid support. Include the app's slug, what you did and the error from the logs. Email Fluid support at [help@fluid.app](mailto:help@fluid.app). The [Getting help](/help/getting-help) page lists what to include in your request. ## Related pages * [Run and publish](/help/mist/run-and-publish) in the Help Center * [Hosting, database and environment variables](/mist-apps/hosting) * [Authentication](/mist-apps/authentication) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.