Back to Blog

Microsoft 365 Copilot Search API - Semantic Search Over Your Work Content

November 20, 2026•7 min read•Michael Ridland

Here's a question we get from almost every client building internal tools on Microsoft 365: "Why can't our app find documents the way Copilot does?"

They've built a portal, a Teams app or an agent. Users type something like "the latest version of the travel policy" and the search comes back with 200 hits containing the word "travel," sorted by something nobody can explain. Meanwhile, they open Microsoft 365 Copilot, ask the same question in plain English, and it finds the right document first time.

The Microsoft 365 Copilot Search API is Microsoft's answer to that gap. It gives your own applications access to the same semantic search that Copilot uses to find documents, while respecting the permissions users already have. I wrote recently about the Copilot Retrieval API, and the two are easy to confuse, so I'll cover how they differ as well.

What the Search API does

The Copilot Search API lets you send a natural language query and get back a ranked list of relevant documents from Microsoft 365 content the calling user can access. It's part of the Copilot APIs under Microsoft Graph, alongside retrieval, chat and others.

The key word is semantic. Classic keyword search matches terms. Semantic search tries to match meaning. If someone searches for "how much can I spend on a hotel in Melbourne," a semantic search should surface the travel and expenses policy even if that document never uses the word "hotel" and talks about "accommodation allowances" instead. Under the hood it's a hybrid approach that combines semantic understanding with traditional lexical matching, which is the right call. Pure vector search is notoriously bad at exact things like project codes, invoice numbers and people's names.

What you get back is a list of documents: the item, a link to it, and a preview of relevant content. You can page through results and narrow searches to specific locations. It's designed for search experiences, not for feeding large chunks of text into a model.

Coverage has started with OneDrive content and is expanding from there. Check the current documentation for what's supported when you read this, because it has been changing quickly.

Search API versus Retrieval API

This is the question I get most, so let's be clear about it.

The Retrieval API returns text extracts. It's built for retrieval augmented generation: you ask a question, get back relevant passages, and pass them to a language model to produce an answer. The output is chunks of text with relevance scores, ready to be dropped into a prompt.

The Search API returns documents. It's built for finding things: you want a list of files to show a user, or you want your agent to identify the right document before doing something with it. The output is a ranked result set, a lot more like what a person expects from a search box.

A rough rule of thumb from our projects:

  • If the user wants an answer, use retrieval.
  • If the user wants a file, use search.

In practice, some solutions use both. An agent might use search to find "the signed contract with Acme," then open that specific document and use it as context. That's a much more reliable pattern than asking a retrieval system to magically surface the right clauses from across thousands of contracts.

How it compares with classic Microsoft Graph search

Microsoft Graph has had a search API for years. It works, and lots of apps use it. But it's fundamentally keyword driven, with KQL for filtering. It's very good when you know what you're looking for: a file name, an author, a date range, a content type.

The Copilot Search API is better when the user describes what they want in plain language. Most real users do exactly that. They don't think in KQL. They think "that spreadsheet Sarah sent about the Q3 forecast."

I wouldn't rip out classic Graph search everywhere. For structured lookups, like "all PDFs in this library modified in the last 30 days," KQL is still more predictable. The Copilot Search API earns its place where queries are vague and conversational.

Where we see it being useful

A few scenarios where I think this API makes a real difference for Australian organisations.

Agents that need to find a document before acting on it. A lot of the agent work we do involves "find the thing, then do something with it." Find the latest board paper template and draft a new paper. Find the client's statement of work and check the payment terms. Before this API, the "find" step was usually the weakest link. If your agent picks the wrong document, everything downstream is wrong, confidently. Our AI agent development work increasingly treats document finding as its own step that needs to be tested on its own.

Search inside line-of-business apps. Professional services firms, legal practices and engineering consultancies have huge amounts of content sitting in OneDrive and SharePoint. Putting a semantic search box inside their existing internal tools, rather than forcing people into the Microsoft 365 search UI, is a quick win that people actually notice.

Copilot Studio and custom agents. If you're building agents in Copilot Studio or with code, having a proper search capability that understands natural language queries makes those agents noticeably less frustrating to use.

Permissions are the real feature

I'll say this every time I write about these APIs: the most valuable thing isn't the semantic ranking. It's that results are trimmed to what the calling user can already see.

Building permission-aware search yourself is painful. You have to sync ACLs, handle group memberships (including nested groups), deal with sharing links, and keep it all current as people change roles. Most homegrown solutions get this subtly wrong, and the failure mode is a junior staff member finding the executive salary review spreadsheet through your shiny new search box.

Because the Copilot Search API runs on behalf of the signed-in user, Microsoft does that work for you.

The flip side: it will faithfully return anything the user technically has access to. If your SharePoint permissions are a mess (and in most organisations we audit, they are), semantic search makes that mess much easier to find. Documents that were "secure through obscurity" stop being obscure. Run an oversharing review before you roll out any Copilot-powered search. This isn't optional.

What's rough or worth watching

Licensing. The Copilot APIs generally require users to have a Microsoft 365 Copilot licence. For organisations that have only licensed Copilot for a subset of staff, that limits who can use apps built on this API. Factor it into your business case early, because it often changes the maths.

Coverage is still growing. Starting with OneDrive is useful but limited. Many organisations keep their important content in SharePoint sites and Teams. Until coverage matches where your content lives, you may need a fallback to classic Graph search or the Retrieval API.

Preview behaviour. Parts of the Copilot API family have sat in beta for a while. Endpoints, request shapes and throttling limits can change. Wrap the API in your own service layer so a change in Microsoft's contract doesn't ripple through your whole application.

Delegated access only, for now. Because it runs as the user, it's not a fit for background jobs or daemon processes that need to search across the whole tenant. That's by design, but it rules out some batch scenarios people ask for.

Evaluating relevance. Semantic search is harder to debug than keyword search. When a result looks wrong, you can't easily see why it ranked where it did. Build a small evaluation set of real queries with known correct answers, and run it regularly. It's boring work and it's the only way to know whether your search is getting better or worse.

My take

The Copilot Search API fills a gap that has annoyed developers on Microsoft 365 for years. Keyword search was never a great fit for how people actually look for things, and building your own semantic search with proper permissions was out of reach for most teams.

I wouldn't build anything mission-critical on it until coverage and licensing line up with your needs. But if you're already licensed for Copilot and building agents or internal apps, it's worth prototyping with now. Pair it with the Retrieval API and you have most of the building blocks for grounded, permission-aware AI on top of your Microsoft 365 content.

If you're working out how this fits into a broader Microsoft AI roadmap, our Microsoft AI consultants can help you work through the options.

Microsoft's documentation is here: Microsoft 365 Copilot Search API overview.