# 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

Source: https://anasaki.live/docs/en/developers/designer-api

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 ` 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.

```python
import json, urllib.request
req = urllib.request.Request(&#34;https://example.com/api/v1/posts/11&#34;,
    headers={&#34;Authorization&#34;: &#34;Bearer &#34; + TOKEN, &#34;User-Agent&#34;: &#34;qraft-sync/1.0&#34;})
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:&#34;page&#34;, 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-)`) 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: {&#34;category&#34;: [&#34;news&#34;, 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: &#34;publish&#34;`) 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

```ts
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. `&#34;Kanit, system-ui&#34;`) `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=&#34;n-&#34;`, stable as long as the id doesn't change; layers inside a placed component get `n--`
- 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=&#34;&#34;`, and code blocks can find the layer with:

```js
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/`. Code blocks load shared files once per page:

```js
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=`, cached for a year) and `text()`.
