{
"openapi": "3.0.1",
"info": {
"title": "Search API",
"description": "\nUse the Search API to execute a search query, retrieve facet values, remove search filters or retrieve a facet query. The Search API applies a [default search configuration](https://doc.sitecore.com/ch/en/developers/cloud-dev/configuration.html) to all searches, using default values and filters. The search endpoint exposes a number of search types, including full-text search and faceted search as well as visual search. It supports various query operators as well as [visual search parameters](https://doc.sitecore.com/ch/en/developers/cloud-dev/supported-visual-search-parameters.html).\n## Authentication\nTo use this 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\n{% admonition type=\"info\" name=\"Note\" %}\n The Search API does not use the `Location` header, as there is no support for the creation of a resource.\n{% /admonition %}\n",
"version": "v1.0",
"x-metadata": {
"product": "Content Hub"
},
"license": {
"name": "closed source",
"url": "https://www.sitecore.com"
}
},
"servers": [
{
"url": "https://{server}",
"variables": {
"server": {
"default": "your-server"
}
}
}
],
"security": [
{
"OAuth2.0": []
}
],
"tags": [
{
"name": "Search",
"description": "Use the Search API for full-text searches, faceted searches, and visual searches."
}
],
"paths": {
"/api/search": {
"post": {
"tags": [
"Search"
],
"summary": "Execute a complex search query",
"description": "Executes a search query and returns the search results. Use POST when the query parameters exceed the URL length limitations. Parameters are passed in a resource instead of URL arguments.",
"operationId": "SearchActions",
"requestBody": {
"description": "Resource containing all the parameters needed for a search.",
"content": {
"application/json-patch+json": {
"schema": {
"$ref": "#/components/schemas/SearchRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/SearchRequest"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/SearchRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Resource"
}
}
}
},
"400": {
"description": "Request is not valid"
},
"401": {
"description": "Unauthorized request or invalid access token"
}
},
"security": [
{
"OAuth2.0": []
}
]
},
"get": {
"tags": [
"Search"
],
"summary": "Execute a simple search query",
"description": "Executes a search query and returns the search results. Use GET for simple queries that fit within URL length limits, for example, to retrieve the current state of a resource, including its content.",
"operationId": "GetSearchActions",
"parameters": [
{
"name": "query",
"in": "query",
"description": "This parameter is generated automatically by Content Hub and contains the information required to restore a search state. Do not create or modify it manually.",
"schema": {
"type": "string",
"default": ""
}
},
{
"name": "skip",
"in": "query",
"description": "Number of results to skip, for example, `0`.",
"schema": {
"type": "integer",
"format": "int32",
"default": 0
}
},
{
"name": "take",
"in": "query",
"description": "Number of results to return, for example, `10`.",
"schema": {
"type": "integer",
"format": "int32",
"default": 0
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Resource"
}
}
}
},
"400": {
"description": "Request is not valid"
},
"401": {
"description": "Unauthorized request or invalid access token"
}
},
"security": [
{
"OAuth2.0": []
}
]
}
},
"/api/search/allfacets": {
"post": {
"tags": [
"Search"
],
"summary": "Retrieve all facet values",
"description": "Retrieves all values for a specific facet field, including translations and selection state.",
"operationId": "PostAllFacets",
"requestBody": {
"description": "Facet request resource.",
"content": {
"application/json-patch+json": {
"schema": {
"$ref": "#/components/schemas/AllFacetsRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/AllFacetsRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/AllFacetsRequest"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/AllFacetsRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Resource"
}
}
}
},
"400": {
"description": "Request is not valid"
},
"401": {
"description": "Unauthorized request or invalid access token"
}
},
"security": [
{
"OAuth2.0": []
}
]
}
},
"/api/search/remove": {
"post": {
"tags": [
"Search"
],
"summary": "Remove search filters",
"description": "Removes the specified filters from the search query and returns the updated query.",
"operationId": "SearchRemoveFilters",
"requestBody": {
"description": "Remove filters request resource.",
"content": {
"application/json-patch+json": {
"schema": {
"$ref": "#/components/schemas/RemoveFiltersRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RemoveFiltersRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RemoveFiltersRequest"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RemoveFiltersRequest"
}
}
}
},
"responses": {
"200": {
"description": "Filters successfully removed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RemoveFiltersResponse"
}
}
}
},
"401": {
"description": "Unauthorized request or invalid access token"
}
},
"security": [
{
"OAuth2.0": []
}
]
}
},
"/api/search/{id}": {
"get": {
"tags": [
"Search"
],
"summary": "Retrieve a facet query for an entity",
"description": "Retrieves a serialized facet query that can be used to filter search results to items related to a specific entity.",
"operationId": "getFacetQueryById",
"parameters": [
{
"name": "id",
"in": "path",
"description": "Entity ID or identifier, for example, `12345` or `entity`.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FacetQueryResponse"
}
}
}
},
"400": {
"description": "Request is not valid"
},
"401": {
"description": "Unauthorized request or invalid access token"
}
},
"security": [
{
"OAuth2.0": []
}
]
}
}
},
"components": {
"schemas": {
"SearchRequest": {
"type": "object",
"properties": {
"query": {
"type": "string",
"nullable": true,
"description": "This parameter is generated automatically by Content Hub and contains the information required to restore a search state. Do not create or modify it manually."
},
"skip": {
"type": "integer",
"format": "int32",
"description": "The number of results to skip, for example, `0`."
},
"take": {
"type": "integer",
"format": "int32",
"description": "The number of results to return, for example, `10`."
},
"filters": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FieldFilterRequestResource"
},
"nullable": true,
"description": "The filters to apply to the search query. Each filter is a `FieldFilterRequestResource` object."
},
"sorting": {
"$ref": "#/components/schemas/SortingRequestResource",
"description": "The sorting to apply to the search query. This is a `SortingRequestResource` object that specifies the field and order (ascending or descending)."
},
"aggregations": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AggregationRequestResource"
},
"nullable": true,
"description": "The aggregations to apply to the search query. Each aggregation is an `AggregationRequestResource` object."
},
"fulltext": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true,
"description": "The full-text search terms to apply to the query. This is an array of strings, where each string is a term to search for."
},
"fields": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true,
"description": "The fields to include in the search results. This is an array of strings, where each string is a field name."
},
"culture": {
"type": "string",
"nullable": true,
"description": "The culture to use for the search, for example, `en-US` or `fr-FR`."
},
"view": {
"type": "string",
"nullable": true,
"description": "The view to use for the search (that is, the view name)."
},
"component": {
"type": "integer",
"format": "int64",
"description": "The component ID to use for the search, for example, `1`."
},
"logical_grouping_template": {
"type": "string",
"nullable": true,
"description": "The logical grouping template to use for the search."
},
"defaults": {
"type": "string",
"nullable": true,
"description": "The default values to use for the search."
},
"configuration_category": {
"type": "string",
"nullable": true,
"description": "The configuration category to use for the search."
},
"customSorting": {
"type": "object",
"additionalProperties": {
"type": "integer",
"format": "int32"
},
"nullable": true,
"description": "Custom sorting options for the search. This is an object where keys are field names and values are integers representing the sort order."
},
"saved_selection": {
"type": "integer",
"format": "int64",
"description": "The ID of a saved selection to use for the search."
},
"calendarStartDate": {
"type": "string",
"format": "date-time",
"description": "The start date for the calendar filter. This is a string in date-time format, for example, `2023-01-01T00:00:00Z`."
},
"calendarStopDate": {
"type": "string",
"format": "date-time",
"description": "The stop date for the calendar filter. This is a string in date-time format, for example, `2023-12-31T23:59:59Z`."
},
"selection_pool": {
"$ref": "#/components/schemas/SelectionPoolFilterResource",
"description": "The selection pool to use for the search. This is a `SelectionPoolFilterResource` object that specifies the selection pool and optional sub-pool ID."
},
"nested_relations": {
"type": "array",
"items": {
"$ref": "#/components/schemas/NestedRelationInfo"
},
"nullable": true,
"description": "The nested relations to include in the search. Each item is a `NestedRelationInfo` object that specifies the relation, role, and properties to include."
},
"group": {
"$ref": "#/components/schemas/SearchGroupRequestResource",
"description": "The grouping information for the search. This is a `SearchGroupRequestResource` object that specifies how to group the search results."
},
"is_initial_request": {
"type": "boolean",
"description": "Indicates whether this is the initial request for the search. This is a boolean value, where `true` means it is the initial request and `false` means it is a subsequent request."
},
"containsUserFilters": {
"type": "boolean",
"readOnly": true,
"description": "Indicates whether the search query contains user-defined filters. This is a boolean value, where `true` means it contains user filters and `false` means it does not."
},
"take_user_settings": {
"type": "boolean",
"description": "Indicates whether to take user settings into account for the search. This is a boolean value, where `true` means user settings are taken into account and `false` means they are not."
},
"l10n": {
"type": "boolean",
"nullable": true,
"description": "Indicates whether to use localization for the search. This is a boolean value, where `true` means localization is used and `false` means it is not."
},
"visualSearch": {
"$ref": "#/components/schemas/VisualSearchRequestResource",
"description": "The visual search parameters to use for the search. This is a `VisualSearchRequestResource` object that specifies the image, color, text, and other parameters for visual search."
}
},
"additionalProperties": {}
},
"AllFacetsRequest": {
"type": "object",
"properties": {
"facetField": {
"type": "string",
"nullable": true,
"description": "The name of the facet field to retrieve values for."
},
"query": {
"type": "string",
"nullable": true,
"description": "This parameter is generated automatically by Content Hub and contains the information required to restore a search state. Do not create or modify it manually."
},
"searchConfigurationName": {
"type": "string",
"nullable": true,
"description": "The name of the search configuration to use for retrieving facet values."
},
"culture": {
"type": "string",
"nullable": true,
"description": "The culture to use for retrieving facet values, for example, `en-US` or `fr-FR`."
},
"component": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "The component ID to use when retrieving facet values."
},
"filters": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FieldFilterRequestResource"
},
"nullable": true,
"description": "The filters to apply to the facet values. Each filter is a `FieldFilterRequestResource` object that specifies the filter criteria."
},
"take_user_settings": {
"type": "boolean",
"description": "Indicates whether to take user settings into account for the facet values. This is a boolean value, where `true` means user settings are taken into account and `false` means they are not."
},
"l10n": {
"type": "boolean",
"nullable": true,
"description": "Indicates whether to use localization for the facet values. This is a boolean value, where `true` means localization is used and `false` means it is not."
}
},
"additionalProperties": false
},
"RemoveFiltersRequest": {
"type": "object",
"properties": {
"query": {
"type": "string",
"nullable": true,
"description": "This parameter is generated automatically by Content Hub and contains the information required to restore a search state. Do not create or modify it manually."
},
"filters": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true,
"description": "The list of filter names to remove from the search query. Each item is a string that represents the name of a filter to be removed."
}
},
"additionalProperties": false
},
"RemoveFiltersResponse": {
"type": "object",
"properties": {
"query": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
},
"FacetQueryResponse": {
"type": "object",
"properties": {
"query": {
"type": "string",
"nullable": true
},
"filters": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FieldFilterResponseResource"
},
"nullable": true
},
"self": {
"$ref": "#/components/schemas/Link"
}
},
"additionalProperties": false
},
"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
},
"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",
"NoneOf",
"Missing",
"Exists",
"Changed"
],
"type": "string"
},
"RequestedFilterType": {
"enum": [
"FieldFilter",
"InFilter",
"DynamicFilter",
"Nested",
"IdFilter",
"SelectionPoolFilter"
],
"type": "string"
},
"SelectionPoolSpecs": {
"type": "object",
"properties": {
"pool_id": {
"type": "integer",
"format": "int64"
},
"sub_pool_id": {
"type": "integer",
"format": "int64",
"nullable": true
}
},
"additionalProperties": false
},
"SortingRequestResource": {
"type": "object",
"properties": {
"field": {
"type": "string",
"nullable": true
},
"asc": {
"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
},
"MetricOptionRequestResource": {
"type": "object",
"properties": {
"name": {
"type": "string",
"nullable": true
},
"type": {
"type": "string",
"nullable": true
},
"field": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
},
"RequestedAggregationType": {
"enum": [
"Term",
"Metric",
"Date"
],
"type": "string"
},
"DateInterval": {
"enum": [
"second",
"minute",
"hour",
"day",
"week",
"month",
"quarter",
"year"
],
"type": "string"
},
"SelectionPoolFilterResource": {
"type": "object",
"properties": {
"selection_pool": {
"type": "string",
"nullable": true
},
"sub_pool_id": {
"type": "integer",
"format": "int64",
"nullable": true
},
"definitions": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true
}
},
"additionalProperties": false
},
"NestedRelationInfo": {
"type": "object",
"properties": {
"relation": {
"type": "string",
"nullable": true
},
"role": {
"$ref": "#/components/schemas/RelationRole"
},
"properties": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true
},
"renditions": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true
},
"limit": {
"type": "integer",
"format": "int32",
"nullable": true
}
},
"additionalProperties": false
},
"RelationRole": {
"enum": [
"Parent",
"Child"
],
"type": "string"
},
"SearchGroupRequestResource": {
"type": "object",
"properties": {
"row": {
"type": "string",
"nullable": true
},
"column": {
"type": "string",
"nullable": true
},
"rowDefinitionId": {
"type": "integer",
"format": "int64",
"nullable": true
},
"columnDefinitionId": {
"type": "integer",
"format": "int64",
"nullable": true
},
"result_count": {
"type": "integer",
"format": "int32"
}
},
"additionalProperties": false
},
"VisualSearchRequestResource": {
"type": "object",
"properties": {
"image": {
"type": "string",
"nullable": true
},
"color": {
"type": "string",
"nullable": true
},
"text": {
"type": "string",
"nullable": true
},
"type": {
"$ref": "#/components/schemas/VisualSearchType"
},
"imageEntityId": {
"type": "integer",
"format": "int64",
"nullable": true
},
"IsDeepSearch": {
"type": "boolean",
"nullable": true
}
},
"additionalProperties": false
},
"VisualSearchType": {
"enum": [
"vector",
"vector+text",
"text",
"vectorAndText",
"vectorOrText"
],
"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."
},
"Resource": {
"type": "object",
"properties": {
"self": {
"$ref": "#/components/schemas/Link"
}
},
"additionalProperties": false,
"description": "Represents a resource with a self-link and a modified date."
}
},
"securitySchemes": {
"OAuth2.0": {
"type": "oauth2",
"flows": {
"authorizationCode": {
"authorizationUrl": "/oauth/authorize",
"tokenUrl": "/oauth/token",
"scopes": {}
}
}
}
}
}
}