SharePoint grounding connection (AI Foundry) — learning guide

SharePoint Connection (AI Foundry) - Create + List.md

SharePoint grounding connection (AI Foundry) — learning guide

This guide shows the exact az rest calls to create, list, and delete an AI Foundry SharePoint grounding connection.

---

Mental model (two APIs)

You’ll touch two different API surfaces:

• Control plane (ARM): https://management.azure.com
  • Use this to create / update / delete the connection resource.
• Project data plane (Foundry project endpoint): https://<accountName>.services.ai.azure.com/api/projects/<projectName>
  • Use this to list/get connections and to call get-with-credentials.

The project data-plane endpoints used in this guide are:

• GET {projectEndpoint}/connections?api-version=v1
• GET {projectEndpoint}/connections/{connectionName}?api-version=v1
• POST {projectEndpoint}/connections/{connectionName}/getConnectionWithCredentials?api-version=v1

---

Prereqs

• Azure CLI: az --version
• Signed in: az login
• You have permission to manage the AI services account / project.

---

Set variables (placeholders)

Replace the placeholders below:

# Azure subscription + Foundry project identity
$subscriptionId = '00000000-0000-0000-0000-000000000000'
$resourceGroup  = 'rg-example'
$accountName    = 'my-ai-services-account'      # Microsoft.CognitiveServices account name
$projectName    = 'my-foundry-project'

# Connection name you will create in the project
$connectionName = 'sharepoint_grounding_demo_001'

# SharePoint site OR folder URL (single value per connection)
$sharePointSiteUrl = 'https://contoso.sharepoint.com/sites/Policies'

# API versions used by these calls
$armApiVersion      = '2025-04-01-preview'
$armBatchApiVersion = '2015-11-01'
$foundryApiVersion  = 'v1'

---

Create a connection (ARM PUT)

$url = "https://management.azure.com/subscriptions/${subscriptionId}/resourceGroups/${resourceGroup}/providers/Microsoft.CognitiveServices/accounts/${accountName}/projects/${projectName}/connections/${connectionName}?api-version=${armApiVersion}"

The payload supports one SharePoint URL per connection (a site or a folder).

$payload = @{
  properties = @{
    authType      = 'CustomKeys'
    category      = 'CustomKeys'
    target        = '_'
    isSharedToAll = $false
    credentials   = @{ keys = @{ siteUrl = $sharePointSiteUrl } }
    metadata      = @{ type = 'sharepoint_grounding' }
  }
}

$tmp = New-TemporaryFile
($payload | ConvertTo-Json -Depth 20) | Set-Content -LiteralPath $tmp -Encoding utf8NoBOM

az rest --method put --url $url --body "@$($tmp.FullName)" --headers 'Content-Type=application/json' --output jsonc

Verify with ARM GET:

az rest --method get --url $url --output jsonc

---

Create multiple connections (ARM batch)

Batch endpoint:

• POST https://management.azure.com/batch?api-version=2015-11-01

Notes:

• Use requests[i].httpMethod, requests[i].relativeUrl, and requests[i].content.
• Do not include per-request headers inside requests[i].

$rel = "/subscriptions/${subscriptionId}/resourceGroups/${resourceGroup}/providers/Microsoft.CognitiveServices/accounts/${accountName}/projects/${projectName}/connections/${connectionName}?api-version=${armApiVersion}"

$batch = @{
  requests = @(
    @{
      httpMethod  = 'PUT'
      relativeUrl = $rel
  
      content     = @{
        properties = @{
  
          authType      = 'CustomKeys'
          category      = 'CustomKeys'
          target        = '_'
          isSharedToAll = $false
          credentials   = @{ keys = @{ siteUrl = $sharePointSiteUrl } }
          metadata      = @{ type = 'sharepoint_grounding' }
        }
      }
    }
  )
}

$tmp = New-TemporaryFile
($batch | ConvertTo-Json -Depth 20) | Set-Content -LiteralPath $tmp -Encoding utf8NoBOM

az rest --method post --url "https://management.azure.com/batch?api-version=${armBatchApiVersion}" --body "@$($tmp.FullName)" --headers 'Content-Type=application/json' --output jsonc

---

List/get connections (project data plane)

Set the project endpoint:

$endpoint = "https://${accountName}.services.ai.azure.com/api/projects/${projectName}"

List connections:

az rest --method get --url "${endpoint}/connections?api-version=${foundryApiVersion}" --resource 'https://ai.azure.com' --output jsonc

Get a single connection:

az rest --method get --url "${endpoint}/connections/${connectionName}?api-version=${foundryApiVersion}" --resource 'https://ai.azure.com' --output jsonc

---

Get connection with credentials

az rest --method post --url "${endpoint}/connections/${connectionName}/getConnectionWithCredentials?api-version=${foundryApiVersion}" --resource 'https://ai.azure.com' --output jsonc

The response can include credential fields (for example, the configured SharePoint URL) along with credentials.type.

---

Delete (ARM)

$url = "https://management.azure.com/subscriptions/${subscriptionId}/resourceGroups/${resourceGroup}/providers/Microsoft.CognitiveServices/accounts/${accountName}/projects/${projectName}/connections/${connectionName}?api-version=${armApiVersion}"
az rest --method delete --url $url

Verify deletion:

# ARM should return 404 NotFound after deletion
az rest --method get --url $url --output jsonc

# Data plane list should no longer show the name
$endpoint = "https://${accountName}.services.ai.azure.com/api/projects/${projectName}"
az rest --method get --url "${endpoint}/connections?api-version=${foundryApiVersion}" --resource 'https://ai.azure.com' --output jsonc

---

SharePoint tool notes (limits + prerequisites)

These notes are for the Microsoft SharePoint tool (preview) in Foundry Agent Service:

• The SharePoint tool supports configuring a single site_url value per connection (a SharePoint site or a SharePoint folder URL). In ARM, this shows up as a single credentials.keys.siteUrl field.
• The SharePoint tool only supports user identity authentication (no service principal / SPN auth).
• Your SharePoint site/folder and the Foundry agent must be in the same tenant.
• Supported document types include .pdf, .docx, .ppt, .txt, .aspx.

Reference: Use the Microsoft SharePoint tool (preview)

Troubleshooting

• If ARM returns a 400 about deserialization, use credentials.keys.siteUrl (camelCase) in the ARM PUT payload.
• For *.services.ai.azure.com calls, pass --resource 'https://ai.azure.com'.