Skip to content
Ergon Code

Ergon CMS · Documentation

Site API

The API for apps that serve a website's customers — sign-in, sessions, the answer format, caching, retries, limits — with the full reference.

Every Ergon CMS website answers at https://<site>/api/site/v1. What it offers depends on its active plugins; GET /bootstrap says which (features), and GET /openapi.json describes every endpoint of that very site, ready for a code generator.

Switch it on under Settings → API → Apps for your customers (it is on by default). The same screen holds the minimum app versions, store links, maintenance notice, and the ids for app links, passkeys and Apple/Google sign-in.

The answer format

{ "data": { "slug": "spring-menu", "title": "Spring menu", "blocks": [ … ] } }

Lists add paging:

{ "data": [ … ], "meta": { "page": 1, "per_page": 20, "total": 57, "last_page": 3 },
  "links": { "next": "https://…/posts?page=2", "prev": null } }

Errors always look like this, whatever went wrong:

{ "error": { "code": "validation_failed", "message": "Please fill in the email address.",
             "fields": { "email": ["Please fill in the email address."] } } }
Status code (examples) Meaning
401 unauthenticated no token, or it expired — renew with /auth/refresh
403 members_only, email_not_verified signed in, but not allowed (yet); members_only carries a paywall
404 not_found does not exist, or is not yours
409 not_payable the state does not allow it any more
422 validation_failed, coupon_rejected, booking_rejected … the input, or a rule of the shop or booking said no
429 too_many_requests slow down; see Retry-After
503 site_api_disabled, maintenance the Site API is switched off, or the whole site is down for maintenance

Conventions: money is {"amount": 1999, "currency": "EUR", "formatted": "19,99 €"} (amount in cents), times are ISO 8601 in UTC, images come with width, height and ready sizes (thumb, small, medium, large, srcset).

Language

Send Accept-Language: de (or ?locale=de). Content comes in that language where it is translated, otherwise in the site's default. /bootstrap lists the site's languages.

Customers and tokens

Public content needs no key — there is nothing secret to ship inside the app. A customer signs in in one of four ways; each returns the same pair:

{ "data": { "token_type": "Bearer", "access_token": "…", "expires_in": 3600, "refresh_token": "…",
            "user": { "id": 12, "name": "Ama Owusu", "email": "[email protected]" } } }
Way Calls
Email + password POST /auth/register → (verification_required) → POST /auth/email/verify with the 6-digit code; later POST /auth/login
Passkey POST /auth/passkey/options → platform passkey API → POST /auth/passkey
Apple / Google the platform SDK's ID token → POST /auth/social/apple or /auth/social/google
Forgotten password POST /auth/password/forgot → code by email → POST /auth/password/reset

Send the access token as Authorization: Bearer …. It lives an hour; before that, swap the refresh token at POST /auth/refresh for a new pair. Refresh tokens work once: using one twice (a stolen copy) ends that sign-in on every device. Store both in the platform keychain, never in plain preferences.

Customer tokens only open the Site API. They never reach staff routes, and a staff token is not accepted where a customer is expected.

