Sitecore Authoring and Management GraphQL API

Sitecore Experience Manager
Sitecore Authoring and Management GraphQL API
Query examples for authoring operations

Query examples for authoring operations

Version:

You can perform authoring operations using queries and mutations for the following GraphQL types:

Item
Media
Search
Site
Template

For a complete list of available types and operations, refer to the built-in documentation in the GraphQL IDE.

Search criteria

The following sections describe the search criteria you can apply to your queries.

Exact

The search criterion is an exact match of the query term. For example, if you search for "apple", the query will only return results for which the exact value is "apple".

{
    "model": {
        "index": "sitecore_master_index",
        "searchStatement": {
            "criteria": [
                {
                    "field": "_group",
                    "value": "227473f1dc3f4d3a8558865f49b4f64f",
                    "criteriaType": "EXACT"
                }
            ]
        }
    }
}

StartsWith

Returns a field value that starts with the specified search criterion. For example, searching for "app" returns both "apple" and "application".

{
    "model": {
        "index": "sitecore_master_index",
        "searchStatement": {
            "criteria": [
                {
                    "field": "_group",
                    "value": "227473f1dc3f4d3a8558",
                    "criteriaType": "STARTSWITH"
                }
            ]
        }
    }
}

Contains

Returns a field value that contains the specified search criterion. For example, searching for "app" returns "apple", "application", "happen".

{
    "model": {
        "index": "sitecore_master_index",
        "searchStatement": {
            "criteria": [
                {
                    "field": "_group",
                    "value": "c3f4d3a8558",
                    "criteriaType": "CONTAINS"
                }
            ]
        }
    }
}

EndsWith

Returns a field value that ends with the specified search criterion. For example, searching for "ple" returns both "apple" and "maple".

{
    "model": {
        "index": "sitecore_master_index",
        "searchStatement": {
            "criteria": [
                {
                    "field": "_group",
                    "value": "65f49b4f64f",
                    "criteriaType": "ENDSWITH"
                }
            ]
        }
    }
}

Wildcard

Includes a wildcard in the search criterion. For example, searching for "a*e" returns both "apple" and "angle".

{
    "model": {
        "index": "sitecore_master_index",
        "searchStatement": {
            "criteria": [
                {
                    "field": "_group",
                    "value": "227*f64f",
                    "criteriaType": "WILDCARD"
                }
            ]
        }
    }
}

Search

Searches for a full-text phrase within a value. For example, searching for "apple pie" returns items for which the value is "We made apple pie".

{
    "model": {
        "index": "sitecore_master_index",
        "searchStatement": {
            "criteria": [
                {
                    "field": "_name",
                    "value": "Unlock",
                    "criteriaType": "SEARCH"
                }
            ]
        }
    }
}

Range

Searches for a range of values in numerical and date fields. For example, you can search for any value between 1 to 5. When applying this criterion, also enter the value: a string defining the queried range within brackets. When entering the value, note the following:

The type of bracket determines whether the range is inclusive or exclusive. Square brackets denote an inclusive range, and round brackets denote an exclusive range. You can mix bracket types in a single query, for example: if the value is [10 TO 20), 10 is included but 20 is excluded.
Separate the lowest and highest values with the string TO (case-sensitive).
Use an asterisk * to denote an unrestricted value (no lower or upper limit). For example, if the value is (10 TO *), 10 is excluded, and there is no upper limit.

{
    "model": {
        "index": "sitecore_master_index",
        "searchStatement": {
            "criteria": [
                {
                    "field": "__boost",
                    "value": "[1 TO 5]",
                    "criteriaType": "RANGE"
                }
            ]
        }
    }
}

Fuzzy

Used to find matches that are similar to the search term, allowing for minor differences such as typos or variations in spelling. It uses similarity parameters (a value between 0 and 1) to determine how close the match should be to the search term. A higher value means stricter matching. For example, searching for "example" with a similarity parameter of 0.8 might match "exampel" and "exmple".

{
    "model": {
        "index": "sitecore_master_index",
        "searchStatement": {
            "criteria": [
                {
                    "field": "_name",
                    "value": "secuty",
                    "criteriaType": "FUZZY",
                    "parameters": "0.5"
                }
            ]
        }
    }
}

Proximity

Used to find documents where the search terms might be separated from each other by other words. The number of separating words is designated with parameters. For example, searching for "apple pie" with a proximity parameter of 5 returns "apple is not a pie".

