The HTTP API.

The API is the same runtime that renders your pages, so what a template can read, a request can usually read too. Most content reads are public. Everything that writes, and everything that returns personal data, is behind a credential and often a role. This page is the map; Authentication and roles covers how you sign a request and what each role may do.

The request and response model

Every JSON endpoint lives under the base path /api/v1, addressed on your own site host, for example https://your-site.fleeksite.com/api/v1/posts. The host resolves the tenant: a request always acts on the site whose address it was sent to. A handful of theme-facing endpoints (the PWA and SEO files below) sit at the site root instead, not under /api/v1.

Responses share one envelope. The top-level state says how it went, and the payload sits under data:

{ "data": { "item": { "uid": "a1b2c3", "title": "Home" } }, "state": "ok" }

A list endpoint returns its rows under data.items with a data.pagination block:

{ "data": { "items": [], "pagination": { "page": 1, "page_size": 20, "total_entries": 42, "more": true, "next_page": 2 } }, "state": "ok" }

An error carries a human-readable message at data.text:

{ "data": { "text": "Item Not Found" }, "state": "error" }

A few older handlers vary the envelope: state can be success (some auth and lead responses) or occasionally info, and a few write handlers put the payload under result rather than data, so an error message may read from result.text. Read state first, then look under both data and result. Key order in the raw JSON is data before state, which is cosmetic.

Access levels

The auth column in every table below uses three levels. They are enforced per handler, not per prefix, so two endpoints on the same resource can differ.

• Public. No credential. The tenant site is still resolved from the host, but no user is needed. Safe to call from a browser or a theme.
• Session. Any authenticated user. Send the bearer token from login, or rely on the current_user cookie. See Authentication and roles.
• Role. A per-site membership role at or above a threshold. In the tables, role 3+ means a membership role of 3 or higher on the site being addressed, and owner means the caller created the record in question.

Site data

The site record itself, and the sign-up endpoints that create one. Membership is resolved on the target site, so a caller cannot act on a site they do not belong to.

Content

The content resources a theme reads and an editor writes: posts, templates, bits, files, comments and redirects. Reads are public; writes take a credential, and most take a role.

Posts

Templates

Bits, files, comments and redirects

Leads and personal data

Lead submission is public, so a contact form on any page can post to it. Reading leads back is not: the records carry the submitter's personal data.

Commerce

The storefront resources: product variants and their options and attributes, orders, carts, discounts and subscriptions. Catalogue reads are public so a storefront can price and display products; writes and customer records are gated.

Checkout and the inbound payment webhooks sit under the /payments prefix, not /api/v1. POST /payments/checkout is public so guests can buy; the provider webhooks under /payments/webhooks/ verify a provider signature rather than a user credential.

PWA and SEO

These are theme-facing files, served from the site root and rendered from your templates when you supply one, else generated. They are all public GETs and none of them live under /api/v1. See PWA and push and SEO and meta for how each one is built.

Runtime and management

The developer and editor endpoints: the runtime manifest that drives the editor, server-side template validation, plugin and webhook management, storage and logs. The manifest is public; the rest need a role, because they change how the site runs.

To sign a request and understand what each role may do, continue to Authentication and roles. To validate and ship a template change, see Validate and deploy.