Understanding queries

Version: 0.4

Reference documentation

Queries let you retrieve data from Sitecore to your Marketplace app, and they are a common development task you perform with the Marketplace SDK.

Commonly used queries include retrieving the application context (details about your app and the Sitecore extension point), the page context (details about a SitecoreAI page), and making GET requests to Sitecore REST APIs.

Note the following about query operations:

Extension points - some operations are only available in certain extension points. For example, querying the page context is only available in the SitecoreAI Page builder.
API access - operations with Sitecore APIs require that you install the SDK package associated with those APIs.

If your app architecture supports server-side API calls to AI skills APIs, you can use the experimental functions to access those APIs directly from the server.

If your app architecture supports server-side API calls to AI skills APIs, you can use the experimental functions to access those APIs directly from the server.
Subscriptions - if the operation supports subscriptions, you can subscribe to events to receive real-time updates in your app as the data in Sitecore changes. For example, when querying page details, you can subscribe to page events that trigger when the SitecoreAI user opens a different page.

Common queries

This section describes commonly used queries and example responses. To make these queries, refer to the developer guides.

Application context

The application context lets you retrieve details about your Marketplace app and the Sitecore app, such as environment information and Context IDs.

Here's an example request and response:

client.query("application.context")

{
  "id": "<MARKETPLACE_APP_ID>",
  "name": "My Marketplace App",
  "type": "custom",
  "url": "<MARKETPLACE_APP_URL_WITH_ORG_ID_AND_TENANT_ID>",
  "iconUrl": "https://...",
  "state": "active",
  "installationId": "20c3f4ee-...",
  "marketplaceAppTenantId": "<TENANT_ID>",
  "organizationId": "<ORGANIZATION_ID>",
  "resourceAccess": [
    {
      "resourceId": "xmcloud",
      "tenantId": "d93a37cd-...",
      "tenantName": null,
      "tenantDisplayName": "<ENVIRONMENT_DISPLAYNAME>",
      "context": {
        "preview": "<PREVIEW_CONTEXT_ID>",
        "live": "<LIVE_CONTEXT_ID>"
      }
    }
  ],
  "extensionPoints": [
    {
      "extensionPointId": "<EXTENSION_POINT_NAME>",
      "route": "<EXTENSION_POINT_ROUTE>",
      "meta": []
    }
  ]
}

Page context

The page context lets you retrieve details about the currently opened page in the SitecoreAI Page builder and the site the page is part of.

Here's an example request and response:

client.query("pages.context")

{
  "siteInfo": {
    "id": "<SITE_ID>",
    "hostId": "<HOST_ID>",
    "name": "<SITE_NAME>",
    "displayName": "<SITE_DISPLAYNAME>",
    "language": "en",
    "appName": "test-site",
    "layoutServiceConfig": "https://...",
    "renderingEngineEndpointUrl": "https://...",
    "renderingEngineApplicationUrl": "https://...",
    "pointOfSale": [],
    "startItemId": "c981c8fb-...",
    "supportedLanguages": [
      "en"
    ],
    "collectionId": "<COLLECTION_ID>",
    "properties": {},
  "pageInfo": {
    "__typename": "Page",
    "id": "<PAGE_ID>",
    "displayName": "Home",
    "name": "Home",
    "icon": "",
    "path": "<PAGE_PATH>",
    "version": 1,
    "language": "en",
    "revision": "0442b20d-...",
    "createdBy": "sitecore\\...",
    "creationDate": "2025-07-15T05:58:40Z",
    "isLatestPublishableVersion": true,
    "template": {
      "__typename": "Template",
      "id": "<TEMPLATE_ID>",
      "name": "Page",
      "path": "<TEMPLATE_PATH>",
    },
    "permissions": {},
    "locking": {},
    "publishing": {},
    "versions": [{}],
    "workflow": null,
    "presentationDetails": "<PRESENTATION_DETAILS>",
    "layoutEditingKind": "FINAL",
    "route": "/Home"
  }
}

Site context

The site context lets you retrieve details about the current SitecoreAI site.

Here's an example request and response:

client.query("site.context")

{
  "siteInfo": {
    "siteId": "<SITE_ID>",
    "name": "<SITE_NAME>",
    "displayName": "<SITE_DISPLAYNAME>",
    "hosts": [
      {
        "id": "<HOST_ID>",
        "name": "<HOST_NAME>",
        "languageSettings": {
          "defaultLanguage": "en"
        }
      }
    ]
  }
}

SitecoreAI Sites REST API

Interacting with the SitecoreAI Sites REST API lets you manage SitecoreAI sites, site collections, jobs, languages, and more.

All requests to SitecoreAI APIs must contain the Context ID of your SitecoreAI environment, which you can retrieve from the application context.

Here's an example request and response for listing sites:

Client-side

client.query("xmc.sites.listSites", {
  params: {
    query: { sitecoreContextId }
  }
})

Server-side

await xmcClient.sites.listSites({
  query: {
    sitecoreContextId,
  },
});

The response is nested in data.data:

{
  "data": {
    "data": [
      {
        "id": "<SITE_ID>",
        "name": "<SITE_NAME>"
        // Rest of API response here
      }
    ],
    "request": {},
    "response": {}
  },
  "status": "success",
  "isLoading": false,
  "isError": false,
  "isSuccess": true
}

Here's an example request and response for listing languages:

Client-side

client.query("xmc.sites.listLanguages", {
  params: {
    query: {
      sitecoreContextId,
    },
  },
});

Server-side

await xmcClient.sites.listLanguages({
  query: {
    sitecoreContextId,
  },
});

The response is nested in data.data:

{
  "data": {
    "data": [
      {
        "id": "<LANGUAGE_ID>"
        // Rest of API response here
      }
    ],
    "request": {},
    "response": {}
  },
  "status": "success",
  "isLoading": false,
  "isError": false,
  "isSuccess": true
}

Ideas for queries

Here are a few examples of what you can achieve with queries:

Retrieve the application context so you can display your app name to the Sitecore product user without hardcoding it in your app's source code.
Retrieve the page content of an SitecoreAI page and use it to generate keywords using your custom application logic. Then, display the keywords in your app so marketers can read them and decide which ones to add to the page.
Combine queries with mutations to develop even more powerful functionalities. While queries are for retrieving data, mutations let you change the data in Sitecore.

Tip

Marketplace SDK queries and mutations follow the industry standard patterns established by GraphQL and React Query. Familiarity with these technologies will help you effectively manage data using the Marketplace SDK.

Consider a Marketplace app that provides AI-generated summaries for SitecoreAI pages. To build such an app, you can first make a query to retrieve the contents of a SitecoreAI page, then use your custom application logic to generate a summary using AI. Next, make a mutation to update the page content with the AI summary included. Finally, make another mutation to reload the canvas. This way, the marketer can immediately see the summary directly on the page.

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