SitePack App API (v1)

The app API uses the same OAuth flow as the SitePack CLI.

GET /api/authentication/oauth/authorize
    ?client_id=your-client-id
    &scope=content:write%20media:read
    &redirect_uri=https://your-app.example/callback
    &state=csrf-token

The merchant picks a site and approves the scopes you asked for, then you are sent back with a code. Exchange it:

POST /api/authentication/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=…&client_id=…&client_secret=…

Send the result on every request. X-SitePack-Access-Token is the preferred header; a standard Authorization: Bearer <access_token> is also accepted:

X-SitePack-Access-Token: <access_token>

Access tokens last an hour; refresh them with grant_type=refresh_token.

A token is bound to one site. The site is never a parameter — an app that serves ten merchants holds ten tokens. That is also why a uuid from one site is simply not found on another.

Three things must hold, and they are checked on every request:

1. your installation on that site is active;
2. the app's subscription on that site is active — if the merchant cancels a paid app, API access stops immediately;
3. the scope is one the merchant actually granted.

Point three is an intersection, re-evaluated per request: if a merchant removes a scope, it stops working at once rather than when your hour-long token expires. GET /me shows the scopes in force right now.

An app with no scopes can reach /me and /scopes, and nothing else.

Scopes read section:action. write implies read; nothing else is implied, and there is no wildcard scope.

Two scopes spend the merchant's money and therefore stand alone — domains:order and mail:order. Holding domains:write does not let you order a domain.

Ask for the narrowest set that does the job: merchants see every scope you request on the consent screen.

Everything is addressed by uuid. No endpoint takes an auto-increment id and no response returns one. New records get a uuid v7, which is time-ordered, so sorting by uuid sorts by creation.

Every response carries a status. Lists are paginated with page and limit (max 100):

{
  "status": "success",
  "items": [],
  "pagination": { "page": 1, "limit": 25, "totalRecords": 42, "totalPages": 2 }
}

Errors name a machine-readable code — switch on error.code, never on the message:

{
  "status": "error",
  "error": { "code": "scope_required", "message": "…", "scope": "content:write" }
}

Every response carries your budget, so you never have to discover a limit by being cut off:

X-SitePack-RateLimit: 600
X-SitePack-RateLimit-Tokens: 574
X-SitePack-RateLimit-Reset: 1750000060

Keying the main budget on the installation rather than on your address means serving many merchants from one server does not throttle you — but it also means one app of yours cannot spend another's budget.

A 429 names Retry-After in seconds. Wait that long; retrying sooner only spends what is left of the window.

The order bucket is separate because those endpoints charge the merchant: a loop that lists domains is a mistake, a loop that buys them is an invoice.

Subscriptions are declared in your app.json manifest. Payloads are deliberately thin: arguments carries only the uuid of the resource that changed. Call the API with that uuid to read the details.

That means a payload can never contain something you are not scoped to read, and can never be stale — by the time a retry lands, embedded values might describe a version that no longer exists, while a uuid always resolves to the current one.

Treat an event as "go look at this", not as data.

• Pages are styled through element settings, not inline HTML. Inline style= attributes are stripped from anything you submit; alignment and colour are lifted into the element's settings so the intent survives.
• Elements cannot carry script. <script> blocks, on…= handlers and javascript: URLs are removed from element values. Markup, links and embeds are left alone — it is scripting specifically that is not yours to add, because the merchant opens your page in their own admin session.
• Responses are never cached. They come back Cache-Control: no-store, private, since most of what they contain is the merchant's data and all of it is specific to your token.
• Order creation prices from the catalogue. A price in your payload is ignored; orders are created unpaid at status new.
• Stock moves by delta, not by absolute value, so two apps adjusting at once do not overwrite each other.
• Paid orders depend on the merchant. On a site with €1+ monthly revenue the mandate is already active and the order is charged ("charged": true); below that you get a checkout_url for the merchant to confirm. Handle both.

This reference says what an endpoint does. The help centre says what the thing it changes means to the merchant looking at it — worth reading before you change it on their behalf.

Authorization: turning a merchant's consent into an access token, and refreshing or revoking it.

In the help centre: Developing apps.

Who am I, and what am I allowed to do? Any valid app token may call these.

In the help centre: Developing apps.

This app's own configuration on this site.

In the help centre: Developing apps.

Which events this app is subscribed to, and every topic that exists.

In the help centre: Developing apps.

Leads: the form submissions visitors send through the site's forms, with their notes. A new one fires the lead.created webhook.

In the help centre: Leads.

Webshop customers. Personal data, behind its own scope.

In the help centre: The webshop.

Comments and reviews visitors leave on the site, and their moderation.

The catalogue, its variants and its stock.

In the help centre: Products.