SitecoreAI Layout Control in Marketer MCP & Agent API: A Postman Guide

On October 12, 2026, Sitecore shipped Marketer MCP and Agent API improvements for SitecoreAI (Sitecore XM Cloud). Here is the short version:

• 🎯 Place components exactly where you want them: add a component before or after an existing one instead of guessing at positions in SitecoreAI.
• 🔀 Move components: reposition them within or across placeholders on the base page layout.
• 🔍 Check references before you delete: a referrers endpoint shows which pages and components use an item.
• 🧪 See what an A/B test is about to lose: removals and deletions report the affected experiments back to you.
• ↩️ Remove orphaned components: safely delete broken components that point to missing or non-existent datasource items.

If you have been following my Model Context Protocol series , you know the pattern. The Marketer MCP server is a thin, AI-friendly layer over the SitecoreAI Agent API. An agent picks a tool, the tool calls an endpoint, and the work happens in SitecoreAI under your existing permissions.

Creating new pages and adding components worked fine, but editing existing layouts felt clumsy. Where does the new component land? What breaks if I delete this datasource? And is someone running an A/B test on that banner?

The October 12 changelog answers those questions with five tools:

• get_content_references
• add_component_on_page
• move_component_on_page
• remove_component_on_page
• delete_content

I wanted to see the raw HTTP behind each one, because that tells you how these tools behave when an agent drives them at scale.

Sitecore states that each Marketer MCP tool corresponds to an Agent API endpoint. The flow looks like this:

1. You prompt an MCP client such as VS Code Copilot, Claude or Cursor.
2. The client picks a Marketer MCP tool.
3. The MCP server calls the Agent API on your behalf.
4. SitecoreAI applies its normal roles, approvals and audit rules.

That is why Postman is such a good way to learn this. You see exactly what the tool will send, and you can test safely before you let an agent loose.

The base URL for every call in this guide is:

https://edge-platform.sitecorecloud.io/stream/ai-agent-api

Create a Postman environment with the variables below. Mark the secret as a secret-type variable, and never commit an exported environment.

To create the client, open SitecoreAI Deploy in the Sitecore Cloud Portal, go to Credentials > Environment > Create credentials > Automation, and copy the secret straight away, since you cannot view it again. You need to be an Organization Admin or Owner.

curl -X POST 'https://auth.sitecorecloud.io/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id={YOUR_CLIENT_ID}' \
  --data-urlencode 'client_secret={YOUR_CLIENT_SECRET}' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'audience=https://api.sitecorecloud.io'

The response contains access_token and expires_in: 86400. Rather than copy and paste the token, drop this into the collection’s Pre-request Script tab so Postman refreshes it for you:

const expiresAt = Number(pm.collectionVariables.get("jwt_expires_at") || 0);

if (!pm.collectionVariables.get("jwt") || Date.now() > expiresAt) {
  pm.sendRequest({
    url: "https://auth.sitecorecloud.io/oauth/token",
    method: "POST",
    header: { "Content-Type": "application/x-www-form-urlencoded" },
    body: {
      mode: "urlencoded",
      urlencoded: [
        { key: "client_id", value: pm.environment.get("client_id") },
        { key: "client_secret", value: pm.environment.get("client_secret") },
        { key: "grant_type", value: "client_credentials" },
        { key: "audience", value: "https://api.sitecorecloud.io" }
      ]
    }
  }, (err, res) => {
    if (err || res.code !== 200) {
      console.error("Token request failed", err || res.text());
      return;
    }
    const json = res.json();
    pm.collectionVariables.set("jwt", json.access_token);
    // refresh 5 minutes early
    pm.collectionVariables.set("jwt_expires_at", Date.now() + (json.expires_in - 300) * 1000);
  });
}

Set the collection Authorization type to Bearer Token with the value {{jwt}}.

Check what depends on an item before you touch it.

Here, we check the inbound references for the datasource item named Text 1 inside the SitecoreAI Content Tree:

To check the item references for the datasource named Text 1 programmatically, execute the following GET request:

Postman API Response (HTTP 200 OK):

{
  "total_places": 1,
  "items": [
    {
      "id": "00000000-0000-0000-0000-000000000",
      "name": "Home",
      "path": "/sitecore/content/amitkumar/Contoso/Home",
      "via": "__Final Renderings",
      "kind": "page",
      "page_item_id": "00000000-0000-0000-0000-000000000",
      "page_url": "/"
    }
  ]
}

