> ## 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.
> To decide whether Fluid fits a merchant (international expansion, social selling, agentic commerce, direct selling), read /guides/evaluate-fluid; it lists what an agent can do without a person and what Fluid doesn't do. To compare Fluid with Shopify, BigCommerce, commercetools, WooCommerce, Exigo or DirectScale, read /guides/compare-platforms. Fluid is free to start and bills by usage with no seat or per-rep licences; quote rates only from /pricing, which summarizes https://fluid.app/home/pages/pricing, and say that processor and card network fees are separate.
> Every live Fluid storefront serves /llms.txt, /agents.md, .md and .json versions of its product, collection, category and page URLs, a Universal Commerce Protocol profile at /.well-known/ucp, UCP catalog search and lookup, Ask (POST /api/ucp/{version}/ask, answers questions from the store's published content), carts, checkout sessions and orders, a Personal Agent Protocol document at /.well-known/poppy.json, and an A2A Agent Card at /.well-known/agent-card.json with a JSON-RPC endpoint at /api/a2a. A checkout session completes inside the agent with Google Pay when the store's profile lists the com.google.pay payment handler; otherwise hand the shopper the continue_url to hosted checkout. A member's share link is /<username>/products/<slug>; see /concepts/agentic-commerce, /concepts/poppy, /concepts/ucp and /concepts/a2a.
> 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 (from a chat with no shell, in one call with the files inline: site_template_get for a starter, then site_deploy with each path's content; or a built folder in two calls: send the 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. site_logs, site_traffic, site_env_list/set/unset, site_seo_get/set and the site_branch tools cover logs, traffic, env vars, SEO and preview branches; a member builds their own Sites with the my_site_* tools. The MCP site_deploy tool publishes server functions sent inline that import nothing; publish functions with imports, and convert a Site to an App, with the fluid sites CLI. A Site can serve light server code: each functions/<name>.ts, declared in config/functions.json with access public, signed_in or key (and an optional UTC cron schedule), answers at /api/<name> on the Site's own host; publish it with fluid deploy, or inline through the MCP site_deploy tool when it imports nothing. See /sites/functions and /sites/rest-api.
> 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.
> To create a URL redirect, create a custom route on the Sitemap: POST /api/theme_region_rules with redirect_type redirect, a redirect_url, region_code default, route_kind non_credit and redirect_status_code 301 or 302. See /themes/custom-routes#create-a-redirect-with-the-api. Never use /api/redirects; those legacy redirects are no longer used, and the admin's Sitemap screen doesn't show them.
> 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.

# Count the member's contacts

> The numbers a Contacts page shows, counted live over the same contacts `GET /contacts` lists (ownership included), so a tab's count is the size of the list it opens. `total` is every contact under the search and facets, `by_status` splits it by status, and `active_7d`, `added_30d` and `unread` count contacts with recent activity, recently added and with unread activity. The windows are instants in UTC, not calendar days. `active_7d` counts contacts whose last activity is at or after seven times 24 hours before the request, `added_30d` contacts created at or after thirty times 24 hours before it. `q`, `filter[source]`, `filter[group_id]` and `filter[tag]` narrow every number as they narrow the list; there is no `filter[status]`, because `by_status` is that split. Status keys are lowercased, contacts with a null, empty or whitespace-only status count under `none`, and a status literally named `none` counts there too. A status with no contacts is absent, but `none` is always present. When a contact's counters await background reconciliation the answer is 503, never partial numbers. Responses are private and the ETag covers the body (`max-age=0`).



## OpenAPI

````yaml /api-reference/member-people-v2026-10.yaml get /api/member/v2026-10/contacts/counts
openapi: 3.1.0
info:
  title: Fluid Member API v2026-10 — People
  description: >
    The signed-in member's own identity, and the memberships their user holds

    across companies. Every operation acts as the member the bearer credential

    speaks for: the member and their company come from the credential alone,

    never from a path, query or body parameter.


    A member credential is a One Auth identity access token for an ordinary rep

    or shopper, a member session JWT, a portal JWT whose user company login is

    linked to a membership in that company, or an opaque member token.

    Identity tokens require the configured issuer, audience and signing key;

    admin, root/platform, machine and impersonated principals are refused.

    Identity access tokens, opaque member tokens and portal JWTs may write, as

    they do on the legacy APIs; a portal JWT the server minted read-only, and a

    legacy member session JWT, read but are refused with 403 on a write.

    Company, partner, public and

    droplet tokens are refused with 401,

    as are an admin's token, a root admin's portal JWT, any credential for a

    member who is also an admin of that company (their own member session JWT

    and member token included), a portal JWT with no membership linked to it,

    and a credential for a member who is removed, inactive or locked, whose

    user is deleted, or whose company is inactive. A portal JWT signed for a

    company admin's login is the exception: it acts as that person's own

    membership as a rep of the company, found by the person and not by the

    UserCompany id the JWT names, and is refused with 401 when they hold no

    active rep membership there.


    A member session JWT is also carried in order and subscription email links,

    so the contact operations (including a contact's activities, notes, tasks,
    orders and

    subscriptions), the contact import reads, the task reads, the note reads and
    the group reads

    refuse it with 403; a portal JWT or a member token reads them. The member's
    own orders,

    subscriptions and activity feed still accept it. The contact

    (including imports, bulk changes and a contact's activities, notes, tasks,
    orders and

    subscriptions), task, note and group operations are

    rep-only, as the legacy CRM endpoints are: a customer or preferred-customer

    membership receives 403 on every one of them, whatever its credential.


    **Sandbox test companies.** A sandbox test company is linked to a live

    company. While the test company cannot be reached, because sandbox access

    is turned off for its live company or the live company was deleted, every

    operation refuses a credential for it with `403` and the standard error

    envelope, before the operation runs.
  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: me
    description: The signed-in member's own identity
    x-fluid-section: People
  - name: profile
    description: The signed-in member's shared public profile
  - name: socials
    x-fluid-section: People
    description: The signed-in member's shared social accounts
  - name: companies
    description: The memberships the signed-in member's user holds, for a company switcher
  - name: points
    description: The signed-in member's loyalty points balance and ledger
    x-fluid-section: People
  - name: addresses
    description: The signed-in member's saved addresses and their default
    x-fluid-section: People
  - name: activities
    description: The signed-in member's activity feed and unread count.
    x-fluid-section: People
  - name: groups
    description: The signed-in member's contact groups.
    x-fluid-section: People
  - name: notes
    description: The notes on the signed-in member's contacts.
    x-fluid-section: People
  - name: tasks
    description: The signed-in member's to-dos.
    x-fluid-section: People
  - name: contacts
    description: The signed-in member's contacts.
    x-fluid-section: People
paths:
  /api/member/v2026-10/contacts/counts:
    get:
      tags:
        - contacts
      summary: Count the member's contacts
      description: >-
        The numbers a Contacts page shows, counted live over the same contacts
        `GET /contacts` lists (ownership included), so a tab's count is the size
        of the list it opens. `total` is every contact under the search and
        facets, `by_status` splits it by status, and `active_7d`, `added_30d`
        and `unread` count contacts with recent activity, recently added and
        with unread activity. The windows are instants in UTC, not calendar
        days. `active_7d` counts contacts whose last activity is at or after
        seven times 24 hours before the request, `added_30d` contacts created at
        or after thirty times 24 hours before it. `q`, `filter[source]`,
        `filter[group_id]` and `filter[tag]` narrow every number as they narrow
        the list; there is no `filter[status]`, because `by_status` is that
        split. Status keys are lowercased, contacts with a null, empty or
        whitespace-only status count under `none`, and a status literally named
        `none` counts there too. A status with no contacts is absent, but `none`
        is always present. When a contact's counters await background
        reconciliation the answer is 503, never partial numbers. Responses are
        private and the ETag covers the body (`max-age=0`).
      operationId: member_contacts_counts
      parameters:
        - name: If-None-Match
          in: header
          required: false
          description: ETag from a previous response.
          schema:
            type: string
        - name: q
          in: query
          required: false
          description: >-
            Search text, as in `GET /contacts`. 2 to 100 characters, not only
            whitespace and without null bytes.
          schema:
            type: string
            minLength: 2
            maxLength: 100
            pattern: ^[^\u0000]*$
          example: jordan
        - name: filter[group_id]
          in: query
          required: false
          description: Only contacts in this group of the member's.
          schema:
            type: string
            format: uuid
        - name: filter[tag]
          in: query
          required: false
          description: Only contacts in the member's group with this name.
          schema:
            type: string
            maxLength: 255
          example: Hot leads
        - name: filter[source]
          in: query
          required: false
          description: >-
            Only contacts whose `source` equals this text, compared
            case-insensitively. 1 to 255 characters, without null bytes.
          schema:
            type: string
            minLength: 1
            maxLength: 255
            pattern: ^[^\u0000]*$
          example: Spring wellness webinar
      responses:
        '200':
          description: The member's contact counts.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactCountsEnvelope'
              example:
                status: 200
                data:
                  total: 412
                  by_status:
                    cold: 130
                    customer: 61
                    new: 190
                    none: 31
                  active_7d: 54
                  added_30d: 77
                  unread: 9
                meta:
                  request_uuid: 0192f4c8-5b6c-7d74-a3e8-0f1a2b3c4d5e
                  timestamp: '2026-09-30T15:08:21Z'
        '304':
          description: >-
            The representation is unchanged; authentication and ownership are
            checked before this response.
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
        '401':
          description: Missing or unusable member credential.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: >-
            The credential is a member session JWT, the kind order and
            subscription email links carry, which cannot read contacts. A
            membership that is neither a rep nor a company admin (a customer or
            preferred customer) also gets 403.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '422':
          description: >-
            A query parameter is not valid, including `filter[status]` and any
            other parameter this endpoint does not take.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: >-
            Counters of contacts under the search and facets are awaiting
            background reconciliation, so `active_7d` and `unread` cannot be
            trusted. `error.details.contact_ids` names up to 100 of them.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
components:
  headers:
    ETag:
      description: >-
        Fingerprint of this member's representation. Send it back in
        If-None-Match to skip the body while it is unchanged.
      schema:
        type: string
    CacheControl:
      description: Standard HTTP Cache-Control directive. Always private for this surface.
      schema:
        type: string
        example: max-age=60, private
  schemas:
    ContactCountsEnvelope:
      type: object
      description: The member's contact counts.
      properties:
        status:
          type: integer
        data:
          type: object
          additionalProperties: false
          properties:
            total:
              type: integer
              minimum: 0
              description: >-
                Contacts under the search and facets. Equals the sum of
                `by_status`.
            by_status:
              type: object
              description: >-
                Contacts per lowercased status. Contacts with a null, empty or
                whitespace-only status, or a status named `none`, count under
                `none`, which is always present. A status no contact has is
                absent.
              additionalProperties:
                type: integer
                minimum: 0
              required:
                - none
            active_7d:
              type: integer
              minimum: 0
              description: >-
                Contacts whose last activity is within the last seven times 24
                hours (UTC instants).
            added_30d:
              type: integer
              minimum: 0
              description: >-
                Contacts created within the last thirty times 24 hours (UTC
                instants).
            unread:
              type: integer
              minimum: 0
              description: Contacts with unread activity.
          required:
            - total
            - by_status
            - active_7d
            - added_30d
            - unread
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      required:
        - status
        - data
        - meta
    ErrorEnvelope:
      type: object
      description: Standard error envelope.
      properties:
        status:
          type: integer
          description: HTTP status code (mirrors the response status line).
        error:
          type: object
          properties:
            message:
              type: string
              description: Human-readable error message.
            details:
              type: object
              additionalProperties: true
          required:
            - message
            - details
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      required:
        - status
        - error
        - meta
    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
  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, an opaque member token, or a verified One Auth identity
        access token for a non-impersonated rep or shopper. The credential alone
        identifies the member and company.

````

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