> ## 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. > Lists use cursor pagination via the page[cursor] and page[limit] query params; follow meta.pagination.next_cursor until it is null. > Never use /api/company/v1 or /api/v1 paths, page/per_page params, or offset pagination — they are legacy. > 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/auth-v0.yaml covers the unversioned auth surface (/api/... paths — authentication, MFA, social auth, and token exchange); 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). > Successful responses wrap the resource payload alongside a top-level integer status and a meta object. # Get playlist by slug (deprecated) ## OpenAPI ````yaml /api-reference/public-v2025-06.yaml post /api/public/v2025-06/playlists openapi: 3.1.0 info: title: Fluid Public SDK API description: >- **Fluid Public SDK API — the REST surface behind the `@fluid-app` FairShare SDK.** This is what the SDK calls on your behalf from the browser. Read it to understand what the SDK sends and receives, to verify a payload, or to call an SDK-backed endpoint directly. It also owns the browser-side platform surface that exists nowhere else: event tracking, lead capture, media and playlists, embeddable widgets, forms, sessions, settings, browser fingerprinting, affiliate lookup, root themes, and Pusher auth. Its cart endpoints (`/api/public/v2025-06/commerce/carts/…`) are **session-aware**: they accept `fluid_session` and populate visitor session and rep attribution on the cart. They also cover enrollment-pack carts (`…/enroll`, `…/enrollment`) and payment-gateway callbacks, which the Checkout API does not. Most browser and cart operations require no bearer token. The cart token in the path scopes cart requests. Synchronizing an authenticated customer, overriding cart item prices, and overriding cart item volumes require a bearer token. **Building a checkout from scratch, server-side? Use the Fluid Checkout API (`checkout-v2026-04`) instead** — it is the forward surface and the only one with customer accounts and subscription management. See [Choosing a cart surface](https://docs.fluid.app/api/choosing-a-cart-surface) for the operation map and boundary. Note: the version label names this spec, not a single path prefix. Endpoints here live under `/api/public/v2025-06/`, its partial `/api/public/stable/` alias, `/api/public/`, `/api/v202506/carts/`, and the cart price-override path under `/api/carts/`. version: v2025-06 contact: email: support@fluid.app license: name: Proprietary identifier: LicenseRef-Proprietary servers: - url: https://api.fluid.app - url: https://{company}.fluid.app description: Production server with company subdomain variables: company: default: myco description: Company subdomain security: [] tags: - name: carts description: >- Create, read, and mutate session-aware carts (items, address, country, language, discounts, shipping method, payment method, magic-link login, checkout). - name: checkout description: Checkout-started event emitted when a shopper enters the checkout flow. - name: commerce description: Admin-authenticated cart price overrides. - name: orders description: Public order lookup by token, including earned loyalty points. - name: product description: Localized product lookup by slug for storefronts and themes. - name: enrollment-packs description: Enrollment pack lookup by slug, for enrollment-pack carts. - name: payment description: Klarna session creation and updates for a cart. - name: paypal description: PayPal order creation, authorization, and shipping callbacks for a cart. - name: events description: Browser-side event ingestion — page visits, URL visits, and lead capture. - name: session description: Visitor session creation, the basis of cart and rep attribution. - name: fingerprint description: Browser fingerprint registration used to link sessions to a visitor. - name: lead description: Lead capture from storefront and theme forms. - name: forms description: Public form retrieval, password verification, and response submission. - name: media description: Media lookup by slug and video analytics events. - name: playlist description: Playlist (library) lookup by slug. - name: widgets description: Embeddable storefront widgets — banners, carts, chats, and popups. - name: page description: Page-visit tracking for storefront and theme pages. - name: url description: Short-link and URL visit tracking. - name: settings description: >- Company storefront settings the SDK reads at boot — company, cart, and affiliate configuration. - name: affiliate description: Affiliate lookup used to resolve a rep from a share link or handle. - name: root-themes description: Root theme catalog backing the theme editor and storefront rendering. - name: public description: >- Public utilities — health checks, Pusher auth, Apple Pay domain verification, leaderboards, and cart item volumes. - name: public-drop-zones description: >- Active checkout and order-confirmation drop zones used internally by the FairShare SDK. Direct REST integrations should use checkout-v2026-04. paths: /api/public/v2025-06/playlists: post: tags: - playlist summary: Get playlist by slug (deprecated) operationId: public_v2025_06_playlist-show-deprecated requestBody: content: application/json: schema: $ref: >- #/components/schemas/PlaylistShowDeprecatedRequestBodyApplicationJsonSchema responses: '200': description: Success content: application/json: schema: $ref: >- #/components/schemas/PlaylistShowResponse200ApplicationJsonSchema deprecated: true security: [] components: schemas: PlaylistShowDeprecatedRequestBodyApplicationJsonSchema: type: - object - 'null' properties: library: type: - object - 'null' properties: id: type: - string - integer - 'null' description: Playlist slug metadata: anyOf: - $ref: '#/components/schemas/RequestMetadata' - type: 'null' PlaylistShowResponse200ApplicationJsonSchema: type: - object - 'null' additionalProperties: false properties: status: type: - integer - 'null' library: title: Library type: - object - 'null' additionalProperties: false properties: id: type: - integer - 'null' slug: type: - string - 'null' custom_slug: type: - boolean - 'null' default: false title: type: - string - 'null' library_items: type: - array - 'null' items: title: LibraryItem type: - object - 'null' additionalProperties: false properties: type: type: - string - 'null' item: type: - object - 'null' additionalProperties: $ref: '#/components/schemas/JsonValue' products: type: - array - 'null' items: title: Product type: - object - 'null' additionalProperties: false properties: id: type: - integer - 'null' title: type: - string - 'null' maxLength: 255 image_url: type: - string - 'null' image_path: type: - string - 'null' cv: type: - string - 'null' format: decimal default: 0 tax: default: '0.0' type: - string - number - 'null' sku: type: - string - 'null' metadata: anyOf: - type: object additionalProperties: $ref: '#/components/schemas/JsonValue' - type: 'null' external_id: type: - string - 'null' canonical_url: type: - string - 'null' price: default: '0.0' minimum: 0 maximum: 99999999 type: - string - number - 'null' introduction: type: - string - 'null' price_in_currency: type: - string - 'null' tax_in_currency: type: - string - 'null' cv_in_currency: type: - string - 'null' metafields: type: - array - 'null' items: title: LegacyMetafield type: - object - 'null' additionalProperties: false properties: id: type: - integer - 'null' namespace: description: >- A container for related metafields. Commonly used to group metafields by app or functionality. type: - string - 'null' maxLength: 20 pattern: ^[a-zA-Z0-9_]+$ key: description: >- The unique identifier for the metafield within its namespace. Must be unique per namespace and owner. type: - string - 'null' maxLength: 30 pattern: ^[a-zA-Z0-9_]+$ value: description: >- The actual data stored in the metafield. Type depends on value_type. anyOf: - type: - string - number - integer - 'null' - type: object additionalProperties: $ref: '#/components/schemas/JsonValue' value_type: description: >- The data type that defines how the value should be interpreted and validated. type: - string - 'null' description: description: >- Optional human-readable description explaining the purpose of this metafield. type: - string - 'null' owner_type: description: >- The type of resource that this metafield belongs to (polymorphic association). type: - string - 'null' owner_id: description: >- The ID of the specific resource that this metafield belongs to. type: - integer - 'null' created_at: description: Timestamp when the metafield was created. type: - string - 'null' format: date-time updated_at: description: Timestamp when the metafield was last updated. type: - string - 'null' format: date-time metafield_definition: title: MetafieldDefinition type: - object - 'null' additionalProperties: false properties: id: type: - integer - 'null' company_id: description: >- The ID of the company that owns this metafield definition. type: - integer - 'null' namespace: description: >- A container for related metafield definitions. Used to group definitions by app or functionality. Must be unique within company and owner_resource. type: - string - 'null' maxLength: 20 pattern: ^[a-zA-Z0-9_]+$ key: description: >- The unique identifier for the metafield definition within its namespace and owner_resource. Combined with namespace and owner_resource, this must be unique per company. type: - string - 'null' maxLength: 30 pattern: ^[a-zA-Z0-9_]+$ name: description: >- Human-readable display name for the metafield definition, shown in admin interfaces and forms. type: - string - 'null' maxLength: 100 description: description: >- Detailed explanation of what this metafield definition represents, how it should be used, and any special instructions for content creators. type: - string - 'null' value_type: description: >- The data type that defines how metafield values should be validated, stored, and displayed. Determines which validation rules are available. type: - string - 'null' validation_rules: anyOf: - type: object additionalProperties: $ref: '#/components/schemas/JsonValue' description: >- JSON object containing validation constraints that will be applied to metafield values. Available rules depend on the value_type. - type: 'null' owner_resource: description: >- The type of resource (model class name) that metafields using this definition can be attached to. Must match the polymorphic owner_type. type: - string - 'null' pinned: description: >- Whether this definition should be prominently displayed or prioritized in admin interfaces and forms. type: - boolean - 'null' default: false position: default: 0 description: >- Sort order for displaying this definition relative to others in the same category and owner_resource. Lower numbers appear first. type: - integer - 'null' locked: description: >- Whether this metafield definition is locked, preventing direct updates or deletions of metafields using this definition. type: - boolean - 'null' default: false created_at: description: >- Timestamp when the metafield definition was created. type: - string - 'null' format: date-time updated_at: description: >- Timestamp when the metafield definition was last updated. type: - string - 'null' format: date-time list_type: description: >- Whether this definition is for list-type metafields that store arrays of values. type: - boolean - 'null' reference_type: description: >- Whether this definition is for reference-type metafields that store references to other resources. type: - boolean - 'null' supported_validations: description: >- Array of validation rule names that are supported for this value_type. type: - array - 'null' items: anyOf: - $ref: '#/components/schemas/JsonValue' - type: 'null' validation_description: description: >- Human-readable description of what the value_type represents and its constraints. type: - string - 'null' category_ids: description: >- Array of category IDs that this metafield definition is associated with for organizational purposes. items: type: - integer - 'null' type: - array - 'null' variants: type: - array - 'null' items: title: Variant type: - object - 'null' additionalProperties: false properties: id: type: - integer - 'null' title: type: - string - 'null' display_name: type: - string - 'null' image_url: type: - string - 'null' image_path: type: - string - 'null' sku: type: - string - 'null' primary_image: type: - string - 'null' price: type: - string - number - 'null' price_in_currency: type: - string - 'null' currency_code: type: - string - 'null' options: type: - array - 'null' items: type: - object - 'null' additionalProperties: false properties: title: type: - string - 'null' value: type: - string - 'null' enrollment_packs: type: - array - 'null' items: title: EnrollmentPack type: - object - 'null' additionalProperties: false properties: id: type: - integer - 'null' title: type: - string - 'null' status: type: - string - 'null' image_thumbnail_url: type: - string - 'null' metadata: $ref: '#/components/schemas/ResponseMetadata' RequestMetadata: type: object properties: fluid_shop: type: - string - 'null' fluid_session: type: - string - 'null' format: /\Afs_[0-9A-Za-z&&[^0OIl]]{22}\z/ fluid_locale: type: - string - 'null' format: /\A[a-z]{2}_[A-Z]{2}\z/ fluid_journey: type: - string - 'null' country: type: - string - 'null' description: >- ISO 3166-1 alpha-2 country of the visitor, read from the edge-set `fluid_geo` cookie (e.g. US). Values that are not an ISO country are recorded as unknown rather than rejected. Omit the field when the cookie is absent. timezone: type: string description: >- IANA timezone identifier (e.g. America/New_York). Omit the field rather than sending null. attribution: anyOf: - $ref: '#/components/schemas/Attribution' - type: 'null' JsonValue: description: >- Any valid JSON value for provider, integration, theme, metadata, or other dynamic payloads whose keys are not fixed by the API contract. anyOf: - type: string - type: number - type: boolean - type: 'null' - type: array items: $ref: '#/components/schemas/JsonValue' - type: object additionalProperties: $ref: '#/components/schemas/JsonValue' ResponseMetadata: type: - object - 'null' properties: fluid_shop: type: - string - 'null' fluid_session: type: - string - 'null' fluid_locale: type: - string - 'null' format: /\A[a-z]{2}_[A-Z]{2}\z/ request_uuid: type: - string - 'null' format: uuid timestamp: type: - string - 'null' Attribution: anyOf: - $ref: '#/components/schemas/AttributionEmail' - $ref: '#/components/schemas/AttributionUsername' - $ref: '#/components/schemas/AttributionSharedGuid' - $ref: '#/components/schemas/AttributionFluidRepId' - $ref: '#/components/schemas/AttributionExternalId' AttributionEmail: type: - object - 'null' properties: email: type: - string - 'null' format: email AttributionUsername: type: - object - 'null' properties: username: type: - string - 'null' AttributionSharedGuid: type: - object - 'null' properties: share_guid: type: - string - 'null' AttributionFluidRepId: type: - object - 'null' properties: fluid_rep_id: type: - integer - 'null' AttributionExternalId: type: - object - 'null' properties: external_id: type: - string - 'null' ````