API

The API

The API v2 under /api/v2 is the integration interface for trusted servers such as the separate central administration. It uses an issued integration key and scopes, HTTPS, finite resource and field allowlists, strong ETags for edits and audit records. It does not expose its key to browser JavaScript and does not enable browser CORS. It covers content (including hiding and showing a published article), structure, users, translations, the cache flush and the change log. There is no login through the API: people sign in on the web at /login/.

Do not send an integration key from a user browser. The browser should call its own application server, which then contacts each WBengine site over verified HTTPS.

API example

curl -H 'Authorization: Bearer <integration key>' \
  https://example.com/api/v2/identity

An administrator issues the key on the /integrations/ page of the site.

Keys and scopes

A key carries scopes that decide what it may do. A missing or invalid key returns 401; a key without the required scope receives 403. Write routes validate allowed fields.

For deployment diagnostics use vendor/bin/wbengine.php doctor; it does not change the schema. API v2 is enabled separately in application configuration and needs its database tables for protected content operations (see the Deployment page). Its discovery, capabilities, resources, scopes and concurrency rules are described in the WBengine API v2 reference. See also the central administration guide.

Hiding and showing an article

POST /api/v2/articles/{id}/hide hides a published article and POST /api/v2/articles/{id}/unhide shows it again. Both need the scopes articles:write and publish:write and the If-Match header with the ETag of the article, and both can be repeated safely. A hidden article is not displayed: its address answers 404, its menu entry disappears and it is left out of the sitemap. The list of articles can be filtered with hidden=0 or hidden=1. The change is recorded in the change log as hide and unhide.

Limiting a key to addresses

A key can be bound to IP addresses or CIDR ranges, on the issue form or later on the card of the key. Such a key works only from those addresses and any other request is refused with ip_not_allowed. The card of a key shows the address it was last used from, which helps to find a key that is used from an unexpected place.

The change feed and the history

GET /api/v2/changes (scope audit:read) returns the change log, newest first, with these filters: resource, resource_id, action, source, actor, since, until and outcome=rejected, which lists the writes the site refused with their error code. Actor labels are written by the clients and are data, not proof of who someone is. The complete snapshots of a page, menu entry, section or box can be read, and restored, through its own changes path. See Logging and audit.

Images

POST /api/v2/images uploads a PNG, JPEG or WebP image of at most 512 KiB as base64 with its mime (scope images:write). The images can be listed and read, and deleted with the ETag and the write scope. The file needs a directory outside the web root (apiV2.imageDirectory or the environment variable WBENGINE_IMAGE_DIR); without it the site reports images as unavailable. The structure and the type of the file are checked, but this is not a full image decoder or an antivirus, so do not use it as a general file upload. An uploaded image is public media: it is served at its own address to anyone who has it, so it must not hold anything secret.

Statistics

GET /api/v2/analytics/overview (scope analytics:read) takes from and to (YYYY-MM-DD), granularity (day, week, month) and an optional locale. It returns the totals, the series, the most viewed pages, articles and boxes, and the views by language. See Statistics.

Presets and the MCP server

When a key is issued the form offers presets for common uses: full management for the central Admin, an editor, an agent for content, an agent that writes drafts only, and read only. An AI assistant works through the MCP server with such a key and can do only what the key allows.