Exploring the Microsoft 365 Copilot APIs with an SPFx Webpart

At Build 2025, Microsoft introduced the Copilot Retrieval (now GA) and Search (public preview) APIs, giving developers programmatic access to the Microsoft 365 Semantic Index and the AI orchestration behind Copilot. The docs explain what these APIs do — but nothing replaces seeing the raw requests and responses yourself. So I built an SPFx webpart for exactly that: a tool to tweak every parameter, compare results across both APIs, and build real intuition for how Copilot searches your tenant.

Table of Contents

• Table of Contents
• My Motivation
• Understanding the APIs — What Makes Them Different
  • The Semantic Index
  • Two Levels of AI Involvement
  • The Non-Determinism Challenge
• What the Webpart Does
  • Retrieval Tab
  • Search Tab
  • Log Viewer
• A Look Under the Hood
• Comparing the Search Approaches
• Conclusion
• Resources

My Motivation

As a developer, I am still fascinated by how far Search has come with RAG, so as soon as it was available as an API in the Microsoft 365 World, I decided to start experimenting how these APIs work, not just that they work. What does the Retrieval API actually return? How do relevance scores compare across queries? How does the Semantic Index handle multilingual content? I also wanted to test them against real data scenarios I had designed — to see how they retrieve and rank content from specific SharePoint data, and how well they handle queries across different languages.

The official documentation answers some of these questions, but nothing replaces hands-on experimentation. So I built a tool for rapid iteration — an SPFx webpart where I can tweak every parameter, compare results across both APIs, inspect the raw request and response JSON, and build intuition for what the Semantic Index actually does with my queries.

Understanding the APIs — What Makes Them Different

The Semantic Index

At the foundation sits the Microsoft 365 Semantic Index. Unlike traditional SharePoint search, which uses keyword matching, the Semantic Index understands meaning. “USA”, “United States”, and “U.S.A.” are recognized as the same concept.

From building this webpart, my key observation is that these APIs go beyond a semantic index — the official documentation states the API “understands the user’s context and intent and performs query transformations,” suggesting AI-powered processing is embedded in the retrieval pipeline itself. In my testing, identical queries returned slightly different results on repeated calls — non-determinism appears baked into the retrieval, not just the generation.

Two Levels of AI Involvement

In my view, the two APIs represent different levels of AI processing:

Retrieval API (/beta/copilot/retrieval) — AI-powered search + chunking. You send a natural language query, the API returns unordered text extracts with relevance scores (0–1). It doesn’t generate answers — you bring your own LLM if you want that. You can scope results with KQL filter expressions and request specific SharePoint managed properties as metadata fields. Think of it as the Swiss army knife for building your own AI solutions — it gives you the raw semantic material, and you decide what to do with it. Maximum 25 results, no pagination.

Search API (/beta/copilot/search) — Hybrid search (semantic and lexical) with natural language processing to understand query intent and intelligent result ranking . Returns ordered documents with pagination and preview text. In API responses, I observed hit-highlighting tags in the preview snippets. KQL filtering is limited to the Path property only, so you can scope results to a specific site, library, or folder — but not filter by author, file type, or other properties. Up to 100 results per page with cursor-based pagination.

The Non-Determinism Challenge

Until now, with SharePoint Search and Graph Search, we were accustomed to deterministic systems. The same query returns the same results. In my hands-on testing, these APIs required a mindset shift — the same query could yield different results, different scores, different orderings. This behavior appears inherent to how AI-augmented retrieval works — the query transformations and intelligent ranking that Microsoft describes likely introduce variability by design. Understanding and accepting this is essential before building production solutions on top of these APIs.

What the Webpart Does

The webpart provides a dedicated tab for each API, plus a shared log viewer for debugging:

Retrieval Tab

Natural language queries with full control over every parameter: data source selection (SharePoint, OneDrive, External Items), result count (1–25), KQL filter expressions, and metadata field selection. The metadata picker is particularly interesting — it dynamically discovers all available SharePoint managed properties from the tenant’s search schema at runtime, so you’re never working with a stale hardcoded list.

Results appear as cards showing the document title, URL, relevance-scored extracts, sensitivity labels, and any requested metadata fields. The webpart adds client-side query-term highlighting on top — the API itself returns plain text extracts without any markup. This has a natural limitation: since the Semantic Index understands meaning, a search for “U.S.A.” may return extracts containing “USA”, but the client-side highlighting won’t match because it relies on exact string comparison. The API is smarter than any literal text matching can be. Switch to JSON view to inspect the raw API response.

Search Tab

Hybrid search (semantic + lexical) with pagination support. KQL filtering is limited to the Path property — the built-in examples panel provides ready-made path-based filters (dynamically injected with your current site URL and library name). Results show preview text with API-generated highlighting. The “Load More” button follows @odata.nextLink cursors for paging through large result sets.

Log Viewer

A structured debug panel that logs every API call with timing metrics, request/response payloads, and categorized log levels. Useful for comparing how the same query behaves across different APIs or parameter configurations.

A Look Under the Hood

The webpart is built on SPFx 1.22.1 with React 17 and Fluent UI 8. The dynamic schema discovery deserves a mention: to populate the metadata field picker, the webpart calls the SharePoint search API with a ManagedProperties refiner — a technique adapted from PnP Modern Search. This returns all indexed managed property names in the tenant without requiring any admin API access.

Comparing the Search Approaches

To put things in perspective, here is a non-exhaustive comparison of the search approaches available in Microsoft 365 today:

Option A — Detailed table:

This comparison is non-exhaustive and reflects the state of these APIs as of February 2026. Consult the official documentation for the latest capabilities.

Conclusion

This webpart was built as developer tooling — by exposing every parameter and showing every response, it makes the behavior of these APIs tangible. Clone the repo and start experimenting.

Personally, I believe that future search or application solution will end up combining both APIs. The Retrieval API’s semantic chunking and the Search API’s hybrid ranking with pagination are complementary — together they cover far more ground than either one alone. And once you have both pipelines feeding results, the natural next step is to layer GPT processing on top to re-rank, summarize, or reason across the combined output. That’s where the real power lies.

Resources

• GitHub Repository
• Copilot Retrieval API Documentation
• Copilot Search API Documentation
• Microsoft 365 Semantic Index
• SPFx API Permissions
• KQL Syntax Reference