Skip to main content
The fluid member-site CLI is a client of two APIs. You can call them yourself to build a member site from your own code, a droplet or a script. This page covers which API to use, how to authenticate, how the file and page APIs behave, and where to find each operation. It doesn’t restate request or response schemas: each operation’s generated page in the API Reference holds those.
Member sites must be turned on for your company by Fluid. Until they are, every request to either API answers 404. To ask for them, contact support.

​
Choose the API

The owner of a site decides which API builds it.
  • The member API reaches only the signed-in member’s own sites. The one exception is copying, which also reaches a published site shared with the member with copy permission. A site another member owns, a site in another company and a malformed id all answer 404. A site is addressed by its public id, never by a numeric id.
  • The company API reaches every site in the company. An admin lists, reads, takes down, deletes and copies a member’s site, and can list and restore its versions. An admin builds a company site: its files, pages and publishing.
  • An admin can’t change a member’s site. For a member’s site, the company API’s file, page and publish routes answer 403, and its routes that create a branch or a share answer 404. The owner builds it. The CLI follows the same rule: see Choose the login.
Send the credential as a Bearer token to https://api.fluid.app.

​
Authenticate

​
The member API

The member API acts as the signed-in member. The credential alone decides which member and which company a request is about. Its credentials are the member’s own: an opaque member token, a member session JWT, a portal JWT linked to a membership in that company, or a verified One Auth identity access token. See Member APIs.
  • It refuses company, partner, public and droplet installation tokens. It also refuses an admin credential, and a credential for a member who is also an admin of that company. That is why the CLI says a member who is an admin builds company sites only.
  • It takes a bearer token only. A request on the same-origin cookie mount is refused with 403, even with a valid member session, because a script on your company’s storefront shares that origin.
  • A member session JWT and a portal JWT are read-only. A write with either answers 403. Use a member token to build. The credential that order and subscription emails carry is a member session JWT. It is also refused on the account menu, the shares and the share-target search.
  • Any member can build. A member needs no particular member type to own sites.

​
The company API

The company API takes a company admin credential. Reading needs the application_themes.view permission and writing needs application_themes.update, the permissions the theme API uses.
  • A write needs a signed-in admin. A company API token, a droplet installation token and any other credential with no user can read, and every write answers 403.
  • A company API token reads sites, pages, versions, shares, branches and the featured list. It can’t read files, which hold a site’s code, and it can’t preview a draft.
  • A droplet installation token with the website scope can read sites, pages and the featured list, and versions when its installation role grants application_themes.view. It is refused on files, shares and branches.
  • An OAuth client token is refused on shares and branches, whatever its scopes.
See Authentication for the token types.

​
Know the order of the checks

A refused credential answers 401 or 403 before anything else, so a refused credential never learns whether member sites are on. A valid credential for a company without member sites then answers 404. A 404 can therefore mean the feature is off, the site is missing, or the site belongs to someone else.

​
Build a member’s site

This builds a site with the member API: create it, write a layout, add a page and publish. The CLI does the same steps from a folder.
A member’s site opens at /accounts/rileys-shop once it is published and the member can open it. See Share a member site. The member API’s bodies are plain JSON objects, and its responses carry the record under data. The company API wraps its bodies and responses in a named key instead: member_site, member_site_file, member_site_page, member_site_share and so on. A company site is created with { "member_site": { "name": "Fall Launch", "visibility": "public" } }. The generated page for each operation shows its exact body.

​
Use the file API

A site’s files have theme-style paths with no subfolders: layouts/, sections/, snippets/, pages/, assets/ and config/. Pages and menus and Build pages with Liquid describe what each holds.
  • One call creates and replaces. Write a site file takes the whole new content of the file at the path in the URL.
  • Every file has a version. Send it back to write the file only if it hasn’t changed since you read it. Send must_not_exist to create a file only if the path is free. Send one of the two, not both. With neither, the write replaces whatever is there and the last write wins. A stale version, or a file that exists under must_not_exist, answers 409, and nothing is written.
  • config/settings.json is versioned by the settings’ lock_version. It moves when a page changes or when config/menus.json is written, so read the settings again before a versioned write.
  • A page’s file must exist before you write it. Add the page first. Pages can’t be removed through the file API: use Remove a page.
  • Writing a config file does more than save it. config/menus.json replaces every menu, and config/pages.json adds, changes and removes pages to match it. config/access.json is a member site’s draft declaration, and a company site refuses it.
  • Assets are text only. An asset is css, js, json, txt or html, and isn’t empty.
  • Layouts, sections, snippets and pages are drafts until you publish. See Know what is live at once.
List a site’s files returns each file’s metadata without its content, a cursor page at a time: send page[cursor] and page[limit], and follow meta.pagination.next_cursor until it is null. A page holds 25 files by default and at most 100. A cursor works only for the site that issued it. A bad cursor answers 400 from the member API and 422 from the company API.

​
Use the page API

The page API changes one page and its content in one step. A site holds at most 50 pages, so the page list isn’t paged. A member holds at most 25 sites, so that list isn’t paged either. The company’s list of sites is paged with page[cursor] and page[limit], and filters with filter[owner_kind] and filter[status]. Send the lock_version you last read when you change or remove a page or a site, and the request answers 409 if it changed since. Without it the change is applied to the current record.

​
Preview a draft

The preview operations return a site’s draft as HTML or text, so you can check a page before you publish. They take a bearer token. Only the owner sees a member’s draft, and a company site’s draft needs a signed-in admin. See Preview the draft.

​
Find every operation

The generated pages hold each operation’s parameters, bodies and responses.

​
Sites

​
Files, pages and preview

​
Publishing, versions and branches

See Publish, restore, copy and take down a member site for how these behave.

​
Shares

See Share a member site.

​
The account menu, pins and home

These belong to the signed-in member, so only the member API has them. Featuring is the company’s version. See Member sites in the account menu.