The Agent API is the missing piece when automating SitecoreAI: it places components on pages. The Content Types, Components, and Content Items APIs create the building blocks, a template, a rendering, and content, but none of them places a component on a page or connects it to its content. The Agent API does both, using the same token as the other three APIs.

This post extends my earlier post, Automating SitecoreAI with PowerShell. That post used the Content Types, Components, and Content Items APIs to create a component and its content from PowerShell. This one picks up where it left off: getting that component onto a page.

In this post, I walk through four steps using PowerShell:

1. Find the site and its pages.
2. Check which components a placeholder allows.
3. Place the component on the page.
4. Point the component at an existing content item as its datasource.

The example uses a Product Spotlight component placed on a Products page and displaying a content item called Wireless Headphones Launch. The component, page, and content item were created earlier using the other APIs.

Before You Start

The one thing that differs from the other three APIs is the base address:

The token is the same for both.

Step 1: Find the Site and Its Pages

Start by listing the sites in the environment. This is also a quick way to check that the token and base address are correct.

$sites = Invoke-RestMethod -Method Get -Headers $Headers -Uri "$AgentApi/sites"
$sites | ConvertTo-Json -Depth 5

The site's ID in the response is the ID of the site item in the content tree, and its root path points to the Home item. You need the site name for the next call, which lists the site's pages:

$SiteName = "mysite"
$pages = Invoke-RestMethod -Method Get -Headers $Headers -Uri "$AgentApi/sites/$SiteName/pages"
$pages | ConvertTo-Json -Depth 5

Find your page in the list and keep its ID. Every call that follows works on that page ID.

Step 2: Check Which Components a Placeholder Allows

Before placing anything, ask the page which components its placeholder accepts. In this example, the placeholder is headless-main.

$PageId      = "<your page ID>"
$Placeholder = "headless-main"

$allowed = Invoke-RestMethod -Method Get -Headers $Headers `
    -Uri "$AgentApi/pages/$PageId/placeholders/$Placeholder/allowed-components"
$allowed | ConvertTo-Json -Depth 5

If your component is missing from the list, the problem could be on the Sitecore side rather than in your script. Check two things:

• The component is in the site's Available Renderings, under Presentation. The Components API adds it there when you send availability.sites.
• The placeholder's own settings do not restrict it. Allowed Controls on a placeholder setting override Available Renderings.

This is a quick way to confirm that a component can go in a placeholder before you place it.

Step 3: Place the Component on the Page

One POST request places the component. It needs the component's rendering ID (the ID returned by the Components API), the placeholder, a name, and a language.

$ComponentId = "<your component ID>"

$body = @{
    componentRenderingId = $ComponentId
    placeholderPath      = $Placeholder
    componentItemName    = "Product Spotlight Local"
    language             = "en"
} | ConvertTo-Json

$added = Invoke-RestMethod -Method Post -Headers $Headers -ContentType "application/json" `
    -Uri "$AgentApi/pages/$PageId/components" -Body $body

$added | ConvertTo-Json -Depth 5

componentItemName is the name of a new datasource item that the call creates under the page, in its local data folder. The call works like the Page Builder when you drop a component and choose to create new content: the component goes on the page, and an empty local content item is created and connected to it. The response provides its ID as datasourceId.

That suits pages with their own content. When the content already exists as a shared item, such as Wireless Headphones Launch in the site's Data folder, place the component first and then set its datasource, as shown in Step 4.

Step 4: Set the Datasource Using the Instance ID

A placed component has two IDs:

The datasource call needs the instance ID. Read the page's components and select the placement of your component:

$onPage   = Invoke-RestMethod -Method Get -Headers $Headers -Uri "$AgentApi/pages/$PageId/components"
$instance = $onPage.components | Where-Object { $_.componentId -eq $ComponentId } | Select-Object -Last 1

Then point that placement at the existing content item:

$DatasourceId = "<your content item ID>"   # Wireless Headphones Launch

$body = @{ datasourceId = $DatasourceId; language = "en" } | ConvertTo-Json

$result = Invoke-RestMethod -Method Post -Headers $Headers -ContentType "application/json" `
    -Uri "$AgentApi/pages/$PageId/components/$($instance.id)/datasource" -Body $body

The empty local item from Step 3 is now unused. The Agent API does not remove it, so delete it with the Content Items API. A deleted item goes to the Recycle Bin, where it can be restored:

$Authoring = "https://edge-platform.sitecorecloud.io/authoring/api/v1"
Invoke-RestMethod -Method Delete -Headers $Headers `
    -Uri "$Authoring/content-items/$($added.datasourceId)?environmentId=main" | Out-Null

