In this section · 4 articles

Headless CMS settings

Every global setting on the Delivery, Editing, Limits and Languages tabs, which ones a content space can override, what's fixed by design, and the permissions and roles.

Applies to
Headless CMS 1.0 and later
Who can do this
Administrator
Where
Headless CMS › Settings
On this page

Headless CMS › Settings opens the Headless CMS panel in the Settings hub. These are the defaults for every content space. To see them you need feature.hcms.settings.view, and to change them feature.hcms.settings.edit. See How the settings hub works.

  • Settings marked Per space can be overridden on a space's Settings tab. The panel shows how many spaces override each one, and the Overridden in spaces table lists them.
  • A save that changes what applications receive asks first: Save changes that applications will notice? It lists the spaces that use the global value and says how long readers may see the previous answer.
  • Reset to previous puts back the values from before the last save, until the next save.
  • Every number has a fixed ceiling that no setting can raise.
The Save changes that applications will notice? dialog, showing Public cache max-age going from 60 s to 600 s, the three spaces using the global value, and a wait of up to 6 minutes.

Delivery

The Delivery tab of the Headless CMS settings panel, showing default and maximum page size, public cache max-age, stale-while-revalidate, the no-delivery-channel choice and the hidden-reason toggle.
SettingWhat it doesDefaultRangePer space
Default page sizeHow many items a list returns when a request names no page size.20 items1 to the maximum page sizeYes
Maximum page sizeThe most a request may ask for with ?per_page=.100 items1 to 100Yes
Public cache max-ageHow long a browser or CDN may reuse a Public space's response before asking again. 0 means always ask.60 s0 to 900 sYes, as Cache time
Stale-while-revalidateAfter that, how long an old response may still be served while a fresh one is fetched.300 s0 to 600 sYes, as Serve while refreshing
When a request names no delivery channelReturn "All channels" entries only, or Refuse the request with a 422 that asks the application to name a channel. An application's default channel from API access applies first.All channels onlyYes, as Requests that name no channel
Tell granted applications why something is hiddenA caller with a granted key gets the reason with a 404, such as assignment_delivery_disabled, to help its developers. Everyone else always gets the identical "not found".OnNo

With the defaults, readers of a Public space may see the previous version of an answer for up to 6 minutes after a change (60 s + 300 s). Restricted spaces are never cached publicly, so these two settings don't apply to them.

Maximum page size says larger requests get this many, but in Headless CMS 1.0.0 a request with a larger ?per_page= is refused with 422, This query is not supported. Have your developers ask for this many at most.

Editing

The Editing tab of the Headless CMS settings panel, showing the undo window, revisions kept per entry per language, trash retention, the duplicate-channels toggle and the stale-version threshold.
SettingWhat it doesDefaultRange
Undo windowHow long every Undo in the module is offered after a change.8 s5 to 30 s
Revisions kept, per entry, per languageOlder revisions are removed each night. An entry always keeps its published version.505 to 500
Trash retention (entries only)Entries in the trash are removed for good after this many days. Nothing else in the trash is removed.30 days7 to 365 days
Duplicating an entry copies its delivery channelsOff: a copy starts on all channels. Either way the copy is a draft.On
Mark a version as stale after N days without callsOnly flags a served version on the schema's Versions tab. No setting ever retires a version.90 days30 to 365 days

Lowering Revisions kept asks first and says how many older revisions are removed that night. Raising it later doesn't bring them back.

Limits

The Limits tab of the Headless CMS settings panel, showing the default size limits from Text (255 characters) to Response size budget (5 MB), beside the Fixed by design list.
SettingWhat it doesDefaultCeiling
TextThe longest value a Text field can hold. Email and URL fields have their own fixed maximums.255 characters1,000
Long textThe largest value a Textarea field can hold.10 kB50 kB
Rich textThe largest document a Rich text field can hold.200 kB1,024 kB
JSON sizeThe largest value a JSON field can hold.64 kB256 kB
JSON depthHow deeply a JSON value may nest.8 levels16
Multi-selectThe most choices one Multi-select field can hold.100 items500
One entryThe largest one language of an entry can be, with its shared values.512 kB2,048 kB
Delivery channels on an entryThe most channels one entry can be shown on.2050
References expanded per requestA request naming more reference fields in include is refused.35
Response size budgetA page that would be larger stops early, never mid-item, and links to the next page.5 MB1 to 20 MB

A field can set a lower limit of its own in its Validation settings. Reference depth is fixed at one level.

Lowering a limit below values already stored asks first and names the entries over it. That content stays delivered as it is. An untouched value still saves, but an editor who changes such a value must shorten it, and Publish refuses until they do. With many entries, the count runs in the background; save again once it has finished.

Languages

The Languages tab of the Headless CMS settings panel, showing Default language for new spaces, Fall back to the space's default language, Required fields must be filled in and Transliteration while typing.
SettingWhat it doesDefaultPer space
Default language for new spacesOnly preselects the language when a space is added. Existing spaces don't change.enNo
Fall back to the space's default languageA language with nothing published receives the default language's copy.OnYes, on the space's Languages panel
Required fields must be filled inThe default language only: other languages may leave a required field empty and fall back. Every language of the space: publishing a language checks its own values. Shared values are always checked.The default language onlyYes
Transliteration while typingPhonetic typing in non-Latin languages in the content editors. Ctrl+G switches it off while typing.OnNo

A space's languages and default language are chosen on each space's page, not here.

Fixed by design

These aren't settings, and nothing changes them: the identical "not found" for anything hidden or missing; rich-text and URL cleaning, with URLs up to 2,048 characters; keys never change once fixed and are never reused; the change rules and the version guard, with retiring a version always a manual, typed step; the eight delivery checks; drafts never reaching the API; every limit's ceiling; and a reference depth of one level.

Permissions

All keys start with feature.hcms.. Give them with a role. See Give someone a role.

ResourceActionsAllows
spacelist, view, create, edit, delete, restore, removeContent spaces: seeing, adding, changing, trashing, restoring and removing spaces for good.
schemaThe same seven, plus export, import, retire_version, emergency_stopContent schemas and their fields, exporting and importing definitions, retiring a version, and stopping a field at once.
assignmentlist, create, edit, delete, restore, removeAssignments: assigning, turning delivery on or off, removing, restoring and removing for good.
entrylist, view, create, edit, delete, restore, remove, publish, unpublish, previewContent: writing, trashing, restoring and removing entries for good, publishing, unpublishing, reordering (needs publish), and previewing drafts.
entry (own)edit_own, delete_own, restore_own, publish_own, unpublish_ownThe same, for entries the person created.
channellist, view, create, edit, delete, restore, removeChannels.
accesslist, view, create, edit, delete, restore, removeAPI access: grants, default channels and version pins. view is also needed to read as an application in the API explorer.
api_explorerviewAPI explorer. It also needs space.view.
settingsview, editThis panel.

schema.retire_version and schema.emergency_stop are never part of Core's curated Administrator role, and neither is any remove action. Installing the Headless CMS on an existing Laramin gives the Administrator role none of these permissions; give them in the role editor.

Roles

RoleKeyHolds
CMS Administratorhcms.cms_administratorEvery Headless CMS permission.
Content Editorhcms.content_editorspace and schema list and view; entry list, view, create, edit, delete, restore and preview; api_explorer.view. Never publishes.
Content Publisherhcms.content_publisherThe Content Editor's permissions, plus entry.publish and entry.unpublish.

The roles are given to nobody when the add-on is installed. An upgrade adds new permissions to them and never removes any you changed, and a role you deleted isn't created again. To uninstall the add-on while people hold these roles, choose Remove the roles too.