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: POST /auth/token, POST /auth/2fa/verify, POST /auth/refresh, POST /auth/revoke, POST /auth/forgot-password, POST /auth/reset-password, GET /auth/setup, POST /auth/setup, GET /ping, and GET /translations/{lang}. 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
409	Conflict
412	Precondition Failed (ETag / `If-Match` mismatch 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, and retrieving the current session. Token/refresh/revoke/2FA/setup/forgot/reset endpoints are public (no auth required). GET /me requires an authenticated session.

Pages

Endpoints for managing Grav pages including listing, creating, updating, deleting, moving, and reordering.

Media

Endpoints for managing media files attached to pages and site-level media.

Configuration

Endpoints for reading and updating Grav configuration scopes including system, site, plugins, and themes.

Users

Endpoints for managing user accounts including listing, creating, updating, and deleting users.

Package Manager

Endpoints for managing Grav packages (plugins and themes) via the GPM, including installation, removal, updates, and repository search.

System

Endpoints for system-level operations including information, cache management, translations, and blueprints.

Blueprints

Endpoints for retrieving blueprint schemas used for page templates, user accounts, and permission definitions.

Sidebar

Dashboard

Endpoints for dashboard data including statistics, notifications, news feed, and page view popularity.

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, an optional shared secret for HMAC signing, and a delivery log. Permissions: api.webhooks.read / api.web...

Admin2 Integration

Endpoints that power Admin2's extensibility: menubar toolbar items, floating widgets, slide-in context panels, settings-page panels, and the registry of plugin-provided custom field components. All endpoints require api.access and are meant to be called by Admin2 during UI composition, not by en...