Developers

Reference

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

17 min readLast updated

View as Markdown

On this page

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 versionAdded
2.0.0The first plugin platform (package, service, WASM and JavaScript) — everything on this page without a version
2.0.3AK.line, AK.open, AK.height, data-ak-line, data-ak-open; admin pages and widgets size to their content
2.0.4AK.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.5JavaScript plugins can declare their own content types (site.postType) — scope post-types, id <plugin id with - as _>_<name> (≤ 20 characters), public: false turns off system routing, spec fields stored under plain names (see JavaScript plugins)
2.0.6Plugin capabilities: capabilities in the manifest (administrators tick them per role under Users → Permissions), 'cap:<capability>' in access lists, site.can(user, cap) / user.can(cap) and caps: { edit, publish } on content types — see Plugin capabilities
2.1.0site.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.1site.cron(expr, fn, { name }); toLocaleString('th-TH') / toLocaleDateString work (Buddhist-era years); REST terms accepts slugs
2.2.0site.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
2.2.2db.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 "Choose a form" from visitors; code.routes may contain dots, e.g. /feed.xml (no .. and no leading dot); files exported from Site Code get category: "utilities"
2.3.0ctx.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.0The 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/<lang>/…)

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

minCore and feature detection#

{ "id": "my-plugin", "version": "1.0.0", "minCore": "2.0.4" }

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:

if (typeof site.dashboardWidget === 'function') site.dashboardWidget('visits', { /* … */ });
if (plugins.has('thai')) site.formatter('price', (v) => plugins.call('thai', 'bahtText', v));
// on an admin page (browser)
if (window.AK && AK.pickMedia) pickButton.hidden = false; else urlInput.hidden = false;

site.*#

APIscope
site.route(spec, opts?, handler) — "GET /x/{id}", access, rawBody, maxBodyroutes
site.page(path, {access, load}) — data for designed pagesroutes
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 <plugin>_<name>, public: false = the plugin serves the pagespost-types
site.job(name, opts?, fn) · site.cron(expr, target, { name }?)jobs
site.can(user, capability) — since 2.0.6 (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.*#

APIscope
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_* viewscontent
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_<id>_* only.

http, mail, jobs, plugins and more#

APIscope
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 '<id>' — 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 (<id>.… 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#

HookRunsTime
site.middlewareBefore routing every request — return nothing = continue, a result = answer now, {headers} = add headers and continue20 ms
site.afterResponseAfter answering (queued, no slowdown) — request data, status, IP etc.2 seconds (before 2.2.0: 500 ms)
site.head / site.bodyEndHTML in <head> / before </body> (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/<id>:<page> and run in a sandboxed iframe — use anasaki.call('<id>:<action>', input) to call actions as the user, anasaki.download(query) for downloads, and draw your own <header class="ak-page-head">
  • 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.

FunctionVersion
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 null2.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.