Skip to main content

Sites

List the sites in your organization, read their details, and create new ones. Renaming and deleting a site stay console actions. You can publish a site, which is what makes writes you made elsewhere in the API appear on the live pages — and, given a list of pages, makes those pages' drafts live.

Several things under a site are resources of their own, with their own scopes: pages — with what is on each and its search listing — the site's page templates, the site's search listing, its business details, its products and orders, its form submissions, and its media.

The site object​

{
"id": "host_demo",
"object": "site",
"displayName": "Demo Bakery",
"subdomain": "demo",
"domain": null
}
FieldTypeNotes
idstringSite id — use it in the paths below.
objectstringAlways "site".
displayNamestring | nullName shown in the console.
subdomainstring | nullThe {subdomain}.aglyn.app address.
domainstring | nullThe custom domain, once verified — null if the site only uses its subdomain.

The form submission object​

{
"id": "sub_1",
"object": "form_submission",
"form": "contact",
"path": "/contact",
"fields": { "email": "hi@example.com", "message": "Hello!" },
"read": false,
"created": "2026-07-20T18:23:23.950Z"
}
FieldTypeNotes
formstring | nullThe form's name — what you filter on.
pathstring | nullThe page path it was submitted from.
fieldsobjectSubmitted values, keyed by field name. Shape follows the form's design, so it varies per form.
readbooleanWhether it's been marked read in the console inbox. Reading over the API doesn't change it.
createdstring | nullISO 8601.

Endpoints​

List sites​

GET /v1/sites — scope sites:read. Paginated, ordered by site id.

curl "https://app.aglyn.com/api/v1/sites" \
-H "Authorization: Bearer aglyn_sk_…"

Create a site​

POST /v1/sites — scope sites:write. Accepts an Idempotency-Key.

curl -X POST "https://app.aglyn.com/api/v1/sites" \
-H "Authorization: Bearer aglyn_sk_…" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{ "displayName": "Demo Bakery", "subdomain": "demo-bakery" }'
FieldRequiredNotes
displayNameyesName shown in the console. Trimmed, truncated at 80 characters.
subdomainyes3–30 characters: lowercase letters, numbers and hyphens, starting with a letter or number. Becomes {subdomain}.aglyn.app.

Returns 201 with the site object. A replayed request returns the same site with 200 — so if you retry after a dropped connection, compare the status to tell a fresh create from a replay.

Send an Idempotency-Key. Subdomains are globally unique, so a retry that reuses the same one happens to 409 — but that is an accident of the namespace, not a guarantee. If your client generates a subdomain per attempt, a retry without a key creates a second site, which consumes a slot of your site allowance.

Refusals:

StatuscodeMeans
400validation_failedMissing displayName, or a subdomain that is malformed or reserved. Never consumes the idempotency key — fix the body and retry with the same one.
403site_quotaYour plan's site limit is reached. Upgrade or add extra sites, then retry with the same key.
409subdomain_takenSomething already uses that subdomain. The message lists free alternatives. Also the answer when another request claims the same subdomain at the same moment: uniqueness is settled inside the transaction that creates the site, so exactly one of two simultaneous creates wins and the loser writes nothing at all — no site, no slot spent.
429—More than 10 creates in an hour for this organization. Honor Retry-After.

Each of those releases the key, so the retry that should finally succeed is not answered with a replay of the refusal.

Renaming and deleting a site are deliberately not available over the API. A delete would erase every page, version, product and uploaded file immediately, with no hold and no undo, from one field in a request body — that is not something to expose to an automated caller before a soft-delete exists.

Retrieve a site​

GET /v1/sites/{siteId} — scope sites:read.

A site your organization doesn't own returns 404 not_found ("No such site") rather than 403 — the API doesn't reveal whether an id exists elsewhere. So a 404 here means "not yours or not real", not "your key is missing a scope". A connected app gets the same 404 for a site its person is not a member of.

Publish​

POST /v1/sites/{siteId}/publish — scope sites:publish. The body is optional: with pages it also makes those pages' drafts live.

Refreshes the site's live pages so data you wrote over the API appears now instead of when the cache happens to expire.

You need this more often than it first looks. Writing a dataset record changes what a page would render, but a live page is cached: pages are rebuilt at most once an hour, the dataset reads behind them are cached for an hour as well, and the page cache is stale-while-revalidate — the first visitor after the window still gets the old copy while the new one is built behind them. So without a publish, "my record is in the API but not on the site" is the expected behavior for an hour or more, and you cannot tell it apart from a write that failed.