Marketer MCP Tool Prompt:

#get_content_references provide the Text1 item references from the contoso site

Marketer MCP Tool Response:

Rather than appending renderings blindly to the end of a layout or manually calculating zero-based presentation indexes, the add_component_on_page operation inserts components relative to existing elements using deterministic spatial anchors (before or after).

See It in SitecoreAI

Below is the current page structure in SitecoreAI before adding the new component:

To add a component relative to another item (insertBeforeComponentId or insertAfterComponentId), you must provide the target element’s Component Instance ID (id). If this parameter is omitted, SitecoreAI appends the component to the very bottom of the placeholder.

You can retrieve the Component Instance ID in two ways:

1. Via Sitecore Marketer MCP: Ask your AI assistant with an explicit prompt:

   get list of components from page /sitecore/content/amitkumar/Contoso/Home and include the component instance IDs.

2. Via SitecoreAI Agent API: Execute the deterministic GET request below.

cURL Equivalent:

curl -i -X GET \
  'https://edge-platform.sitecorecloud.io/stream/ai-agent-api/api/v1/pages/0000000000000000000000000000000/components?language=en' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'x-sc-job-id: job-1234'

Sample API Response (HTTP 200 OK):

{
  "pageId": "0000000000000000000000000000000",
  "pageName": "Home Page",
  "pagePath": "/sitecore/content/Home",
  "version": 1,
  "language": "en",
  "route": "/home",
  "layoutEditingKind": "Standard",
  "template": {
    "id": "0000000000000000000000000000000",
    "name": "Article Page"
  },
  "components": [
    {
      "id": "00000000-0000-0000-0000-000000000101",
      "componentId": "00000000-0000-0000-0000-000000000201",
      "componentName": "RichText",
      "dataSource": "local:/Data/Text 1",
      "dataSourceItem": {
        "itemId": "00000000-0000-0000-0000-000000000301",
        "name": "Text 1",
        "path": "/sitecore/content/Tenant/Site/Home/Data/Text 1",
        "template": "Text",
        "fields": {
          "Text": "<p>Enterprise-Grade Agility with SitecoreAI.</p>"
        }
      },
      "placeholder": "headless-main",
      "parameters": {
        "GridParameters": "{7465D855-992E-4DC2-9855-A03250DFA74B}",
        "FieldNames": "{F7E889BA-D657-4DB8-B1AD-F766AECC7074}",
        "Styles": "{BD396F09-FD42-4D60-B489-EFD70926B07A}"
      },
      "deviceId": "00000000-0000-0000-0000-000000000401",
      "layoutId": "00000000-0000-0000-0000-000000000501",
      "editable": true
    }
  ]
}

To add the component programmatically, dispatch a POST request to the SitecoreAI Agent API.

📮 Postman Configuration

Request body (raw, JSON):

{
  "componentRenderingId": "86a03271-dff4-470a-92bd-b68c67de2e25",
  "placeholderPath": "headless-main",
  "componentItemName": "homePageRichText-1",
  "language": "en",
  "fields": {
    "Text": "<p>1-Your rich text content goes here.</p>"
  },
  "insertAfterComponentId": "9c6d53e3-fe57-4638-af7b-6d68304c7a94"
}

Sample API Response (HTTP 201 Created):

A successful call returns 201 with componentId, pageId, placeholderId and, where relevant, datasourceId (The datasource item would be created as local item). Keep that componentId, because the move and remove calls need it. If you followed my previous VS Code integration article , the structure is identical except for the new spatial before/after anchor.

{
  "componentId": "00000000-0000-0000-0000-000000000101",
  "pageId": "00000000-0000-0000-0000-000000000002",
  "placeholderId": "headless-main",
  "datasourceId": "00000000-0000-0000-0000-000000000301"
}

When an autonomous AI agent in Copilot Studio, Cursor, or VS Code executes this step, it invokes the corresponding add_component_on_page tool over JSON-RPC:

Marketer MCP Tool Prompt:

#add_component_on_page Add RichText component on Home page of site Contso with datasource item named homePageRichText-1 with Text field value as "<p>1-Your rich text content goes here.</p>" and placeholder is headless-main with en language, and insert after Promo component which using the datasource as PromoLeft

