Rest API Reference

Complete REST API endpoint reference with parameters, examples, and response codes. All endpoints are prefixed with the configured route (default: /api/v1).

Base URL

All endpoints are prefixed with: {site_url}/api/v1

Authentication

The public endpoints that do not require authentication are everything under /auth/ (token, 2FA verify, refresh, revoke, forgot and reset password, setup, invitation accept, password policy, captcha and SSO), GET /translations/{lang}, GET /thumbnails/{file} and GET /ping. Plugins can add their own public routes through the onApiCollectPublicRoutes event. Everything else requires authentication via:

an API Key (X-API-Key header or ?api_key= query param),
a JWT access token (preferred as X-API-Token, accepted as Authorization: Bearer), or
an active Grav session (passthrough).

See Authentication for details including why X-API-Token is preferred over Authorization: Bearer on FastCGI / PHP-FPM hosts.

Environments

The API respects Grav environments. Pass X-Grav-Environment: <hostname> to target a specific environment configuration.

Common Response Codes

Code	Description
200	Success
201	Created
204	No Content (successful deletion)
304	Not Modified (ETag match on conditional GET)
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
405	Method Not Allowed (the path exists, but not for this method)
409	Conflict (including an `If-Match` ETag that no longer matches on update)
422	Validation Error
429	Rate Limited
500	Internal Server Error
502	Bad Gateway (e.g. GPM repository unreachable, webhook test failed)

Authentication

Endpoints for JWT login/logout, password reset, two-factor verification, first-run setup, the password policy, invitation accept, login captcha, SSO login, and retrieving the current session. Everything under /auth/ is public (no auth required). GET /me requires an authenticated session.

Pages

Endpoints for managing Grav pages including listing, creating, updating, deleting, copying, moving, and reordering, plus page translations, batch operations, draft preview tokens, taxonomy, and the site's language list.

Media

Endpoints for managing media files attached to pages and site-level media, their .meta.yaml metadata, the manual order of site media folders, and files saved by blueprint file fields. Reading needs api.media.read and changing anything needs api.media.write. Page media also follows the page's o...

Configuration

Endpoints for reading, updating and reverting Grav configuration scopes including system, site, media, security, plugins, themes and site-authored custom scopes, plus the Flex accounts configuration. Reads need api.config.read and writes need api.config.write; writes to system, security and...

Users

Endpoints for managing user accounts (listing, creating, updating and deleting users, avatars, API keys and 2FA), user groups, and invitations.

Package Manager

Endpoints for managing Grav packages (plugins and themes) via the GPM, including installation, removal, updates, and repository search, plus the endpoints that serve plugin admin pages and web component scripts to Admin2.

System

Endpoints for system-level operations including information, cache management, environments, logs, backups, translations, and reports.

Blueprints

Endpoints for retrieving blueprint schemas used for page templates, user accounts, groups, plugins, themes, configuration and permission definitions, plus GET /blueprint-files, which lists files for blueprint folder picker fields. Uploading and deleting files for blueprint file fields is covered...

Sidebar

Dashboard

Endpoints for dashboard data including statistics, notifications, news feed, page view popularity, the storage exposure check, and the customizable widget layout.

Scheduler

Manage Grav's cron-based scheduler. List registered jobs, inspect cron installation status, review execution history, and trigger manual runs. Permissions: api.scheduler.read / api.scheduler.write.

Webhooks

Register outgoing HTTP webhooks that fire when API write events happen (page/media/user mutations, config updates, GPM installs, Grav upgrades). Each webhook has a URL, an event filter list, optional custom headers, a generated secret for HMAC signing, and a delivery log. Permissions: api.webhook...

Admin2 Integration

Endpoints that power Admin2's extensibility and preferences: menubar toolbar items, floating widgets, slide-in context panels, settings-page panels, the registry of plugin-provided custom field components, markdown editor toolbar buttons, and Admin2's user and site preferences and branding. All en...

Flex Objects

Endpoints for managing Flex Object directories and their records: listing directories and blueprints, full CRUD on objects, YAML export, and per-object media (files stored alongside the object in its own folder).

Audit Trail

Read the admin audit trail: a log of the actions taken through the API, with who did them, when, from which IP and against what. Because Admin Next does everything through the API, the log covers the whole of Admin Next plus any API-key clients. Actions taken in the classic admin that bypass the API...

Translations Editor

The endpoints behind the Admin Next translations editor. They let you browse every translation string that Grav core, plugins and themes ship, see how complete each language is, and override any string for this site. Overrides are stored per language in user/languages/.yaml. These routes l...

MCP

Tool manifests for Model Context Protocol servers. An MCP server such as the Grav MCP Server already has tools for everything the API plugin does itself, but it can't know about routes that other plugins add through onApiRegisterRoutes. A plugin describes those routes as tools, in an mcp.yaml...

Demo Mode

Control the demo-mode reset engine, for public demo sites. A demo account is any account with access.api.demo set. Demo accounts can read, but writes are blocked except for the permissions listed in plugins.api.demo.writable, and some reads that reveal server paths or other visitors' data are hi...