Settings API

UnfoldCMS settings are dot-notation key-value pairs stored in the database (e.g. general.site_name, comments.enabled, seo.fallback_image). The API exposes them via two routes: a public read-only whitelist and an admin full-access surface.

Public Endpoint

GET /api/v1/settings/public

Returns only settings on the public allowlist. The whitelist is defined in code, not in admin settings — adding a key requires a code change. This protects against accidentally exposing secrets if an admin tags the wrong setting "public."

Currently whitelisted keys:

Key	Description
`general.site_name`	Site title
`general.site_tagline`	Site tagline
`general.site_description`	Long-form site description
`general.contact_email`	Public contact email
`general.logo_url`	Logo image URL
`general.favicon_url`	Favicon URL
`general.timezone`	Site timezone
`general.locale`	Default locale
`seo.fallback_image`	Default OG image
`social.twitter`	Twitter/X profile URL
`social.github`	GitHub profile URL
`social.linkedin`	LinkedIn URL
`social.facebook`	Facebook page URL
`social.youtube`	YouTube channel URL
`social.instagram`	Instagram profile URL
`social.discord`	Discord invite URL
`blog.posts_per_page`	Default pagination size
`comments.enabled`	Whether commenting is allowed
`comments.allow_guest_comments`	Whether unauthenticated users can comment
`comments.require_approval`	Whether comments need admin approval

Example:

curl https://your-site.com/api/v1/settings/public

Response:

{
  "success": true,
  "message": "Public settings retrieved successfully",
  "data": {
    "general.site_name": "UnfoldCMS",
    "general.contact_email": "[email protected]",
    "social.twitter": "https://twitter.com/unfoldcms",
    "comments.enabled": true
  }
}

Settings with null or empty values are omitted from the response.

Admin Endpoints

Requires bearer token with admin ability.

GET /api/v1/admin/settings

List all settings (paginated).

Query parameters:

Param	Description
`group`	Filter by setting group (`general`, `social`, `comments`, etc.)
`per_page`	Items per page (default 100, max 200)

GET /api/v1/admin/settings/{key}

Read a single setting by key.

curl https://your-site.com/api/v1/admin/settings/general.site_name \
  -H "Authorization: Bearer ADMIN_TOKEN"

Response:

{
  "success": true,
  "message": "Setting retrieved successfully",
  "data": {
    "key": "general.site_name",
    "value": "UnfoldCMS"
  }
}

Returns 404 if the key doesn't exist.

PUT /api/v1/admin/settings/{key}

Set a value. Type is auto-inferred from the value, or pass it explicitly.

curl -X PUT https://your-site.com/api/v1/admin/settings/general.site_name \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value": "My Awesome Site"}'

With explicit type:

{
  "value": "true",
  "type": "boolean"
}

Valid types: string, boolean, integer, array, json.

DELETE /api/v1/admin/settings/{key}

Remove a setting. The next read returns the default from config/site.php.

Security Notes

Public endpoint never returns secrets. Database passwords, API keys, encryption keys — none of these are on the public whitelist, and adding them would require a code change.
Admin endpoint requires admin ability. A regular user token gets 403.
No write rate limit beyond the admin throttle (30/min). For bulk updates, batch them or expect throttling.

Roadmap

Currently exposed:

✅ Single setting read/write
✅ Public whitelist

Not yet exposed (planned for v1.2):

❌ Bulk group operations (/admin/settings/group/{group})
❌ Toggle endpoint for booleans
❌ Settings schema introspection

Menus Webhooks