Marketer MCP Tool Response:

The move_component_on_page operation repositions an existing component instance on the base page layout between compatible, editable placeholders.

To move the component programmatically, dispatch a PATCH request to update its layout position:

Request Body (raw ➡ JSON):

{
  "targetPlaceholderPath": "/headless-main/container-1",
  "insertBeforeComponentId": "3a6f45e9-9459-42d1-981f-0f2c97404bbd",
  "language": "en"
}

cURL Equivalent:

curl -i -X PATCH \
  'https://edge-platform.sitecorecloud.io/stream/ai-agent-api/api/v1/pages/00000000-0000-0000-0000-000000000/components/00000000-0000-0000-0000-000000000101/position' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'x-sc-job-id: job-1234' \
  -H 'Content-Type: application/json' \
  -d '{
    "targetPlaceholderPath": "/headless-main/container-1",
    "insertBeforeComponentId": "3a6f45e9-9459-42d1-981f-0f2c97404bbd",
    "language": "en"
  }'

API Response Status Codes

Sample Response Payload (HTTP 200 OK):

{
  "success": true,
  "pageId": "00000000-0000-0000-0000-000000000",
  "componentInstanceId": "00000000-0000-0000-0000-000000000101",
  "sourcePlaceholderPath": "/headless-main",
  "targetPlaceholderPath": "/headless-main/container-1"
}

When an AI assistant (such as Copilot Studio, Cursor, or VS Code) repositions components on your behalf, it executes the equivalent move_component_on_page tool over JSON-RPC:

Marketer MCP Tool Prompt:

#move_component_on_page move the component RichText from placholder headless-main/container-1 placeholder to headless-main after the Image component present in headless-main placeholder

Marketer MCP Tool Response:

Error Details:

{
  "success": false,
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "Invalid request (400). Check pageId, componentInstanceId, move directives, and targetPlaceholderPath rules.",
    "retryable": false,
    "statusCode": 400
  },
  "diagnostics": {
    "resolvedApiBaseUrl": "https://edge-platform.sitecorecloud.io/ai/ai-agent-api",
    "statusCode": 400,
    "statusCodes": {
      "preCheck": 200,
      "move": 400,
      "postCheck": null
    },
    "retryCount": 0
  }
}
{
  "success": false,
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "Invalid request (400). Check pageId, componentInstanceId, move directives, and targetPlaceholderPath rules.",
    "retryable": false,
    "statusCode": 400
  },
  "diagnostics": {
    "resolvedApiBaseUrl": "https://edge-platform.sitecorecloud.io/ai/ai-agent-api",
    "statusCode": 400,
    "statusCodes": {
      "preCheck": 200,
      "move": 400,
      "postCheck": null
    },
    "retryCount": 0
  }
}

The delete_content operation permanently deletes a content or datasource item. Beyond simply deleting the record, it provides governance telemetry by reporting downstream layout impacts, affected components, and active A/B experiments.

cURL Equivalent:

curl -i -X DELETE \
  'https://edge-platform.sitecorecloud.io/stream/ai-agent-api/api/v1/content/00000000-0000-0000-0000-000000000301?remove_references=false' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'x-sc-job-id: job-1234'

API Response Status Codes

Sample Response Payload (HTTP 200 OK):

{
  "success": true,
  "deletedId": "00000000-0000-0000-0000-000000000301",
  "affectedComponents": [
    {
      "pageId": "00000000-0000-0000-0000-0000000003017",
      "pageName": "Home",
      "componentId": "00000000-0000-0000-0000-000000000101",
      "componentRenderingId": "00000000-0000-0000-0000-0000000001014",
      "placeholderKey": "/headless-main/container-1",
      "language": "en",
      "removed": false,
      "error": null
    }
  ],
  "affectedExperiments": []
}

When an AI assistant (such as Copilot Studio, Cursor, or VS Code) deletes content on your behalf, it executes the corresponding delete_content tool over JSON-RPC:

Marketer MCP Tool Prompt:

#delete_content  delete the homePageRichText-1 datasource item

Marketer MCP Tool Response:

✕

The remove_component_on_page operation removes a component instance from a page layout.

Unlike a destructive delete that fails if dependencies are active, this endpoint incorporates a governance safeguard: instead of failing the request, it completes the removal and returns an affectedExperiments report so you can review any impacted A/B/n tests.