The Full Script

Here are the four steps in one script. It works in Windows PowerShell 5.1 and PowerShell 7.

# Add-ComponentWithAgentApi.ps1
$ErrorActionPreference = "Stop"

# ---------------- Settings ----------------
$SiteName     = "mysite"
$PageId       = "<your page ID>"
$ComponentId  = "<your component ID>"
$DatasourceId = "<your content item ID>"
$Placeholder  = "headless-main"
# ------------------------------------------

. "$PSScriptRoot\Settings.ps1"   # sets $ClientId and $ClientSecret

$AgentApi  = "https://edge-platform.sitecorecloud.io/stream/ai-agent-api/api/v1"
$Authoring = "https://edge-platform.sitecorecloud.io/authoring/api/v1"

# Token
$token = (Invoke-RestMethod -Method Post -Uri "https://auth.sitecorecloud.io/oauth/token" `
    -ContentType "application/x-www-form-urlencoded" -Body @{
        client_id = $ClientId; client_secret = $ClientSecret
        grant_type = "client_credentials"; audience = "https://api.sitecorecloud.io"
    }).access_token
$Headers = @{ Authorization = "Bearer $token" }

# 1. List the site's pages (confirms the token and the site name)
$pages = Invoke-RestMethod -Method Get -Headers $Headers -Uri "$AgentApi/sites/$SiteName/pages"
Write-Host "Site $SiteName found."

# 2. Check the placeholder allows the component
$allowed = Invoke-RestMethod -Method Get -Headers $Headers `
    -Uri "$AgentApi/pages/$PageId/placeholders/$Placeholder/allowed-components"
$allowed | ConvertTo-Json -Depth 5 | Write-Host

# 3. Place the component (this also creates an empty local datasource)
$added = Invoke-RestMethod -Method Post -Headers $Headers -ContentType "application/json" `
    -Uri "$AgentApi/pages/$PageId/components" -Body (@{
        componentRenderingId = $ComponentId
        placeholderPath      = $Placeholder
        componentItemName    = "Product Spotlight Local"
        language             = "en"
    } | ConvertTo-Json)
Write-Host "Placed in $Placeholder."

# 4. Find the instance ID, then set the datasource
$onPage   = Invoke-RestMethod -Method Get -Headers $Headers -Uri "$AgentApi/pages/$PageId/components"
$instance = $onPage.components | Where-Object { $_.componentId -eq $ComponentId } | Select-Object -Last 1
if (-not $instance) { throw "Could not find the placed component on the page." }

$result = Invoke-RestMethod -Method Post -Headers $Headers -ContentType "application/json" `
    -Uri "$AgentApi/pages/$PageId/components/$($instance.id)/datasource" `
    -Body (@{ datasourceId = $DatasourceId; language = "en" } | ConvertTo-Json)
Write-Host "Datasource set: $($result.success)"

# Remove the unused local datasource (goes to the Recycle Bin)
if ($added.datasourceId -and $added.datasourceId -ne $DatasourceId) {
    Invoke-RestMethod -Method Delete -Headers $Headers `
        -Uri "$Authoring/content-items/$($added.datasourceId)?environmentId=main" | Out-Null
    Write-Host "Unused local datasource removed."
}

How You Can Use It

• Build pages from a script. Create a page, place its components, and connect their content in one run. This suits new site setups, landing pages, and campaign pages that follow the same layout.
• Reuse shared content. One content item in the Data folder can serve as the datasource for the same component on multiple pages. Update the item once, and every page displays the change.
• Roll out a component across pages. List a site's pages, then place a new component on each page that needs it, instead of opening every page in the Page Builder.
• Check before you change. The allowed-components call confirms that placement is possible, and the page's component list shows what is already there. This allows a script to skip pages that already have the component.
• Complete the automation. With the Content Types, Components, and Content Items APIs, the entire chain can be scripted: content type, component, page, content, and placement.

With the Agent API, the last manual step of building a component goes away: the component lands on the page with its content, directly from a script. Together with the Content Types, Components, and Content Items APIs, a content type, a component, a page, its content, and the placement can all be created in one run.