{
    "model": {
        "index": "sitecore_master_index",
        "searchStatement": {
            "criteria": [
                {
                    "field": "_name",
                    "value": "collection",
                    "criteriaType": "PROXIMITY",
                    "parameters": "0"
                }
            ]
        }
    }
}

RegEx

A search term that applies a regular expression (RegEx). For example, searching for "a.*e$" returns "apple" and "angle".

{
    "model": {
        "index": "sitecore_master_index",
        "searchStatement": {
            "criteria": [
                {
                    "field": "_name",
                    "value": "\\w*configuration",
                    "criteriaType": "REGEXP"
                }
            ]
        }
    }
}

Query examples

The following sections contain example queries for authoring operations.

Item

Create an item

You can create an item with the createItem mutation.

Query

mutation {
  createItem(
    input: {
      name: "Sitecore Authoring and Management API"
      templateId: "{76036F5E-CBCE-46D1-AF0A-4143F9B557AA}"
      parent: "{110D559F-DEA5-42EA-9C1C-8A5DF7E70EF9}"
      language: "en"
      fields: [
        { name: "title", value: "Welcome to Sitecore" }
        { name: "text", value: "Welcome to Sitecore" }
      ]
    }
  ) {
    item {
      itemId
      name
      path
      fields(ownFields: true, excludeStandardFields: true) {
        nodes {
          name
          value
        }
      }
    }
  }
}

Result

{
  "data": {
    "createItem": {
      "item": {
        "itemId": "30a8616da7c6411db307d4f2c9684e76",
        "name": "Sitecore Authoring and Management API",
        "path": "/sitecore/content/Home/Sitecore Authoring and Management API",
        "fields": {
          "nodes": [
            {
              "name": "Text",
              "value": "Welcome to Sitecore"
            },
            {
              "name": "Title",
              "value": "Welcome to Sitecore"
            }
          ]
        }
      }
    }
  }
}

Delete an item

You can delete an Item using the deleteItem mutation. You can specify the item ID or path. If you specify both, the path parameter is ignored. You can request a permanent deletion by setting the permanently parameter value to true in the request input.

Query

mutation {
  deleteItem( input: { 
      path: "/sitecore/content/Home/Sitecore Authoring and Management API"
      permanently: true
    }
  ) {
    successful
  }
}

Result

{
  "data": {
    "deleteItem": {
      "successful": true
    }
  }
}

Get an item

You can use the item query to retrieve an item. This query retrieves a single item based on the supported identifier arguments, such as itemId.

Query

query {
    item(
        where: {
            database: "master",
            itemId: "{A58AAB49-FE07-4GT5-B03F-927C581E74D7}"
    }){
        itemId
        name
        path
        fields(ownFields: true, excludeStandardFields: true) {
            nodes {
                name
                value
            }
        }
    }
}

Result

{
    "data": {
        "item": {
            "itemId": "a58aab49fe074gt5b03f927c581e74d7",
            "name": "Sitecore Authoring and Management API",
            "path": "/sitecore/content/Home/Sitecore Authoring and Management API",
            "fields": {
                "nodes": [
                    {
                        "name": "Text",
                        "value": "Welcome to Sitecore"
                    },
                    {
                        "name": "Title",
                        "value": "Welcome to Sitecore"
                    }
                ]
            }
        }
    }
}

Update an item

You can use the updateItem mutation to update item fields.

Query

mutation {
  updateItem(
    input: {
      fields: [
        { name: "Title", value: "My new page", reset: false }
        { name: "Content", value: "Lorem Ipsum", reset: false }
      ]
      database: "master"
      itemId: "{59C9BA60-6483-451C-A435-B60BED2DBA75}"
      language: "en"
      path: "/sitecore/content/mycollection/mysite/Home/PageTest"
      version: 1
    }
  ) {
    item {
      name
      itemId
      fields(ownFields: true) {
        nodes {
          name
          value
        }
      }
    }
  }
}

Result

{
  "data": {
    "updateItem": {
      "item": {
        "name": "PageTest",
        "itemId": "59c9ba606483451ca435b60bed2dba75",
        "fields": {
          "nodes": [
            {
              "name": "Title",
              "value": "My new page"
            },
            {
              "name": "Content",
              "value": "Lorem Ipsum"
            }
          ]
        }
      }
    }
  }
}

Copy an item

You can use the copyItem mutation to create a copy of an existing item.

Query

mutation {
  copyItem(
    input: {
      itemId: "{SOURCE_ITEM_ID}"
      targetParentId: "{TARGET_PARENT_ITEM_ID}"
      copyItemName: "Copied Sample Item"
    }
  ) {
    item {
      itemId
      name
      path
      parent {
        itemId
        path
      }
    }
  }
}

