Copilot APIs for M365 Developers: 03 - Building Search Experiences with the Search API

Hi everyone!

Welcome to the third installment of my series on Microsoft 365 Copilot APIs! In the first post, I gave you an overview of all available APIs, and in the second post, we did a deep dive into the Chat API with a real-world SPFx sample. Today, we’re exploring another powerful capability: the Search API.

What is the Search API?

The Microsoft 365 Copilot Search API enables you to perform hybrid search (combining both semantic and lexical search) across OneDrive for work or school content using natural language queries. Unlike traditional keyword-based search, this API understands context and intent, returning the most relevant documents and files to your users.

⚠️ Important Note: At the time of writing, the Search API is in Preview status. This means it’s available under the /beta endpoint and is subject to change. Use of these APIs in production applications is not supported. Always check the official documentation for the most current status.

Why Use the Search API?

You might be wondering: “Why should I use this API when I can build my own search with Azure AI Search or Microsoft Graph Search API?” Great question. Let me explain why the Search API is particularly compelling.

🔍 Hybrid Search Out of the Box

The Search API combines semantic search (understanding meaning and context) with lexical search (traditional keyword matching) to deliver highly relevant results. Building this yourself would require:

• Setting up a vector database for semantic search
• Implementing a traditional search index for lexical search
• Creating a ranking algorithm to combine both approaches
• Continuously keeping both indexes synchronized

With the Search API, Microsoft has already done all of this work. You get enterprise-grade hybrid search capabilities without building or maintaining the underlying infrastructure.

🔒 Security and Compliance Built-In

Here’s what gets me most excited: permissions are respected automatically. The Search API:

• Only returns results the user is authorized to access
• Respects sensitivity labels and information barriers
• Maintains all compliance settings your organization has configured
• Keeps data in place without requiring export or duplication

This means you don’t need to build complex permission-trimming logic or worry about inadvertently exposing sensitive content.

💰 No Additional Infrastructure Costs

If your users have Microsoft 365 Copilot licenses, the Search API is included at no extra cost. You’re not paying for:

• Separate Azure AI Search instances
• Vector database hosting
• Storage for duplicated content
• Compute resources for indexing pipelines

The semantic index that powers Microsoft 365 Copilot is already there, and you can leverage it directly.

🎯 Always Fresh, Always Relevant

Because the Search API searches data in place on OneDrive, the results are always current. There’s no synchronization lag, no stale indexes, and no need to worry about keeping search data up to date. When a user searches, they get results based on the latest state of their content.

⚖️ When This Makes Sense (and When It Doesn’t)

Let’s be realistic about the current scope and limitations:

Great for:

• Document discovery applications
• Knowledge management solutions
• Custom search experiences grounded in OneDrive content
• Contextual file recommendations
• Enterprise content exploration tools

Not suitable for (yet):

• Searching SharePoint sites (currently only OneDrive is supported)
• Searching data outside Microsoft 365
• Scenarios requiring advanced KQL filtering beyond path expressions
• Applications needing to search more than OneDrive content sources

The good news? Microsoft is actively expanding the Search API. Support for SharePoint, Copilot Connectors, and other data sources is planned for future releases.

Search API Capabilities

The Search API provides the following capabilities:

• Hybrid Search: Combines semantic understanding with traditional keyword matching
• Natural Language Queries: Users can search using natural language, not just keywords
• Path-based Filtering: Scope searches to specific OneDrive folders using KQL path expressions
• Metadata Retrieval: Request specific metadata fields (title, author, etc.) in search results
• Pagination: Handle large result sets with customizable page sizes
• Batch Support: Execute up to 20 search requests in a single batch call

Working with the Search API

Let’s walk through how to use the Search API, from basic queries to advanced scenarios.

Required Permissions

Before you start, configure these Microsoft Graph permissions for your application:

• Files.Read.All or Files.ReadWrite.All
• Sites.Read.All or Sites.ReadWrite.All

⚠️ Important: Only delegated permissions (work or school account) are supported. Application permissions are not supported.

Basic Search Request

The simplest search request requires just a natural language query:

POST https://graph.microsoft.com/beta/copilot/search
Content-Type: application/json

{
  "query": "How to setup corporate VPN?"
}

The response includes search results with previews and web URLs:

{
  "totalCount": 2,
  "searchHits": [
    {
      "webUrl": "https://contoso.sharepoint.com/sites/IT/VPNAccess.docx",
      "preview": "To configure the VPN, click the Wi-Fi icon on your corporate device and select the VPN option...",
      "resourceType": "driveItem"
    },
    {
      "webUrl": "https://contoso.sharepoint.com/sites/IT/Corporate_VPN.docx",
      "preview": "Once you have selected Corporate VPN under the VPN options, log in with your corporate credentials...",
      "resourceType": "driveItem"
    }
  ]
}

