# Plugin API (reference summary)

> A summary of every public API a plugin can use — the versions that added them, minCore and feature detection, site.*, db.*, http/mail/jobs/plugins, public page hooks, admin pages and the admin UI kit

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

The core never contains special code for any plugin — the official plugins (seo, forms …) use only the APIs on this page, so whatever they can do, your plugin can too. The full documents are in the repository: `docs/plugin-api.md` (API), `docs/site-code.md` (JS API details), and the most accurate types are `anasaki.d.ts` (`GET /api/v1/code/types`).

## API versions

| CMS version | Added |
| --- | --- |
| **2.0.0** | The first plugin platform (package, service, WASM and JavaScript) — everything on this page without a version |
| **2.0.3** | `AK.line`, `AK.open`, `AK.height`, `data-ak-line`, `data-ak-open`; admin pages and widgets size to their content |
| **2.0.4** | `AK.pickMedia` (pick an image from the media library); paths declared by plugins are reserved (`GET /api/v1/settings/reserved-paths`); recommended plugins in the setup wizard come from the Store |
| **2.0.5** | JavaScript plugins can declare their own content types (`site.postType`) — scope `post-types`, id `_` (≤ 20 characters), `public: false` turns off system routing, spec fields stored under plain names (see [JavaScript plugins](/docs/en/developers/js-plugins)) |
| **2.0.6** | Plugin capabilities: `capabilities` in the manifest (administrators tick them per role under Users → Permissions), `'cap:'` in `access` lists, `site.can(user, cap)` / `user.can(cap)` and `caps: { edit, publish }` on content types — see [Plugin capabilities](/docs/en/developers/plugin-capabilities) |
| **2.1.0** | `site.taxonomy` and `db.terms.*` (scopes `taxonomies` / `terms-write`), `media.*` / `files.*` / `request.files()` (scopes `media` / `media-write` / `files`), `secret` settings, new field types (relation, user, term, file, gallery, repeater, richtext, color), events carry `actor` and `previous`, scheduled posts (`scheduled`) |
| **2.1.1** | `site.cron(expr, fn, { name })`; `toLocaleString('th-TH')` / `toLocaleDateString` work (Buddhist-era years); REST `terms` accepts slugs |
| **2.2.0** | `site.asset('public/…')` in Site Code and `public/` files at `/site-assets/`; `atob` / `btoa`; in the browser `anasaki.ref()` / `anasaki.refs()` (code names) and `anasaki.lib()` / `anasaki.style()` — see [Designer API](/docs/en/developers/designer-api) |
| **2.2.2** | `db.users.list / get` (scope `users`) — public user profiles without email; content types administrators create under Settings → Content types are readable with `db.posts` like code-declared ones (`post-types` of `GET /api/v1/post-types` has `admin: true`); `ctx.preview` in `site.block`'s `render` (`true` = shown in the designer, `false` = the live site) to hide hints such as &#34;Choose a form&#34; from visitors; `code.routes` may contain dots, e.g. `/feed.xml` (no `..` and no leading dot); files exported from Site Code get `category: &#34;utilities&#34;` |
| **2.3.0** | `ctx.isAdminUser` (middleware) / `isAdminUser` (afterResponse) include administrators viewing the site in the same browser as the admin (`ctx.user` is still `null`); the home page's URL from `db.posts` is `/`; REST `GET /posts?status=any` and drafts of published pages (`asDraft`); the designer's data source list hides plugin tables (`p_*`); post lists of custom content types filter by their own categories (slug, id or name) |
| **2.4.0** | The admin activity log (`GET /api/v1/audit`, permission `manage_users`) — actions users press on plugin admin pages are recorded too; Store packages carry an Ed25519 signature (`X-Anasaki-Signature`, the Store's `GET /api/v1/signing-key`) checked by the CMS before install; designer images have `props.lightbox`; the Docs plugin 1.2.0 has multilingual articles (`/docs//…`) |

The site's version is in `GET /api/public/site` (`version`) and on Site settings → General.

### minCore and feature detection

```jsonc
{ &#34;id&#34;: &#34;my-plugin&#34;, &#34;version&#34;: &#34;1.0.0&#34;, &#34;minCore&#34;: &#34;2.0.4&#34; }
```

Set `minCore` to the API version you **cannot do without** (older systems refuse the install), and check optional features before using them so older sites can still install:

```ts
if (typeof site.dashboardWidget === 'function') site.dashboardWidget('visits', { /* … */ });
if (plugins.has('thai')) site.formatter('price', (v) => plugins.call('thai', 'bahtText', v));
```

```js
// on an admin page (browser)
if (window.AK && AK.pickMedia) pickButton.hidden = false; else urlInput.hidden = false;
```

## site.*

| API | scope |
| --- | --- |
| `site.route(spec, opts?, handler)` — `&#34;GET /x/{id}&#34;`, `access`, `rawBody`, `maxBody` | `routes` |
| `site.page(path, {access, load})` — data for designed pages | `routes` |
| `site.collection(name, spec)` · `site.action(name, spec)` · `site.formatter(name, fn)` | — |
| `site.on(event, fn)` · `site.emit(name, data)` · `site.export(name, fn)` | — |
| `site.filter(name, fn, {priority})` · `site.applyFilter(name, value, ctx)` | `filters-core` for system hook points |
| `site.visitor(fn)` · `site.visitorGroups(groups)` | `visitor` |
| `site.fields(type, fields)` · `site.meta(postId)` · `site.setMeta(postId, values)` | `content-fields` |
| `site.postType(id, spec)` — plugins: since 2.0.5, id `_`, `public: false` = the plugin serves the pages | `post-types` |
| `site.job(name, opts?, fn)` · `site.cron(expr, target, { name }?)` | `jobs` |
| `site.can(user, capability)` — since 2.0.6 ([Plugin capabilities](/docs/en/developers/plugin-capabilities)) | — |
| `site.adminPage(id, spec)` · `site.dashboardWidget(id, spec)` · `site.adminNotice(fn, {access})` | `admin-pages` |
| `site.block(type, spec)` — server-rendered blocks (`render(ctx, props)`: `ctx.site`, `ctx.post`, `ctx.item`, `ctx.path`, `ctx.query`, `ctx.user`, `ctx.preview` since 2.2.2) | — |
| `site.middleware(fn, {priority})` · `site.afterResponse(fn)` | `middleware` |
| `site.head(fn)` · `site.bodyEnd(fn)` | — (`head-scripts` = unfiltered HTML) |
| `site.settings(key?)` · `site.saveSettings(values)` · `site.info()` · `site.asset(path)` | — |

Results of route/page/action: a value (JSON), `{status, headers?, body?}`, bytes (`Uint8Array` ≤ 20 MB), `{page: {title, html}}` (shown inside the site's header/footer) — context: `request {method, path, params, query, headers, cookies, body, json(), ip, host}`, `response.setCookie(...)`, `user`, `visitor`

## db.*

| API | scope |
| --- | --- |
| `db.table(name)` / `db.from(name)` — query builder, aggregates (`selectCount`, `selectSum` …) | `db` |
| `db.transaction(fn)` · `db.raw(sql, params)` (no SELECT/FROM/JOIN) · `db.docs(name)` | `db` |
| Migrations `migrations/NNN_name.ts` with `migration({up, down})` | `db` |
| `db.posts.list / get` · `core_*` views | `content` |
| `db.users.list({ role?, search?, page?, perPage? })` · `db.users.get(id)` — name, picture, bio, website, role, post count (no email, suspended users excluded, 2.2.2) | `users` |
| `db.posts.create / update / delete` · `db.asSystem(fn)` | `content-write` |

Plugins don't get `db.query` or `schema.raw` — a plugin's tables are `p__*` only.

## http, mail, jobs, plugins and more

| API | scope |
| --- | --- |
| `http.fetch(url, {method, headers, body, timeout})` | `http` (+ `code.hosts`) |
| `http.webhook(url, event, data, {secret?})` | `webhooks` |
| `mail.send({to, subject, html?, text?, replyTo?})` | `mail` |
| `jobs.enqueue(name, data, {delay, key})` | `jobs` |
| `plugins.call(id, fn, ...args)` · `plugins.has(id)` · `plugins.version(id)` · error `PluginUnavailable` | — |
| `import { x } from ''` — the library/exports of plugins in `requires` | — |
| `cache.*` · `crypto.*` · `log.*` / `console.*` | — |

## System events and filters

- **Events**: `post.published`, `post.saved`, `post.deleted`, `user.created`, `media.uploaded` — other events belong to the plugin that sends them (`.…` or names in `code.eventAliases` such as `form.submitted`)
- **Filters** (scope `filters-core`): `post.content`, `post.beforeSave`, `page.head`, `page.meta`, `collection.items`, `action.input`, `action.result`, `mail.beforeSend`, `sitemap.urls`, `robots.txt` — when any unit filters `sitemap.urls` or `robots.txt`, the system serves `/sitemap.xml` and `/robots.txt`

## Public page hooks

| Hook | Runs | Time |
| --- | --- | --- |
| `site.middleware` | Before routing every request — return nothing = continue, a result = answer now, `{headers}` = add headers and continue | 20 ms |
| `site.afterResponse` | After answering (queued, no slowdown) — request data, status, IP etc. | 2 seconds (before 2.2.0: 500 ms) |
| `site.head` / `site.bodyEnd` | HTML in `` / before `` (HTML is filtered without `head-scripts`) | 50 ms |
| filter `page.meta` | `{title, fullTitle, description, image, canonical, robots, noindex, og}` | 50 ms |

The middleware's `ctx.isAdminUser` and afterResponse's `isAdminUser` are `true` when a signed-in CMS user opened the page. Since 2.3.0 this includes administrators viewing the site (GET) in the same browser as the admin, but `ctx.user` is still `null` then. Use it for display decisions (e.g. skipping the maintenance page, not counting statistics), never to grant actions.

## Admin pages, widgets and notices

- **Admin pages** (`site.adminPage`) live at `/admin/x/code/:` and run in a sandboxed iframe — use `anasaki.call(':', input)` to call actions as the user, `anasaki.download(query)` for downloads, and draw your own ``
- **Dashboard widgets** (`site.dashboardWidget`, ≤ 10 per plugin) show on the admin home page
- **Notice banners** (`site.adminNotice`, ≤ 5 per plugin) with level `info | warning | danger | success` and a link
- Administrators can override which roles open the pages under **Site Code → Access**

## Admin UI kit (`window.AK`)

Every admin page and widget loads `/ext-ui/kit.css` + `/ext-ui/kit.js` automatically — `ak-*` classes (cards, buttons, badges, tables, forms, tabs, toasts, dialogs, charts) with light/dark themes.

| Function | Version |
| --- | --- |
| `AK.toast(msg, kind?)` · `AK.confirm(text, {ok, cancel, danger})` · `AK.tabs(el)` · `AK.table(el, opts)` · `AK.sortable(table)` · `AK.pager(el, opts)` · `AK.validate(form)` · `AK.bar(el, data)` · `AK.sparkline(el, data)` · `AK.lang()` · `AK.t(key)` | 2.0.0 |
| `AK.line(el, {labels, series})` · `AK.open(path)` · `AK.height()` | 2.0.3 |
| `AK.pickMedia({accept: 'image' \| 'file'})` → `{url, id, alt, width, height}` or `null` | 2.0.4 |

## Reserved public paths

Plugins declare their own paths in `code.routes` (JavaScript) or `service.public` (service/WASM) and cannot use the system's: `api`, `uploads`, `download`, `plugin-assets`, `ext-ui`, `setup`, `_a`, `_c`, `site-assets` (since 2.2.0), `sitemap.xml`, `robots.txt`, `favicon.ico`, `favicon.svg`, `assets`, `static`, plus the admin address and the post/category prefixes. Since 2.0.4 the paths installed plugins declare are reserved too — administrators cannot set the admin address or prefixes to clash with them.

---

Missing an API you need? Every API on this page was added because a plugin needed it — describe the use case and the smallest general API that solves it, instead of relying on the system's internals. See real usage in the [Plugin example](/docs/en/developers/plugin-example).