Result

{
  "data": {
    "copyItem": {
      "item": {
        "itemId": "ad15387ecce14faabf27866ec06fe045",
        "name": "Copied Sample Item",
        "path": "/sitecore/content/Home/Copied Sample Item",
        "parent": {
          "itemId": "110d559fdea542ea9c1c8a5df7e70ef9",
          "path": "/sitecore/content/Home"
        }
      }
    }
  },
  "extensions": {}
}

Template

Create a Template item

You can use the createItemTemplate mutation to create the item template.

Query

mutation {
  createItemTemplate(
    input: {
      name: "NewTemplate"
      parent: "{B29EE504-861C-492F-95A3-0D890B6FCA09}"
      sections: {
        # Create a new template section if the ID is empty, otherwise update the template section
        name: "newSection"
        fields: [
          # Create a new template field if the ID is empty, otherwise update the template field
          { name: "Field 1", type: "Single-Line Text" }
          { name: "Field 2", type: "Rich Text" }
        ]
      }
    }
  ) {
    itemTemplate {
      name
      ownFields {
        nodes {
          name
          type
        }
      }
    }
  }
}

Result

{
  "data": {
    "createItemTemplate": {
      "itemTemplate": {
        "name": "NewTemplate",
        "ownFields": {
          "nodes": [
            {
              "name": "Field 1",
              "type": "Single-Line Text"
            },
            {
              "name": "Field 2",
              "type": "Rich Text"
            }
          ]
        }
      }
    }
  }
}

Update a Template item and its fields

You can use the updateItemTemplate mutation to update the item template.

Query

mutation {
  updateItemTemplate(
    input: {
      templateId: "{A597BE8E-3DD6-483F-B474-A18AF0560E89}"
      name: "UpdatedTemplate"
      sections: [
        {
          # Create a new template section if the ID is empty, otherwise update the template section
          templateSectionId: "{C8076CA2-FDDE-423C-A819-B6C7573B3FF2}"
          name: "Updated Section 1"
          fields: [
            {
              # Create a new template field if the ID is empty, otherwise update the template field
              fieldId: "{59B88198-5C5B-4E64-A051-3D5ADD003884}"
              name: "Updated Field 1"
            }
            { name: "Create New Field", type: "Single-Line Text" }
          ]
        }
        { name: "Create New Section 2" }
      ]
    }
  ) {
    itemTemplate {
      name
      ownFields {
        nodes {
          name
          type
        }
      }
    }
  }
}

Result

{
  "data": {
    "updateItemTemplate": {
      "itemTemplate": {
        "name": "UpdatedTemplate",
        "ownFields": {
          "nodes": [
            {
              "name": "Updated Field 1",
              "type": "Single-Line Text"
            },
            {
              "name": "Field 2",
              "type": "Rich Text"
            },
            {
              "name": "Create New Field",
              "type": " Single-Line Text "
            }
          ]
        }
      }
    }
  }
}

Media

Upload media

You can use the uploadMedia mutation to get a pre-signed upload URL. You use the pre-signed upload URL to upload a media file to Sitecore.

Query

mutation
{
  # The itemPath parameter should not include the Sitecore media library obsolete path
  # The media item name should be included in the itemPath
  uploadMedia(input: { itemPath: "Default Website/new media" }) {
    presignedUploadUrl
  }
}

Result

{
  "data": {
    "uploadMedia": {
      "presignedUploadUrl": "https://xmcloudcm.localhost/sitecore/api/v1/authoring/media/upload?token=dFh6hm_yH2DrUppd2v7zAU4kvIHk7CgMsXgg2ieaeQzKCU7v7q_W_L9mBY7wGyPw0"
    }
  }
}

XM Cloud is now SitecoreAI

Some code examples, images, and UI labels may still use XM Cloud while engineering assets are being updated.

Note

If the query for a pre-signed upload URL returns an error with the message The specified key is not a valid size for this algorithm, check if the GraphQL.UploadMediaOptions.EncryptionKey setting has a value. For example:

<setting name="GraphQL.UploadMediaOptions.EncryptionKey" value="432A462D4A614E64" />

If it does not, you must set it.

After you get the pre-signed upload URL from the response, you can send a POST request to upload the media file to Sitecore.

For example, by using the curl client:

curl --request POST "https://<your_server>/sitecore/api/v1/authoring/media/upload?token=dFh6hm_yH2DrUppd2v7zAU4kvIHk7CgMsXgg2ieaeQzKCU7v7q_W_L9mBY7wGyPw0" 
--header "Authorization: Bearer <JWT_TOKEN>" --form =@<path_to_your_file>