That’s it! No conversation creation, no complex multi-turn flow. Just send a query and get results. The Search API is stateless, which makes it perfect for building search interfaces.

Understanding the Request Parameters

The Search API accepts several parameters to customize your search:

Advanced Scenarios

Let me show you some powerful scenarios that demonstrate the full capabilities of the Search API.

Search with Filtering and Metadata

You can filter searches to specific OneDrive paths and request additional metadata:

POST https://graph.microsoft.com/beta/copilot/search
Content-Type: application/json

{
  "query": "quarterly budget analysis",
  "pageSize": 2,
  "dataSources": {
    "oneDrive": {
      "filterExpression": "path:\"https://contoso-my.sharepoint.com/personal/megan_contoso_com/Documents/Finance/\" OR path:\"https://contoso-my.sharepoint.com/personal/megan_contoso_com/Documents/Budget\"",
      "resourceMetadataNames": [
        "title",
        "author"
      ]
    }
  }
}

The response includes the requested metadata and pagination support:

{
  "@odata.nextLink": "https://graph.microsoft.com/beta/copilot/searchNextPage?$skipToken=eyJDb250aW51YXRpb25Ub2tlbiI6...",
  "totalCount": 24,
  "searchHits": [
    {
      "webUrl": "https://contoso-my.sharepoint.com/personal/megan_contoso_com/Documents/Finance/Q1_Budget_Analysis.xlsx",
      "preview": "This quarterly budget analysis shows significant improvements in operational efficiency and cost reduction across all departments...",
      "resourceType": "driveItem",
      "resourceMetadata": {
        "title": "Q1 Budget Analysis 2025",
        "author": "Megan Bowen"
      }
    },
    {
      "webUrl": "https://contoso-my.sharepoint.com/personal/megan_contoso_com/Documents/Budget/Annual_Financial_Review.docx",
      "preview": "The annual financial review demonstrates strong performance indicators and provides recommendations for the upcoming quarter...",
      "resourceType": "driveItem",
      "resourceMetadata": {
        "title": "Annual Financial Review",
        "author": "Alex Wilber"
      }
    }
  ]
}

Path-Based Filtering

Use Keyword Query Language (KQL) path expressions to scope searches to specific folders:

POST https://graph.microsoft.com/beta/copilot/search
Content-Type: application/json

{
  "query": "project timeline milestones",
  "pageSize": 2,
  "dataSources": {
    "oneDrive": {
      "filterExpression": "path:\"https://contoso-my.sharepoint.com/personal/john_contoso_com/Documents/Projects/\"",
      "resourceMetadataNames": [
        "title",
        "author"
      ]
    }
  }
}

💡 Pro Tip: Always use the full OneDrive path from the file or folder’s details pane, not a sharing link or browser address.

Batch Requests to the Search API

The Search API supports batching up to 20 requests in a single call:

POST https://graph.microsoft.com/beta/$batch
Accept: application/json
Content-Type: application/json

{
  "requests": [
    {
      "id": "1",
      "method": "POST",
      "url": "/copilot/search",
      "headers": {"Content-Type": "application/json"},
      "body": {
        "query": "quarterly budget reports"
      }
    },
    {
      "id": "2",
      "method": "POST",
      "url": "/copilot/search",
      "headers": {"Content-Type": "application/json"},
      "body": {
        "query": "project planning documents"
      }
    }
  ]
}

This is particularly useful when you need to execute multiple searches simultaneously, such as when building a dashboard with multiple search-driven widgets.

Best Practices

Microsoft provides several best practices for working with the Search API:

For All Queries

• Use all results: The Search API returns results ordered by relevance. Use all search results for comprehensive document discovery.
• Avoid overly generic queries: Be specific to get better results. Instead of “documents”, try “Q1 2026 financial reports”.
• Provide context: The more descriptive and natural language-based your query, the better the semantic understanding.
• Check spelling: Spelling errors in important keywords can significantly impact result quality.

For Filtered Queries

• Use full paths: For the path parameter, use the complete OneDrive path as shown in the file or folder’s details pane, not a sharing link or browser address.
• Example: https://contoso-my.sharepoint.com/personal/username_domain_com/Documents/Project/Report.docx

Current Limitations and Restrictions

Being in preview, the Search API has several limitations you should be aware of:

Scope Limitations

• ❌ Only OneDrive for work or school is supported as a data source (SharePoint, Copilot Connectors coming in future releases)
• ❌ Only path expressions are supported in filterExpression (more KQL properties may be supported later)
• ❌ Semantic search on non-textual content (tables, images, charts) is not supported

