Skip to main content
The Fluid API is a versioned REST API that gives you programmatic access to your storefront: catalog, content, media, and the resources that back your storefront pages. Requests and responses are JSON, and every response follows a single, predictable envelope so your integration can parse success and error bodies the same way across every endpoint.

​
Base URLs

The API base URL is https://api.fluid.app. All requests are made over HTTPS. Public storefront reads are the one exception. They carry no token, so Fluid identifies your company from the request host. Send them to your storefront’s own host instead. For example, a company product request goes to https://api.fluid.app/api/v202604/company/products. A public catalog request goes to https://acme.fluid.app/api/v202604/products. The same public request sent to api.fluid.app returns 404, because the host names no storefront.

​
API versioning

The current, canonical surface is v2026-04. Its URL paths use the non-hyphenated form /api/v202604/...:
New standardized surfaces ship under date versions like this one. Earlier per-domain surfaces (v0/v1) remain live but frozen — no new fields or endpoints are added to them — so build new integrations against the current version.
A small number of related surfaces carry their own date version in the path. Each endpoint’s reference entry shows its exact path, so always copy the version from there. For token types, scopes, and how to pass credentials, see Authentication.

​
Authentication

Company endpoints require a bearer token in the Authorization header:
Public storefront endpoints (/api/v202604/{resource} and /api/v202604/{resource}/{slug}) require no authentication — the company is resolved from the request host. Company endpoints (/api/v202604/company/...) require a company-admin bearer token with storefront.view for reads and storefront.update for writes. See the Authentication guide for token types, scopes, and management.

​
Request format

Send request bodies as JSON and set the Content-Type header:
String values must be quoted, booleans must be true or false, and numbers must not be quoted.

​
Response format

Every successful response carries a top-level integer status, a meta object, and the resource under its own key. List endpoints return the resource under a plural key (for example products) and add a pagination object to meta:
Show, create, and update endpoints return a single resource under its singular key (for example product or category) and omit pagination:
meta.request_id is a per-request identifier (it may be null) — include it when contacting support so a request can be traced.

​
Errors

Validation (422) and not-found (404) responses use a wrapped error envelope that mirrors the success shape — an error object, a top-level status, and meta:
Two responses are deliberate exceptions to the envelope, and integrators should handle them explicitly. A 401 returns a bare { "message": "..." }, and a 403 returns a bare { "error": "..." } (or { "message": "..." } when the credential is not company-admin tier). Neither is wrapped in the error/status/meta envelope.
Status codes follow these conventions:

​
Pagination

List endpoints use opaque cursor pagination. Two query parameters control it: Each list response reports pagination under meta.pagination:
To walk a full result set, pass the response’s next_cursor as page[cursor] on the next request and repeat until next_cursor comes back null. Cursors are opaque strings — pass them back verbatim and do not attempt to decode or construct them. Pagination is count-free by design: there are no total_count or total_pages fields.

​
Localization

Every storefront resource can carry its translated text — title, description, and image — in more than one language. Reads render a locale with the lang query parameter (a field with no translation falls back to its English value); writes add a translation with a company PATCH carrying lang. Writing a translation is always a company update, never a public read, and never a separate translations endpoint. See Translate storefront resources for the full model and a per-resource reference.

​
What’s available

The v2026-04 storefront surface covers categories, collections, products, pages, posts, media, playlists, and enrollment packs — each with a public (unauthenticated) read surface and a company (token-authenticated) management surface. Browse every endpoint, with request and response schemas, in the auto-generated Endpoints reference.

Authentication

Token types, scopes, and how to pass and manage credentials.

Storefront API overview

The storefront resources, the current version, and how the public and company endpoints differ.

Find and create resources

List, search, and filter storefront resources, then create them with the company API.

Visibility, drafts, and scheduling

What makes a resource live, and what drafts return.

Agent signup

Create a Fluid company with one API call.

SEO

What search engines see, and how to control it.
Additional surfaces — including checkout, payments, and webhooks — are being published to this same standard.
Download the full OpenAPI specification at https://storage.googleapis.com/fluid-public/docs/api/storefront-v2026-04.yaml. This public mirror is synced hourly; the same spec is committed in this docs repo at api-reference/storefront-v2026-04.yaml and drives the Endpoints reference.