To remove the component programmatically, dispatch a DELETE request to the layout components endpoint:

cURL Equivalent:

curl -i -X DELETE \
  'https://edge-platform.sitecorecloud.io/stream/ai-agent-api/api/v1/pages/00000000-0000-0000-0000-000000000002/components/00000000-0000-0000-0000-000000000101?language=en' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'x-sc-job-id: job-1234'

API Response Status Codes

Sample Response Payload (HTTP 200 OK):

{
  "success": true,
  "removedComponentId": "00000000-0000-0000-0000-00000000030171",
  "affectedExperiments": []
}

When an AI assistant (such as GitHub Copilot, Cursor, or Claude Desktop) removes components, it invokes the remove_component_on_page tool over standard JSON-RPC.

Unlike direct REST API calls, the Marketer MCP tool evaluates the blast radius first—detecting any active A/B experiments and prompting the user for explicit confirmation before altering the layout.

Marketer MCP Tool Prompt:

#remove_component_on_page  remove RichText component from Home page which uses the datasource as homePageRichText-1

Marketer MCP Tool Response:

✕

• 🧩 Mutations vs. Cascade:
  Removing a component only deletes the presentation rendering reference from the page layout delta (final layout). It does not delete the underlying datasource item-use delete_content (covered above) if you want to eliminate the content item as well.

• 🛡️ Safe A/B Testing Governance:
  Both the Agent API and Marketer MCP surface affectedExperiments directly in the response payload instead of aborting the operation with a 4xx error code.

• 🤖 MCP Interactive Safety:
  In conversational AI tooling (Cursor, VS Code, Copilot Studio), the MCP server intercepts the call to confirm the removal with the marketer before committing changes to the layout.

The operations call lists each action with its type, status and timestamps. The revert call restores the state before the job ran.

• 📖 Read before you write: call the referrers endpoint before any delete, and get_components_on_page before any move so you have real instance IDs.
• 🧾 One job ID per logical change: several related calls under one ID means one revert.
• 📍 Prefer anchors to guesses: pass insertBeforeComponentId or insertAfterComponentId rather than relying on whatever order the page has today.
• 📝 Log the response, not just the status: affectedExperiments and affectedComponents are the real result.
• 🧪 Rehearse in a non-production site first: all Agent API requests run against your production environment.

The Marketer MCP server rate limit is documented as 50 requests per 10 seconds , so a bulk job that touches hundreds of pages needs throttling. In Postman, use the Collection Runner with a delay between requests. For scripts, batch by page and back off when throttled. The referrers items list is capped, so for impact reports rely on total_places and walk your page list separately.

• 🔑 Protect the client secret: use a secret-type Postman variable or a vault, never a shared collection.
• 🛡️ Permissions still apply: the Agent API follows SitecoreAI’s built-in security and approval rules, and an AI client does not get extra access.
• ♻️ Scope and rotate credentials: create automation credentials for a specific purpose.
• 👀 Review before publishing: layout changes through the API are still changes to your content, subject to your workflow and publishing process.

Say a seasonal banner is ending and you want it gone from every SitecoreAI page that uses it.

1. Create a job ID, for example retire-fall-promo-2026.
2. Call the referrers endpoint for the banner datasource. Read total_places and the page_url of each referrer.
3. Remove the banner on each referencing page, passing the same job ID. Log every affectedExperiments entry, because this is where you find the A/B test still pointing at it.
4. Delete the datasource, using remove_references=true only if you want the cascade. Read affectedComponents for any removed: false leftovers.
5. Revert if needed. If something looks wrong, call the revert endpoint for the job ID and start again.

That is the same sequence an agent would follow through the MCP tools, only now you can see every step.

The October 12 update makes SitecoreAI page editing through the Agent API and Marketer MCP much more precise. You can anchor components before or after others, move them, see what references an item before deleting it, and revert a whole job if an agent gets it wrong.

1. Build the Postman collection above against a non-production SitecoreAI site.
2. Run the retire-a-banner scenario end to end, including a revert.
3. Check your MCP client lists the five tools, and test how it handles the confirmation step.
4. Add a throttle to any bulk script.

If this saved you time, share it with your SitecoreAI team, and tell me which scenario you would like next. You can browse more in the MCP article series and follow along for the next SitecoreAI release breakdown.