Developer docs

Start

Build with AI

Themes

Apps

API and AI agents

Security and contributing

Docs API & AI

API reference

Updated October 13, 2026 5 min read

Every endpoint Basehim core registers, with the scope an API key needs to call it. The REST API lives under /api/v1; the OAuth and MCP endpoints are at the root of your domain. For how authentication, responses and errors work, read the REST API guide first.

Apps add their own endpoints. Your site's admin lists everything installed under API → Reference, including app routes and AJAX actions.

Conventions

Base URL: https://your-site.com/api/v1
Single items are read by slug and changed by id: GET /posts/{slug}, PATCH /posts/{id}.
Lists take page and per_page (up to 100). They return {"data": [...], "meta": {"page", "per_page", "total", "last_page"}}.
Scope is what an API key needs. A JWT carries its user's role instead of scopes. Every write also needs the matching capability on the account, such as edit_posts or manage_users.

Public: no authentication

Method	Path	Purpose
GET	`/posts`	Published posts. `q`, `author_id`, `page`, `per_page`
GET	`/posts/{slug}`	One published post, with `terms` and `seo`
GET	`/pages`	Published pages
GET	`/pages/{slug}`	One published page
GET	`/search?q=`	Search published posts
GET	`/taxonomies`	Taxonomies (category, tag…)
GET	`/taxonomies/{taxonomy}/terms`	Terms of one taxonomy
GET	`/menus/{slug}`	A menu with its items
GET	`/widget-areas`	Widget areas
GET	`/widget-areas/{area}`	One area with its widgets
GET	`/settings/public`	Public settings: title, tagline, formats, timezone, reading
GET	`/time`	Site timezone, offset, formats and the current time
GET	`/time/convert?value=…&to=local`	Convert a time between UTC and the site timezone (`to=local` or `to=utc`)
GET	`/timezones`	Every timezone with its current offset
GET	`/posts/{slug}/comments`	Approved comments on a post
POST	`/posts/{slug}/comments`	Submit a comment: `content`, `author_name`, `author_email`, `author_url`, `parent_id`
GET	`/schedule/run?token=`	Run due scheduled tasks (for cron; the token comes from `GET /schedule`)

Authentication

Method	Path	Scope	Purpose
POST	`/auth/login`	none	`login` (username or email), `password`, optional `otp`. Returns `access_token`, `refresh_token`, `expires_in`
POST	`/auth/refresh`	none	`refresh_token` → a new token pair
POST	`/auth/logout`	none	`refresh_token` → revoke it
POST	`/auth/register`	none	`username`, `email`, `password`; only when registration is open
GET	`/me`	none	The authenticated user
PATCH	`/me`	`users:write`	Update your own profile (a new email or password needs `current_password`)
GET, POST, DELETE	`/me/avatar`	`users:read` / `users:write`	Your profile photo (POST is a `file` upload)

Posts and pages

Method	Path	Scope	Purpose
POST	`/posts`	`posts:write`	Create a post
PUT, PATCH	`/posts/{id}`	`posts:write`	Update a post (only the fields sent)
DELETE	`/posts/{id}`	`posts:write`	Move a post to the trash
POST	`/pages`	`posts:write`	Create a page
PUT	`/pages/{id}`	`posts:write`	Update a page
DELETE	`/pages/{id}`	`posts:write`	Move a page to the trash

Body fields: title, content, content_format (html, markdown or blocks), excerpt, status (draft, pending or published), slug, comment_status, featured_media_id and term_ids. Responses may include a warnings array when HTML was filtered.

Media

Method	Path	Scope	Purpose
GET	`/media`	`media:read`	The library, paginated
POST	`/media`	`media:write`	Upload: multipart `file`, plus `title`, `alt_text` and `caption`
PATCH	`/media/{id}`	`media:write`	Update `title`, `alt_text`, `caption`, `description`
DELETE	`/media/{id}`	`media:write`	Delete the file and its sizes

Taxonomies and terms

Method	Path	Scope	Purpose
POST	`/taxonomies/{taxonomy}/terms`	`taxonomies:write`	Create a term: `name`, `slug`, `description`, `parent_id`
PUT	`/terms/{id}`	`taxonomies:write`	Update a term
DELETE	`/terms/{id}`	`taxonomies:write`	Delete a term

