api.yaml

enabled: true
route: /api
version_prefix: v1

auth:
  api_keys_enabled: true
  jwt_enabled: true
  # The JWT signing secret is auto-generated and stored, outside this config
  # tree, in user/config/plugins/api-private.php (a non-committed PHP file,
  # mirroring Grav core's security-private.php). It is intentionally not set here.
  jwt_algorithm: HS256
  jwt_expiry: 3600
  jwt_refresh_expiry: 604800
  session_enabled: true

cors:
  enabled: true
  # Cross-origin browser access is OFF by default (same-origin only). To allow a
  # browser app on another origin, list its exact scheme+host here, e.g.
  # 'https://app.example.com'. '*' is intentionally NOT the default: the API
  # serves authenticated data, and a wildcard lets any website read responses
  # for any token it can supply. A configured '*' is honored only for
  # unauthenticated endpoints.
  origins: []
  methods:
    - GET
    - POST
    - PATCH
    - DELETE
    - OPTIONS
  headers:
    - Content-Type
    - Authorization
    - X-API-Key
    - X-API-Token
    - X-Grav-Environment
    - If-Match
    - If-None-Match
  expose_headers:
    - ETag
    - X-Invalidates
    - X-RateLimit-Limit
    - X-RateLimit-Remaining
    - X-RateLimit-Reset
  max_age: 86400
  credentials: false

rate_limit:
  enabled: true
  requests: 120
  window: 60
  storage: file

demo:
  # Demo mode is activated per-account via the `access.api.demo` flag, not by a
  # global switch — a demo account browses everything (typically also granted
  # access.api.super) but all writes are blocked except the resources listed
  # below, and operational/secret data is redacted on read. These settings only
  # tune the writable allowlist and the reset engine; they do nothing until an
  # account is flagged and a baseline has been captured.
  #
  # Permissions a demo account may still write. Leave EMPTY ([]) for a fully
  # read-only demo; use just [api.pages.write] to allow page editing without
  # media uploads. A small hard denylist (config, users, gpm, system, backups,
  # webhooks, and demo itself) is always blocked regardless of what's listed here.
  writable:
    - api.pages.write
    - api.media.write
  # Minutes between automatic resets of the demo content back to the captured
  # baseline. Only takes effect once a baseline exists.
  reset_interval: 30
  # Lazily reset on incoming API requests when the content is stale. Recommended
  # for installs that don't run `bin/grav scheduler` via cron.
  reset_on_request: true
  # Also register a Scheduler job (for installs running `bin/grav scheduler`).
  reset_on_schedule: true
  # A safety snapshot of the live content is taken before every reset, in case
  # the baseline itself is wrong. Oldest snapshots beyond this count are purged.
  keep_safety_snapshots: 5

# Let the new admin's page editor preview an unpublished (published: false) page
# on the front end. The preview is authorized by a short-lived, route-scoped
# token minted only for users with page-read permission; turn this off to disable
# draft previews entirely regardless of the token.
allow_draft_preview: true
# Lifetime of a draft-preview token, in seconds (minimum 30). Short by design —
# it only needs to survive from clicking Preview to the page loading.
preview_token_ttl: 300

flex_backend:
  pages: true
  accounts: true

media_metadata:
  # Descriptive fields editable in the media metadata editor (page media field
  # and site media manager). Each entry's `key` is the exact key written to the
  # `<filename>.meta.yaml` sidecar next to the media file. Order is preserved in
  # the editor. `type` is `text` (single line), `textarea` (multi-line), or
  # `tags` (a list of values, stored as a YAML sequence).
  #
  # Any keys NOT listed here — EXIF data, width/height, the `upload` block core
  # writes, image-action keys like `resize`/`quality` — are left untouched when
  # metadata is saved. Reserved technical keys can never be assigned to a field.
  fields:
    - { key: alt, label: 'Alt Text', type: text }
    - { key: title, label: 'Title', type: text }
    - { key: caption, label: 'Caption', type: textarea }
    - { key: description, label: 'Description', type: textarea }
    - { key: tags, label: 'Tags', type: tags }
  # Maximum characters accepted per metadata value. Values are also stripped of
  # HTML tags on save, since they render into `<img>` attributes on the site.
  max_length: 2000

pagination:
  default_per_page: 20
  max_per_page: 1000

invitations:
  # Default lifetime of a user invite link, in seconds (default 7 days).
  expiration: 604800

popularity:
  enabled: true
  # Skip page views from logged-in admins so your own testing/demo visits
  # don't skew the stats.
  exclude_admin: true
  # Visitor IPs or CIDR ranges to exclude from tracking, e.g.
  # '203.0.113.7' or '203.0.113.0/24' (IPv4 and IPv6 both supported).
  exclude_ips: []
  history:
    daily: 30
    monthly: 12
    visitors: 20
  ignore:
    - '/test*'
    - '/modular'