API Events

The API fires events before and after all write operations, allowing plugins to react, validate, modify data, or cancel operations.

API Events (onApi*)

These are the API plugin's own events, fired for every mutation:

Page Events

Media Events

Config, User, and GPM Events

Admin-Compatible Events (onAdmin*)

The API also fires the same events that Grav's admin plugin fires. This ensures third-party plugins that subscribe to admin events (SEO Magic, Auto Date, Mega Frontmatter, etc.) work correctly regardless of whether changes come from the admin UI or the API.

Both event families fire for every operation — admin events first, then API events.

Event Ordering Example

For a page create operation, events fire in this order:

1. onApiBeforePageCreate — API before event
2. onAdminCreatePageFrontmatter — admin frontmatter injection
3. onAdminSave — admin pre-save (plugins can modify the page)
4. onAdminAfterSave — admin post-save (indexing, notifications)
5. onApiPageCreated — API after event (triggers webhooks)

Using Events in Your Plugin

public static function getSubscribedEvents(): array
{
    return [
        'onApiPageCreated' => ['onPageChanged', 0],
        'onApiPageUpdated' => ['onPageChanged', 0],
        'onApiPageDeleted' => ['onPageChanged', 0],
    ];
}

public function onPageChanged(Event $event): void
{
    // Rebuild search index, clear CDN cache, etc.
    $page = $event['page'] ?? null;
    $route = $event['route'] ?? $page?->route();

    $this->rebuildIndex($route);
}

Route Registration

Plugins can extend the API with custom endpoints:

See the Plugin API Integration guide for details.