curl -X POST "https://app.aglyn.com/api/v1/sites/host_demo/publish" \
-H "Authorization: Bearer aglyn_sk_…"
{
"object": "publish",
"site": "host_demo",
"published": true,
"reason": null,
"pages": 12,
"pagesDropped": 0
}
FieldNotes
publishedtrue when the site's pages were refreshed. Check it — see below.
reasonnull on success. Otherwise why not: "not_routed" (the site has no live pages yet), "not-configured", "tenant-{status}", "error".
pagesHow many cached pages were dropped.
pagesDroppedPages not refreshed because the site exceeded the 250-page limit for one call. They catch up on their own when their cached copy expires, within the hour.
promotedOnly when the request named pages: what happened to each.

A 200 does not always mean published. published: false with a reason is the honest answer for a site with nothing routed yet, or a refresh we could not complete — reported rather than hidden, because otherwise you would poll a page that is never going to change. Treat published as the field that matters, not the status code.

Publishing is idempotent and takes no Idempotency-Key: publishing twice lands the same state and returns the same answer.

Publish pages​

Send a body with pages, a list of 1 to 25 page ids, to make those pages' drafts live as well — what the editor's Publish does for one page. This is how edits to a page's content and a new page reach visitors.

curl -X POST "https://app.aglyn.com/api/v1/sites/host_demo/publish" \
-H "Authorization: Bearer aglyn_sk_…" \
-H "Content-Type: application/json" \
-d '{ "pages": ["scr_about", "scr_catering"] }'

For each page, in order:

