Find and create storefront resources

Every storefront resource is found and created the same way. The examples here use posts. Swap posts for any other resource path, and post for that resource’s body key — see Storefront resources for the list.

List a resource

GET /api/v202604/<resource> returns a page of live resources: the ones a shopper can see right now. Call it on the store’s own host, with no token:

curl "https://acme.fluid.app/api/v202604/posts"

Rows come back in an array named after the resource, next to a status and a meta block:

{
  "status": 200,
  "posts": [
    {
      "id": 7314,
      "slug": "spring-training-plan",
      "title": "Your spring training plan",
      "description": "Four weeks of workouts to build a base before race season.",
      "image_url": "https://cdn.fluid.app/posts/7314/cover.jpg",
      "canonical_url": "https://acme.fluid.app/home/blog/spring-training-plan",
      "active": true,
      "status": "published",
      "publish_at": null,
      "countries": [],
      "languages": ["en"]
    }
  ],
  "meta": {
    "request_id": "7f3c2a90-1c2b-4d5e-9aaa-112233445566",
    "timestamp": "2026-09-29T12:34:56Z",
    "pagination": {
      "cursor": null,
      "next_cursor": "eyJpZCI6NzMxNH0",
      "prev_cursor": null,
      "limit": 25
    }
  }
}

Every resource list accepts these query parameters:

string

Free-text search over title and description.

string

An ISO-2 country code. Returns resources available in that country, including unrestricted ones. Products use country instead. See Country availability.

string

A language code. Returns only resources translated into that language. Not available on products.

string

A sort key. Prefix it with - for descending order, for example -created_at. Each resource has its own default order — see Storefront resources.

string

The language to return text in, for example fr. Omit it for the store’s default language.

Some resources add their own filters, such as filter[parent_id] on categories or filter[media_type] on media. See Storefront resources.

curl "https://acme.fluid.app/api/v202604/posts?q=training&filter[country]=GB&sort=-created_at"

Page through results

Lists use cursor pagination. Pass meta.pagination.next_cursor back as page[cursor] to get the next page, and repeat until next_cursor is null. page[limit] sets the page size: the default is 25 and the maximum is 100. A larger value returns 422.

curl "https://acme.fluid.app/api/v202604/posts?page[limit]=50&page[cursor]=eyJpZCI6NzMxNH0"

Look one up by slug

GET /api/v202604/<resource>/{slug} returns one resource, under its singular key:

curl "https://acme.fluid.app/api/v202604/posts/spring-training-plan"

A slug lookup can return a resource that isn’t in the public list, such as a draft. See Visibility, drafts, and scheduling before you rely on it.

Find anything as an admin

The company list returns every resource of that type, whatever its state. Call it on https://api.fluid.app with a Bearer token:

curl "https://api.fluid.app/api/v202604/company/posts" \
  -H "Authorization: Bearer <token>"

It accepts the same parameters as the public list, plus two that the public side ignores:

string

One status value, such as draft or published. On products, use active, draft, or archived.

string

"true" or "false". Not available on products.

curl "https://api.fluid.app/api/v202604/company/posts?filter[status]=draft" \
  -H "Authorization: Bearer <token>"

To fetch one resource as an admin, use its numeric id:

curl "https://api.fluid.app/api/v202604/company/posts/7314" \
  -H "Authorization: Bearer <token>"

Create a resource

POST /api/v202604/company/<resource> creates a resource. Wrap the fields in the resource’s body key. title is the only required field:

curl -X POST "https://api.fluid.app/api/v202604/company/posts" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "post": {
      "title": "Your spring training plan"
    }
  }'

A fuller create can set the slug, lifecycle, countries, metafields, and SEO in one request:

curl -X POST "https://api.fluid.app/api/v202604/company/posts" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "post": {
      "title": "Your spring training plan",
      "description": "Four weeks of workouts to build a base before race season.",
      "slug": "spring-training-plan",
      "custom_slug": true,
      "active": true,
      "status": "scheduled",
      "publish_at": "2026-10-06T08:00:00Z",
      "country_isos": ["GB", "US"],
      "metafields_attributes": [
        {
          "namespace": "custom",
          "key": "reading_time",
          "value": "6 min",
          "value_type": "single_line_text_field"
        }
      ],
      "search_engine_optimizer_attributes": {
        "title": "Spring training plan: four weeks to race-ready",
        "description": "A four-week base-building plan for runners.",
        "indexable": true
      }
    }
  }'

A successful create returns 201 with the new resource under its singular key. Things to know when you write:

Updates change only what you send. PATCH /api/v202604/company/<resource>/{id} leaves every key you leave out as it was.
Unknown keys are rejected. A key the write schema doesn’t define returns 422. Don’t send a response object back as a write: fields like countries and seo are read-only.
SEO is written and read under different keys. Write it as search_engine_optimizer_attributes. Read it as seo. See SEO.
Visibility is two fields. active (or public, for products) switches the resource on or off, and status sets its lifecycle. See Visibility, drafts, and scheduling.
Slugs are generated unless you pin one. See Slugs and URLs.
Metafields are public. Everything in metafields is returned by the public endpoints, so keep private data out of them.

Get started

Sites

Mist apps

Core concepts

Guides

Guided setup

Storefront guides

SDKs

Portal & Widgets

Find and create storefront resources

List a resource

Search, filter, and sort

Page through results

Look one up by slug

Find anything as an admin

Create a resource

Next steps