Docs Developer Site
Developer Docs CMS reference docs next Apis GraphQL API

GraphQL API

Contents

The GraphQL API is Enonic’s primary headless API. It is provided by Guillotine, a separately installed and versioned Enonic app that exposes CMS content through a typed GraphQL schema.

The examples in this CMS reference use Guillotine 9, which requires Enonic XP 8.1.0 or later. For changes from earlier Guillotine versions, see the upgrade notes.

Location

On a local sandbox with Guillotine installed, send HTTP POST requests to:

http://localhost:8080/api/com.enonic.app.guillotine:graphql

Guillotine is a Universal API. A deployment can expose /api as a shared API base URL, with GraphQL at <apiBaseUrl>/com.enonic.app.guillotine:graphql and the Image and Attachment APIs under the same base. Public routes depend on your deployment; see Guillotine setup for routing and site mounting.

The endpoint does not serve a query editor. Use Content Studio’s Query Playground or a third-party GraphQL client to explore the schema.

Project and branch

Guillotine: 9.0.0 Guillotine Guillotine 9.0.0 9.0.0 At the Web endpoint, select the project and branch on the guillotine field. Use master for published content and draft for work in progress. Examples in this reference use myproject; replace it, the content paths and the example content types with your own.

Query Playground supplies the project and branch selected in Content Studio. At a site-mounted endpoint, the request determines them and query arguments cannot override them. See Guillotine’s content context for details.

Authorization

Guillotine applies the caller’s content permissions. Anonymous requests can read content granted READ permission for role:system.everyone. Published content must also be readable to be returned; publishing alone does not grant access.

For protected content, authenticate using the session or authorization mechanism configured by your deployment’s identity provider or gateway. Installing Guillotine does not create a separate API credential. Query Playground uses your signed-in Content Studio user, while external clients need their own authentication. See Guillotine troubleshooting for authentication and configuration for browser CORS settings.

Schema

Guillotine generates its GraphQL schema from the content types and other schemas in the Enonic installation. Each form field maps to a GraphQL field: TextLine becomes a string, ImageSelector resolves to image content, and ItemSet becomes a nested object. CMS mixin data is available under x.

The schema exposes pages and components, content hierarchies, search, and references. Search uses queryDsl or queryDslConnection. For field definitions, pagination and aggregations, use the Guillotine API reference.

Usage

Requests use HTTP POST with a JSON body containing query and optional variables. This example reads a published article that is accessible to anonymous callers:

curl -X POST 'http://localhost:8080/api/com.enonic.app.guillotine:graphql' \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ guillotine(project: \"myproject\", branch: \"master\") { get(key: \"/articles/hello\") { displayName } } }"}'
{
  "data": {
    "guillotine": {
      "get": {
        "displayName": "Hello world"
      }
    }
  }
}

Check the response for GraphQL errors as well as the HTTP status; errors can accompany partial data. See Guillotine usage for request variables and complete client examples, or Developer 101 for hands-on content modeling and querying.

URLs and rich text

Guillotine 9 returns URL objects. Select path and queryString from imageUrl, mediaUrl or attachmentUrl, then concatenate your public API or media base URL with both values. Keep the returned path and query string intact. See Image content for an example.

For page links, adapt pageUrl.path to your front-end routes. The optional scopeKey selects the content that paths are relative to, usually a site; it does not restrict searches to that subtree. Without it, page URLs use the project context. See Site URL scope for examples and the change from siteKey in earlier versions, and Guillotine’s URL documentation for URL handling.

Rich text contains placeholders in processedHtml. Use its structured links, images and macros fields to render them in your front-end.

Extending the schema

Guillotine’s generated content API is read-only. Applications can add custom fields, queries and mutations through extensions, including integrations with external systems. See the Guillotine extension documentation for implementation details.

Contents

Contents