{ "openapi": "3.0.0", "info": { "title": "SitePack App API", "description": "The REST API installed apps use to read and change a SitePack site: content,\ncommerce, domains and mailboxes.\n\n**Machine-readable:** the full [OpenAPI document](https://sitepack.dev/openapi.json), one [Markdown file per section](https://sitepack.dev/llms.txt) (for example [Leads](https://sitepack.dev/api-reference/leads.md)) and an index in [llms.txt](https://sitepack.dev/llms.txt).\n\n## Authorization\n\nThe app API uses the same OAuth flow as the SitePack CLI.\n\n```http\nGET /api/authentication/oauth/authorize\n ?client_id=your-client-id\n &scope=content:write%20media:read\n &redirect_uri=https://your-app.example/callback\n &state=csrf-token\n```\n\nThe merchant picks a site and approves the scopes you asked for, then you are sent\nback with a `code`. Exchange it:\n\n```http\nPOST /api/authentication/oauth/token\nContent-Type: application/x-www-form-urlencoded\n\ngrant_type=authorization_code&code=…&client_id=…&client_secret=…\n```\n\nSend the result on every request. `X-SitePack-Access-Token` is the preferred header;\na standard `Authorization: Bearer ` is also accepted:\n\n```http\nX-SitePack-Access-Token: \n```\n\nAccess tokens last an hour; refresh them with `grant_type=refresh_token`.\n\n**A token is bound to one site.** The site is never a parameter — an app that\nserves ten merchants holds ten tokens. That is also why a uuid from one site is\nsimply *not found* on another.\n\n## What your token can do\n\nThree things must hold, and they are checked on **every** request:\n\n1. your installation on that site is active;\n2. the app's subscription on that site is active — if the merchant cancels a paid\n app, API access stops immediately;\n3. the scope is one the merchant actually granted.\n\nPoint three is an intersection, re-evaluated per request: if a merchant removes a\nscope, it stops working at once rather than when your hour-long token expires.\n`GET /me` shows the scopes in force right now.\n\n**An app with no scopes can reach `/me` and `/scopes`, and nothing else.**\n\n## Scopes\n\nScopes read `section:action`. **`write` implies `read`**; nothing else is implied,\nand there is no wildcard scope.\n\nTwo scopes spend the merchant's money and therefore stand alone — `domains:order`\nand `mail:order`. Holding `domains:write` does *not* let you order a domain.\n\nAsk for the narrowest set that does the job: merchants see every scope you request\non the consent screen.\n\n## Identifiers\n\nEverything is addressed by **uuid**. No endpoint takes an auto-increment id and no\nresponse returns one. New records get a uuid v7, which is time-ordered, so sorting\nby uuid sorts by creation.\n\n## Responses\n\nEvery response carries a `status`. Lists are paginated with `page` and `limit`\n(max 100):\n\n```json\n{\n \"status\": \"success\",\n \"items\": [],\n \"pagination\": { \"page\": 1, \"limit\": 25, \"totalRecords\": 42, \"totalPages\": 2 }\n}\n```\n\nErrors name a machine-readable code — switch on `error.code`, never on the message:\n\n```json\n{\n \"status\": \"error\",\n \"error\": { \"code\": \"scope_required\", \"message\": \"…\", \"scope\": \"content:write\" }\n}\n```\n\n| Status | Meaning |\n| --- | --- |\n| `400` | Malformed request |\n| `401` | No token, or it is invalid or expired |\n| `403` | Missing scope, or the installation is no longer active |\n| `404` | Not found — or on another site, which reads the same on purpose |\n| `409` | Conflict: slug taken, no free mailbox slot, unpaid invoices |\n| `422` | Validation failed; `error.field` names the field |\n| `429` | Rate limited; `Retry-After` says for how long |\n| `500` | Failed on our side. `internal_error`, with a deliberately generic message — the detail is in our logs, not in your response |\n\n## Rate limits\n\nEvery response carries your budget, so you never have to discover a limit by being\ncut off:\n\n```http\nX-SitePack-RateLimit: 600\nX-SitePack-RateLimit-Tokens: 574\nX-SitePack-RateLimit-Reset: 1750000060\n```\n\n| Bucket | Limit | Keyed on |\n| --- | --- | --- |\n| Everything | 600 / minute | your installation — app *and* site |\n| Endpoints behind an `:order` scope | 20 / hour | your installation |\n| Refused access tokens | 60 / minute | calling IP address |\n| `/docs` and `/docs.json` | 60 / minute | calling IP address |\n| The OAuth endpoints | 120 / minute | calling IP address |\n\nKeying the main budget on the installation rather than on your address means serving\nmany merchants from one server does not throttle you — but it also means one app of\nyours cannot spend another's budget.\n\nA `429` names `Retry-After` in seconds. Wait that long; retrying sooner only spends\nwhat is left of the window.\n\nThe order bucket is separate because those endpoints charge the merchant: a loop that\nlists domains is a mistake, a loop that *buys* them is an invoice.\n\n## Webhooks\n\nSubscriptions are declared in your `app.json` manifest. Payloads are deliberately\nthin: `arguments` carries **only the uuid** of the resource that changed. Call the\nAPI with that uuid to read the details.\n\nThat means a payload can never contain something you are not scoped to read, and\ncan never be stale — by the time a retry lands, embedded values might describe a\nversion that no longer exists, while a uuid always resolves to the current one.\n\nTreat an event as \"go look at this\", not as data.\n\n## Things worth knowing before you start\n\n- **Pages are styled through element settings, not inline HTML.** Inline `style=`\n attributes are stripped from anything you submit; alignment and colour are lifted\n into the element's `settings` so the intent survives.\n- **Elements cannot carry script.** `