The Problem That Copilot APIs Solve
Most organizations already have Microsoft 365 data—documents, emails, meetings, chats—secured under their tenant’s access controls, sensitivity labels, and conditional access policies. When they want to add AI reasoning on top of that data, the engineering question becomes immediate: how do you ground AI responses in tenant data without extracting it to an external system, and without losing the security and compliance controls that protect it?
The instinct is to build a custom pipeline. That instinct is expensive. The burden breaks into at least six distinct engineering problems that each carry ongoing operational cost:
Data extraction and ingestion. To ground an LLM in Microsoft 365 content, you must export that content—SharePoint documents, emails, meeting transcripts—to an index your pipeline controls. The moment content leaves the tenant boundary, you take on data residency risk, DLP boundary concerns, and the continuous operational cost of keeping that index fresh and in sync with the source.
Permission trimming. Microsoft 365 permission models operate at site, library, item, and label level. A custom retrieval layer must enforce the same access boundaries that Microsoft Graph enforces natively, or you risk returning content to users who should not see it. This is not a configuration detail—it is a security boundary, and getting it wrong is a security incident.
Sensitivity label and policy propagation. Microsoft Purview sensitivity labels carry information protection policies that govern what can be done with labelled content. A custom pipeline operating outside the platform boundary must read, honour, and propagate those labels at retrieval time. The Copilot APIs operate inside the platform’s policy enforcement layer, where this is handled natively.
Conditional access enforcement. Conditional access policies govern when and from where tenant data can be accessed. A pipeline that runs outside that enforcement boundary must re-implement equivalent controls or accept documented gaps in compliance posture.
Responsible AI validation. Content safety, harmful content filtering, and compliance enforcement are not capabilities that come free with any LLM deployment. The Microsoft documentation explicitly identifies responsible AI validation checks as part of what the Copilot API platform provides—capabilities that a custom build has to implement and maintain independently.
Ongoing operational cost. Index freshness, incremental update pipelines, scale management, and retrieval quality monitoring are not one-time engineering investments. They are continuous commitments that compete with product roadmap work indefinitely.
Microsoft 365 Copilot APIs are Microsoft’s answer to that burden. They expose AI reasoning capabilities over Microsoft 365 data directly through Microsoft Graph, with your existing tenant’s security and compliance controls inherited—not reconstructed—at the API layer. The semantic index that powers AI grounding over tenant content is built and maintained by Microsoft as part of the platform; you consume it through the API rather than operating it yourself.
What Copilot APIs Are and Where They Live
Copilot APIs are REST APIs exposed under two namespaces inside Microsoft Graph:
graph.microsoft.com/v1.0/copilot/...— production-ready endpointsgraph.microsoft.com/beta/copilot/...— preview endpoints (not for production use)
The key distinction between plain Microsoft Graph APIs and Copilot APIs is what they do. Graph APIs are for CRUD operations—read a user, send a mail, query a calendar event. Copilot APIs are for AI reasoning over that data: semantic retrieval, grounded chat responses, meeting intelligence extraction, and activity change notifications. Different purpose, same authentication model.
One API surface, Work IQ, uses a separate endpoint (workiq.svc.cloud.microsoft) and is also in preview.
The eight named API surfaces in this series, with current status:
| API Surface | Status | Endpoint namespace |
|---|---|---|
| Retrieval API | GA | /v1.0/copilot |
| Meeting Insights API | GA | /v1.0/copilot |
| Copilot Usage Reports API | GA | /v1.0/ |
| Search API | Preview | /beta/copilot |
| Chat API | Preview | /beta/copilot |
| AI Interactions Change Notifications | Preview | /beta/ |
| Package Management API | Preview | /beta/copilot |
| Work IQ API | Preview | workiq.svc.cloud.microsoft |
This post is an orientation — each surface gets a dedicated post (Posts 5–9) with request shapes, permission details, and practical guidance.
When to Use Copilot APIs vs the Alternatives
Copilot APIs are not the right fit for every scenario. Four paths exist for building AI-powered experiences on Microsoft 365 data. Each is legitimate; the question is which matches your constraints.
| Path | When to choose it | Key tradeoff |
|---|---|---|
| Copilot APIs (this series) | Need AI reasoning over M365 data with tenant security and compliance inherited | Microsoft 365 Copilot license required per user; several surfaces still in preview |
| Microsoft Graph CRUD APIs only | Need direct data access or manipulation—no AI reasoning required | No Copilot reasoning layer; data retrieval, processing, and AI are your responsibility |
| Azure OpenAI + custom RAG pipeline | Need full control over model selection, orchestration logic, or data sources outside M365 | You own data ingestion, indexing, retrieval, permission trimming, responsible AI, and compliance enforcement entirely |
| Copilot Studio (low-code path) | Prefer a low-code/no-code declarative agent build without custom code | Orchestration model and platform boundaries differ from a fully custom engine approach |
Decision guidance by scenario
Choose Copilot APIs when: your scenario is grounding AI responses in data users already have access to inside Microsoft 365—documents, meetings, chats—and you need those responses to respect existing permissions without rebuilding the retrieval and enforcement layer. The canonical signal: “Surface M365-grounded answers inside our line-of-business app, with permissions respected, without building a retrieval stack.”
Choose Graph CRUD APIs when: you need to read, write, or manipulate Microsoft 365 data programmatically—query SharePoint lists, send calendar invites, retrieve email metadata—and no AI reasoning is required. Graph APIs are sufficient and appropriate here. Note that in practice many applications use both: Graph for data operations and Copilot APIs for AI reasoning in the same integration. They share the same authentication model, which makes this combination straightforward.
Choose Azure OpenAI + custom RAG when: you need control that the Copilot API surface does not provide. Specific signals include: you need to ground responses in data sources that live outside Microsoft 365, your orchestration requirements exceed what the Copilot API contracts support, or your compliance requirements mandate full ownership of the retrieval and processing stack. Accept that this path means owning every layer described in the problem decomposition above—the capability flexibility comes with the full operational burden.
Choose Copilot Studio when: the builder is a business analyst or power user who wants to configure a declarative agent without writing code. Copilot Studio is a distinct runtime and orchestration model with its own platform boundaries. It is not a simpler variant of the Copilot API path—it is a different product tier for a different builder persona.
Where the boundaries get blurry
Two cases often cause teams to misroute their design:
The first is the Graph-only temptation: teams already comfortable with Microsoft Graph sometimes try to replicate AI reasoning by pulling raw content through Graph CRUD APIs and piping it to an LLM themselves. This recreates the custom RAG burden at smaller scale—you still own the permission-trimming, chunking, and responsible AI layers, without the platform providing them. If the scenario warrants AI reasoning over M365 data with compliance controls intact, Copilot APIs are the designed path.
The second is the Copilot Studio confusion: Copilot Studio can call custom APIs, but it is not a code-first integration platform. If your requirements include direct API integration, custom business logic, or embedding AI capabilities inside an existing application, the Copilot API path is the appropriate choice.
Licensing and Prerequisites
Before any Copilot API call succeeds, two licensing conditions must be satisfied:
- Microsoft 365 Copilot license — required per user for Copilot API access. This is stated directly in the Microsoft documentation; it is not optional.
- Microsoft 365 base subscription — Microsoft 365 E3/E5 or an equivalent eligible plan is foundational.
For users who meet both conditions: Copilot APIs are available at no additional API charge. There is no per-call cost on top of the existing license.
One exception applies in preview: the Retrieval API has a pay-as-you-go path for non-licensed users, but this is a preview capability with scope limitations. Do not treat it as a production licensing strategy.
For the current full list of eligible SKUs, refer to the Microsoft 365 Copilot licensing page directly. Licensing details change; a blog post is not the right long-term source for this.
Cautious wording: Licensing eligibility can change. Always verify against the official Microsoft licensing documentation before committing to a procurement or deployment plan.
Pre-Flight Checklist: Before Your Team Commits to Copilot APIs
Teams that skip the readiness evaluation tend to discover blockers late—often after app registration, integration design, and stakeholder alignment work is already complete. Before committing to Copilot API integration, work through this checklist.
Licensing
- Confirm that the target users hold a Microsoft 365 Copilot license. The API will not return results for unlicensed users regardless of how the application is registered or configured. This is not a graceful degradation—it is a hard prerequisite.
- Confirm the tenant’s underlying Microsoft 365 subscription (E3/E5 or equivalent eligible plan). The Copilot license requires this foundation.
- Understand the cost model: Copilot APIs are available at no additional per-call charge for licensed users. The cost is in the license itself. The Retrieval API has a preview pay-as-you-go path for non-licensed users, but do not plan production architecture around a preview pricing model.
Tenant and platform configuration
- Verify that Microsoft 365 Copilot is enabled and deployed for the relevant users in your tenant. An inactive Copilot deployment does not automatically make the APIs available to those users.
- Understand that the semantic index—the Microsoft-managed index that powers AI grounding over tenant content—is built and maintained by Microsoft. You do not manage or provision it directly. Users who have not had Copilot active will not have a complete semantic index, which affects the quality and completeness of API responses.
App registration and permissions
- Register an application in Microsoft Entra ID using the same process as any Microsoft Graph integration.
- Identify the specific permissions required for each Copilot API surface you plan to use. Permission requirements differ by surface; do not assume a single broad delegated permission covers all surfaces. The per-surface permission requirements are detailed in Post 02.
- Plan for admin consent. Copilot API permissions require tenant administrator consent—individual user consent is not sufficient for most Copilot API surfaces.
Preview governance
- Identify every API surface in your integration design that is currently under
/beta. For each one: document which surface it is, establish a mechanism to track Microsoft announcements about that surface, and define an internal policy for what happens if the API shape changes before your integration ships. - Do not ship production code that depends on
/betaendpoints. If a required surface is in preview, treat the integration as explicitly provisional and maintain a migration plan for when it reaches GA.
Compliance review
- Review the Copilot API Terms of Use with your legal and compliance team before committing to contractual obligations. The Terms of Use are currently labelled preview; verify their current status before use.
- Confirm data handling requirements with your data governance team. Understand where AI reasoning executes relative to your tenant’s data residency boundaries.
Namespace, Authentication, and Permission Basics
Copilot APIs use the same Microsoft Entra ID authentication model as all other Microsoft Graph APIs. Token acquisition flows, consent models, and SDK patterns are identical. If your team already integrates with Microsoft Graph, the authentication plumbing for Copilot APIs is not new work.
Two permission types apply across Copilot API surfaces:
- Delegated permissions — the API acts on behalf of a signed-in user. Required for scenarios where user context matters (for example, retrieving content the signed-in user has access to).
- Application permissions — the API runs as a background service with no user present. Available on some surfaces, not all.
Not every Copilot API surface supports both permission types equally. The per-surface permission requirements are covered in detail in Post 02 (Auth, Permissions, SDK Patterns, and Production Readiness), which is the recommended next read for developers.
GA vs Preview: What This Means for Your Production Decisions
The /v1.0/ and /beta/ path distinction is not cosmetic. Microsoft explicitly states that /beta APIs are not supported for production use. Behaviour, shape, and availability can change before a beta API reaches GA.
GA and preview status for this series
| Claim | Confidence level | Basis |
|---|---|---|
Retrieval API available under /v1.0/copilot | GA — verified | Microsoft docs, no beta label |
Meeting Insights API available under /v1.0/copilot | GA — verified | Microsoft docs, no beta label |
Copilot Usage Reports API available under /v1.0/ | GA — verified | Microsoft docs |
Chat API available under /beta/copilot | Preview — not for production | Microsoft docs, explicit preview statement |
Search API available under /beta/copilot | Preview — not for production | Microsoft docs, limited to OneDrive for work/school data |
AI Interactions Change Notifications available under /beta/ | Preview — not for production | Microsoft docs |
Package Management API available under /beta/copilot | Preview — not for production | Microsoft docs |
Work IQ API at workiq.svc.cloud.microsoft | Preview — not for production | Microsoft docs |
| Copilot API Terms of Use | Labelled preview | Microsoft legal/terms page |
The Copilot API Terms of Use are themselves labelled preview. GA endpoints under /v1.0/ can be used in production integrations; endpoints under /beta/ cannot—regardless of how stable they appear in testing.
If a preview API you are evaluating graduates to GA during this series, a follow-up post will note the change. Do not assume stability based on current /beta/ behaviour.
Common mistakes when reading the /v1.0 and /beta surfaces
Treating beta stability in testing as a GA signal. A /beta endpoint that behaves consistently across weeks of testing is still a preview endpoint. Testing results tell you nothing about future API shape. Microsoft reserves the right to modify or remove beta API capabilities without the advance notice that applies to GA endpoints.
Designing data contracts against beta response schemas. Beta response schemas frequently differ from the eventual GA shape. If you design database columns, API response models, UI field bindings, or downstream integration contracts against beta response properties, expect to rework them when the API graduates. Treat beta schema as informational until GA is confirmed.
Assuming application permissions work across all surfaces. Some Copilot API surfaces only support delegated permissions—they require a signed-in user and cannot be called by a background service or daemon. Designing a background integration against an endpoint that only supports delegated access will fail at runtime, not at design time. Check the permission model for each surface individually. Post 02 covers this in detail.
Misreading the Search API scope. The Search API under /beta/copilot is currently scoped to OneDrive for work/school data only. It is not a full-tenant or cross-service search surface in its current preview form. Misreading that scope leads to integration designs that do not match what the API can actually return—often discovered only after significant design work.
Planning production timelines around preview surfaces without a contingency. If your integration depends on a surface currently in preview, building your production launch date around an assumed GA timeline is a planning risk. Preview APIs graduate on Microsoft’s schedule, not yours. Build timelines that account for the possibility that a needed surface remains in preview longer than anticipated.
How to Navigate This Series
This series runs 13 posts across three phases:
- Phase 1 — Foundations and Governance (Posts 1–4): Landscape, auth fundamentals, usage reporting, and admin package management
- Phase 2 — Core APIs (Posts 5–9): One post per API surface — Retrieval, Search, Chat, Meeting Insights, and AI Interactions Change Notifications
- Phase 3 — Agents and Extensibility (Posts 10–13): Declarative and custom agents, Copilot Studio, connectors, and integration patterns
Read next based on your role:
- IT admins and Copilot deployment leads: Post 01 → Post 03 (Usage Reports API) → Post 04 (Package Management API, preview)
- Developers starting to build: Post 01 → Post 02 (Auth and Permissions) → Post 05 (Retrieval API) or Post 07 (Chat API, preview, based on your scenario)
- Architects evaluating the platform: Post 01 → Post 02 → all of Phase 2 → Phase 3
The immediate next post is Post 02 — Auth, Permissions, SDK Patterns, and Production Readiness.
References
All claims in this post are traced to the following official Microsoft documentation sources:
- Microsoft 365 Copilot APIs overview
- Microsoft 365 Copilot extensibility overview
- Microsoft 365 Copilot extensibility planning guide
- Microsoft 365 Copilot extensibility cost considerations
- Microsoft 365 Copilot licensing
- Retrieval API overview
- Chat API overview
- Search API overview
- Work IQ API overview
- Microsoft 365 Copilot architecture
- Semantic index for Copilot
- Microsoft Graph authentication concepts
- Microsoft 365 Copilot APIs terms of use