Query Limitations

• ⚠️ Query parameter limited to 1,500 characters
• ⚠️ Page size maximum of 100 results
• ⚠️ 200 requests per user per hour rate limit

File Limitations

• ⚠️ Files larger than 512 MB (.docx, .pptx, .pdf) are not supported for semantic search
• ⚠️ Files larger than 150 MB (other extensions) are not supported for semantic search
• ⚠️ Semantic search only available on specific file extensions: .aspx, .docx, .pptx, .pdf, .onepart, .doc, .html, .eml, .mp4, .loop, .one, .fluid, .png, .jpg, .json, .csv, .xml, .ppt

Data Coverage

• ⚠️ Semantic search is available on a personalized working set of data for OneDrive content, which does not include all content in the user’s OneDrive
• ⚠️ Subject to all limitations of the Microsoft 365 Copilot semantic index

📋 Important: If searchHits in the response payload is empty, no relevant results were found for the query.

Licensing

The Search API is available at no extra cost to users with a Microsoft 365 Copilot add-on license. Support for users without a Microsoft 365 Copilot license isn’t currently available.

📋 Review the Microsoft 365 Copilot APIs Terms of Use (preview) before building with these APIs!

Comparing Search API with Other Options

Let me clarify when to use the Search API versus other Microsoft Graph search capabilities:

The Search API is the right choice when you need intelligent, context-aware document discovery from OneDrive content for Copilot-licensed users.

Tips for Building Great Search Experiences

Based on my experimentation with the Search API, here are some practical tips:

1. Design for Natural Language

Train your users to think in questions, not keywords. Instead of a search box that expects “budget 2026”, encourage queries like “What are the latest budget projections for this year?“

2. Show Previews Prominently

The preview field in the response is gold. It provides context-aware snippets that help users quickly determine if a result is relevant. Display these prominently in your UI.

3. Leverage Metadata

Request metadata like title and author to build richer result displays. This additional context helps users identify the right document faster.

4. Implement Smart Filtering

If you’re building a departmental portal, use filterExpression to scope searches to relevant OneDrive paths by default. Users can then refine further if needed.

5. Handle Empty Results Gracefully

When searchHits is empty, don’t just show “No results found”. Suggest alternative queries or broader searches to help users find what they need.

6. Consider Batch Requests

If you’re building a dashboard with multiple search-driven components, use batch requests to reduce network overhead and improve performance.

Looking Ahead: What’s Coming

While the Search API is already powerful, Microsoft has indicated that future releases will include:

• SharePoint Support: Expand search beyond OneDrive to include SharePoint sites and libraries
• Additional Data Sources: Support for Copilot Connectors and other Microsoft 365 services
• Enhanced KQL Support: More properties beyond path for advanced filtering scenarios
• Broader File Type Support: Improved semantic search coverage for additional file types

Keep an eye on the official documentation for updates as these capabilities roll out.

This is Part of a Series

This is the third post in my series about Microsoft 365 Copilot APIs:

1. 01 - Getting Started - Overview of all available APIs
2. 02 - Deep Dive into the Chat API - Chat API with Smart Context sample
3. 03 - Building Search Experiences with the Search API (this post)
4. Coming Soon - Exporting Copilot Interactions for Compliance
5. Coming Soon - SPFx Web Parts powered by Copilot APIs

Useful Resources

• Search API Overview
• Perform Search using the Search API
• Try with Graph Explorer
• KQL Syntax Reference
• JSON Batching in Microsoft Graph

Wrapping Up

The Search API is a game-changer for building intelligent document discovery experiences in Microsoft 365. What I appreciate most is how it handles all the complexity of hybrid search, permissions, and semantic understanding for you. You just send natural language queries and get relevant, permission-trimmed results.

While it’s currently limited to OneDrive content, the foundation is incredibly solid. The combination of semantic and lexical search, automatic permission trimming, and zero infrastructure requirements makes this API a powerful tool for any developer building custom experiences in the Microsoft 365 ecosystem.

I’m particularly excited about the upcoming support for SharePoint and other data sources. Once those capabilities land, the Search API will become even more indispensable for building enterprise search experiences.

What search experiences are you planning to build with this API? Are you thinking of replacing existing custom search implementations? Let me know in the comments!

In the next post, we’ll explore the Interaction Export API for compliance scenarios, and then we’ll dive into building complete SPFx solutions that combine these APIs into cohesive experiences.

See you soon! 🚀

Federico

Content Creation Note: Portions of this post were prepared with assistance from AI tools including Copilot for M365 and GitHub Copilot, to streamline the writing process. All content has been reviewed and edited to ensure accuracy and quality.