{ "openapi": "3.0.4", "info": { "title": "Components API", "description": "Use the SitecoreAI Components API to manage components, data sources, and component categories.\n\n This REST API lets you:\n\n - Manage components for a site, including its rendering parameters, and the editing controls that determine the appearance of the component in an editing interface such as the Page Builder.\n\n - Read and update data sources and read data source hierarchies for an environment.\n\n# Authorization\nTo authorize your requests, use environment automation client credentials and generate a JSON Web Token (JWT).\n\nNote: To create client credentials, you must be an [Organization Admin](https://doc.sitecore.com/portal/en/developers/sitecore-cloud-portal/roles.html) or Organization Owner.\n\n## Create an automation client\n 1. In the Sitecore Cloud Portal, open SitecoreAI Deploy.\n 2. Click **Credentials** > **Environment** > **Create credentials** > **Automation**.\n 3. Fill out the automation client details, then click **Create**.\n 4. Copy the client ID and the client secret because you won't be able to view them again in SitecoreAI Deploy. You'll use them to request a JWT.\n\n## Request a JWT\n\nRun the following cURL command to request a JWT. Replace the placeholder values with your client ID and client secret.\n```curl\n curl -X POST 'https://auth.sitecorecloud.io/oauth/token' \\\n --header 'Content-Type: application/x-www-form-urlencoded' \\\n --data-urlencode 'client_id={YOUR_CLIENT_ID}' \\\n --data-urlencode 'client_secret={YOUR_CLIENT_SECRET}' \\\n --data-urlencode 'grant_type=client_credentials' \\\n --data-urlencode 'audience=https://api.sitecorecloud.io'\n```\n\nIn the response, the `access_token` key contains the JWT:\n\n```json\n {\n \"access_token\": \"{YOUR_JWT}\",\n \"scope\": \"xmcloud.cm:admin\",\n \"expires_in\": 86400,\n \"token_type\": \"Bearer\"\n }\n```\n\nThe JWT expires in 24 hours. If your requests unexpectedly return a response with status `401 Unauthorized`, request a new JWT by repeating this `POST` request.\n\nWe recommend that you cache the JWT for 24 hours to avoid repeating this `POST` request while the JWT is still valid.\n\n## Include the JWT in the request header\n\nYou can now start making REST API requests. You must include the JWT in the request header of every request. For example:\n ```curl\n curl -X GET '{YOUR_BASE_URL}/...' \\\n -H 'Authorization: Bearer {YOUR_JWT}' \\\n -H 'Accept: application/json'\n ```", "contact": { "name": "Sitecore Corporation A/S" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0" }, "version": "v1", "x-metadata": { "product": "SitecoreAI" } }, "servers": [ { "url": "https://edge-platform.sitecorecloud.io/authoring", "description": "Production server" } ], "paths": { "/api/v1/components/drafts/{componentDraftId}": { "get": { "tags": [ "Components" ], "summary": "Retrieve a component draft", "description": "Retrieves a component draft by id.", "operationId": "RetrieveDraft", "parameters": [ { "name": "componentDraftId", "in": "path", "description": "The component draft identifier.", "required": true, "schema": { "type": "string" }, "example": "2492bac4-da07-4c86-87f0-9873d40e2276" }, { "name": "environmentId", "in": "query", "description": "The environment identifier.", "schema": { "type": "string" }, "example": "main" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComponentDraft" } } } }, "400": { "description": "One or more validation errors occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Bad Request", "status": 400, "detail": "A detailed explanation, specific to this occurrence of the problem.", "instance": "If available, a URI reference that identifies the specific occurrence of the problem.", "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00", "errors": { "sampleProperty": [ "The sampleProperty field is required" ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7235#section-3.1", "title": "Unauthorized", "status": 401, "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00" } } } }, "404": { "description": "Invalid component draft id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found", "status": 404, "detail": "A detailed explanation, specific to this occurrence of the problem.", "instance": "If available, a URI reference that identifies the specific occurrence of the problem." } } } } } }, "patch": { "tags": [ "Components" ], "summary": "Update a component draft", "description": "Updates a component draft.", "operationId": "PatchDraft", "parameters": [ { "name": "componentDraftId", "in": "path", "description": "The component draft identifier.", "required": true, "schema": { "type": "string" }, "example": "2492bac4-da07-4c86-87f0-9873d40e2276" }, { "name": "environmentId", "in": "query", "description": "The environment identifier.", "schema": { "type": "string" }, "example": "main" } ], "requestBody": { "description": "Details of the component draft to update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateComponentDraftInput" } }, "text/json": { "schema": { "$ref": "#/components/schemas/UpdateComponentDraftInput" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/UpdateComponentDraftInput" } } }, "required": true }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComponentDraft" } } } }, "400": { "description": "One or more validation errors occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Bad Request", "status": 400, "detail": "A detailed explanation, specific to this occurrence of the problem.", "instance": "If available, a URI reference that identifies the specific occurrence of the problem.", "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00", "errors": { "sampleProperty": [ "The sampleProperty field is required" ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7235#section-3.1", "title": "Unauthorized", "status": 401, "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00" } } } }, "404": { "description": "Invalid component draft id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found", "status": 404, "detail": "A detailed explanation, specific to this occurrence of the problem.", "instance": "If available, a URI reference that identifies the specific occurrence of the problem." } } } }, "502": { "description": "Bad Gateway" } } }, "put": { "tags": [ "Components" ], "summary": "Update a component draft", "description": "Fully replaces a component draft. All user-editable fields are replaced with the provided values.\nNull values reset optional fields to their defaults. Unlike PATCH, the entire Variants collection\nis replaced — any existing variant not present in the request body is removed.", "operationId": "UpdateDraft", "parameters": [ { "name": "componentDraftId", "in": "path", "description": "The component draft identifier.", "required": true, "schema": { "type": "string" }, "example": "2492bac4-da07-4c86-87f0-9873d40e2276" }, { "name": "environmentId", "in": "query", "description": "The environment identifier.", "schema": { "type": "string" }, "example": "main" } ], "requestBody": { "description": "Details of the component draft to update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplaceComponentDraftInput" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ReplaceComponentDraftInput" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/ReplaceComponentDraftInput" } } }, "required": true }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComponentDraft" } } } }, "400": { "description": "One or more validation errors occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Bad Request", "status": 400, "detail": "A detailed explanation, specific to this occurrence of the problem.", "instance": "If available, a URI reference that identifies the specific occurrence of the problem.", "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00", "errors": { "sampleProperty": [ "The sampleProperty field is required" ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7235#section-3.1", "title": "Unauthorized", "status": 401, "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00" } } } }, "404": { "description": "Invalid component draft id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found", "status": 404, "detail": "A detailed explanation, specific to this occurrence of the problem.", "instance": "If available, a URI reference that identifies the specific occurrence of the problem." } } } }, "502": { "description": "Bad Gateway" } } }, "delete": { "tags": [ "Components" ], "summary": "Delete a component draft", "description": "Deletes a component draft by id.", "operationId": "DeleteDraft", "parameters": [ { "name": "componentDraftId", "in": "path", "description": "The component draft identifier.", "required": true, "schema": { "type": "string" }, "example": "2492bac4-da07-4c86-87f0-9873d40e2276" }, { "name": "environmentId", "in": "query", "description": "The environment identifier.", "schema": { "type": "string" }, "example": "main" } ], "responses": { "204": { "description": "Successful operation" }, "400": { "description": "One or more validation errors occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Bad Request", "status": 400, "detail": "A detailed explanation, specific to this occurrence of the problem.", "instance": "If available, a URI reference that identifies the specific occurrence of the problem.", "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00", "errors": { "sampleProperty": [ "The sampleProperty field is required" ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7235#section-3.1", "title": "Unauthorized", "status": 401, "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00" } } } }, "404": { "description": "Invalid component draft id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found", "status": 404, "detail": "A detailed explanation, specific to this occurrence of the problem.", "instance": "If available, a URI reference that identifies the specific occurrence of the problem." } } } } } } }, "/api/v1/components/drafts": { "get": { "tags": [ "Components" ], "summary": "List component drafts", "description": "Lists component drafts.", "operationId": "ListDrafts", "parameters": [ { "name": "environmentId", "in": "query", "description": "The environment identifier.", "schema": { "type": "string" }, "example": "main" } ], "responses": { "200": { "description": "Successful operation. The content type draft in the response body is the content type draft associated with this component draft.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ComponentDraft" } } } } }, "400": { "description": "One or more validation errors occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Bad Request", "status": 400, "detail": "A detailed explanation, specific to this occurrence of the problem.", "instance": "If available, a URI reference that identifies the specific occurrence of the problem.", "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00", "errors": { "sampleProperty": [ "The sampleProperty field is required" ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7235#section-3.1", "title": "Unauthorized", "status": 401, "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00" } } } } } }, "post": { "tags": [ "Components" ], "summary": "Create a component draft", "description": "Creates a component draft.", "operationId": "CreateDraft", "parameters": [ { "name": "environmentId", "in": "query", "description": "The environment identifier.", "schema": { "type": "string" }, "example": "main" } ], "requestBody": { "description": "Details of the component draft to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateComponentDraftInput" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateComponentDraftInput" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateComponentDraftInput" } } }, "required": true }, "responses": { "201": { "description": "Successful operation. ContentModel object can be empty once created but it can be populated subsequently using the Patch/Update Draft endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComponentDraft" } } } }, "400": { "description": "One or more validation errors occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Bad Request", "status": 400, "detail": "A detailed explanation, specific to this occurrence of the problem.", "instance": "If available, a URI reference that identifies the specific occurrence of the problem.", "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00", "errors": { "sampleProperty": [ "The sampleProperty field is required" ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7235#section-3.1", "title": "Unauthorized", "status": 401, "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00" } } } } } } }, "/api/v1/components": { "get": { "tags": [ "Components" ], "summary": "List components", "description": "Retrieves a list of components and their details for all sites or specific sites.", "operationId": "ListComponents", "parameters": [ { "name": "siteId", "in": "query", "description": "The site identifier.", "schema": { "type": "string" }, "example": "497f6eca-6276-4993-bfeb-53cbbbba6f08" }, { "name": "environmentId", "in": "query", "description": "The environment identifier. Defaults to \"main\". Currently only \"main\" is supported.", "schema": { "type": "string" }, "example": "main" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Component" } } } } }, "400": { "description": "One or more validation errors occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Bad Request", "status": 400, "detail": "A detailed explanation, specific to this occurrence of the problem.", "instance": "If available, a URI reference that identifies the specific occurrence of the problem.", "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00", "errors": { "sampleProperty": [ "The sampleProperty field is required" ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7235#section-3.1", "title": "Unauthorized", "status": 401, "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00" } } } } } }, "post": { "tags": [ "Components" ], "summary": "Create a component", "description": "Creates a component.", "operationId": "CreateComponent", "parameters": [ { "name": "environmentId", "in": "query", "description": "The environment identifier.", "schema": { "type": "string" }, "example": "main" } ], "requestBody": { "description": "Details of the component to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateComponentInput" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateComponentInput" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateComponentInput" } } }, "required": true }, "responses": { "201": { "description": "Successful operation. The variants array in the response body will be empty on create as no variants exist yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Component" } } } }, "400": { "description": "One or more validation errors occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Bad Request", "status": 400, "detail": "A detailed explanation, specific to this occurrence of the problem.", "instance": "If available, a URI reference that identifies the specific occurrence of the problem.", "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00", "errors": { "sampleProperty": [ "The sampleProperty field is required" ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7235#section-3.1", "title": "Unauthorized", "status": 401, "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00" } } } }, "404": { "description": "Provided content type not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found", "status": 404, "detail": "A detailed explanation, specific to this occurrence of the problem.", "instance": "If available, a URI reference that identifies the specific occurrence of the problem." } } } } } } }, "/api/v1/components/summaries": { "get": { "tags": [ "Components" ], "summary": "List component summaries", "description": "Retrieves a lightweight list of components containing only `id`, `name`, `displayName`, `systemName` and `modelId` for all sites or specific sites. Use this endpoint for any scenario that does not require full component details.", "operationId": "ListComponentSummaries", "parameters": [ { "name": "siteId", "in": "query", "description": "The site identifier.", "schema": { "type": "string" }, "example": "497f6eca-6276-4993-bfeb-53cbbbba6f08" }, { "name": "environmentId", "in": "query", "description": "The environment identifier. Defaults to \"main\". Currently only \"main\" is supported.", "schema": { "type": "string" }, "example": "main" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ComponentSummary" } } } } }, "400": { "description": "One or more validation errors occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Bad Request", "status": 400, "detail": "A detailed explanation, specific to this occurrence of the problem.", "instance": "If available, a URI reference that identifies the specific occurrence of the problem.", "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00", "errors": { "sampleProperty": [ "The sampleProperty field is required" ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7235#section-3.1", "title": "Unauthorized", "status": 401, "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00" } } } } } } }, "/api/v1/components/{componentId}": { "get": { "tags": [ "Components" ], "summary": "Retrieve a component", "description": "Retrieves a component and its details.", "operationId": "RetrieveComponent", "parameters": [ { "name": "componentId", "in": "path", "description": "The component identifier.", "required": true, "schema": { "type": "string" }, "example": "2492bac4-da07-4c86-87f0-9873d40e2276" }, { "name": "siteId", "in": "query", "description": "The site identifier.", "schema": { "type": "string" }, "example": "497f6eca-6276-4993-bfeb-53cbbbba6f08" }, { "name": "environmentId", "in": "query", "description": "The environment identifier. Defaults to \"main\". Currently only \"main\" is supported.", "schema": { "type": "string" }, "example": "main" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Component" } } } }, "400": { "description": "One or more validation errors occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Bad Request", "status": 400, "detail": "A detailed explanation, specific to this occurrence of the problem.", "instance": "If available, a URI reference that identifies the specific occurrence of the problem.", "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00", "errors": { "sampleProperty": [ "The sampleProperty field is required" ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7235#section-3.1", "title": "Unauthorized", "status": 401, "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00" } } } }, "404": { "description": "Component not found or not available for the requested site", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found", "status": 404, "detail": "A detailed explanation, specific to this occurrence of the problem.", "instance": "If available, a URI reference that identifies the specific occurrence of the problem." } } } } } }, "patch": { "tags": [ "Components" ], "summary": "Update a component", "description": "Updates a component.", "operationId": "UpdateComponent", "parameters": [ { "name": "componentId", "in": "path", "description": "The component identifier.", "required": true, "schema": { "type": "string" } }, { "name": "environmentId", "in": "query", "description": "The environment identifier. Defaults to \"main\". Currently only \"main\" is supported.", "schema": { "type": "string" }, "example": "main" } ], "requestBody": { "description": "Details of the component to update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateComponentInput" } }, "text/json": { "schema": { "$ref": "#/components/schemas/UpdateComponentInput" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/UpdateComponentInput" } } }, "required": true }, "responses": { "201": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Component" } } } }, "400": { "description": "One or more validation errors occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Bad Request", "status": 400, "detail": "A detailed explanation, specific to this occurrence of the problem.", "instance": "If available, a URI reference that identifies the specific occurrence of the problem.", "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00", "errors": { "sampleProperty": [ "The sampleProperty field is required" ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7235#section-3.1", "title": "Unauthorized", "status": 401, "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00" } } } }, "404": { "description": "Invalid model", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found", "status": 404, "detail": "A detailed explanation, specific to this occurrence of the problem.", "instance": "If available, a URI reference that identifies the specific occurrence of the problem." } } } } } } }, "/api/v1/components/{componentId}/metadata": { "get": { "tags": [ "Components" ], "summary": "Retrieve component metadata", "description": "Fetches the metadata of a component.", "operationId": "RetrieveComponentMetadata", "parameters": [ { "name": "componentId", "in": "path", "description": "The component identifier.", "required": true, "schema": { "type": "string" }, "example": "2492bac4-da07-4c86-87f0-9873d40e2276" }, { "name": "siteId", "in": "query", "description": "The site identifier.", "required": true, "schema": { "type": "string" }, "example": "497f6eca-6276-4993-bfeb-53cbbbba6f08" }, { "name": "contextItemId", "in": "query", "description": "The context item identifier.", "required": true, "schema": { "type": "string" }, "example": "2f34355e-c52d-450e-b1b9-d4e9cbe64af2" }, { "name": "componentName", "in": "query", "description": "The component name.", "schema": { "type": "string" }, "example": "Promo" }, { "name": "renderingHostName", "in": "query", "description": "The rendering host name.", "required": true, "schema": { "type": "string" }, "example": "nextjs-production" }, { "name": "environmentId", "in": "query", "description": "The environment identifier.", "schema": { "type": "string" }, "example": "main" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComponentMetadata" } } } }, "400": { "description": "One or more validation errors occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Bad Request", "status": 400, "detail": "A detailed explanation, specific to this occurrence of the problem.", "instance": "If available, a URI reference that identifies the specific occurrence of the problem.", "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00", "errors": { "sampleProperty": [ "The sampleProperty field is required" ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7235#section-3.1", "title": "Unauthorized", "status": 401, "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00" } } } }, "404": { "description": "Invalid component or site ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found", "status": 404, "detail": "A detailed explanation, specific to this occurrence of the problem.", "instance": "If available, a URI reference that identifies the specific occurrence of the problem." } } } } } } }, "/api/v1/components/{componentId}/variant/{componentVariantId}/metadata": { "get": { "tags": [ "Components" ], "summary": "Retrieve component variant metadata by ID", "description": "Fetches component variant metadata.", "operationId": "RetrieveComponentVariantMetadata", "parameters": [ { "name": "componentId", "in": "path", "description": "The component identifier.", "required": true, "schema": { "type": "string" }, "example": "2492bac4-da07-4c86-87f0-9873d40e2276" }, { "name": "componentVariantId", "in": "path", "description": "The component variant identifier.", "required": true, "schema": { "type": "string" }, "example": "2f34355e-c52d-450e-b1b9-d4e9cbe64af2" }, { "name": "siteId", "in": "query", "description": "The site identifier.", "required": true, "schema": { "type": "string" }, "example": "497f6eca-6276-4993-bfeb-53cbbbba6f08" }, { "name": "environmentId", "in": "query", "description": "The environment identifier. Defaults to \"main\". Currently only \"main\" is supported.", "schema": { "type": "string" }, "example": "main" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComponentVariantMetadata" } } } }, "400": { "description": "One or more validation errors occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Bad Request", "status": 400, "detail": "A detailed explanation, specific to this occurrence of the problem.", "instance": "If available, a URI reference that identifies the specific occurrence of the problem.", "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00", "errors": { "sampleProperty": [ "The sampleProperty field is required" ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7235#section-3.1", "title": "Unauthorized", "status": 401, "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00" } } } }, "404": { "description": "Invalid component or site ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found", "status": 404, "detail": "A detailed explanation, specific to this occurrence of the problem.", "instance": "If available, a URI reference that identifies the specific occurrence of the problem." } } } } } } }, "/api/v1/components/{componentId}/sites": { "get": { "tags": [ "Components" ], "summary": "Get sites where specified component is allowed", "description": "Returns an array of sites where the specified component is allowed.", "operationId": "RetrieveSitesByComponentId", "parameters": [ { "name": "componentId", "in": "path", "description": "The component identifier.", "required": true, "schema": { "type": "string" }, "example": "C5F905F8-FD1F-444E-A9E5-AC6B774FF0DE" }, { "name": "environmentId", "in": "query", "description": "The environment identifier. Defaults to \"main\". Currently only \"main\" is supported.", "schema": { "type": "string" }, "example": "main" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Site" } } } } }, "400": { "description": "Invalid component ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Bad Request", "status": 400, "detail": "A detailed explanation, specific to this occurrence of the problem.", "instance": "If available, a URI reference that identifies the specific occurrence of the problem.", "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00", "errors": { "sampleProperty": [ "The sampleProperty field is required" ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7235#section-3.1", "title": "Unauthorized", "status": 401, "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00" } } } } } } }, "/api/v1/components/drafts/{id}/model-suggestion": { "post": { "tags": [ "Components" ], "summary": "Generate a draft content type suggestion", "description": "Generates a content type suggestion from all draft variant code by calling the AI Service.", "operationId": "CreateDraftModelSuggestion", "parameters": [ { "name": "id", "in": "path", "description": "The component draft identifier.", "required": true, "example": "2492bac4-da07-4c86-87f0-9873d40e2276", "schema": { "type": "string" } }, { "name": "environmentId", "in": "query", "description": "The environment identifier.", "schema": { "type": "string" }, "example": "main" } ], "requestBody": { "description": "Optional payload containing Rendering Host atoms to enhance the AI model suggestion alongside variant code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDraftModelSuggestionInput" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateDraftModelSuggestionInput" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateDraftModelSuggestionInput" } } }, "required": true }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentModelDraft" } } } }, "400": { "description": "One or more validation errors occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Bad Request", "status": 400, "detail": "A detailed explanation, specific to this occurrence of the problem.", "instance": "If available, a URI reference that identifies the specific occurrence of the problem.", "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00", "errors": { "sampleProperty": [ "The sampleProperty field is required" ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7235#section-3.1", "title": "Unauthorized", "status": 401, "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00" } } } }, "404": { "description": "Invalid component draft id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found", "status": 404, "detail": "A detailed explanation, specific to this occurrence of the problem.", "instance": "If available, a URI reference that identifies the specific occurrence of the problem." } } } } } } }, "/api/v1/components/drafts/{componentDraftId}/activation": { "post": { "tags": [ "Components" ], "summary": "Activate a component draft", "description": "Activates an existing component draft by creating the corresponding content type (when present),\ncomponent, and variants, then permanently removes the draft from storage.\nActivation is a one-way operation — once successful the draft is no longer retrievable.\nWhen activation availability is omitted, the endpoint falls back to the draft's stored availability.\nIf neither activation input nor the stored draft defines site assignments, the component is created without site assignments.", "operationId": "ActivateDraft", "parameters": [ { "name": "componentDraftId", "in": "path", "description": "The component draft identifier.", "required": true, "schema": { "type": "string" }, "example": "2492bac4-da07-4c86-87f0-9873d40e2276" }, { "name": "environmentId", "in": "query", "description": "The environment identifier.", "schema": { "type": "string" }, "example": "main" } ], "requestBody": { "description": "Optional availability overrides and variant names to activate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateComponentDraftInput" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ActivateComponentDraftInput" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/ActivateComponentDraftInput" } } }, "required": true }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateComponentDraftResult" } } } }, "400": { "description": "One or more validation errors occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Bad Request", "status": 400, "detail": "A detailed explanation, specific to this occurrence of the problem.", "instance": "If available, a URI reference that identifies the specific occurrence of the problem.", "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00", "errors": { "sampleProperty": [ "The sampleProperty field is required" ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7235#section-3.1", "title": "Unauthorized", "status": 401, "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00" } } } }, "404": { "description": "Component draft not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found", "status": 404, "detail": "A detailed explanation, specific to this occurrence of the problem.", "instance": "If available, a URI reference that identifies the specific occurrence of the problem." } } } } } } }, "/api/v1/components/drafts/suggestions": { "post": { "tags": [ "Components" ], "summary": "Generate a component draft suggestion", "description": "Generates a component draft suggestion from a natural-language prompt.", "operationId": "CreateDraftSuggestion", "parameters": [ { "name": "environmentId", "in": "query", "description": "The environment identifier. Defaults to \"main\". Currently only \"main\" is supported.", "schema": { "type": "string" }, "example": "main" } ], "requestBody": { "description": "The prompt describing the desired component.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDraftSuggestionInput" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateDraftSuggestionInput" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateDraftSuggestionInput" } } }, "required": true }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftSuggestion" } } } }, "400": { "description": "One or more validation errors occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Bad Request", "status": 400, "detail": "A detailed explanation, specific to this occurrence of the problem.", "instance": "If available, a URI reference that identifies the specific occurrence of the problem.", "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00", "errors": { "sampleProperty": [ "The sampleProperty field is required" ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7235#section-3.1", "title": "Unauthorized", "status": 401, "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00" } } } } } } }, "/api/v1/component-categories": { "get": { "tags": [ "Categories" ], "summary": "List component categories", "description": "Fetches the list of component categories.", "operationId": "ListComponentsCategories", "parameters": [ { "name": "environmentId", "in": "query", "description": "The environment identifier.", "schema": { "type": "string" }, "example": "main" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ComponentCategory" } } } } }, "400": { "description": "One or more validation errors occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Bad Request", "status": 400, "detail": "A detailed explanation, specific to this occurrence of the problem.", "instance": "If available, a URI reference that identifies the specific occurrence of the problem.", "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00", "errors": { "sampleProperty": [ "The sampleProperty field is required" ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7235#section-3.1", "title": "Unauthorized", "status": 401, "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00" } } } } } } }, "/api/v1/component-categories/{category}/components": { "get": { "tags": [ "Categories" ], "summary": "List components in a category", "description": "Fetches the list of components in a specific component category.", "operationId": "ListCategoryComponents", "parameters": [ { "name": "category", "in": "path", "description": "The Item ID or Item name of the component category.", "required": true, "schema": { "type": "string" }, "example": "Page%20Content" }, { "name": "environmentId", "in": "query", "description": "The environment identifier.", "schema": { "type": "string" }, "example": "main" } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Component" } } } } }, "400": { "description": "One or more validation errors occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "Bad Request", "status": 400, "detail": "A detailed explanation, specific to this occurrence of the problem.", "instance": "If available, a URI reference that identifies the specific occurrence of the problem.", "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00", "errors": { "sampleProperty": [ "The sampleProperty field is required" ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" }, "example": { "type": "https://tools.ietf.org/html/rfc7235#section-3.1", "title": "Unauthorized", "status": 401, "traceId": "00-982607166a542147b435be3a847ddd71-fc75498eb9f09d48-00" } } } } } } } }, "components": { "schemas": { "ActivateComponentDraftInput": { "required": [ "variantNames" ], "type": "object", "properties": { "availability": { "$ref": "#/components/schemas/AvailabilityInput" }, "variantNames": { "type": "array", "items": { "type": "string" }, "description": "The names of the draft variants that should be activated.", "example": [ "Default", "Dark" ] } }, "additionalProperties": false, "description": "Input model for activating a component draft." }, "ActivateComponentDraftResult": { "type": "object", "properties": { "componentId": { "type": "string", "description": "The identifier of the created component.", "nullable": true, "example": "2492bac4-da07-4c86-87f0-9873d40e2276" }, "contentModelId": { "type": "string", "description": "The identifier of the created content type, or `null` when the draft had no content type definition.", "nullable": true, "example": "2f34355e-c52d-450e-b1b9-d4e9cbe64af2" } }, "additionalProperties": false, "description": "The result of a component draft activation." }, "AvailabilityInput": { "type": "object", "properties": { "sites": { "type": "array", "items": { "type": "string" }, "description": "The list of sites where the component will be assigned.", "nullable": true, "example": [ "4f2d7c8b9e1a4f0d8f3c2b176a4e9d22", "c1378a9fe2bd4e56a1c4d9f87b33a6c4" ] }, "placeholders": { "type": "array", "items": { "type": "string" }, "description": "The list of placeholders where the component can be used.", "nullable": true, "example": [ "4f2d7c8b9e1a4f0d8f3c2b176a4e9d22", "c1378a9fe2bd4e56a1c4d9f87b33a6c4" ] }, "pageModels": { "type": "array", "items": { "type": "string" }, "description": "The list of allowed page models.", "nullable": true, "example": [ "4f2d7c8b9e1a4f0d8f3c2b176a4e9d22", "c1378a9fe2bd4e56a1c4d9f87b33a6c4" ] } }, "additionalProperties": false, "description": "Represents the availability constraints for a component, specifying which sites, placeholders, and page models the component can be used with." }, "BaseContentModel": { "type": "object", "properties": { "id": { "type": "string", "description": "The content type identifier.", "nullable": true, "example": "d4e5f6a7-b8c9-0123-4567-89abcdef0123" }, "name": { "type": "string", "description": "The content type name.", "nullable": true, "example": "Promo" }, "created": { "type": "string", "description": "The content type creation date.", "nullable": true, "example": "2024-01-01T12:00:00Z" }, "createdBy": { "type": "string", "description": "The content type author.", "nullable": true, "example": "sitecore\\admin" }, "updated": { "type": "string", "description": "The content type last update date.", "nullable": true, "example": "2024-01-02T12:00:00Z" }, "updatedBy": { "type": "string", "description": "The author of the last update to the content type.", "nullable": true, "example": "sitecore\\admin" } }, "additionalProperties": false, "description": "Simplified representation of a content type." }, "Component": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "description": "The identifier of the component.", "example": "2492bac4-da07-4c86-87f0-9873d40e2276" }, "name": { "type": "string", "nullable": true, "description": "The name of the component.", "example": "Hero Banner" }, "displayName": { "type": "string", "nullable": true, "description": "The component displayName.", "example": "Banner" }, "systemName": { "type": "string", "nullable": true, "description": "The component system name.", "example": "HeroBanner" }, "description": { "type": "string", "nullable": true, "description": "The component description.", "example": "A promo component is a content block designed to showcase promotions using a combination of text and visuals" }, "category": { "$ref": "#/components/schemas/ComponentCategory" }, "icon": { "type": "string", "nullable": true, "description": "The component icon URL.", "example": "https://xmc-instance.sitecore-staging.cloud/-/icon/SXA_MDI/16x16/Promo.png" }, "datasourceTemplateField": { "type": "string", "nullable": true, "description": "Datasource template item path.", "example": "/sitecore/templates/Feature/Promos" }, "modelId": { "type": "string", "nullable": true, "description": "The content type identifier.", "example": "/sitecore/templates/Feature/Promos" }, "renderingParameters": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true, "description": "The component rendering parameters.", "example": { "ButtonText": "Click me!" } }, "settings": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true, "description": "The component settings.", "example": { "IsRenderingsWithDynamicPlaceholders": "true", "RandomNumber": "10" } }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/ComponentVariant" }, "nullable": true, "description": "The component variants.", "example": [ { "name": "Default", "id": "2492bac4-da07-4c86-87f0-9873d40e2276", "siteId": "497f6eca-6276-4993-bfeb-53cbbbba6f08" }, { "name": "Advanced", "id": "2f34355e-c52d-450e-b1b9-d4e9cbe64af2", "siteId": "497f6eca-6276-4993-bfeb-53cbbbba6f08" } ] }, "system": { "$ref": "#/components/schemas/System" }, "type": { "$ref": "#/components/schemas/ComponentType" } }, "additionalProperties": false, "description": "The Component entity." }, "ComponentAvailability": { "type": "object", "properties": { "sites": { "type": "array", "items": { "$ref": "#/components/schemas/Site" }, "description": "List of sites the component is assigned to.", "nullable": true }, "pageModels": { "type": "array", "items": { "$ref": "#/components/schemas/BaseContentModel" }, "description": "The content types where component is allowed.", "nullable": true } }, "additionalProperties": false, "description": "The component availability model" }, "ComponentCategory": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "description": "The category identifier", "example": "ae070691-099d-4081-856c-4c4a7e3543df" }, "name": { "type": "string", "nullable": true, "description": "The category name", "example": "Page Content" }, "path": { "type": "string", "nullable": true, "description": "The path to category item", "example": "/sitecore/content/Tenant/Site/Home/Categories/Page-Content" } }, "additionalProperties": false }, "ComponentCategoryInput": { "type": "object", "properties": { "id": { "type": "string", "description": "The category identifier.", "nullable": true, "example": "ae070691-099d-4081-856c-4c4a7e3543df" }, "name": { "maxLength": 50, "minLength": 0, "pattern": "^(?![\\s-])[a-zA-Z0-9_\\s-]*(?

Hello!

;" }, "renderingParameters": { "type": "array", "items": { "$ref": "#/components/schemas/RenderingParameter" }, "description": "Rendering parameters", "nullable": true }, "settings": { "type": "object", "additionalProperties": {}, "description": "Component settings.", "nullable": true }, "availability": { "$ref": "#/components/schemas/ComponentAvailability" } }, "additionalProperties": false, "description": "The ComponentMetadata entity." }, "ComponentSummary": { "type": "object", "properties": { "id": { "type": "string", "description": "The identifier of the component.", "nullable": true, "example": "2492bac4-da07-4c86-87f0-9873d40e2276" }, "name": { "type": "string", "description": "The name of the component.", "nullable": true, "example": "Hero Banner" }, "displayName": { "type": "string", "description": "The component display name.", "nullable": true, "example": "Banner" }, "systemName": { "type": "string", "description": "The component system name.", "nullable": true, "example": "HeroBanner" }, "modelId": { "type": "string", "description": "The identifier of the content type.", "nullable": true, "example": "3f2504e0-4f89-11d3-9a0c-0305e82c3301" } }, "additionalProperties": false, "description": "A lightweight API response model containing only the fields required\nfor list and sidebar scenarios where the full component payload would be excessive." }, "ComponentSystem": { "type": "object", "properties": { "createdAt": { "type": "string", "description": "The component creation time.", "nullable": true, "example": "2023-01-01T00:00:00Z" }, "createdBy": { "type": "string", "description": "The component creator.", "nullable": true, "example": "sitecore\\admin" }, "updatedAt": { "type": "string", "description": "The component last updating time.", "nullable": true, "example": "2023-01-01T00:00:00Z" }, "updatedBy": { "type": "string", "description": "The last component updater.", "nullable": true, "example": "sitecore\\admin" } }, "additionalProperties": false, "description": "Component system information." }, "ComponentType": { "enum": [ "Code", "Hosted" ], "type": "string", "description": "Specifies the type of a component based on its rendering template." }, "ComponentVariant": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "description": "The component variant identifier.", "example": "Default" }, "name": { "type": "string", "nullable": true, "description": "The component variant name.", "example": "Default" }, "displayName": { "type": "string", "nullable": true, "description": "The component variant display name.", "example": "Default" }, "description": { "type": "string", "nullable": true, "description": "The component variant description.", "example": "Sample variant description" }, "siteName": { "type": "string", "nullable": true, "description": "The site name.", "example": "skate-park" }, "siteId": { "type": "string", "nullable": true, "description": "The site identifier.", "example": "497f6eca-6276-4993-bfeb-53cbbbba6f08" }, "attributes": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "The component variant attributes." } }, "additionalProperties": false, "description": "The ComponentVariant entity." }, "ComponentVariantDraft": { "type": "object", "properties": { "name": { "pattern": "^[A-Za-z0-9_ -]+$", "type": "string", "description": "The variant name. Used as the unique key for add-or-replace operations.", "nullable": true, "example": "Default" }, "code": { "type": "string", "description": "The variant code.", "nullable": true, "example": "" } }, "additionalProperties": false, "description": "A draft variant containing a name and its associated code." }, "ComponentVariantMetadata": { "type": "object", "properties": { "id": { "type": "string", "description": "The component variant identifier.", "nullable": true, "example": "2492bac4-da07-4c86-87f0-9873d40e2276" }, "componentId": { "type": "string", "description": "The component identifier.", "nullable": true, "example": "2492bac4-da07-4c86-87f0-9873d40e2276" }, "name": { "type": "string", "description": "The component variant name.", "nullable": true, "example": "Promo Ba" }, "displayName": { "type": "string", "description": "The component variant display name.", "nullable": true, "example": "Promo" }, "codeId": { "type": "string", "description": "The component variant code identifier.", "nullable": true, "example": "2492bac4-da07-4c86-87f0-9873d40e2276" }, "code": { "type": "string", "description": "The component variant code.", "nullable": true, "example": "const Greeting = () =>

Hello!

;" }, "parsedCode": { "type": "string", "description": "The parsed representation of the component variant code.", "nullable": true, "example": "{\"type\":\"nextjs-pages\",\"code\":{\"type\":\"tsx\",\"content\":\"Hi\"},\"styles\":{\"type\":\"css-module\",\"content\":\"\"}}" } }, "additionalProperties": false, "description": "The component variant metadata entity." }, "ContentModelDraft": { "type": "object", "properties": { "name": { "type": "string", "description": "The content type draft name.", "nullable": true, "example": "Promo" }, "description": { "type": "string", "description": "The description of the content type draft.", "nullable": true, "example": "Draft content type" }, "fieldGroups": { "type": "array", "items": { "$ref": "#/components/schemas/FieldGroupDraft" }, "description": "The content type draft field groups.", "nullable": true } }, "additionalProperties": false, "description": "The content type draft associated with component draft." }, "ContentModelFieldDraft": { "type": "object", "properties": { "name": { "type": "string", "description": "The field draft name.", "nullable": true, "example": "PromoText" }, "type": { "type": "string", "description": "The field draft type.", "nullable": true, "example": "Single-Line Text" }, "helperText": { "type": "string", "description": "Help text for the field draft.", "nullable": true, "example": "Helper Text" }, "value": { "description": "The default value of the field draft. Accepts string or object types.", "nullable": true, "type": "object", "example": { "text": "Field Value Text" } }, "source": { "type": "string", "description": "The source of the field.", "nullable": true, "example": "/sitecore/content/Tenant/Site/Home" }, "sortOrder": { "type": "integer", "description": "The sort order.", "format": "int32", "nullable": true, "example": 1 }, "validationRules": { "type": "array", "items": { "type": "string" }, "description": "The validation rules assigned to the field as a list of validation rule item IDs.", "nullable": true, "example": [ "59D4EE10-627C-4FD3-A964-61A88B092CBC", "A76C1092-EE2E-4021-B9EE-21E541CDA1D7" ] } }, "additionalProperties": false, "description": "The content field draft." }, "CreateComponentDraftInput": { "required": [ "name" ], "type": "object", "properties": { "name": { "maxLength": 50, "minLength": 0, "type": "string", "description": "The component draft name.", "example": "Promo" }, "displayName": { "maxLength": 50, "minLength": 0, "type": "string", "description": "The component draft display name.", "nullable": true, "example": "Promo" }, "category": { "$ref": "#/components/schemas/ComponentCategoryInput" }, "iconUrl": { "type": "string", "description": "The component draft icon URL.", "nullable": true, "example": "/temp/iconcache/sxa_mdi/32x32/promo.png" }, "renderingParameters": { "type": "array", "items": { "$ref": "#/components/schemas/RenderingParameterInput" }, "description": "The component draft rendering parameters.", "nullable": true }, "settings": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The component draft settings.", "nullable": true, "example": { "Sample": "10" } }, "description": { "type": "string", "description": "The component draft description.", "nullable": true, "example": "Promo description" }, "type": { "$ref": "#/components/schemas/DraftType" } }, "additionalProperties": false, "description": "Create component draft input" }, "CreateComponentInput": { "required": [ "category", "name" ], "type": "object", "properties": { "name": { "maxLength": 50, "minLength": 0, "pattern": "^(?![\\s-])[a-zA-Z0-9_\\s-]*(?Submit" } }, "additionalProperties": false, "description": "Input for generating a draft content type suggestion." }, "CreateDraftSuggestionInput": { "required": [ "prompt" ], "type": "object", "properties": { "prompt": { "maxLength": 1000, "minLength": 0, "type": "string", "description": "A natural-language description of the component to generate a suggestion for.\nMust be between 5 and 1000 characters.", "example": "A full-width banner with a background image, headline, subtext, and a call-to-action button" } }, "additionalProperties": false, "description": "Input for generating a component draft suggestion." }, "DraftSuggestion": { "type": "object", "properties": { "name": { "type": "string", "description": "The suggested system name of the component, formatted in PascalCase without spaces.", "nullable": true, "example": "HeroBanner" }, "displayName": { "type": "string", "description": "The human-readable display name of the component.", "nullable": true, "example": "Hero Banner" }, "category": { "type": "string", "description": "The suggested category for the component draft.", "nullable": true, "example": "Page Content" }, "description": { "type": "string", "description": "A generated description summarising the component's purpose and content structure.", "nullable": true, "example": "A full-width banner section featuring a background image, headline, subtext, and a call-to-action button." } }, "additionalProperties": false, "description": "An AI-generated suggestion for a component draft." }, "DraftType": { "enum": [ "Code", "Hosted" ], "type": "string", "description": "Specifies the delivery model of a component draft." }, "EditingControl": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "description": "The editing control identifier.", "example": "{18293E6E-708E-4B15-84C3-AE52CC17A1}" }, "name": { "type": "string", "nullable": true, "description": "The editing control name.", "example": "Spacing" }, "displayName": { "type": "string", "nullable": true, "description": "The editing control display name.", "example": "Spacing" }, "type": { "type": "string", "nullable": true, "description": "The editing control type.", "example": "icon-button-group-check" }, "tooltip": { "type": "string", "nullable": true, "description": "The editing control tooltip.", "example": "Use this control to adjust the spacing of your component." }, "values": { "type": "array", "items": { "$ref": "#/components/schemas/EditingControlValue" }, "nullable": true } }, "additionalProperties": false }, "EditingControlInput": { "type": "object", "properties": { "type": { "type": "string", "description": "The control type.", "nullable": true, "example": "Single-Line Text" }, "value": { "type": "string", "description": "The control value.", "nullable": true, "example": "Placeholder text" } }, "additionalProperties": false, "description": "The rendering parameter editing control input." }, "EditingControlValue": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "description": "The editing control value identifier.", "example": "{18293E6E-708E-4B15-84C3-AE52CC17A1EE}" }, "name": { "type": "string", "nullable": true, "description": "The editing control value name.", "example": "Indent top" }, "icon": { "type": "string", "nullable": true, "description": "The editing control value icon.", "example": "add-spacing-top" }, "value": { "type": "string", "nullable": true, "description": "The editing control value.", "example": "indent-top" }, "tooltip": { "type": "string", "nullable": true, "description": "The editing control tooltip.", "example": "Top spacing" } }, "additionalProperties": false }, "FieldGroupDraft": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the field group.", "nullable": true, "example": "GroupName" }, "sortOrder": { "type": "integer", "description": "The sort order.", "format": "int32", "nullable": true, "example": 1 }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/ContentModelFieldDraft" }, "description": "The content type draft fields.", "nullable": true } }, "additionalProperties": false, "description": "The field group draft" }, "Placeholder": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "description": "The identifier of the placeholder", "example": "6f9619ff-8b86-d011-b42d-00c04fc964ff" }, "name": { "type": "string", "nullable": true, "description": "The name of the placeholder", "example": "Main Content" }, "placeholderKey": { "type": "string", "nullable": true, "description": "The placeholder key.", "example": "main-content" } }, "additionalProperties": false }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of the error response entity.", "nullable": true }, "title": { "type": "string", "description": "The title of the error response entity.", "nullable": true }, "status": { "type": "integer", "description": "The response status code.", "format": "int32", "nullable": true }, "detail": { "type": "string", "description": "A detailed explanation, specific to this occurrence of the problem.", "nullable": true }, "instance": { "type": "string", "description": "If available, a URI reference that identifies the specific occurrence of the problem.", "nullable": true } }, "additionalProperties": { "description": "Any additional optional properties that describe the error(s)." } }, "RenderingParameter": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "description": "The rendering parameter name", "example": "styles" }, "displayName": { "type": "string", "nullable": true, "description": "The rendering parameter display name", "example": "Styling" }, "editingControls": { "type": "array", "items": { "$ref": "#/components/schemas/EditingControl" }, "nullable": true } }, "additionalProperties": false }, "RenderingParameterInput": { "required": [ "editingControl", "name" ], "type": "object", "properties": { "name": { "maxLength": 50, "minLength": 0, "type": "string", "description": "The parameter name.", "example": "Promo" }, "displayName": { "maxLength": 50, "minLength": 0, "type": "string", "description": "The parameter display name.", "nullable": true, "example": "Promo" }, "editingControl": { "$ref": "#/components/schemas/EditingControlInput" } }, "additionalProperties": false, "description": "Create rendering parameter input" }, "ReplaceComponentDraftInput": { "required": [ "name" ], "type": "object", "properties": { "name": { "maxLength": 50, "minLength": 0, "type": "string", "description": "The component draft name.", "example": "Promo" }, "displayName": { "maxLength": 50, "minLength": 0, "type": "string", "description": "The component draft display name. Falls back to name when empty.", "nullable": true, "example": "Promo" }, "description": { "type": "string", "description": "The component draft description.", "nullable": true, "example": "Promo description" }, "category": { "$ref": "#/components/schemas/ComponentCategoryInput" }, "modelId": { "type": "string", "description": "The content type identifier.", "nullable": true, "example": "ae070691-099d-4081-856c-4c4a7e3543df" }, "renderingParameters": { "type": "array", "items": { "$ref": "#/components/schemas/RenderingParameterInput" }, "description": "The rendering parameters. Replaces the entire stored list.\nSend an empty array to clear all rendering parameters.", "nullable": true }, "settings": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Other component draft settings. Replaces the entire stored dictionary.\nSend an empty object to clear all settings.", "nullable": true }, "contentModel": { "$ref": "#/components/schemas/ContentModelDraft" }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/ComponentVariantDraft" }, "description": "The full variant list. Replaces the entire stored variants dictionary.\nVariants not present in this list are removed.\nSend an empty array to clear all variants. Variant names must be unique.", "nullable": true }, "availability": { "$ref": "#/components/schemas/AvailabilityInput" } }, "additionalProperties": false, "description": "Input for a full replacement (PUT) of a component draft." }, "ResourceLink": { "type": "object", "properties": { "href": { "type": "string", "description": "The relative URL of the linked resource.", "nullable": true, "example": "/api/v1/sites/497f6eca-6276-4993-bfeb-53cbbbba6f08" } }, "additionalProperties": false, "description": "A single hypermedia link (RFC 8288)." }, "Site": { "type": "object", "properties": { "id": { "type": "string", "description": "The identifier of the site.", "nullable": true, "example": "497f6eca-6276-4993-bfeb-53cbbbba6f08" }, "name": { "type": "string", "description": "The name of the site.", "nullable": true, "example": "skate-park" }, "displayName": { "type": "string", "description": "The display name of the site.", "nullable": true, "example": "Skate Park Website" }, "links": { "$ref": "#/components/schemas/SiteLinks" } }, "additionalProperties": false, "description": "Site short information." }, "SiteLinks": { "type": "object", "properties": { "self": { "$ref": "#/components/schemas/ResourceLink" } }, "additionalProperties": false, "description": "Hypermedia links associated with a Site resource." }, "System": { "type": "object", "properties": { "created": { "type": "string", "nullable": true, "description": "Time of creation.", "example": "2023-01-01T00:00:00Z" }, "createdBy": { "type": "string", "nullable": true, "description": "Name of creator.", "example": "sitecore admin" }, "updated": { "type": "string", "nullable": true, "description": "Time of last update.", "example": "2023-01-01T00:00:00Z" }, "updatedBy": { "type": "string", "nullable": true, "description": "The last updater.", "example": "sitecore admin" } }, "additionalProperties": false }, "UpdateComponentDraftInput": { "type": "object", "properties": { "name": { "type": "string", "description": "Component draft name.", "nullable": true, "example": "Promo" }, "displayName": { "type": "string", "description": "Component draft display name.", "nullable": true, "example": "Promo" }, "description": { "type": "string", "description": "Component draft description.", "nullable": true, "example": "A promo component is a content block designed to showcase promotions using a combination of text and visuals" }, "category": { "$ref": "#/components/schemas/ComponentCategoryInput" }, "modelId": { "type": "string", "description": "Content type identifier.", "nullable": true, "example": "d4e5f6a7-b8c9-0123-4567-89abcdef0123" }, "settings": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Other component draft properties.", "nullable": true }, "contentModel": { "$ref": "#/components/schemas/ContentModelDraft" }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/ComponentVariantDraft" }, "description": "Variant drafts to add or replace by name.\nOmit or pass `null` — existing variants are left unchanged. Empty array `[]` — all existing variants are removed. Non-empty array — only the named variants are added or updated; variants not present in the list are preserved.\nVariant names must be unique.", "nullable": true }, "availability": { "$ref": "#/components/schemas/AvailabilityInput" } }, "additionalProperties": false, "description": "Update component draft input." }, "UpdateComponentInput": { "type": "object", "properties": { "name": { "maxLength": 50, "minLength": 0, "pattern": "^(?![\\s-])[a-zA-Z0-9_\\s-]*(?