The response to the request is a JSON-formatted response with the media item ID, Name, and Full path on successful media upload.

Site

Get the configured site

You can query information about a specific site by its name.

Query

query {
  site(siteName: "website") {
    name
    domain
    rootPath
    startPath
    browserTitle
    cacheHtml
    cacheMedia
    enablePreview
  }
}

Result

{
"data": {   
  "site": {     
    "name": "website",     
    "domain": "extranet",    
    "rootPath": "/sitecore/content",     
    "startPath": "/home",     
    "browserTitle": "Website - Sitecore",     
    "cacheHtml": true,     
    "cacheMedia": true,     
    "enablePreview": true   
    }
  }
}

Search

Search items under a specific path

You can search through all the items using the search query. In addition to the example shown, you can use various system fields in your query, such as _name, _template, _templatename.

Query

query {
  search(
    query: {
      index: "sitecore_master_index"
      searchStatement: {
        criteria: [
          { criteriaType: SEARCH, field: "Title", value: "sample item" }
          {
            operator: MUST
            field: "_path"
            value: "110d559fdea542ea9c1c8a5df7e70ef9"
          }
        ]
      }
    }
  )
 {
    results {
      innerItem {
        path
        field(name: "Title") {
          value
        }
      }
    }
  }
}

Result

{  "data": {
    "search": {
      "results": [
        {
          "innerItem": {
            "path": "/sitecore/content/Home/Sample Item1",
            "field": {
              "value": "Sample Item1"
            }
          }
        },
        {
          "innerItem": {
            "path": "/sitecore/content/Home/Sample Item2",
            "field": {
              "value": "Sample Item2"
            }
          }
        }
      ]
    }
  }
}

Sort search results by created date

You can sort search results by a field value.

Query

query {
  search(
    query: {
      index: "sitecore_master_index"
      sort: { field: "__smallcreateddate", direction: DESCENDING }
      searchStatement: {
        criteria: [
          {
            operator: MUST
            field: "_template"
            value: "76036f5ecbce46d1af0a4143f9b557aa" # Sample Item template ID
          }
        ]
      }
    }
  ) {
    results {
      innerItem {
        name
        path
        field(name: "__Created") {
          value
        }
      }
    }
  }
}

Result

{
  "data": {
    "search": {
      "results": [
        {
          "innerItem": {
            "name": "NewestItem",
            "path": "/sitecore/content/Home/NewestItem",
            "field": {
              "value": "20241114T120709Z"
            }
          }
        },
        {
          "innerItem": {
            "name": "OldItem",
            "path": "/sitecore/content/Home/OldItem",
            "field": {
              "value": "20230512T110132Z"
            }
          }
        }
      ]
    }
  }
}

Configure search results using paging

By default, the query returns the first ten search results. You can change this by adding paging parameters to your query.

To do so, use the following parameters:

pageSize - the number of results per page.
skip - the number of results to skip.
pageIndex - the name of the search results page index to return.

Query

query {
  search(
    query: {
      index: "sitecore_master_index"
      paging: { pageSize: 3, skip: 0, pageIndex: 0 }
      searchStatement: {
        criteria: [
          {
            operator: MUST
            field: "_template"
            value: "76036f5ecbce46d1af0a4143f9b557aa" # Sample Item template ID
          }
        ]
      }
    }
  ) {
    results {
      innerItem {
        name
        path
      }
    }
  }
}

Results

{
  "data": {
    "search": {
      "results": [
        {
          "innerItem": {
            "name": "One",
            "path": "/sitecore/content/Home/One"
          }
        },
        {
          "innerItem": {
            "name": "Two",
            "path": "/sitecore/content/Home/Two"
          }
        },
        {
          "innerItem": {
            "name": "Three",
            "path": "/sitecore/content/Home/Three"
          }
        }
      ]
    }
  }
}

Validation

Get validation results for an item template

You can get details about potential validation errors for a field in a field template by querying the validation item.

Query

query fieldValidation {
  item(where: { itemId: "{F704D058-D53C-490A-8803-37249B4F4031}" }) {
    field(name: "Title") {
      value
      validation {
        mode
        results {
          nodes {
            message
            result
            valid
            validator
          }
        }
      }
    }
  }
}

Result

