Reference
Designer API — build and edit pages with scripts
Endpoints for pages, components, menus and media, the designer's node structure, the rendered classes, code names (data-ref) and what to watch for when calling through Cloudflare
On this page
Every page built in the designer is stored as a tree of nodes (JSON) in the post's design field, so scripts and AI tools can create or edit pages through the same REST API the admin uses. This page collects what you need in one place (CMS 2.2.0).
Authentication#
Send Authorization: Bearer <token> with every request. Get a token from POST /api/v1/auth/login {email, password}, or a long-lived one from POST /api/v1/auth/tokens. Editing designs needs the edit_pages permission, plus edit_scripts when there are code blocks.
Through Cloudflare: if the site is behind Cloudflare, requests without a
User-Agent, or with the default of some libraries such as Python'surllib, get403 error code: 1010(Browser Integrity Check). Set your ownUser-Agent, e.g.my-script/1.0, or create a WAF rule that exempts/api/v1/*requests carrying anAuthorizationheader.
import json, urllib.request
req = urllib.request.Request("https://example.com/api/v1/posts/11",
headers={"Authorization": "Bearer " + TOKEN, "User-Agent": "qraft-sync/1.0"})
page = json.load(urllib.request.urlopen(req))
Endpoints#
| Method | Path | Used for |
|---|---|---|
| GET | /api/v1/posts?type=page | List pages (perPage, page, q, status = draft / publish / scheduled / any) |
| GET | /api/v1/posts/{id} | One page with design, updatedAt and draft (if there is one) |
| POST | /api/v1/posts | Create {type:"page", title, slug?, status?, design?} |
| PUT | /api/v1/posts/{id} | Update {title?, slug?, status?, design?, baseUpdatedAt?, asDraft?, discardDraft?} |
| GET / POST / PUT | /api/v1/components · /api/v1/components/{id} | Reusable components {name, node, baseUpdatedAt?} |
| GET / POST / PUT | /api/v1/menus · /api/v1/menus/{id} | Menus {name, items:[{label, url}]} |
| POST | /api/v1/media (multipart file) | Upload an image/file → {id, url, width, height} |
| GET | /api/v1/settings → theme | The site's colours and fonts (var(--c-<key>)) and breakpoints |
| POST | /api/v1/links/replace {from, to} | Replace a link everywhere (designs, components, menus) after moving a page |
- No overwrites: send
baseUpdatedAtwith theupdatedAtyou read. If someone saved in the meantime, the system answers409instead of overwriting their work - Layer ids must be unique: duplicate ids get a
400naming the id (since 2.1.1) - Post categories:
terms: {"category": ["news", 12]}accepts slugs and ids - status: omitted,
anyorall= every status; unknown values answer400(since 2.3.0; earlier an empty list) - Drafts of published pages (2.3.0):
asDraft: truekeepstitle/slug/designin the page'sdraftwhile visitors still see the published version. Send again withoutasDraft(or withstatus: "publish") to publish, ordiscardDraft: trueto throw the draft away — on unpublished pagesasDrafthas no effect (saved as usual) - Authentication: scripts use
Authorization: Bearer; the admin (2.3.0) uses anHttpOnlycookie together with theX-Anasaki-Session: cookieheader — the cookie alone does not count as signed in - Every save keeps the previous version — see
GET /api/v1/posts/{id}/revisions(the last 25)
Node structure#
interface Node {
id: string; // unique in the page → class n-<id>
type: 'frame' | 'text' | 'rect' | 'image' | 'button' | 'menu' | 'postList' | 'postContent' | 'instance'
| 'embed' | 'collection' | 'pluginBlock' | 'download' | 'breadcrumb' | 'icon' | 'shape' | 'vector'
| 'pagination' | 'input' | 'codeblock';
name?: string; // the name in the layers panel
visible?: boolean; locked?: boolean;
absolute?: boolean; x?: number; y?: number; // free position inside an auto layout box
width: Size; height: Size; // { mode: 'fixed', value: 320 } | { mode: 'fill' } | { mode: 'hug' }
layout?: { mode?: 'none' | 'horizontal' | 'vertical'; gap?: number; padding?: [top, right, bottom, left];
align?: 'start' | 'center' | 'end' | 'stretch'; justify?: 'start' | 'center' | 'end' | 'between';
wrap?: boolean; columns?: number };
style?: Style; // below
props?: Record<string, any>; // per type, below
responsive?: { tablet?: Override; mobile?: Override }; // values that differ on smaller screens (phones inherit tablet's)
children?: Node[];
}
// Override = { x?, y?, width?, height?, visible?, layout?: Partial<layout>, style?: Partial<style> }
Common style keys: fill color stroke + strokeWidth (+ strokeStyle) radius / radii shadow opacity fontFamily (several fonts separated by commas, e.g. "Kanit, system-ui") fontSize fontWeight lineHeight letterSpacing textAlign maxWidth minHeight minHeightScreen + minHeightOffset (screen height minus the menu bar) backgroundImage overlay objectFit hover: {fill, color, stroke, scale, lift, shadow, opacity, duration} active: {fill, color, stroke} (the selected tab / the current page's link in a menu) anim: {type: 'fade' | 'up' | …, delay, duration} textStyle (a text style id from the theme), and for menus linkPadding: [v, h] linkRadius
props per type
| Type | props |
|---|---|
text | text, rich (inline HTML), tag (h1…p), href, newTab |
button | text, href, newTab, icon (icon name), iconPosition: 'end', action |
image | src, alt, href, lightbox (2.4.0: opens full size in a gallery on click, grouped by the enclosing frame) |
menu | menuId, burger (collapses to ☰ on phones) |
postList | query: {postType, category, limit, order} + the first card as children |
input | kind (text search select checkbox …), name, placeholder, value (+ valueText: true = literal text), options, filter: {collection, param} |
codeblock | html, css (:scope = the block), js |
instance | componentId, variant, overrides |
icon | icon, strokeWidth, label |
Every type can have props.ref (a code name) and props.showWhen (a show condition).
Rendered classes#
- Each layer gets
class="n-<id>", stable as long as the id doesn't change; layers inside a placed component getn-<instance id>-<id inside the component> - Ids can change on duplicate, paste or detaching a component, and the designer gives duplicated layers new ids when a page opens — so code that needs a lasting name should use a code name instead
Code names (data-ref)#
Set it on any layer under Content → Code name (or props.ref in the API). It renders as data-ref="<name>", and code blocks can find the layer with:
const btn = anasaki.ref('download'); // the first one (or null)
anasaki.refs('card').forEach(c => …); // all of them, e.g. cards in a list
Names start with a-z, followed by a-z A-Z 0-9 _ -, up to 40 characters. The layers panel shows a </> badge on layers with a code name, so designers know code refers to them.
Files shared by code blocks#
Files in Site Code's public/ folder (e.g. public/qr.js, public/base.css, .svg, .txt, .json) are not bundled; the published version serves them at /site-assets/<file name>. Code blocks load shared files once per page:
await anasaki.lib('qr'); // runs /site-assets/qr.js once (every block awaits the same promise)
await anasaki.style('base'); // adds /site-assets/base.css
In Site Code, site.asset('public/qr.js') gives the url (with ?v=<version>, cached for a year) and text().