The pageWhat publishing it doesstatus
Published, with a draftThe draft is saved into the page's live version, replacing what the page showed, and the draft is cleared. The version it replaces is not kept.published
Published, with no draftNothing; it is left as it is.unchanged
Not yet publishedIts draft, if it has one, is saved into its version, and the page is published at its own address (its slug under its parent's address), with any published pages below it.published
The site's placeholder home pageIts draft is saved, and its address is republished as the site's own home page.published

Every page is checked before any is written. If one is refused, nothing is published and the publish budget is not spent. After the pages, the site's live pages are refreshed exactly as a publish without a body does.

{
"object": "publish",
"site": "host_demo",
"published": true,
"reason": null,
"pages": 14,
"pagesDropped": 0,
"promoted": [
{ "page": "scr_about", "status": "published", "path": "/about" },
{ "page": "scr_catering", "status": "published", "path": "/catering" }
]
}

promoted is present only when you sent pages: one line per page, with its address as a visitor types it. A retry is safe: a page whose draft already went live has no draft left and answers unchanged.

Only a site's ordinary pages are published this way. Layouts, reusable components, email designs and templates are never published by it, and neither is any page you did not name. A body with no pages member, or no body at all, only refreshes the live pages, as before.

With pages, a connected app needs its person's Publish site content permission on the site, not only Edit site content.

When a page is refused​

A refusal answers with the first refused page's status and reason in the usual error envelope, and every page's line beside it in results:

{
"error": {
"type": "conflict",
"message": "This page’s draft was started before its last save, so it is out of date. Open it in the editor to bring it up to date, then publish.",
"code": "stale_draft"
},
"results": [
{ "page": "scr_about", "status": "refused", "code": "stale_draft", "message": "This page’s draft was started before its last save, so it is out of date. Open it in the editor to bring it up to date, then publish." },
{ "page": "scr_catering", "status": "not_attempted" }
]
}

A body that is not valid — not a JSON object, pages not 1 to 25 distinct page ids, or another member beside it — is an ordinary 400 with code: "validation_failed" and fields, and no results. Each page's own refusals:

StatuscodeMeans
400not_a_pageThe id is an email design, an error page, a collection template or a folder.
400no_slugA page not yet published has no address (slug). Give it one first.
400slug_path_separatorThe page's address holds a /.
400reserved_addressThe page, or a published page below it, would take a reserved address.
404page_not_foundNo such page on this site, or it is deleted.
409stale_draftThe page's draft was started before its last save, so it is out of date. Open it in the editor to bring it up to date, then publish.
409scheduled_publish_pendingA scheduled publish is waiting on the page. Cancel it or run it in the console first.
409forms_off_for_siteThe page carries a form, and Forms is switched off for the site.
409no_versionThe page has no saved version to publish.
409unpublished_ancestorThe page sits under a page that is not published yet. Publish the parent first.
409address_takenAnother published page holds the address, or another page in the same request would take it.
409address_changedThe page is live at one address, and publishing it would move it to another. Publish it from the editor.
409publish_from_editorThe page's saved version has layout style overrides (its own restyles of the layout it sits in), and its draft does not carry them: a draft whose author cleared them in the editor, or a draft an API edit or an AI edit saved before those edits kept them. Publishing could keep them or clear them, and the draft cannot say which, so publish this page from the editor. A draft made by an API edit now carries the overrides, and publishes with them.
409page_changedThe page changed while it was being published. Nothing was published; try again.
413page_too_largeThe page is over 900,000 bytes.

A refusal found while writing — another writer changed a page between the check and the write — stops there: the response carries promoted with what already went live, and results with every page's line, so nothing is claimed that did not happen. If a new page's draft was saved but its address was then refused (code: "route_refused"), its line says "draftSaved": true: the page still has no address, so no visitor sees it.

When a publish fails partway​

An unexpected error — not a refusal — can stop a publish after some pages went live. The answer is then 500 with type: "internal_error", and still says exactly what happened:

{
"error": {
"type": "internal_error",
"message": "Something went wrong while publishing the pages. The pages in `promoted` went live; see `results` for the rest.",
"code": "internal_error"
},
"promoted": [
{ "page": "scr_about", "status": "published", "path": "/about" }
],
"results": [
{ "page": "scr_about", "status": "published", "path": "/about" },
{
"page": "scr_catering",
"status": "failed",
"message": "An unexpected error stopped this page’s publish after its draft was saved into the page; the page has no address yet, so no visitor sees it. Publish it again.",
"draftSaved": true
},
{ "page": "scr_menu", "status": "not_attempted" }
]
}

promoted lists the pages that were done before it stopped (published or unchanged). results has one line per page you named, in order: those done, then the page that failed (status: "failed"), then not_attempted for every page after it. The failed page's line says only what is known to have been written for it:

The failed lineMeans
No draftSavedNothing was written for the page, or what was written is not known. Its message says which; read the page before publishing it again if it says so.
"draftSaved": true, no pathIts draft was saved into the page, which has no address yet, so no visitor sees it.
"draftSaved": true and a pathIts draft is live at that address; only republishing the address as the site's home page did not finish.

Publishing the same pages again is safe: a page whose draft already went live answers unchanged.

If every named page went live and the refresh of the site's live pages afterwards fails, the answer is also 500 with type: "internal_error", now with code: "refresh_failed", and promoted and results both list every page's outcome. Those pages are published; publish again without pages to refresh the live copies.

It is rate limited per site, not per key​

10 publishes per site per hour, counted separately from the 120 requests a minute your key gets. One publish can drop up to 250 pages and each one costs real work to rebuild, so this limit is sized to the work rather than to the request — and minting more keys does not raise it, because the budget belongs to the site.

Over budget returns 429 rate_limited with a Retry-After. Nothing is lost when it does: the hour-long cache is still underneath, so the change appears on its own — an hour or more later rather than now.

Publish once at the end of a batch, not after every record. A sync that writes 500 records and publishes once is both faster and within budget; one that publishes per record is refused after ten and gains nothing over waiting.

A connected app publishes only where its person has Edit site content on the site — and Publish site content when the request names pages — see Conventions → Sites a connected app can reach.

Writes that are live without a publish​

Some writes refresh the live site themselves, because the console has no draft for them either: products, a site's search listing, a page's search listing, business details, and a published page's name, description, address or place and its deletion. Each is saved at once and the live site refreshes right away — no publish needed, and none of them spends the publish budget.

Edits to a page's content are not among them: they are saved as the page's draft, and visitors see them only once the page is published.

Because there is nothing to review afterwards, an app acting for a person should show the change and get their approval before it sends the write.

Form submissions​

Moved to their own page: Form submissions. They live under a site (/v1/sites/{siteId}/form-submissions) but carry their own scopes — forms:read to read, forms:write to mark read or delete — and, unlike a site, they can be written.

Errors​

StatustypeWhen
403insufficient_scopeKey lacks sites:read, or sites:publish on the publish path.
400bad_requestcode: "validation_failed" — a publish body that is not valid; see When a page is refused.
403forbiddencode: "site_permission_required" — a connected app publishing a site its person can't edit, or naming pages without the permission to publish.
404not_foundUnknown or unowned site; unknown sub-path.
405method_not_allowedAnything other than GET, or anything other than POST on /publish.
423—The site is locked: every call on it while the lock lasts, or only writes under a read-only lock.
400, 404, 409, 413—A page named in pages was refused. See When a page is refused.
429rate_limitedThe site's publish budget is spent. Carries Retry-After.
500internal_errorA publish of pages stopped partway (code: "internal_error"), or the refresh after them failed (code: "refresh_failed"). Both still say what went live; see When a publish fails partway.