Docs Developer Site
Developer Docs Guillotine - Headless GraphQL API next Configuration options

Configuration options

Contents

The following configuration options are available for Guillotine

Config file

To configure Guillotine, add a configuration file to your XP instance’s config folder. This example enables CORS for two frontend origins without cookie credentials. Replace the origins with your frontend addresses, including the scheme and port when applicable.

com.enonic.app.guillotine.cfg
graphql.extensions.modifyUnknownField=throw

cors.origin=https://example.com, https://admin.example.com
cors.credentials=false
cors.allowedHeaders=Content-Type
cors.methods=POST, OPTIONS
cors.exposedHeaders=X-Request-Id, X-Custom-Header
cors.maxAge=3600

maxQueryTokens=15000
graphql.extensions.modifyUnknownField

Controls attempts to modify an unknown schema field: throw raises an error, ignore skips the modification, and warn logs a warning. Default is throw.

cors.origin

Allowed origins, comma-separated. Omit this property to disable CORS. Supports (all origins), literal origins, and ~-prefixed regular expressions for dynamic matching. ~. reflects any origin.

cors.credentials

Sets the Access-Control-Allow-Credentials header. Use true or false; the default is false. For cross-origin cookie authentication, set it to true, configure explicit allowed origins, and use credentials: 'include' in the browser’s fetch() request. Browsers do not accept the wildcard origin * with credentials.

cors.allowedHeaders

Sets the Access-Control-Allow-Headers header. If your client sends an Authorization header, include it, for example cors.allowedHeaders=Content-Type, Authorization. If this property is omitted, the request’s Access-Control-Request-Headers value is reflected when present.

cors.methods

Sets the Access-Control-Allow-Methods header. The Guillotine endpoint answers POST and OPTIONS requests only. The library default is GET, HEAD, POST; the example explicitly allows POST, OPTIONS.

cors.exposedHeaders

Extra response headers browser scripts may read beyond the CORS safelist. Listing a header does not create it; expose headers your deployment actually returns. Browsers treat * as a wildcard only for requests without credentials.

cors.maxAge

Sets the Access-Control-Max-Age header, specifying the preflight cache duration in seconds.

maxQueryTokens

Maximum number of raw query tokens. The parser throws an exception when this limit is exceeded. Default is 15000.

CORS controls which browser origins can read responses. Authentication and content permissions still determine which content the caller can access. See Troubleshooting when requests fail.

Media base URL

When exposing XP’s shared API base URL, GraphQL, images and attachments are reachable under the same public base by default. Clients can use this base, or a separate CDN base, when building media links from path and queryString. Configure the public route to serve those paths.

XP also generates media links inside processed rich text. On XP 8.1 and later, configure their default media base in the XP portal configuration:

com.enonic.xp.portal.cfg
media.defaultBaseUrl = https://cdn.example.com/api

This produces media URLs under https://cdn.example.com/api/media:image/…​; and https://cdn.example.com/api/media:attachment/…​; where a more specific API location or a contextual media mount does not take precedence. Configure the CDN to forward those paths to XP’s corresponding /api/media:image/…​ and /api/media:attachment/…​ endpoints. This setting changes URL generation; the CDN route must be configured separately.

Sites that mount the media APIs keep URLs under their own endpoints. To move their media to the default media base, also set legacy.mediaApiAutoMount.enabled = false and omit the relevant media APIs from the site’s descriptor. See the XP media configuration for mount precedence and preview behavior.

Virtual-host context can also declare a shared API location or individual API locations. See the API locations reference for dedicated hosts and paths.

Contents

Contents