Comments

Method	Path	Scope	Purpose
GET	`/comments`	`comments:read`	Every comment, newest first; filter with `status`, `search`, `post_id`
GET	`/comments/counts`	`comments:read`	Counts by status
GET	`/comments/{id}`	`comments:read`	One comment
PATCH	`/comments/{id}/status`	`comments:write`	`status`: `approved`, `pending`, `spam` or `trash`
DELETE	`/comments/{id}`	`comments:write`	Delete permanently

Menus

Method	Path	Scope	Purpose
GET	`/menus`	`menus:read`	All menus
POST	`/menus`	`menus:write`	Create a menu
PUT	`/menus/{id}`	`menus:write`	Rename or relocate a menu
DELETE	`/menus/{id}`	`menus:write`	Delete a menu
GET	`/menus/{id}/items`	`menus:read`	Items of a menu
POST	`/menus/{id}/items`	`menus:write`	Add an item: `title`, `url`, `parent_id`, `target`
PUT	`/menu-items/{id}`	`menus:write`	Update an item
DELETE	`/menu-items/{id}`	`menus:write`	Remove an item

The public GET /menus/{slug} reads by slug; these manage menus by id.

Users

Method	Path	Scope	Purpose
GET	`/users`	`users:read`	Users (administrators only)
GET	`/users/{id}`	`users:read`	One user: the full record for yourself and user managers, the public profile for others
POST	`/users`	`users:write`	Create a user
PUT	`/users/{id}`	`users:write`	Update a user
DELETE	`/users/{id}`	`users:write`	Delete a user
GET, POST, DELETE	`/users/{id}/avatar`	`users:read` / `users:write`	A user's profile photo

Settings, apps, cache and scheduling

Method	Path	Scope	Purpose
GET	`/settings`	`settings:read`	All settings by group (credentials come back as `[redacted]`)
PUT	`/settings`	`settings:write`	Update settings: `{"group": {"key": "value"}}`
GET	`/apps`	`settings:read`	Installed apps
GET	`/apps/{slug}`	`settings:read`	One app
POST	`/cache/flush`	`settings:write`	Clear the cache
GET	`/schedule`	`settings:read`	Scheduled tasks, last sweep and `meta.cron_url` (needs `manage_settings`)
POST	`/schedule/{app}/{key}/run`	`settings:write`	Run one task now

Activating, deactivating and uninstalling apps stay in the admin on purpose.

OAuth 2.1 (root level)

Method	Path	Purpose
GET	`/.well-known/oauth-protected-resource`	Resource metadata (RFC 9728)
GET	`/.well-known/oauth-protected-resource/mcp`	The same, at the path clients derive from the MCP URL
GET	`/.well-known/oauth-authorization-server`	Server metadata (RFC 8414), including the scopes this site offers
GET	`/.well-known/openid-configuration`	The same metadata at the OIDC discovery path
POST	`/oauth/register`	Dynamic client registration (RFC 7591)
GET, POST	`/oauth/authorize`	Sign-in and consent screen
POST	`/oauth/token`	Exchange a code, or refresh

Grants: authorization_code with PKCE (S256) and refresh_token. Access tokens last 8 hours and refresh tokens 30 days.

MCP (root level)

Method	Path	Purpose
GET	`/mcp`	Discovery: transport, auth methods, metadata URL
POST	`/mcp`	JSON-RPC 2.0: `initialize`, `tools/list`, `tools/call`, `resources/list`, `resources/read`

Authenticate with an OAuth token or an API key. The tools and their scopes are listed in MCP and AI agents.

AJAX gateway

POST /ajax is for this site's own pages, signed in with the browser session. It isn't part of the token API. See AJAX actions.

Discovery files

Path	Contents
`/sitemap.xml`	Every published post and page, categories, tags, authors
`/feed`	RSS feed of recent posts
`/robots.txt`	Crawler rules, including AI crawler choices
`/llms.txt`, `/llms-full.txt`	The site summarised for language models
`/.well-known/ard.json`, `/.well-known/ai-catalog.json`	Agent resource catalog

See AI discovery.