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:
- The first call to an endpoint that needs a session answers with a header
X-Session-Token: <40 characters>(andX-Session-Token-Issued: true). - The app stores it and sends
X-Session-Tokenon every later call. - 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.
App links and passkeys
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
name | string | |
email | string (email) | |
current_password | string |
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
password | string | |
code | string |
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 | |
label | string | |
company | string | |
line2 | string | |
phone | string | |
is_default | boolean |
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 | |
device | string | a 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 | |
code | string | two-factor code, when asked for |
device | string | a 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 * | object | the assertion from the platform |
device | string | a 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 | |
device | string | a 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 | |
device | string | a 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
Booking
GET
/booking/services
Bookable services (appointments, classes, rooms, hire)
Parameters
kind | query |
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 | |
date | query | |
party | query | |
from | query | |
to | query | |
adults | query | |
children | query | |
infants | query | |
plan | query |
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
start | string (date-time) | |
session | integer | |
from | string (date) | |
to | string (date) | |
party | integer | |
name | string | |
email | string (email) | |
phone | string | |
note | string |
Answer · {"data": …}
Bookings
GET
/bookings/{reference}
One booking
session
Parameters
reference * | path | |
t | query | the 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
t | string | guests |
Answer · {"data": …}
GET
/me/bookings
The customer's bookings
sign-in session
Parameters
when | query |
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_id | integer | its default variant |
variant_id | integer | |
quantity | integer | |
spec | object | chosen 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
after | query | only messages after this id (polling) |
Answer · {"data": …}
POST
/chat/messages
Write in the chat
session
JSON body
body * | string | |
name | string | |
email | string (email) |
Answer · {"data": …}
Checkout
GET
/checkout
Everything the checkout screen needs
session
Parameters
country | query | ISO code for the shipping quotes |
shipping_method | query |
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 * | string | an id from GET /checkout |
terms * | boolean | the customer ticked the terms |
billing_address * | object | name, line1, postcode, city, country (+ company, line2, phone) |
ship_to_different | boolean | |
shipping_address | object | |
shipping_method | string | |
note | string |
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 * | query | e.g. /blog/spring-menu |
Answer · {"data": …}
POST
/comments
Write a comment
Held for approval as on the website.
JSON body
path * | string | |
body * | string | |
name | string | needed when not signed in |
email | string (email) | needed when not signed in |
parent_id | integer |
Answer · {"data": …}
Contact
POST
/contact
Send the contact form
JSON body
email * | string (email) | |
message * | string | |
name | string | |
phone | string | |
company | string | |
subject | string |
Answer · {"data": …}
Devices
POST
/me/devices
Register this device for push
sign-in
JSON body
token * | string | the FCM token |
platform * | ios | android | web | |
topics | array<string> | e.g. news; only topics the site offers are kept |
locale | string |
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
guests | integer | |
name | string | guests |
email | string (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
Newsletter
Notifications
GET
/me/notifications
The customer's inbox
sign-in
Parameters
status | query |
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 | |
access | query | the key from checkout (guests) |
Answer · {"data": …}
GET
/orders/{reference}/messages
The conversation about an order
session
Parameters
reference * | path | |
access | query | guests |
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
category | query | category slug |
tag | query | tag slug |
q | query |
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
category | query | category slug |
type | query | |
q | query |
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 | |
limit | query | |
sort | query |
Answer · {"data": …}
Reviews
POST
/reviews
Write a review (checked before it shows)
session
JSON body
product_id * | integer | |
rating * | integer | 1 to 5 |
body * | string | |
title | string | |
author_name | string | guests |
email | string (email) | guests |
order | string | order reference, for the verified badge |
Answer · {"data": …}
Search
GET
/search
Search the site
Parameters
q * | query | at least 2 characters |
Answer · {"data": …}
Subscriptions
GET
/me/subscriptions
Subscriptions with their renewal links
sign-in session
Answer · {"data": …}
Tags
Tickets
GET
/me/tickets
The customer's tickets
sign-in session
Answer · {"data": …}
GET
/tickets/{reference}
One ticket
session
Parameters
reference * | path | |
t | query | the access key (guests) |
Answer · {"data": …}
POST
/tickets/{reference}/cancel
Cancel an RSVP
session
Parameters
reference * | path |
JSON body
t | string | guests |
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": …}