Developers

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

11 min readLast updated

View as Markdown

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's urllib, get 403 error code: 1010 (Browser Integrity Check). Set your own User-Agent, e.g. my-script/1.0, or create a WAF rule that exempts /api/v1/* requests carrying an Authorization header.

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#

MethodPathUsed for
GET/api/v1/posts?type=pageList 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/postsCreate {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 → themeThe 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 baseUpdatedAt with the updatedAt you read. If someone saved in the meantime, the system answers 409 instead of overwriting their work
  • Layer ids must be unique: duplicate ids get a 400 naming the id (since 2.1.1)
  • Post categories: terms: {"category": ["news", 12]} accepts slugs and ids
  • status: omitted, any or all = every status; unknown values answer 400 (since 2.3.0; earlier an empty list)
  • Drafts of published pages (2.3.0): asDraft: true keeps title / slug / design in the page's draft while visitors still see the published version. Send again without asDraft (or with status: "publish") to publish, or discardDraft: true to throw the draft away — on unpublished pages asDraft has no effect (saved as usual)
  • Authentication: scripts use Authorization: Bearer; the admin (2.3.0) uses an HttpOnly cookie together with the X-Anasaki-Session: cookie header — 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

Typeprops
texttext, rich (inline HTML), tag (h1…p), href, newTab
buttontext, href, newTab, icon (icon name), iconPosition: 'end', action
imagesrc, alt, href, lightbox (2.4.0: opens full size in a gallery on click, grouped by the enclosing frame)
menumenuId, burger (collapses to ☰ on phones)
postListquery: {postType, category, limit, order} + the first card as children
inputkind (text search select checkbox …), name, placeholder, value (+ valueText: true = literal text), options, filter: {collection, param}
codeblockhtml, css (:scope = the block), js
instancecomponentId, variant, overrides
iconicon, 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 get n-<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().