{
"openapi": "3.0.1",
"info": {
"title": "Entity definitions API",
"description": "Use the Entity definitions API to manage entity definitions or retrieve all entities for a specific defintion.\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).",
"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": "Entity definitions",
"description": "Use these endpoints to manage entity definitions."
},
{
"name": "Entities",
"description": "Use this endpoint to retrieve all entities that match a specific entity definition."
}
],
"paths": {
"/api/entitydefinitions": {
"get": {
"tags": [
"Entity definitions"
],
"summary": "Retrieve all entity definitions",
"description": "Lists all entity definitions.",
"operationId": "EntityDefinitions",
"parameters": [
{
"name": "skip",
"in": "query",
"description": "Number of definitions to skip before retrieving results, for example, `1`.",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "take",
"in": "query",
"description": "Number of definitions to retrieve, for example, `10`. The maximum is 100.",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "filter",
"in": "query",
"description": "Additional filters to apply when retrieving definitions. Use `PropertyName==value` for property-based filtering (for example, `IsSystemOwned==true`), or a free-text value to search in definition names and labels (for example, `asset`).",
"schema": {
"type": "string"
}
},
{
"name": "definitionsToLoad",
"in": "query",
"description": "(Deprecated) Definition names to include in the retrieved definitions. Use definitionsToLoadByName instead.",
"schema": {
"type": "string"
},
"deprecated": true
},
{
"name": "definitionsToLoadByName",
"in": "query",
"description": "Definition names to include in the retrieved definitions, for example, `M.Asset, M.Project.Task`.",
"schema": {
"type": "string"
}
},
{
"name": "definitionsToLoadById",
"in": "query",
"description": "Definition IDs to include in the retrieved definitions, for example, `10`, `20`.",
"schema": {
"type": "string"
}
},
{
"name": "viewMode",
"in": "query",
"description": "The level of detail to include in the returned entity definitions. Use `Basic` or `Extended`.",
"schema": {
"$ref": "#/components/schemas/ViewMode"
}
},
{
"name": "loadPermissions",
"in": "query",
"description": "Whether to include all permissions the user has on the entity definition, for example, `true` or `false`.",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "includeConditionalMembers",
"in": "query",
"description": "Whether to include conditional members in the result, for example, `true` or `false`.",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "excludeTaxonomyDefinitions",
"in": "query",
"description": "Whether to exclude taxonomy definitions from the result, for example, `true` or `false`.",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "excludeSystemOwnedDefinitions",
"in": "query",
"description": "Whether to exclude system-owned definitions from the result, for example, `true` or `false`.",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "excludeLightDefinitions",
"in": "query",
"description": "Whether to exclude light entity definitions from the result, for example, `true` or `false`.\n Light entity definitions contain only basic information.",
"schema": {
"$ref": "#/components/schemas/ExcludeLightDefinition"
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Resource"
}
}
}
},
"400": {
"description": "Request or entity definition is not valid (for example, less than or equal to zero or does not exist), or at least one culture is null"
},
"401": {
"description": "Unauthorized request or invalid access token"
},
"404": {
"description": "Entity not found or user not authorized"
}
},
"security": [
{
"OAuth2.0": []
}
]
}
},
"/api/entitydefinitions/{name}": {
"get": {
"tags": [
"Entity definitions"
],
"summary": "Retrieve an entity definition by name",
"description": "Retrieves an entity definition using its name, with options to include conditional members, load permissions, and exclude light entity definitions.",
"operationId": "EntityDefinitionByName",
"parameters": [
{
"name": "name",
"in": "path",
"description": "The definition name (string), for example, `M.Asset`.",
"required": true,
"schema": {
"type": "string",
"pattern": "^[A-Za-z_][A-Za-z0-9_.-]*$"
}
},
{
"name": "If-Modified-Since",
"in": "header",
"description": "The date and time after which to check for modifications, for example, `2023-01-01T00:00:00Z`.",
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "includeConditionalMembers",
"in": "query",
"description": "Whether to include conditional members, for example, `true` or `false`.",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "loadPermissions",
"in": "query",
"description": "Whether to load permissions, for example, `true` or `false`.",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "excludeLightDefinitions",
"in": "query",
"description": "Whether to exclude light entity definitions, for example, `true` or `false`.",
"schema": {
"$ref": "#/components/schemas/ExcludeLightDefinition"
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EntityDefinitionResource"
}
}
}
},
"400": {
"description": "Request is not valid (for example, invalid parameters)"
},
"401": {
"description": "Unauthorized request or invalid access token"
},
"404": {
"description": "Entity definition not found or user not authorized"
}
},
"security": [
{
"OAuth2.0": []
}
]
},
"post": {
"tags": [
"Entity definitions"
],
"summary": "Create an entity definition",
"description": "Creates a new entity definition with the provided details.",
"operationId": "AddEntityDefinition",
"parameters": [
{
"name": "name",
"in": "path",
"description": "The definition name (string), for example, `M.Asset`.",
"required": true,
"schema": {
"type": "string",
"pattern": "^[A-Za-z_][A-Za-z0-9_.-]*$"
}
}
],
"requestBody": {
"required": true,
"description": "The details of the entity definition to be created, for example, an instance of `Stylelabs.M.Base.Web.Api.Models.EntityDefinitionResource` containing the name, member groups, and other properties.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EntityDefinitionResource"
}
}
}
},
"responses": {
"200": {
"description": "Successful operation"
},
"201": {
"description": "The entity definition was successfully created"
},
"400": {
"description": "The request is invalid (for example, the resource is `null` or contains invalid data)"
},
"401": {
"description": "Unauthorized request or invalid access token"
},
"403": {
"description": "The user does not have the required privileges to create the entity definition"
},
"404": {
"description": "Entity not found or user not authorized"
}
},
"security": [
{
"OAuth2.0": []
}
]
},
"put": {
"tags": [
"Entity definitions"
],
"summary": "Update an entity definition",
"description": "Updates an entity definition with the details provided.",
"operationId": "UpdateEntityDefinition",
"parameters": [
{
"name": "name",
"in": "path",
"description": "The name of the entity definition to update, for example, `M.Asset`.",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "The updated details of the entity definition, for example, an instance of `Stylelabs.M.Base.Web.Api.Models.EntityDefinitionResource` containing the updated properties.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EntityDefinitionResource"
}
}
}
},
"responses": {
"200": {
"description": "The entity definition was successfully updated"
},
"400": {
"description": "The request is invalid (for example, the resource is `null` or contains invalid data)"
},
"401": {
"description": "Unauthorized request or invalid access token"
},
"403": {
"description": "The user does not have the required privileges to update the entity definition"
},
"404": {
"description": "The entity definition with the specified name was not found"
}
},
"security": [
{
"OAuth2.0": []
}
]
},
"delete": {
"tags": [
"Entity definitions"
],
"summary": "Delete an entity definition by name",
"description": "Removes the entity definition with a specific name.",
"operationId": "DeleteEntityDefinitionByName",
"parameters": [
{
"name": "name",
"in": "path",
"description": "The name of the entity definition to delete, for example, `M.Asset`.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "The entity definition was successfully deleted"
},
"401": {
"description": "Unauthorized request or invalid access token"
},
"404": {
"description": "The entity definition with the specified name was not found"
}
},
"security": [
{
"OAuth2.0": []
}
]
}
},
"/api/entitydefinitions/{name}/entities": {
"get": {
"tags": [
"Entities"
],
"summary": "Retrieve all entities for a specific entity definition",
"description": "Lists all entities that match a specific entity definition, with support for filtering, pagination, and localization.",
"operationId": "EntitiesByDefinition",
"parameters": [
{
"name": "name",
"in": "path",
"description": "Entity definition name to filter the entities, for example, `abc`.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "skip",
"in": "query",
"description": "Number of entities to skip before retrieving results, for example, `1`.",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "take",
"in": "query",
"description": "Number of entities to retrieve, for example, `1`.",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "culture",
"in": "query",
"description": "User culture in which to load the entities, for example, `en-US`.",
"schema": {
"type": "string"
}
},
{
"name": "filter",
"in": "query",
"description": "Additional filters to apply when retrieving entities, for example, `status:active AND type:image`.",
"schema": {
"type": "string"
}
},
{
"name": "groups",
"in": "query",
"description": "Member groups to include in the retrieved entities, for example, `DefaultGroup,SystemGroup`.",
"schema": {
"type": "string"
}
},
{
"name": "members",
"in": "query",
"description": "Members to include in the retrieved entities, for example, `TestStringProperty,SystemOwnedStringProperty`.",
"schema": {
"type": "string"
}
},
{
"name": "nestedRelations",
"in": "query",
"description": "Related entities to include fully loaded in the result, for example, `ParentRelation,ChildRelation`.",
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
],
"responses": {
"200": {
"description": "Successful operation.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EntityCollectionResource"
}
}
}
},
"400": {
"description": "Request or Entity definition is not valid (for example, less than or equal to zero or does not exist), or at least one culture is null."
},
"401": {
"description": "Unauthorized request."
},
"404": {
"description": "Entity not found or user not authorized."
}
},
"security": [
{
"OAuth2.0": []
}
]
}
},
"/api/entitydefinitions/name/{name}": {
"get": {
"tags": [
"Entity definitions"
],
"summary": "Retrieve an entity definition by name (V2)",
"description": "Retrieves an entity definition by its name (V2 endpoint).",
"operationId": "EntityDefinitionByNameV2",
"parameters": [
{
"name": "name",
"in": "path",
"description": "The definition name, for example, `M.Asset`.",
"required": true,
"schema": {
"type": "string",
"pattern": "^[A-Za-z_][A-Za-z0-9_.-]*$"
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EntityDefinitionResource"
}
}
}
},
"401": {
"description": "Unauthorized request or invalid access token"
},
"404": {
"description": "Entity definition not found or user not authorized"
}
},
"security": [
{
"OAuth2.0": []
}
]
}
},
"/api/entitydefinitions/{id}": {
"get": {
"tags": [
"Entity definitions"
],
"summary": "Retrieve an entity definition by ID",
"description": "Retrieves an entity definition by its ID, with options to include conditional members, load permissions, and exclude light entity definitions.",
"operationId": "EntityDefinitionById",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The unique identifier of the entity definition, for example, `12345`.",
"required": true,
"schema": {
"type": "integer",
"format": "int64",
"pattern": "^\\d+$"
}
},
{
"name": "If-Modified-Since",
"in": "header",
"description": "The date and time to check for modifications since, for example, `2023-01-01T00:00:00Z`.",
"schema": {
"type": "string",
"format": "date-time"
}
},
{
"name": "includeConditionalMembers",
"in": "query",
"description": "Whether to include conditional members, for example, `true` or `false`.",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "loadPermissions",
"in": "query",
"description": "Whether to load permissions, for example, `true` or `false`.",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "excludeLightDefinitions",
"in": "query",
"description": "Whether to exclude light entity definitions, for example, `true` or `false`.",
"schema": {
"$ref": "#/components/schemas/ExcludeLightDefinition"
}
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EntityDefinitionResource"
}
}
}
},
"400": {
"description": "Request is not valid (for example, invalid parameters)"
},
"401": {
"description": "Unauthorized request or invalid access token"
},
"404": {
"description": "Entity definition not found or user not authorized"
}
},
"security": [
{
"OAuth2.0": []
}
]
},
"delete": {
"tags": [
"Entity definitions"
],
"summary": "Delete an entity definition by ID",
"description": "Removes the entity definition identified by the given ID.",
"operationId": "DeleteEntityDefinitionById",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The ID of the entity definition to delete, for example, `1`.",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
"responses": {
"200": {
"description": "The entity definition was successfully deleted"
},
"401": {
"description": "Unauthorized request or invalid access token"
},
"404": {
"description": "The entity definition with the specified ID was not found"
}
},
"security": [
{
"OAuth2.0": []
}
]
}
},
"/api/entitydefinitions/{name}/impact": {
"post": {
"tags": [
"Entity definitions"
],
"summary": "Calculate the impact of changes to an entity definition",
"description": "Submits a modified version of an entity definition and returns an analysis of the impact those changes would have compared to the current definition. Used to preview the effects of schema changes before applying them.",
"operationId": "CalculateGraphImpact",
"parameters": [
{
"name": "name",
"in": "path",
"description": "The name of the entity definition to analyze, for example, `M.Asset`.",
"required": true,
"schema": {
"type": "string",
"pattern": "^[A-Za-z_][A-Za-z0-9_.-]*$"
}
}
],
"requestBody": {
"description": "The updated details of the entity definition to compare against the original, for example, an instance of Stylelabs.M.Base.Web.Api.Models.EntityDefinitionResource containing the proposed changes.",
"content": {
"application/json-patch+json": {
"schema": {
"$ref": "#/components/schemas/EntityDefinitionResource"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/EntityDefinitionResource"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/EntityDefinitionResource"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/EntityDefinitionResource"
}
}
}
},
"responses": {
"200": {
"description": "The impact analysis was successfully calculated and returned"
},
"400": {
"description": "The request is invalid (for example, the resource is null or contains invalid data)"
},
"401": {
"description": "Unauthorized request or invalid access token"
},
"404": {
"description": "The entity definition with the specified name was not found"
}
}
}
}
},
"components": {
"schemas": {
"EntityDefinitionResource": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"name": {
"type": "string",
"nullable": true
},
"modified_on": {
"type": "string",
"format": "date-time"
},
"created_on": {
"type": "string",
"format": "date-time"
},
"display_template": {
"type": "string",
"nullable": true
},
"is_taxonomy_item_definition": {
"type": "boolean"
},
"is_path_enabled_definition": {
"type": "boolean"
},
"is_manual_sorting_allowed": {
"type": "boolean"
},
"is_system_owned": {
"type": "boolean"
},
"is_built_in": {
"type": "boolean"
},
"is_light": {
"type": "boolean",
"description": "Gets a value indicating whether the entity definition is a light definition.",
"readOnly": true
},
"labels": {
"type": "object",
"additionalProperties": {
"type": "string",
"nullable": true
},
"nullable": true
},
"member_groups": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MemberGroup"
},
"nullable": true
},
"entities": {
"$ref": "#/components/schemas/Link"
},
"related_paths": {
"$ref": "#/components/schemas/Link"
},
"modified_by": {
"$ref": "#/components/schemas/Link"
},
"created_by": {
"$ref": "#/components/schemas/Link"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
},
"description": "All available permissions for the entity definition",
"nullable": true
},
"self": {
"$ref": "#/components/schemas/Link"
}
},
"additionalProperties": false
},
"MemberGroup": {
"type": "object",
"properties": {
"name": {
"type": "string",
"nullable": true
},
"content_group": {
"type": "string",
"nullable": true
},
"labels": {
"type": "object",
"additionalProperties": {
"type": "string",
"nullable": true
},
"nullable": true
},
"members": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MemberDefinition"
},
"nullable": true
},
"is_system_owned": {
"type": "boolean"
},
"is_conditional": {
"type": "boolean"
},
"conditions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MemberCondition"
},
"nullable": true
},
"is_secured": {
"type": "boolean",
"nullable": true
},
"can_write": {
"type": "boolean",
"nullable": true
}
},
"additionalProperties": false
},
"MemberDefinition": {
"type": "object",
"properties": {
"name": {
"type": "string",
"nullable": true
},
"labels": {
"type": "object",
"additionalProperties": {
"type": "string",
"nullable": true
},
"nullable": true
},
"helptext": {
"type": "object",
"additionalProperties": {
"type": "string",
"nullable": true
},
"nullable": true
},
"is_conditional": {
"type": "boolean"
},
"conditions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MemberCondition"
},
"nullable": true
},
"can_trigger_conditional_members": {
"type": "boolean"
},
"is_system_owned": {
"type": "boolean"
},
"is_secured": {
"type": "boolean",
"nullable": true
},
"can_write": {
"type": "boolean",
"nullable": true
},
"allow_updates": {
"type": "boolean",
"nullable": true
}
},
"additionalProperties": false
},
"MemberCondition": {
"type": "object",
"properties": {
"member": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
},
"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."
},
"ExcludeLightDefinition": {
"enum": [
"True",
"False",
"UserSecurity"
],
"type": "string",
"description": "Enum representing the exclusion of light definitions."
},
"ViewMode": {
"enum": [
"Basic",
"Extended"
],
"type": "string"
},
"Resource": {
"type": "object",
"properties": {
"self": {
"$ref": "#/components/schemas/Link"
}
},
"additionalProperties": false,
"description": "Represents a resource with a self-link and a modified date."
},
"EntityCollectionResource": {
"type": "object",
"description": "Collection of entities resulted of a query",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EntityResource"
}
},
"total": {
"type": "integer",
"format": "int32"
},
"self": {
"$ref": "#/components/schemas/Link"
}
},
"additionalProperties": false
},
"EntityResource": {
"type": "object",
"description": "Represents an entity resource with various properties, relations and metadata.",
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"name": {
"type": "string"
}
},
"additionalProperties": true
}
},
"securitySchemes": {
"OAuth2.0": {
"type": "oauth2",
"flows": {
"clientCredentials": {
"tokenUrl": "/oauth/token",
"scopes": {}
},
"authorizationCode": {
"authorizationUrl": "/oauth/authorize",
"tokenUrl": "/oauth/token",
"scopes": {}
}
}
}
}
}
}