Using the Copilot Retrieval API for Microsoft 365 Searches

Introduction

The Copilot Retrieval API represents a major advancement for IT professionals seeking to optimize their integrations with Microsoft 365 Copilot. This tool enables targeted searches on content in SharePoint Online, OneDrive for Business, and external connectors, and provides relevant text excerpts to enrich user queries.

Key Features of the Copilot Retrieval API

What is Query "Grounding"?

Grounding consists of contextually enriching user queries by using text excerpts from authorized Microsoft 365 sources. Unlike tools like ChatGPT that process uploaded documents, the Copilot Retrieval API enables deep searches within Microsoft 365 data.

Differences Between the Search API and the Retrieval API

• Search API: Performs semantic searches.
• Retrieval API: Executes searches based on the RAG method, complemented by text excerpts.

This positioning facilitated by Microsoft provides rich context for integrated applications such as Word, Excel, or PowerPoint.

Access and Permissions of the Connected User

Usage of this API is limited to the context of the connected user. This means the API requires delegated permissions such as:

• Files.Read.All
• Sites.Read.All
• ExternalItem.Read.All for connectors

These permissions ensure that the API only returns results accessible to the connected user.

Tutorial: Using the Copilot Retrieval API with the Microsoft Graph PowerShell SDK

Here is a series of steps to execute a search via the Copilot Retrieval API:

1Connect-MgGraph -NoWelcome -Scopes Files.Read.All, Sites.Read.All

1$Uri = 'https://graph.microsoft.com/v1.0/copilot/retrieval'

1$BodyRequest = @{}
2$BodyRequest.Add("datasource", "sharepoint")
3$BodyRequest.Add("queryString", "How to write a PowerShell script for Microsoft 365")
4$BodyRequest.Add("maximumNumberOfResults", "3")

1$BodyRequest.add("filterexpression", 'FileExtension:"DOCX" AND LastModifiedTime>=2025-11-01 AND LastModifiedTime<=2026-01-31')

1[array]$Data = Invoke-MgGraphRequest -Uri $Uri -Method Post -Body $BodyRequest -OutputType PsObject

1$Hits = $Data.RetrievalHits
2ForEach ($Hit in $Hits) {
3    Write-Host "File Title :" $Hit.ResourceMetaData.Title
4    Write-Host "Creation Date :" $Hit.ResourceMetadata.Created
5    Write-Host "Relevance :" $Hit.extracts.relevanceScore
6    Write-Host "Sensitivity Label :" $Hit.SensitivityLabel.DisplayName
7    Write-Host "Excerpt :" $Hit.extracts.text.substring(0,120)
8}

Possible Uses and Benefits

• Optimized contextualization of queries for Copilot applications.
• Improved results by using advanced filters and metadata.
• Facilitated integration with Microsoft Graph and PowerShell.

Conclusion

The Copilot Retrieval API paves the way for advanced contextual search in the Microsoft 365 environment, offering IT teams a powerful tool to exploit data in their automated processes or custom applications. As Microsoft continues to strengthen its features in Microsoft 365 Copilot, remaining agile with these tools will enable teams to maximize their benefits.