The account side: GET/PATCH /me, PUT /me/password, GET /me/sessions (signed-in devices, each can be ended), GET /me/export (all stored data), and DELETE /me — apps that create accounts must let people delete them (App Store rule 5.1.1(v), Google Play's account deletion policy).

The app session

Shops keep a visitor's cart, coupons, gift card and guest orders in a session. An app has no cookie, so it carries a token instead:

  1. The first call to an endpoint that needs a session answers with a header X-Session-Token: <40 characters> (and X-Session-Token-Issued: true).
  2. The app stores it and sends X-Session-Token on every later call.
  3. When a guest signs in, the next call with the same token moves the guest cart into the account.

Endpoints marked with the X-Session-Token parameter in the reference use it.

Paying

POST /checkout places the order and starts the payment. The answer's payment.status says what the app does next:

status The app …
client pays inside the app: payment.data holds the Stripe client_secret and publishable_key for PaymentSheet
redirect opens payment.url in an in-app browser (PayPal, Klarna, others), then polls GET /orders/{reference}
pending shows payment.instructions (bank transfer, pay on collection)
paid is done (a gift card or points covered everything)

The order is confirmed by the payment provider's webhook on the server — never by the app saying so. A guest keeps the order's access key to open it later.

Caching

Read answers carry an ETag. Send it back as If-None-Match and an unchanged answer comes back as 304 Not Modified with no body. Public answers may be cached for 60 seconds (Cache-Control: public, max-age=60); anything with a token or session is private.

Retries

Send an Idempotency-Key (any unique string, up to 128 characters) with writes that must not happen twice — placing an order, booking, RSVP. Repeating the call with the same key within 24 hours replays the first answer (with Idempotent-Replayed: true) instead of doing it again.

Limits

Each customer (or, without a token, each IP address) may make 240 calls a minute by default (Settings → API). Sign-in endpoints are stricter: 20 a minute per address and 6 per email. Over the limit the answer is 429 with Retry-After.

App versions and maintenance

Send X-App-Version: ios/1.4.0. The API Monitor plugin shows calls per app version, which tells you when an old version can be dropped. /bootstrap returns app.min_version per platform with the store links: an app below it should ask for an update. With the maintenance switch on, /bootstrap says so and the app shows the message.

Push

POST /me/devices registers the device's FCM token and the topics it follows (news by default). Customers receive pushes for their orders, replies about an order, chat answers and anything a plugin sends; each also lands in GET /me/notifications with a path the app opens. The site's team sends news to a topic from Settings → API.

With the iOS app id and the Android package and signing fingerprints filled in, the site publishes /.well-known/apple-app-site-association and /.well-known/assetlinks.json. That lets links to the site open in the app, and lets passkeys made on the website work in the app and back.

Versions

This is version 1. Within it, things are only added. A route that goes away first answers with Deprecation: true, a Sunset date and a Link to what replaces it, for at least six months.

Reference

Base URL https://<site>/api/site/v1. Generated from an installation with every plugin active; each site's own description is at /api/site/v1/openapi.json. Download openapi.json

Account

GET /me The signed-in customer sign-in

Answer · {"data": …}

PATCH /me Change name or email sign-in

A new email address needs the current password.

JSON body

namestring
emailstring (email)
current_passwordstring

Answer · {"data": …}

DELETE /me Delete the account sign-in

App Store rule 5.1.1(v): an app that creates accounts must let people delete them. Needs the password, or a code from /password/forgot for accounts made with Apple/Google.

JSON body

passwordstring
codestring

Answer · {"data": …}

GET /me/export Everything stored about the customer (GDPR Art. 15/20) sign-in

Answer · {"data": …}

PUT /me/password Change the password sign-in

JSON body

current_password *string
password *string
password_confirmation *string

Answer · {"data": …}

GET /me/sessions Signed-in devices sign-in

Answer · {"data": …}

DELETE /me/sessions/{id} Sign out one device sign-in

Parameters

id *path

Answer · {"data": …}

Addresses

GET /me/addresses Saved addresses sign-in session

Answer · {"data": …}

POST /me/addresses Save an address (up to 20) sign-in session

JSON body

name *string
line1 *string
postcode *string
city *string
country *string
labelstring
companystring
line2string
phonestring
is_defaultboolean

Answer · {"data": …}

PUT /me/addresses/{address} Change an address sign-in session

Parameters

address *path

JSON body

name *string
line1 *string
postcode *string
city *string
country *string

Answer · {"data": …}

DELETE /me/addresses/{address} Delete an address sign-in session

Parameters

address *path

Answer · {"data": …}

Auth

POST /auth/email/resend Email a new confirmation code

JSON body

email *string (email)

Answer · {"data": …}

POST /auth/email/verify Confirm the email address with the 6-digit code

JSON body

email *string (email)
code *string
devicestringa name for this device, shown under signed-in devices

Answer · {"data": …} — access_token, refresh_token, expires_in and the customer

POST /auth/login Sign in with email and password

JSON body

email *string (email)
password *string
codestringtwo-factor code, when asked for
devicestringa name for this device, shown under signed-in devices

Answer · {"data": …} — access_token, refresh_token, expires_in and the customer. two_factor_required → send again with code; email_not_verified → a new code was emailed

POST /auth/logout Sign out this device sign-in

Answer · {"data": …}

POST /auth/logout-all Sign out every device sign-in

Answer · {"data": …}

POST /auth/passkey Finish a passkey sign-in

JSON body

challenge_id *string
credential *objectthe assertion from the platform
devicestringa name for this device, shown under signed-in devices

Answer · {"data": …} — access_token, refresh_token, expires_in and the customer

POST /auth/passkey/options Start a passkey sign-in

Answer · {"data": …} — challenge_id and the WebAuthn request options for the platform passkey API

POST /auth/password/forgot Email a password reset code

Always answers sent: true, so it never tells whether an address has an account.

JSON body

email *string (email)

Answer · {"data": …}

POST /auth/password/reset Set a new password with the emailed code

Signs the customer out on every other device.

JSON body

email *string (email)
code *string
password *string
password_confirmation *string
devicestringa name for this device, shown under signed-in devices

Answer · {"data": …} — access_token, refresh_token, expires_in and the customer

POST /auth/refresh Renew the access token

Refresh tokens rotate: each one works once. Using one twice ends that sign-in everywhere.

JSON body

refresh_token *string

Answer · {"data": …} — access_token, refresh_token, expires_in and the customer

POST /auth/register Create a customer account

JSON body

name *string
email *string (email)
password *string
password_confirmation *string
devicestringa name for this device, shown under signed-in devices

Answer · {"data": …} — When email confirmation is on: verification_required and a code is emailed; otherwise access_token, refresh_token, expires_in and the customer

POST /auth/social/{provider} Sign in with Apple or Google

Send the ID token the platform SDK gave the app; it is verified against the client ids in Settings → API → Apps for your customers.

Parameters

provider *path

JSON body

id_token *string
namestringApple sends the name only the first time
devicestringa name for this device, shown under signed-in devices

Answer · {"data": …} — access_token, refresh_token, expires_in and the customer

Booking

GET /booking/services Bookable services (appointments, classes, rooms, hire)

Parameters

kindquery

Answer · {"data": …}

GET /booking/services/{slug} One service with its availability

availability by kind — appointment: ?date=YYYY-MM-DD&party= gives slots · class: upcoming sessions · room: ?from=&to=&adults=&children=&infants=&plan=&extras[]= gives a quote · rental: ?from=&to= gives a quote and the deposit.

Parameters

slug *path
datequery
partyquery
fromquery
toquery
adultsquery
childrenquery
infantsquery
planquery

Answer · {"data": …}

POST /booking/services/{slug} Book session

Fields by kind — appointment: start (ISO time from slots), party · class: session, party, waitlist · room: from, to, adults, children, infants, plan, extras · rental: from, to. Always name and email (taken from the account when signed in), phone, note. A booking that must be paid lands in the cart (next: checkout).

Parameters

slug *path

JSON body

startstring (date-time)
sessioninteger
fromstring (date)
tostring (date)
partyinteger
namestring
emailstring (email)
phonestring
notestring

Answer · {"data": …}

Bookings

GET /bookings/{reference} One booking session

Parameters

reference *path
tquerythe access key (guests)

Answer · {"data": …}

POST /bookings/{reference}/cancel Cancel a booking session

Allowed until the notice period; a paid booking is cancelled by the business.

Parameters

reference *path

JSON body

tstringguests

Answer · {"data": …}

GET /me/bookings The customer's bookings sign-in session

Parameters

whenquery

Answer · {"data": …}

Bootstrap

GET /bootstrap Everything the app needs at start

Site name, colours, languages, which features the site has (shop, booking, events …), minimum app versions with store links, maintenance notice, legal links, the page blocks the app draws natively. Call it on every start; it is cached (ETag).

Answer · {"data": …}

Cart

GET /cart The app session's cart with server totals session

Answer · {"data": …}

DELETE /cart Empty the cart session

Answer · {"data": …}

POST /cart/coupon Apply a coupon code session

JSON body

code *string

Answer · {"data": …} — the cart

DELETE /cart/coupon Remove a coupon session

JSON body

code *string

Answer · {"data": …}

POST /cart/gift-card Pay with a gift card session

JSON body

code *string

Answer · {"data": …} — the cart

DELETE /cart/gift-card Remove the gift card session

Answer · {"data": …}

POST /cart/items Put a product in the cart session

JSON body

product_idintegerits default variant
variant_idinteger
quantityinteger
specobjectchosen options

Answer · {"data": …}

PATCH /cart/items/{item} Change a line's quantity (0 removes it) session

Parameters

item *path

JSON body

quantity *integer

Answer · {"data": …}

DELETE /cart/items/{item} Remove a line session

Parameters

item *path

Answer · {"data": …}

POST /cart/points Redeem points on the cart sign-in session

JSON body

points *integer

Answer · {"data": …}

DELETE /cart/points Stop redeeming points sign-in session

Answer · {"data": …}

Categories

GET /categories Blog categories

Answer · {"data": …}

Chat

GET /chat/messages The chat conversation of this app session session

Parameters

afterqueryonly messages after this id (polling)

Answer · {"data": …}

POST /chat/messages Write in the chat session

JSON body

body *string
namestring
emailstring (email)

Answer · {"data": …}

Checkout

GET /checkout Everything the checkout screen needs session

Parameters

countryqueryISO code for the shipping quotes
shipping_methodquery

Answer · {"data": …} — cart with shipping_quotes, gateways, countries, legal links, extra_fields plugins ask for, the signed-in customer

POST /checkout Place the order and start the payment session

Send an Idempotency-Key: a retried tap never orders twice. payment.status: paid (nothing left to pay) · client (pay in the app: payment.data has the Stripe client_secret and publishable_key for PaymentSheet) · redirect (open payment.url in an in-app browser, then poll GET /orders/{reference}) · pending (pay later; payment.instructions). Keep access to open the order as a guest.

JSON body

email *string (email)
gateway *stringan id from GET /checkout
terms *booleanthe customer ticked the terms
billing_address *objectname, line1, postcode, city, country (+ company, line2, phone)
ship_to_differentboolean
shipping_addressobject
shipping_methodstring
notestring

Answer · {"data": …}

Collections

GET /collections Public content types (team, menu, FAQ …)

Answer · {"data": …}

GET /collections/{type} Published entries of a type

Parameters

type *path

Answer · {"data": …}

GET /collections/{type}/{slug} One entry with its fields

Parameters

type *path
slug *path

Answer · {"data": …}

Comments

GET /comments Approved comments of a page or post

Parameters

path *querye.g. /blog/spring-menu

Answer · {"data": …}

POST /comments Write a comment

Held for approval as on the website.

JSON body

path *string
body *string
namestringneeded when not signed in
emailstring (email)needed when not signed in
parent_idinteger

Answer · {"data": …}

Contact

POST /contact Send the contact form

JSON body

email *string (email)
message *string
namestring
phonestring
companystring
subjectstring

Answer · {"data": …}

Devices

POST /me/devices Register this device for push sign-in

JSON body

token *stringthe FCM token
platform *ios | android | web
topicsarray<string>e.g. news; only topics the site offers are kept
localestring

Answer · {"data": …}

DELETE /me/devices Stop push to this device sign-in

JSON body

token *string

Answer · {"data": …}

Events

GET /events Upcoming events

Answer · {"data": …}

GET /events/{slug} One event

Parameters

slug *path

Answer · {"data": …}

POST /events/{slug}/rsvp RSVP / get tickets session

A paid event puts the tickets in the cart (next: checkout). Keep access to open the ticket as a guest. check_in_code is what the app shows as a QR code at the door.

Parameters

slug *path

JSON body

guestsinteger
namestringguests
emailstring (email)guests

Answer · {"data": …}

Forms

GET /forms/{key} A form's fields, in the asked language

requires_sign_in: true for forms protected by a captcha on the website — the app sends them as a signed-in customer.

Parameters

key *path

Answer · {"data": …}

POST /forms/{key} Send a form

Body: the field keys from GET /forms/{key}. Validated with the form's own rules.

Parameters

key *path

Answer · {"data": …}

Membership

GET /me/membership The customer's membership level sign-in session

Answer · {"data": …}

GET /membership/tiers Membership tiers on offer

Answer · {"data": …}

Menus

GET /menus All menus by location

Answer · {"data": …}

GET /menus/{location} One menu

Parameters

location *path

Answer · {"data": …}

Newsletter

GET /newsletter The consent text and privacy link to show next to the sign-up

Answer · {"data": …}

POST /newsletter Sign up (double opt-in)

Sends the confirmation email; the address is subscribed once it is confirmed.

JSON body

email *string (email)
consent *booleanmust be true
namestring
interestsstring

Answer · {"data": …}

Notifications

GET /me/notifications The customer's inbox sign-in

Parameters

statusquery

Answer · {"data": …}

POST /me/notifications/read-all Mark all read sign-in

Answer · {"data": …}

POST /me/notifications/{id}/read Mark one message read sign-in

Parameters

id *path

Answer · {"data": …}

Orders

GET /me/orders The customer's orders sign-in session

Answer · {"data": …}

GET /orders/{reference} One order session

Includes downloads and invoices when those plugins are active.

Parameters

reference *path
accessquerythe key from checkout (guests)

Answer · {"data": …}

GET /orders/{reference}/messages The conversation about an order session

Parameters

reference *path
accessqueryguests

Answer · {"data": …}

POST /orders/{reference}/messages Write to the shop about an order session

Parameters

reference *path

JSON body

body *string

Answer · {"data": …}

POST /orders/{reference}/pay Pay an open order again session

Parameters

reference *path

JSON body

gateway *string

Answer · {"data": …}

Pages

GET /pages Published pages

Answer · {"data": …}

GET /pages/{slug} One page with its blocks

Blocks the app draws natively carry data; every block also carries ready html as a fallback. "home" is the front page. A members-only page answers 403 members_only with a paywall.

Parameters

slug *path

Answer · {"data": …}

Points

GET /me/points Points balance and what a point is worth sign-in session

Answer · {"data": …}

Posts

GET /posts Published posts

Parameters

categoryquerycategory slug
tagquerytag slug
qquery

Answer · {"data": …}

GET /posts/{slug} One post with its blocks

A members-only post answers 403 members_only with a paywall.

Parameters

slug *path

Answer · {"data": …}

Product Categories

GET /product-categories Product categories

Answer · {"data": …}

Products

GET /products Published products

Parameters

categoryquerycategory slug
typequery
qquery

Answer · {"data": …}

GET /products/{slug} One product with variants, prices (Money) and blocks

Parameters

slug *path

Answer · {"data": …}

GET /products/{slug}/reviews Approved reviews and the rating summary

Parameters

slug *path
limitquery
sortquery

Answer · {"data": …}

Reviews

POST /reviews Write a review (checked before it shows) session

JSON body

product_id *integer
rating *integer1 to 5
body *string
titlestring
author_namestringguests
emailstring (email)guests
orderstringorder reference, for the verified badge

Answer · {"data": …}

Subscriptions

GET /me/subscriptions Subscriptions with their renewal links sign-in session

Answer · {"data": …}

Tags

GET /tags Blog tags

Answer · {"data": …}

Tickets

GET /me/tickets The customer's tickets sign-in session

Answer · {"data": …}

GET /tickets/{reference} One ticket session

Parameters

reference *path
tquerythe access key (guests)

Answer · {"data": …}

POST /tickets/{reference}/cancel Cancel an RSVP session

Parameters

reference *path

JSON body

tstringguests

Answer · {"data": …}

Wishlist

GET /me/wishlist The wishlist sign-in session

Answer · {"data": …}

POST /me/wishlist Save or unsave a product sign-in session

JSON body

product_id *integer

Answer · {"data": …}

DELETE /me/wishlist/{product} Remove a product sign-in session

Parameters

product *path

Answer · {"data": …}