{
"openapi": "3.0.3",
"info": {
"title": "Selection API",
"description": "Use the Selection API to manage entity selections across selection pools.\n{% admonition type=\"info\" name=\"Note\" %}The maximum selection limit is 5000 entities. This limit is configurable through `CONTENT.SelectionPoolDefinition.MaxSelection`.{% /admonition %}\n## Authentication\nTo use this API, you need:\n- The URL of your Content Hub server. You can get this from your Content Hub Administrator. Enter this URL in the {{server}} variable by hovering your mouse over the variable in the Try it pane and then clicking Edit.\n- An access token and the client ID. Both are sent with every request. You can create a token through the [Content Hub interface](https://doc.sitecore.com/ch/en/users/content-hub/create-an-oauth-client.html) or by [requesting one using the API itself](https://doc.sitecore.com/ch/en/developers/cloud-dev/oauth-tokens.html#grant-flows).",
"version": "v1.0",
"license": {
"name": "closed source",
"url": "https://www.sitecore.com"
},
"x-metadata": {
"product": "Content Hub"
}
},
"servers": [
{
"url": "https://{server}",
"variables": {
"server": {
"default": "your-server"
}
}
}
],
"security": [
{
"OAuth2.0": []
}
],
"tags": [
{
"name": "Selection",
"description": "The Selection API lets you list, add, and remove entities from a selection."
}
],
"paths": {
"/api/selection/{selectionPool}/{definitionName}": {
"get": {
"operationId": "getSelection",
"tags": [
"Selection"
],
"summary": "Retrieve a selection by pool and definition",
"description": "Retrieves selection items for a given selection pool.\n\n{% admonition type=\"info\" name=\"Note\" %}\nAt least one of the following must be provided. If both are provided, the route parameter takes precedence:\n- `definitionName` (route parameter) - single definition name.\n- `definitionNames` (query parameter) - comma-separated list of definition names; for example, `GET /api/selection/AssetSelectionPool?definitionNames=M.Asset,M.Content`. \n{% /admonition %} \n",
"parameters": [
{
"name": "selectionPool",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Selection pool identifier"
},
{
"name": "definitionName",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "Single definition name"
},
{
"name": "definitionNames",
"in": "query",
"required": false,
"schema": {
"type": "string",
"example": "M.Asset,M.Content"
},
"description": "Comma-separated list of definition names"
},
{
"name": "subPoolId",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
},
"description": "Optional sub-pool identifier for scoped selections"
},
{
"name": "ignorePermissions",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"default": false
},
"description": "Skip permission calculation for faster response"
},
{
"name": "If-Modified-Since",
"in": "header",
"required": false,
"schema": {
"type": "string",
"format": "date-time"
},
"description": "Conditional request support (not currently implemented)"
}
],
"responses": {
"200": {
"description": "Selection retrieved successfully",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SelectionResponse"
},
"examples": {
"singleDefinition": {
"summary": "Single definition",
"value": {
"M.Asset": {
"items": [
1234,
5678,
9012
],
"permissions": [
"entity.read",
"entity.update"
],
"link": {
"href": "/api/entities/456",
"type": "application/json"
}
}
}
},
"multipleDefinitions": {
"summary": "Multiple definitions",
"value": {
"M.Asset": {
"items": [
1234,
5678
],
"permissions": [
"entity.read",
"entity.update"
],
"link": {
"href": "/api/entities/456",
"type": "application/json"
}
},
"M.Content": {
"items": [
3456
],
"permissions": [
"entity.read"
],
"link": {
"href": "/api/entities/456",
"type": "application/json"
}
}
}
}
}
}
}
},
"400": {
"description": "No definition name provided (either route or query parameter)"
},
"404": {
"description": "Selection pool identifier not found"
}
}
},
"delete": {
"operationId": "clearSelection",
"tags": [
"Selection"
],
"summary": "Clear a selection for a definition",
"description": "Removes all the entities for a specific definition from the selection. It does not delete the selection pool itself and does not affect other definitions in the same pool or other sub-pools.",
"parameters": [
{
"name": "selectionPool",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "definitionName",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "subPoolId",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "Selection cleared successfully"
},
"404": {
"description": "Selection pool not found"
}
}
}
},
"/api/selection": {
"post": {
"operationId": "createSelection",
"tags": [
"Selection"
],
"summary": "Create a selection",
"description": "Creates a selection using one of the following modes:\n\n- **Mode 1** Direct Entity IDs - use this mode when you know the specific entity IDs to add.\n- **Mode 2** Query-Based Selection - use this mode to select entities based on search criteria. The system executes the query and adds matching entities. \n\nQuery types are case-insensitive (for example, `BASIC`, `basic`, `Basic`). You can create queries that include various [parameters](https://doc.sitecore.com/ch/en/developers/cloud-dev/parameters.html).\n\n{% admonition type=\"info\" name=\"Note\" %}If `values` is provided and non-empty, it takes precedence and `query` is ignored.{% /admonition %}\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SelectionCreateRequest"
},
"examples": {
"directValues": {
"summary": "Direct entity IDs",
"value": {
"values": [
1234,
5678,
9012
],
"selectionPool": "AssetSelectionPool",
"definitionName": "M.Asset",
"subPoolId": 123,
"ignorePermissions": false
}
},
"queryBased": {
"summary": "Query-based selection",
"value": {
"type": "basic",
"query": "Parent('AssetMediaToAsset').id == 1029 AND Decimal('FileSize') gt 10",
"selectionPool": "SelectionPool.Create",
"definitionName": "M.Asset"
}
}
}
}
}
},
"responses": {
"201": {
"description": "Selection created",
"headers": {
"Location": {
"description": "URI to retrieve the selection",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SelectionResult"
}
}
}
},
"400": {
"description": "Invalid request"
},
"403": {
"description": "Selection capacity exceeded. Default limit is 5000 entities per selection. Validation considers (current items + items to add - items to remove).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Selection pool not found"
}
}
},
"patch": {
"operationId": "updateSelection",
"tags": [
"Selection"
],
"summary": "Update a selection",
"description": "Add or remove entities from a selection. {% admonition type=\"info\" name=\"Note\" %} This request can contain multiple commands and is used both to add and to remove entities from a selection using the PATCH object. {% /admonition %}",
"parameters": [
{
"name": "loadPermissions",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"default": false
},
"description": "Return updated permissions in response"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SelectionPatchRequest"
}
}
}
},
"responses": {
"200": {
"description": "Selection updated with permissions",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SelectionResult"
}
}
}
},
"204": {
"description": "Selection updated successfully"
},
"400": {
"description": "Invalid request body"
},
"403": {
"description": "Selection capacity exceeded. Default limit is 5000 entities per selection. Validation considers (current items + items to add - items to remove).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"404": {
"description": "Selection pool not found"
}
}
}
}
},
"components": {
"schemas": {
"SelectionResponse": {
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/SelectionResult"
}
},
"SelectionResult": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "integer"
}
},
"permissions": {
"type": "array",
"items": {
"type": "string"
}
},
"link": {
"$ref": "#/components/schemas/Link"
}
}
},
"Link": {
"type": "object",
"properties": {
"href": {
"type": "string"
},
"type": {
"type": "string"
}
}
},
"SelectionCreateRequest": {
"type": "object",
"properties": {
"values": {
"type": "array",
"items": {
"type": "integer"
}
},
"type": {
"type": "string",
"description": "Query type (e.g. \"basic\")"
},
"query": {
"type": "string"
},
"selectionPool": {
"type": "string"
},
"definitionName": {
"type": "string"
},
"subPoolId": {
"type": "integer",
"format": "int64"
},
"ignorePermissions": {
"type": "boolean",
"default": false
}
},
"required": [
"selectionPool"
]
},
"SelectionPatchRequest": {
"type": "object",
"required": [
"selectionPool",
"definitionName",
"patches"
],
"properties": {
"selectionPool": {
"type": "string"
},
"definitionName": {
"type": "string"
},
"subPoolId": {
"type": "integer",
"format": "int64"
},
"patches": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PatchOperation"
}
}
}
},
"PatchOperation": {
"type": "object",
"required": [
"operation",
"value"
],
"properties": {
"operation": {
"type": "string",
"enum": [
"Add",
"Remove"
]
},
"value": {
"type": "array",
"items": {
"type": "integer"
}
}
}
},
"ErrorResponse": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
},
"securitySchemes": {
"OAuth2.0": {
"type": "oauth2",
"flows": {
"authorizationCode": {
"authorizationUrl": "/oauth/authorize",
"tokenUrl": "/oauth/token",
"scopes": {}
}
}
}
}
}
}