Browse API docs
Free pages
A free page is a whole page in your own design: a Liquid template and a stylesheet that take the place of the shop’s header, hero and blocks. Tickets, checkout, consent and the legal pages stay with Usetix, and the shop’s footer always follows. With a free page for the home page and one for all event pages, the whole website is yours.
Usetix checks every free page in a real browser before visitors get it: accessibility, contrast, and whether it fits a desktop, a phone and a window 320 pixels wide. Until a page passed, visitors keep the page they had.
Reading requires a token with Read or Read + Write permission, everything else Read + Write. Personal co-organizer tokens work on the free pages of their assigned events only. See Authentication.
Which page
| Address | Free page of |
|---|---|
/admin/events/:slug/page/free_page |
One event. It goes before the design all events wear. |
/admin/website/free_pages/home |
The home page. |
/admin/website/free_pages/events |
Every event’s page that has no free page of its own. |
/admin/website/free_pages/:slug |
A page of the website, by its address. |
All four read and answer in the same shape. A version of the design that isn’t live keeps its own home page and events design at /admin/website/versions/:id/free_pages/home and …/events.
GET /admin/events/:slug/page/free_page
curl \
-H "Authorization: Bearer your-token-here" \
-H "Accept: application/json" \
https://app.usetix.io/admin/events/summer-night/page/free_page
Response
{
"kind": "event",
"title": "Summer Night",
"state": "live",
"shows": "free_page",
"held": false,
"template": "<main data-part=\"Hero\">…</main>",
"stylesheet": "h1 { color: var(--shop-text); }",
"follows_look": true,
"files": [
{ "name": "poster.jpg", "content_type": "image/jpeg", "byte_size": 184220 }
],
"parts": [
{
"key": "3f9a1c0b7d2e",
"name": "Hero",
"heading": "Summer Night",
"anchor": null,
"hidden": false,
"texts": [
{ "key": "a81c4e02f6b9", "kind": "heading", "original": "Summer Night", "text": "Summer Night" }
],
"media": [
{ "kind": "picture", "file": "poster.jpg", "still": null }
],
"items": [],
"url": "https://app.usetix.io/admin/events/summer-night/page/free_page/parts/3f9a1c0b7d2e.json"
}
],
"check": {
"passed": true,
"checked_at": "2026-11-17T12:00:00Z",
"problems": [],
"violations": [],
"unjudged": [],
"render_error": null,
"pictures": {
"desktop": "https://app.usetix.io/admin/events/summer-night/page/free_page/pictures/desktop",
"phone": "https://app.usetix.io/admin/events/summer-night/page/free_page/pictures/phone",
"narrow": null
}
},
"design_fee": { "amount": "3.00", "currency": "EUR" },
"design": null,
"url": "https://app.usetix.io/admin/events/summer-night/page/free_page.json",
"updated_at": "2026-11-17T12:00:04Z"
}
| Key | Meaning |
|---|---|
kind |
event, home, events or page. |
state |
none (no free page), checking, live (passed and shown), held (passed, waiting for you to take it live) or failed. |
shows |
What visitors get right now: usual_page, shared_design (the design all events wear), free_page or earlier_version (the version that was live before). |
held |
Whether the newest version waits to be taken live. |
follows_look |
Whether the design changes with the shop’s theme settings: it writes the look’s variables such as var(--shop-accent), or was built in the shop’s accent color. |
files |
The page’s own pictures, videos and fonts, which the template names by file name. |
parts |
The design’s blocks, as the editor lists them beside the page. See Blocks. |
check |
Usetix’s last check, null before the first. problems has one sentence per defect, unjudged the texts whose contrast got no verdict because they lie over a picture or a gradient. The pictures the check took are private and need the token. |
design_fee |
What the next page by Usetix’s AI costs before VAT: 0.00 while your shop’s first page is free. null for a version of the design that isn’t live. |
design |
What Usetix’s AI last did for this page, null where it was never asked. See Have Usetix’s AI design it. |
Set and change
On an event, POST sets a free page and answers 201 with its Location; PATCH changes it, and sets one where there is none. On the website’s addresses, PATCH does both.
curl -X PATCH \
-H "Authorization: Bearer your-token-here" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"template": "<main data-part=\"Hero\"><h1></h1></main>", "stylesheet": "h1 { color: var(--shop-text); }"}' \
https://app.usetix.io/admin/website/free_pages/home
| Parameter | Meaning |
|---|---|
template |
The page’s Liquid template: its whole HTML, without scripts. Left out, it stays as it is. |
stylesheet |
The page’s CSS. Left out, it stays as it is. |
files |
Pictures, videos and fonts, as a multipart upload or as the signed ids of direct uploads. A file takes the place of one with its name. |
remove_files |
File names to take away. |
hold |
true makes the page wait once it passed, until you take it live. false shows it as soon as it passed. Left out, a page that already waits keeps waiting. |
A multipart request nests the parameters under free_page. The answer is the free page with state checking; Usetix checks it in the background, usually within a minute. Read it again for the result, or ask for another check with POST …/free_page/check (202).
A change to a page that passed is its next version: visitors keep the one that passed until the new one passed too. What can’t be kept (a template that doesn’t parse, a file of a kind a page can’t hold) comes back with 422:
{ "errors": { "template": ["Liquid syntax error: …"] } }
DELETE …/free_page removes the free page with its files and gives the page its usual self back (204).
Look first, then take it live
A page set with hold: true passes its check and waits: its state is held, and visitors keep the page they had. In the dashboard, the free page shows it in your real shop, with a button to take it live.
curl -X POST \
-H "Authorization: Bearer your-token-here" \
-H "Accept: application/json" \
https://app.usetix.io/admin/website/free_pages/home/publication
POST …/free_page/publication takes the page live and answers with the free page; where nothing waits that passed, it answers 422. DELETE …/free_page/publication drops the page that waits and goes back to the one before (204).
Have Usetix’s AI design it
Without code or an AI of your own, Usetix’s AI writes the whole page from a few words, with your events, flyers and pictures, repairs what the check finds and holds the page back for you to look at.
curl -X POST \
-H "Authorization: Bearer your-token-here" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"prompt": "Dark and classy, the next dates on top, the flyer large"}' \
https://app.usetix.io/admin/website/free_pages/home/design
| Parameter | Meaning |
|---|---|
prompt |
What the page should be, or what should change on it. |
change |
true starts from the page as it is and changes only what the prompt asks for. |
The answer is 202 with the free page’s Location. The AI works for a few minutes; the free page’s design says how far it is:
"design": {
"state": "working",
"error": null,
"requested_at": "2026-11-19T10:12:00Z",
"fee": { "amount": "3.00", "currency": "EUR" }
}
state is pending, working, done or failed; error says why a design failed. A finished page has the state held: look at it, then take it live with POST …/publication.
What it costs. Your shop’s first page is free. Each further page costs the fee plus VAT from your Usetix Credit, taken once the page passed Usetix’s check. A page that doesn’t pass costs nothing. Before you ask, the free page’s design_fee names what the next page costs. The request answers 422 with the reason where the credit doesn’t cover the fee, where the AI is already designing another page of the shop, where Usetix’s AI isn’t available for your account right now, or where there is nothing to change. Personal co-organizer tokens can’t ask, since the design is paid from the shop’s credit.
An AI of your own designs without a fee: connect it over MCP, where get_free_page brings the guide to writing a free page, set_free_page sets one and publish_free_page takes it live.
Blocks
A free page’s parts are blocks you move, leave out and reword without touching its code. Each change is the page’s next version and is checked like an upload.
PATCH …/free_page/parts/:key changes one block:
curl -X PATCH \
-H "Authorization: Bearer your-token-here" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"hidden": false, "texts": {"a81c4e02f6b9": "Termine"}}' \
https://app.usetix.io/admin/website/free_pages/home/parts/3f9a1c0b7d2e
| Parameter | Meaning |
|---|---|
hidden |
true leaves the block off the page, false brings it back. |
texts |
New wording by text key. A blank value reads as the design wrote it again. |
files |
A new picture or video in place of one, by the name of the file it replaces (multipart, nested under part). |
PUT …/free_page/parts/:key/position with position (counted from 1) moves the block among the blocks beside it and answers with the blocks in their order.