{
  "data": {
    "item": {
      "field": {
        "value": "Page",
        "validation": [
          {
            "mode": "FieldRegexValidation",
            "results": {
              "nodes": [
                {
                  "message": "Only numbers are allowed!",
                  "result": "Error",
                  "valid": false,
                  "validator": "Field RegEx validator"
                }
              ]
            }
          }
        ]
      }
    }
  },
  "extensions": {}
}

Examples of multiple queries

This section describes a series of authoring operations for managing content.

Get all page content

You can make the following three queries to get all the contents of a page. This can be useful if you are building a custom solution, such as a Sitecore Marketplace app, that requires retrieving text content from a page and details such as the last modified date and the user that last edited the content.

Query

First, you can query sites to get the path of the site you want to work with:

query GetSites {
  sites {
    name
    rootPath # Get site path
    rootItem {
      itemId
    }
  }
}

Result

{
  "data": {
    "sites": [
      {
        "name": "<SITE_NAME>",
        "rootPath": "<SITE_PATH>",
        "rootItem": {
          "itemId": "<SITE_ID>"
        }
      }
    ]
  },
  "extensions": {}
}

Query

Next, you can use the site path to find and get all the site pages, including the page ID and path:

query GetSitePages {
  search(
    query: {
      index: "sitecore_master_index"
      searchStatement: {
        criteria: [
          {
            criteriaType: STARTSWITH
            field: "_fullpath"
            value: "<SITE_PATH>" # Replace with your site path
          }
          { operator: MUST, field: "_templatename", value: "Page" }
        ]
      }
      paging: { pageSize: 100, pageIndex: 0 }
    }
  ) {
    totalCount
    results {
      innerItem {
        itemId # Get the page ID
        name
        path # Get the page path
      }
    }
  }
}

Result

{
  "data": {
    "search": {
      "totalCount": 127,
      "results": [
        {
          "innerItem": {
            "itemId": "<PAGE_ID>",
            "name": "<PAGE_NAME>",
            "path": "<PAGE_PATH>"
          }
        }
      ]
    }
  },
  "extensions": {}
}

Query

Finally, you can use the page ID and path to get the contents of a page, including its datasources:

query GetPageContents {
  # Replace itemId with your page ID
  page: item(where: { itemId: "<PAGE_ID>" }) {
    itemId
    name
    path

    fields(ownFields: true, excludeStandardFields: true) {
      nodes {
        name
        value
      }
    }
  }

  # Query the Data folder directly using the page path + /Data
  dataFolder: item(
    where: {
      path: "<PAGE_PATH>/Data" # Replace with your page path
    }
  ) {
    itemId
    name
    path
    template {
      name
    }

    # Get all data source items under the Data folder (Text 1, Text 2, etc.)
    dataSources: children {
      nodes {
        itemId
        name
        path
        createdField: field(name: "__Created") {
          value
        }
        modifiedField: field(name: "__Updated") {
          value
        }
        createdByField: field(name: "__Created by") {
          value
        }
        updatedByField: field(name: "__Updated by") {
          value
        }
        template {
          name
        }

        # Get all fields from data source items
        fields(ownFields: true, excludeStandardFields: true) {
          nodes {
            fieldId
            name
            value
          }
        }
      }
    }
  }
}

Result

{
  "data": {
    "page": {
      "itemId": "<PAGE_ID>",
      "name": "<PAGE_NAME>",
      "path": "<PAGE_PATH>",
      "fields": {
        "nodes": [
          {
            "name": "Title",
            "value": "<PAGE_TITLE>"
          }
        ]
      }
    },
    "dataFolder": {
      "itemId": "<DATA_ITEM_ID>",
      "name": "Data",
      "path": "<DATA_PATH_ID>",
      "template": {
        "name": "Page Data"
      },
      "dataSources": {
        "nodes": [
          {
            "itemId": "<DATASOURCE_ID>",
            "name": "<DATASOURCE_NAME>",
            "path": "<DATASOURCE_PATH>",
            "createdField": {
              "value": "<DATASOURCE_CREATED_DATETIME>"
            },
            "modifiedField": {
              "value": "<DATASOURCE_MODIFIED_DATETIME>"
            },
            "createdByField": {
              "value": "<CREATED_BY_USER>"
            },
            "updatedByField": {
              "value": "<UPDATED_BY_USER>"
            },
            "template": {
              "name": "Text"
            },
            "fields": {
              "nodes": [
                {
                  "fieldId": "<FIELD_ID>",
                  "name": "Text",
                  "value": "<div class=\"ck-content\"><p>Example text content on the page</p></div>"
                }
              ]
            }
          }
        ]
      }
    }
  },
  "extensions": {}
}

If you have suggestions for improving this article, let us know!