{
"openapi": "3.0.1",
"info": {
"title": "Querying API",
"description": "\nUse the Querying API to fetch multiple pages of search results sequentially.
This REST API returns entities that match specific criteria and supports both [generic](https://doc.sitecore.com/ch/en/developers/cloud-dev/generic-properties.html) and [specific](https://doc.sitecore.com/ch/en/developers/cloud-dev/specific-properties.html) properties along with numerous [parameters](https://doc.sitecore.com/ch/en/developers/cloud-dev/parameters.html).
When using the Querying API, keep the following considerations in mind:\n- Due to deep paging considerations the querying endpoint is limited to retrieve up to 10,000 results.\n- When search results are sorted on a property and there are multiple results that have the same value for that property, then those results are displayed in random order. To address this limitation, use a secondary sort property as a tie-breaker.\n- With [full-text search](https://doc.sitecore.com/ch/en/developers/cloud-dev/full-text-search.html), do not use the following characters: `«`, `»`, `÷`,`×`, `¦`, `¤`, `⋇`, or `؉`. Do not combine special characters and wildcards within the same word. For example, use invoice re*ort instead of invoice-re*ort to ensure consistent results like invoice-report.\n- The FullText search property only supports the `==` operator, but can be negated.\n- When you run a query, make sure you include all the entity members that you want to retrieve. If you omit the members parameter, the response will return all the existing entity members (all properties, all relations, and so on). To ensure optimal performance, only request the members you actually need.\n- The API is configured to only load the related paths that are specified in a query. If you don't specify related path relations in your query, the response won't return any.\n## Authentication\nTo use the Querying API, you need:\n- The URL of your Content Hub server. You can get this from your Content Hub\n Administrator. Enter this URL in the {{server}} variable by hovering your mouse\n over the variable in the Try it pane and then clicking Edit.\n\n- An access token and the client ID. Both are sent with every request. You \n can create a token through the [Content Hub\n interface](https://doc.sitecore.com/ch/en/users/content-hub/create-an-oauth-client.html) \n or by [requesting one using the API\n itself](https://doc.sitecore.com/ch/en/developers/cloud-dev/oauth-tokens.html#grant-flows).\n",
"version": "v1.0",
"x-metadata": {
"product": "Content Hub",
"category": "Query and search"
},
"license": {
"name": "closed source",
"url": "https://www.sitecore.com"
}
},
"servers": [
{
"url": "https://{server}",
"variables": {
"server": {
"default": "your-server"
}
}
}
],
"security": [
{
"OAuth2.0": []
}
],
"tags": [
{
"name": "Querying",
"description": "The Querying API is responsible for fetching multiple pages of results sequentially. "
}
],
"paths": {
"/api/entities/scroll": {
"get": {
"tags": [
"Querying"
],
"summary": "Retrieve entities using a scroll-based query",
"description": "Lists entities using a scroll-based query for efficient large result set traversal.",
"operationId": "EntitiesByScroll1",
"parameters": [
{
"name": "query",
"in": "query",
"description": "The query string, for example, `Definition.Name == 'M.Asset'`.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "identifier",
"in": "query",
"description": "The scroll token used to fetch the next page of results, for example, `DXF1ZXJ5QW`.",
"schema": {
"type": "string"
}
},
{
"name": "take",
"in": "query",
"description": "Number of entities to retrieve, for example, `25`. The maximum is 100.",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "members",
"in": "query",
"description": "Comma-separated list of members to retrieve, for example, `Title,Filename`.",
"schema": {
"type": "string"
}
},
{
"name": "renditions",
"in": "query",
"description": "Comma-separated list of renditions to retrieve, for example, `Preview,Thumbnail`.",
"schema": {
"type": "string"
}
},
{
"name": "culture",
"in": "query",
"description": "The culture code of the user, for example, `en-US`.",
"schema": {
"type": "object"
}
},
{
"name": "sort",
"in": "query",
"description": "Sort field, for example, `created_on`.",
"schema": {
"type": "string"
}
},
{
"name": "order",
"in": "query",
"description": "Sort order, for example, `desc`.",
"schema": {
"type": "string"
}
},
{
"name": "sortCulture",
"in": "query",
"description": "Used for sorting operations, affecting the order of strings based on language-specific rules, for example, `en-US`.",
"schema": {
"type": "object"
}
},
{
"name": "nestedRelations",
"in": "query",
"description": "Nested relations to retrieve, for example, `Children,Parent`.",
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EntityCollectionResource"
}
}
}
},
"400": {
"description": "Request not valid"
},
"401": {
"description": "Unauthorized request or invalid access token"
}
},
"security": [
{
"OAuth2.0": []
}
]
}
},
"/api/entities/searchAfter": {
"get": {
"tags": [
"Querying"
],
"summary": "Retrieve entities using a search query",
"description": "Lists entities that match the criteria. This endpoint supports sorted pagination using the `search-after` property.",
"operationId": "EntitiesBySearchAfter",
"parameters": [
{
"name": "query",
"in": "query",
"description": "The search query, for example, `Definition.Name == 'M.Asset'`.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "take",
"in": "query",
"description": "Number of entities to retrieve, for example, `25`. The maximum is 100.",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "members",
"in": "query",
"description": "Comma-separated list of members to retrieve, for example, `Title,Filename`.",
"schema": {
"type": "string"
}
},
{
"name": "renditions",
"in": "query",
"description": "Comma-separated list of renditions to retrieve, for example, `Preview,Thumbnail`.",
"schema": {
"type": "string"
}
},
{
"name": "culture",
"in": "query",
"description": "The culture code of the user, for example, `en-US`.",
"schema": {
"type": "object"
}
},
{
"name": "sort",
"in": "query",
"description": "Sort field, for example, `created_on`.",
"schema": {
"type": "string"
}
},
{
"name": "order",
"in": "query",
"description": "Sort order, for example, `desc`.",
"schema": {
"type": "string"
}
},
{
"name": "sortCulture",
"in": "query",
"description": "Used for sorting operations, affecting the order of strings based on language-specific rules, for example, `en-US`.",
"schema": {
"type": "object"
}
},
{
"name": "searchAfter",
"in": "query",
"description": "To retrieve the next page of results using a set of sort values from the previous results. For example, if you make a request and receive 100 results, ending with `entity_id_1`, your subsequent query can include `search_after=entity_id_1` to fetch the next page.",
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
},
{
"name": "nestedRelations",
"in": "query",
"description": "Nested relations to retrieve, for example, `Children,Parent`.",
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EntityCollectionResource"
}
}
}
},
"400": {
"description": "Request not valid"
},
"401": {
"description": "Unauthorized request or invalid access token"
}
},
"security": [
{
"OAuth2.0": []
}
]
}
},
"/api/entities/query/{query}": {
"get": {
"tags": [
"Querying"
],
"summary": "Retrieve entities using a route-based query string",
"description": "Lists entities that match the query using a route-based query string, for example, `/api/entities/query/Definition.Name=='M.Asset'`.",
"operationId": "EntitiesByQuery",
"parameters": [
{
"name": "query",
"in": "path",
"description": "The query string, for example, `Definition.Name == 'M.Asset'`.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "skip",
"in": "query",
"description": "The number of items to skip before retrieving results, for example, `0`.",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "take",
"in": "query",
"description": "The number of items to retrieve, for example, `25`. The maximum is 100.",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "members",
"in": "query",
"description": "Comma-separated list of members to retrieve, for example, `Title,Filename`.",
"schema": {
"type": "string"
}
},
{
"name": "renditions",
"in": "query",
"description": "Comma-separated list of renditions to retrieve, for example, `Preview,Thumbnail`.",
"schema": {
"type": "string"
}
},
{
"name": "culture",
"in": "query",
"description": "Culture for the results, for example, `en-US`.",
"schema": {
"type": "object"
}
},
{
"name": "sort",
"in": "query",
"description": "Sort field, for example, `created_on`.",
"schema": {
"type": "string"
}
},
{
"name": "order",
"in": "query",
"description": "Sort order, for example, `desc`.",
"schema": {
"type": "string"
}
},
{
"name": "sortCulture",
"in": "query",
"description": "Culture for sorting, for example, `en-US`.",
"schema": {
"type": "object"
}
},
{
"name": "nestedRelations",
"in": "query",
"description": "Nested relations to retrieve, for example, `Children,Parent`.",
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EntityCollectionResource"
}
}
}
},
"400": {
"description": "Request not valid"
},
"401": {
"description": "Unauthorized request or invalid access token"
}
},
"security": [
{
"OAuth2.0": []
}
]
}
},
"/api/entities/query": {
"get": {
"tags": [
"Querying"
],
"summary": "Retrieve entities using a parameter-based query string",
"description": "Lists entities that match the query using a parameter-based query string, for example, `/api/entities/query?query=Definition.Name=='M.Asset'`.",
"operationId": "EntitiesByQueryParam",
"parameters": [
{
"name": "query",
"in": "query",
"description": "The query string, for example, `Definition.Name == 'M.Asset'`.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "skip",
"in": "query",
"description": "Number of items to skip, for example, `0`.",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "take",
"in": "query",
"description": "Number of items to retrieve. maximum is 100, for example, `25`.",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "members",
"in": "query",
"description": "Comma-separated list of members to retrieve, for example, `Title,Filename`.",
"schema": {
"type": "string"
}
},
{
"name": "renditions",
"in": "query",
"description": "Comma-separated list of renditions to retrieve, for example, `Preview,Thumbnail`.",
"schema": {
"type": "string"
}
},
{
"name": "culture",
"in": "query",
"description": "Culture for the results, for example, `en-US`.",
"schema": {
"type": "object"
}
},
{
"name": "sort",
"in": "query",
"description": "Sort field, for example, `created_on`.",
"schema": {
"type": "string"
}
},
{
"name": "order",
"in": "query",
"description": "Sort order, for example, `desc`.",
"schema": {
"type": "string"
}
},
{
"name": "sortCulture",
"in": "query",
"description": "Culture for sorting, for example, `en-US`.",
"schema": {
"type": "string"
}
},
{
"name": "permissionsToLoad",
"in": "query",
"description": "Comma-separated list of permissions to load, for example, `Read,Write`.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EntityCollectionResource"
}
}
}
},
"400": {
"description": "Request not valid"
},
"401": {
"description": "Unauthorized request or invalid access token"
}
},
"security": [
{
"OAuth2.0": []
}
]
}
}
},
"components": {
"schemas": {
"EntityCollectionResource": {
"type": "object",
"properties": {
"last_hit_data": {
"type": "array",
"items": {
"type": "string"
},
"description": "The last returned hits, which are used to fetch the next page of results.",
"nullable": true
},
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EntityResource"
},
"description": "Gets or sets the list of items.",
"nullable": true
},
"total_items": {
"type": "integer",
"description": "Gets or sets the total number of items.",
"format": "int64",
"nullable": true
},
"returned_items": {
"type": "integer",
"description": "Gets or sets the number of returned items.",
"format": "int64",
"nullable": true
},
"offset": {
"type": "integer",
"description": "Gets or sets the offset of the items.",
"format": "int32",
"nullable": true
},
"next": {
"$ref": "#/components/schemas/Link"
},
"previous": {
"$ref": "#/components/schemas/Link"
},
"identifier": {
"type": "string",
"description": "Gets or sets the identifier of the resource.",
"nullable": true
},
"self": {
"$ref": "#/components/schemas/Link"
}
},
"additionalProperties": {},
"description": "Collection of entities resulted of a query"
},
"EntityResource": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "The ID for the entity, for example `39752`.",
"format": "int64"
},
"identifier": {
"type": "string",
"description": "The identifier for the entity.",
"nullable": true
},
"cultures": {
"type": "array",
"items": {
"type": "string"
},
"description": "The cultures associated with the entity, for example `en-US`.",
"nullable": true
},
"properties": {
"type": "object",
"additionalProperties": {
"type": "object",
"nullable": true
},
"description": "The properties of the entity.",
"nullable": true
},
"relations": {
"type": "object",
"additionalProperties": {
"type": "object",
"nullable": true
},
"description": "The relations of the entity.",
"nullable": true
},
"created_by": {
"$ref": "#/components/schemas/Link"
},
"created_on": {
"type": "string",
"description": "The date and time when the entity was created.",
"format": "date-time"
},
"modified_by": {
"$ref": "#/components/schemas/Link"
},
"modified_on": {
"type": "string",
"description": "The date and time when the entity was last modified.",
"format": "date-time"
},
"locked_by": {
"$ref": "#/components/schemas/Link"
},
"locked_on": {
"type": "string",
"description": "The date and time when the entity was locked.",
"format": "date-time",
"nullable": true
},
"entitydefinition": {
"$ref": "#/components/schemas/Link"
},
"copy": {
"$ref": "#/components/schemas/Link"
},
"copyasync": {
"$ref": "#/components/schemas/Link"
},
"permissions": {
"$ref": "#/components/schemas/Link"
},
"requested_permissions": {
"type": "object",
"additionalProperties": {
"type": "boolean",
"nullable": true
},
"description": "The requested permissions with identification if a certain user has the permissions.",
"nullable": true
},
"lifecycle": {
"$ref": "#/components/schemas/Link"
},
"saved_selections": {
"$ref": "#/components/schemas/Link"
},
"roles": {
"$ref": "#/components/schemas/Link"
},
"annotations": {
"$ref": "#/components/schemas/Link"
},
"is_root_taxonomy_item": {
"type": "boolean",
"description": "Gets or sets a value indicating whether the entity is a root taxonomy item.",
"nullable": true
},
"is_path_root": {
"type": "boolean",
"description": "Gets or sets a value indicating whether the entity is a path root.",
"nullable": true
},
"inherits_security": {
"type": "boolean",
"description": "Gets or sets a value indicating whether the entity inherits security."
},
"is_system_owned": {
"type": "boolean",
"description": "Gets or sets a value indicating whether the entity is system owned."
},
"version": {
"type": "integer",
"description": "The version of the entity.",
"format": "int64"
},
"full": {
"$ref": "#/components/schemas/Link"
},
"modules": {
"type": "array",
"items": {
"type": "string"
},
"description": "The modules associated with the entity.",
"nullable": true
},
"self": {
"$ref": "#/components/schemas/Link"
}
},
"additionalProperties": {},
"description": "Represents an entity resource with various properties, relations, and metadata."
},
"FieldFilterRequestResource": {
"type": "object",
"properties": {
"name": {
"type": "string",
"nullable": true
},
"definition": {
"type": "string",
"nullable": true
},
"group_identifier": {
"type": "string",
"nullable": true
},
"operator": {
"$ref": "#/components/schemas/FilterOperator"
},
"values": {
"type": "array",
"items": {},
"nullable": true
},
"nested_values": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FieldFilterRequestResource"
},
"nullable": true
},
"hidden": {
"type": "boolean"
},
"type": {
"$ref": "#/components/schemas/RequestedFilterType"
},
"role": {
"type": "string",
"nullable": true
},
"visible": {
"type": "boolean"
},
"multi_select": {
"type": "boolean"
},
"selection_pool_specs": {
"$ref": "#/components/schemas/SelectionPoolSpecs"
}
},
"additionalProperties": false
},
"FieldFilterResponseResource": {
"type": "object",
"properties": {
"name": {
"type": "string",
"nullable": true
},
"label": {
"type": "string",
"nullable": true
},
"type": {
"type": "string",
"nullable": true
},
"values": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FieldFilterValueResponseResource"
},
"nullable": true
},
"nested_values": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FieldFilterResponseResource"
},
"nullable": true
},
"definition": {
"type": "string",
"nullable": true
},
"operator": {
"$ref": "#/components/schemas/FilterOperator"
},
"removeQuery": {
"type": "string",
"nullable": true
},
"dynamic": {
"type": "boolean"
},
"nested": {
"type": "boolean"
},
"group": {
"type": "string",
"nullable": true
},
"visible": {
"type": "boolean"
},
"multi_select": {
"type": "boolean"
}
},
"additionalProperties": false
},
"AggregationRequestResource": {
"type": "object",
"properties": {
"name": {
"type": "string",
"nullable": true
},
"field": {
"type": "string",
"nullable": true
},
"size": {
"type": "integer",
"format": "int32"
},
"datasource": {
"type": "string",
"nullable": true
},
"children": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AggregationRequestResource"
},
"nullable": true
},
"metric_option": {
"$ref": "#/components/schemas/MetricOptionRequestResource"
},
"type": {
"$ref": "#/components/schemas/RequestedAggregationType"
},
"interval": {
"$ref": "#/components/schemas/DateInterval"
},
"format": {
"type": "string",
"nullable": true
},
"include_missing": {
"type": "boolean"
}
},
"additionalProperties": false
},
"RequestedAggregationType": {
"enum": [
"Term",
"Metric",
"Date"
],
"type": "string"
},
"RequestedFilterType": {
"enum": [
"FieldFilter",
"InFilter",
"DynamicFilter",
"Nested",
"IdFilter",
"SelectionPoolFilter"
],
"type": "string"
},
"Link": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "Gets or sets the URI that points to the resource this link refers to.",
"nullable": true
},
"filename_properties": {
"type": "array",
"items": {
"type": "string"
},
"description": "Gets or sets the URI that points to the resource this link refers to.",
"nullable": true
},
"title": {
"type": "string",
"description": "Gets or sets the title that describes this link.",
"nullable": true
},
"templated": {
"type": "boolean",
"description": "Gets or sets a value indicating whether the contained URI is a template.",
"default": false
}
},
"additionalProperties": false,
"description": "Represents a link to a resource."
},
"MetricOptionRequestResource": {
"type": "object",
"properties": {
"name": {
"type": "string",
"nullable": true
},
"type": {
"type": "string",
"nullable": true
},
"field": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
},
"DateInterval": {
"enum": [
"second",
"minute",
"hour",
"day",
"week",
"month",
"quarter",
"year"
],
"type": "string"
},
"FieldFilterValueResponseResource": {
"type": "object",
"properties": {
"value": {
"type": "string",
"nullable": true
},
"label": {
"type": "string",
"nullable": true
},
"data": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
},
"FilterOperator": {
"enum": [
"None",
"Equals",
"LessThan",
"GreaterThan",
"Between",
"StartsWith",
"EndsWith",
"Contains",
"FacetEquals",
"DoesNotContain",
"DoesNotStartWith",
"DoesNotEndWith",
"LessThanOrEquals",
"GreaterThanOrEquals",
"DoesNotEqual",
"AnyOf",
"AllOf"
],
"type": "string"
},
"SelectionPoolSpecs": {
"type": "object",
"properties": {
"pool_id": {
"type": "integer",
"format": "int64"
},
"sub_pool_id": {
"type": "integer",
"format": "int64",
"nullable": true
}
},
"additionalProperties": false
}
},
"securitySchemes": {
"OAuth2.0": {
"type": "oauth2",
"flows": {
"clientCredentials": {
"tokenUrl": "/oauth/token",
"scopes": {}
},
"authorizationCode": {
"authorizationUrl": "/oauth/authorize",
"tokenUrl": "/oauth/token",
"scopes": {}
}
}
}
}
}
}