> ## 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. # Send a message to the assistant > Stores the member's message, generates the reply with the company's assistant and returns both. One reply runs per conversation, and at most 10 replies run at once for a member. The first message names an untitled conversation. Send `Accept: text/event-stream` to receive the reply as it is written, as the company's admin chat streams it: `data:` frames of JSON, `{"delta": ""}` for each part of the reply, then `{"exchange": {...}}` with the stored messages (the same object as the `data` of the 201), then `data: END_OF_STREAM`. A failure after the stream has opened arrives as `{"error": "", "status": }` before the end; one found before it opens (a conflict, a billing refusal, a limit) is the JSON error below. A client that prefers `application/json`, or sends no `Accept`, gets the completed exchange instead. Stopping the reply, with the stop operation or by closing the connection, ends the stream with the reply stored as `stopped`. Limited to 20 messages per minute per credential, past which the rate limiter answers 429 with its own body rather than the error envelope; replies use the company's AI billing, which can refuse with 402 or 429 in the error envelope. ## OpenAPI ````yaml /api-reference/member-ai-v2026-10.yaml post /api/member/v2026-10/ai/conversations/{id}/messages openapi: 3.1.0 info: title: Fluid Member API v2026-10 — AI description: >- The signed-in member's own conversations with the company's AI assistant: history, replies, stopping a reply and feedback. Conversations belong to the member the bearer credential speaks for; another member's conversation is 404. The assistant is available to rep-eligible memberships; a customer membership gets 403. Replies use the company's assistant configuration and AI billing. A member session JWT, the kind order and subscription email links carry, cannot read conversations and also gets 403. contact: email: support@fluid.app license: name: Proprietary identifier: LicenseRef-Proprietary version: 2026-10 servers: - url: https://api.fluid.app description: Production API server - url: https://api.fluid.test description: Local development server security: - MemberBearer: [] tags: - name: ai description: The signed-in member's conversations with the company's AI assistant. x-fluid-section: Members paths: /api/member/v2026-10/ai/conversations/{id}/messages: post: tags: - ai summary: Send a message to the assistant description: >- Stores the member's message, generates the reply with the company's assistant and returns both. One reply runs per conversation, and at most 10 replies run at once for a member. The first message names an untitled conversation. Send `Accept: text/event-stream` to receive the reply as it is written, as the company's admin chat streams it: `data:` frames of JSON, `{"delta": ""}` for each part of the reply, then `{"exchange": {...}}` with the stored messages (the same object as the `data` of the 201), then `data: END_OF_STREAM`. A failure after the stream has opened arrives as `{"error": "", "status": }` before the end; one found before it opens (a conflict, a billing refusal, a limit) is the JSON error below. A client that prefers `application/json`, or sends no `Accept`, gets the completed exchange instead. Stopping the reply, with the stop operation or by closing the connection, ends the stream with the reply stored as `stopped`. Limited to 20 messages per minute per credential, past which the rate limiter answers 429 with its own body rather than the error envelope; replies use the company's AI billing, which can refuse with 402 or 429 in the error envelope. operationId: member_ai_messages_create parameters: - $ref: '#/components/parameters/ConversationId' requestBody: required: true content: application/json: schema: type: object description: The member's message. additionalProperties: false required: - text properties: text: type: string minLength: 1 maxLength: 8000 description: The message; must contain a non-space character. example: text: Draft a follow-up for Sam, who asked about the starter kit responses: '200': description: >- The reply as server-sent events, sent when `Accept` prefers `text/event-stream`. The status is 200 because it is sent before the reply is complete; the reply's outcome is in the final frames. headers: Cache-Control: $ref: '#/components/headers/CacheControl' content: text/event-stream: schema: type: string description: >- Frames separated by a blank line. Each starts with `data: ` and holds one JSON object (`delta`, `exchange` or `error`), except the last, `END_OF_STREAM`. example: > data: {"delta":"Hi Sam, "} data: {"delta":"thanks for asking about the starter kit."} data: {"exchange":{"user_message":{"id":"01a0f512-2c1e-7b11-9a3d-4f0e8d1c2b10","conversation_id":"01a0f512-1a00-7c22-8b11-5e3f2a1d0c01","role":"user","text":"Draft a follow-up for Sam","tool_calls":[],"status":null,"feedback":null,"created_at":"2026-10-01T15:01:00.104000Z"},"assistant_message":{"id":"01a0f512-2c40-7d55-a1b2-0c9e8f7a6b54","conversation_id":"01a0f512-1a00-7c22-8b11-5e3f2a1d0c01","role":"assistant","text":"Hi Sam, thanks for asking about the starter kit.","tool_calls":[],"status":"completed","feedback":null,"created_at":"2026-10-01T15:01:04.512000Z"}}} data: END_OF_STREAM '201': description: >- The stored exchange. The reply's status is `completed`, or `stopped` when the member stopped it, with the text produced until then. headers: Cache-Control: $ref: '#/components/headers/CacheControl' content: application/json: schema: $ref: '#/components/schemas/ExchangeEnvelope' example: status: 201 data: user_message: id: 01a0f512-2c1e-7b11-9a3d-4f0e8d1c2b10 conversation_id: 01a0f512-1a00-7c22-8b11-5e3f2a1d0c01 role: user text: Draft a follow-up for Sam, who asked about the starter kit tool_calls: [] status: null feedback: null created_at: '2026-10-01T15:01:00.104000Z' assistant_message: id: 01a0f512-2c40-7d55-a1b2-0c9e8f7a6b54 conversation_id: 01a0f512-1a00-7c22-8b11-5e3f2a1d0c01 role: assistant text: >- Hi Sam, thanks for asking about the starter kit. Would a quick call on Thursday work? tool_calls: [] status: completed feedback: null created_at: '2026-10-01T15:01:04.512000Z' meta: request_uuid: 01a0f4fe-de00-75b3-8d8a-b74b0cde8b07 timestamp: '2026-10-01T15:04:05Z' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/InvalidParameters' '429': $ref: '#/components/responses/TooManyRequests' '503': $ref: '#/components/responses/Unavailable' components: parameters: ConversationId: name: id in: path required: true description: Conversation id. schema: type: string format: uuid headers: CacheControl: description: >- Standard HTTP Cache-Control directive. Conversation reads are private and sent with max-age=0, so a client revalidates with If-None-Match on every use. Writes are no-store. schema: type: string example: max-age=0, private schemas: ExchangeEnvelope: type: object description: The member's message and the reply. properties: status: type: integer const: 201 description: HTTP response status. data: type: object description: The stored exchange. additionalProperties: false properties: user_message: $ref: '#/components/schemas/Message' assistant_message: $ref: '#/components/schemas/Message' required: - user_message - assistant_message meta: $ref: '#/components/schemas/ResponseMeta' required: - status - data - meta Message: type: object description: One turn of a member AI conversation. additionalProperties: false properties: id: type: string format: uuid description: Message id. conversation_id: type: string format: uuid description: The conversation it belongs to. role: type: string enum: - user - assistant description: Who wrote it. text: type: string description: Message text. tool_calls: type: array maxItems: 0 description: >- Read-only summary of assistant tool calls. The assistant has no tools, so this is always empty. items: type: object description: A tool call summary. status: type: - string - 'null' enum: - completed - stopped - failed - null description: >- How a reply ended: completed, stopped by the member, or failed partway. Null on the member's own messages. feedback: type: - object - 'null' description: The member's rating of a reply, or null when there is none. additionalProperties: false properties: rating: type: string enum: - up - down description: Thumbs up or down. comment: type: - string - 'null' description: Optional comment. required: - rating - comment created_at: type: string format: date-time description: When it was recorded. required: - id - conversation_id - role - text - tool_calls - status - feedback - created_at ResponseMeta: type: object description: Envelope metadata present on every response. properties: request_uuid: type: string format: uuid description: Server-generated UUIDv7 uniquely identifying this response. timestamp: type: string format: date-time description: ISO 8601 timestamp at which the server produced the response. required: - request_uuid - timestamp additionalProperties: true ErrorEnvelope: type: object description: Standard error envelope. properties: status: type: integer description: HTTP status code (mirrors the response status line). error: type: object description: The error message and field-keyed details. properties: message: type: string description: Human-readable error message. details: type: object description: >- Machine-readable details, keyed by field where a field is at fault. additionalProperties: true required: - message - details meta: $ref: '#/components/schemas/ResponseMeta' required: - status - error - meta RateLimitBody: type: object description: >- The body of a request refused by the credential's rate limit, sent by the platform's rate limiter before the request reaches the assistant. It is not the standard error envelope. additionalProperties: true properties: error: type: string description: Short name of the refusal. message: type: string description: Human-readable explanation. retry_after: type: integer description: >- Seconds until the limit window ends and the credential may send again. required: - error - message - retry_after example: error: Rate limit exceeded message: Too many requests. Please wait before trying again. retry_after: 37 responses: Unauthorized: description: Missing or unusable member credential. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' PaymentRequired: description: >- The company's AI billing is unresolved or its credits are used up; the member's message is kept. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' Forbidden: description: >- The membership has no AI assistant (it is not rep-eligible), a write was made with a read-only credential, or a read was made with a member session JWT, the kind order and subscription email links carry. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' NotFound: description: >- The conversation or message is missing, deleted, malformed or another member's. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' Conflict: description: >- A reply is already being generated in the conversation (send), or none is (stop). After a stop, a new message is refused until the stopped reply is stored. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' InvalidParameters: description: >- Unsupported parameter, invalid value, or a rating on the member's own message. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' TooManyRequests: description: >- Either the standard error envelope, when the company's AI usage cap or limit is reached (the member's message is kept) or the member already has 10 replies being generated (nothing is stored), or the rate limiter's own body, when the credential sent more than 20 messages in a minute (nothing is stored). The rate limiter's response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ErrorEnvelope' - $ref: '#/components/schemas/RateLimitBody' Unavailable: description: >- The assistant could not answer, or its reply ran past the time allowed. The member's message is kept, and any part of the reply already produced is stored with status `failed`. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' securitySchemes: MemberBearer: type: http scheme: bearer description: | A member credential in the `Authorization: Bearer` header: a member session JWT, a portal JWT whose login is linked to a membership in that company, or a member token. The credential alone identifies the member and company. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.