REST APIs under the Microsoft Graph /copilot/ namespace that enable secure access to Microsoft 365 Copilot capabilities including retrieval, chat, and search, for use in custom applications and agents.
openapi: 3.1.0
info:
title: Microsoft Copilot Microsoft 365 Copilot APIs
description: >-
REST APIs under the Microsoft Graph /copilot/ namespace that enable secure
access to Microsoft 365 Copilot capabilities including retrieval, search,
chat, interaction export, and change notifications. These APIs provide
production-ready AI capabilities that work directly with Microsoft 365 data
while respecting existing permissions, sensitivity labels, compliance
controls, and policy enforcement.
version: 1.0.0
contact:
name: Microsoft Graph Support
url: https://learn.microsoft.com/en-us/graph/overview
license:
name: Microsoft API Terms of Use
url: https://learn.microsoft.com/en-us/legal/microsoft-apis/terms-of-use
termsOfService: https://learn.microsoft.com/en-us/legal/m365-copilot-apis/terms-of-use
externalDocs:
description: Microsoft 365 Copilot APIs Overview
url: https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/copilot-apis-overview
servers:
- url: https://graph.microsoft.com/v1.0
description: Microsoft Graph v1.0 (production)
- url: https://graph.microsoft.com/beta
description: Microsoft Graph beta (preview)
security:
- oauth2: []
tags:
- name: Change Notifications
description: >-
Subscribe to change notifications for Copilot interactions across
Microsoft 365.
externalDocs:
url: https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/api/ai-services/change-notifications/aiinteraction-changenotifications
- name: Chat
description: >-
Programmatically start and continue conversations with Microsoft 365
Copilot using enterprise search and web search grounding. Preview API.
externalDocs:
url: https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/api/ai-services/chat/overview
- name: Interaction Export
description: >-
Export and archive user interactions with Copilot across Microsoft 365
applications for compliance and auditing.
externalDocs:
url: https://learn.microsoft.com/en-us/microsoftteams/export-teams-content
- name: Retrieval
description: >-
Retrieve relevant text chunks from SharePoint, OneDrive, and Copilot
connectors content for Retrieval Augmented Generation (RAG) scenarios.
externalDocs:
url: https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/api/ai-services/retrieval/overview
- name: Search
description: >-
Perform hybrid search (semantic and lexical) across OneDrive for work or
school content using natural language queries. Preview API.
externalDocs:
url: https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/api/ai-services/search/overview
paths:
/copilot/retrieval:
post:
operationId: copilot.retrieval
summary: Microsoft Copilot Retrieve Grounding Data
description: >-
Retrieve relevant text extracts from SharePoint, OneDrive, and Copilot
connectors content that the calling user has access to, while respecting
defined access controls within the tenant. Use this endpoint to ground
generative AI solutions with Microsoft 365 data while optimizing for
context recall. Results include text snippets with relevance scores,
sensitivity labels, and optional resource metadata.
tags:
- Retrieval
externalDocs:
url: https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/api/ai-services/retrieval/copilotroot-retrieval
security:
- oauth2:
- Files.Read.All
- Sites.Read.All
parameters:
- $ref: '#/components/parameters/authorizationHeader'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RetrievalRequest'
examples:
sharePointRetrieval:
summary: Retrieve from SharePoint with metadata
value:
queryString: How to setup corporate VPN?
dataSource: sharePoint
resourceMetadata:
- title
- author
maximumNumberOfResults: 10
filteredRetrieval:
summary: Retrieve from a specific SharePoint site
value:
queryString: How to setup corporate VPN?
dataSource: sharePoint
filterExpression: 'path:"https://contoso.sharepoint.com/sites/HR1/"'
resourceMetadata:
- title
- author
maximumNumberOfResults: 4
connectorRetrieval:
summary: Retrieve from Copilot connectors
value:
queryString: How to setup corporate VPN?
dataSource: externalItem
dataSourceConfiguration:
externalItem:
connections:
- connectionId: ContosoITServiceNowKB
- connectionId: ContosoHRServiceNowKB
resourceMetadata:
- title
- author
maximumNumberOfResults: 10
responses:
'200':
description: Retrieval results returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/RetrievalResponse'
examples:
sharePointResults:
summary: SharePoint retrieval results
value:
retrievalHits:
- webUrl: https://contoso.sharepoint.com/sites/HR/VPNAccess.docx
extracts:
- text: >-
To configure the VPN, click the Wi-Fi icon on your
corporate device and select the VPN option.
relevanceScore: 0.8374363553387588
- text: >-
You will need to sign in with 2FA to access the
corporate VPN.
relevanceScore: 0.7465472642498679
resourceType: listItem
resourceMetadata:
title: VPN Access
author: John Doe
sensitivityLabel:
sensitivityLabelId: f71f1f74-bf1f-4e6b-b266-c777ea76e2s8
displayName: Confidential\Any User (No Protection)
priority: 4
color: '#FF8C00'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/copilot/search:
post:
operationId: copilot.search
summary: Microsoft Copilot Perform Hybrid Search
description: >-
Perform hybrid search (semantic and lexical) across OneDrive for work or
school content using natural language queries with contextual
understanding and intelligent results. Discover relevant documents and
files while respecting defined access controls within the organization.
This API is currently in preview.
tags:
- Search
externalDocs:
url: https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/api/ai-services/search/copilotroot-search
security:
- oauth2:
- Files.Read.All
- Sites.Read.All
parameters:
- $ref: '#/components/parameters/authorizationHeader'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SearchRequest'
examples:
basicSearch:
summary: Basic search request
value:
query: How to setup corporate VPN?
filteredSearch:
summary: Search with path filtering and metadata
value:
query: quarterly budget analysis
pageSize: 2
dataSources:
oneDrive:
filterExpression: 'path:"https://contoso-my.sharepoint.com/personal/megan_contoso_com/Documents/Finance/"'
resourceMetadataNames:
- title
- author
responses:
'200':
description: Search results returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/SearchResponse'
examples:
basicResults:
summary: Basic search results
value:
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
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/copilot/chat/conversations:
post:
operationId: copilot.chat.startConversation
summary: Microsoft Copilot Start a Chat Conversation
description: >-
Start a new multi-turn conversation with Microsoft 365 Copilot. The Chat
API allows you to programmatically engage in conversations using
enterprise search grounding and web search grounding. Responses are
grounded in Microsoft 365 data and web content while respecting all
existing permissions and compliance controls. This API is currently in
preview.
tags:
- Chat
externalDocs:
url: https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/api/ai-services/chat/overview
security:
- oauth2:
- Chat.Read
parameters:
- $ref: '#/components/parameters/authorizationHeader'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ChatConversationRequest'
examples:
startConversation:
summary: Start a new conversation
value:
prompt: What are the key highlights from last quarter's financial report?
conversationWithOptions:
summary: Start conversation with web search disabled
value:
prompt: Summarize the latest HR policy changes
enableWebSearch: false
responses:
'200':
description: Conversation started and response returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ChatConversationResponse'
examples:
CopilotChatStartconversation200Example:
summary: Default copilot.chat.startConversation 200 response
x-microcks-default: true
value:
conversationId: '500123'
message:
id: abc123
body:
contentType: example_value
content: example_value
citations:
- {}
createdDateTime: '2026-01-15T10:30:00Z'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/copilot/chat/conversations/{conversationId}/messages:
post:
operationId: copilot.chat.continueConversation
summary: Microsoft Copilot Continue a Chat Conversation
description: >-
Send a follow-up message in an existing multi-turn conversation with
Microsoft 365 Copilot. Uses the conversation context from prior turns to
provide more relevant and contextual responses.
tags:
- Chat
security:
- oauth2:
- Chat.Read
parameters:
- $ref: '#/components/parameters/authorizationHeader'
- name: conversationId
in: path
required: true
description: The unique identifier of the conversation to continue.
schema:
type: string
example: '500123'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ChatMessageRequest'
examples:
followUp:
summary: Send a follow-up message
value:
prompt: Can you provide more details on the revenue figures?
responses:
'200':
description: Message sent and response returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ChatMessageResponse'
examples:
CopilotChatContinueconversation200Example:
summary: Default copilot.chat.continueConversation 200 response
x-microcks-default: true
value:
message:
id: abc123
body:
contentType: example_value
content: example_value
citations:
- {}
createdDateTime: '2026-01-15T10:30:00Z'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/copilot/interactionHistory/getAllEnterpriseInteractions:
get:
operationId: copilot.interactionHistory.getAllEnterpriseInteractions
summary: Microsoft Copilot List All Enterprise Copilot Interactions
description: >-
Retrieve all Copilot interactions across the organization for compliance
and auditing purposes. Returns aiInteraction objects representing
user prompts and Copilot responses across Microsoft 365 applications.
Requires compliance administrator permissions.
tags:
- Interaction Export
externalDocs:
url: https://learn.microsoft.com/en-us/microsoftteams/export-teams-content
security:
- oauth2:
- AIInteraction.Read.All
parameters:
- $ref: '#/components/parameters/authorizationHeader'
- name: $filter
in: query
description: OData filter expression to filter interactions by date range, user, or application.
schema:
type: string
example: createdDateTime ge 2025-01-01T00:00:00Z and createdDateTime le 2025-03-31T23:59:59Z
- name: $top
in: query
description: Maximum number of interactions to return per page.
schema:
type: integer
minimum: 1
maximum: 999
default: 50
example: 10
- name: $skipToken
in: query
description: Pagination token for retrieving the next page of results.
schema:
type: string
example: example_value
responses:
'200':
description: List of Copilot interactions returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/AiInteractionCollectionResponse'
examples:
CopilotInteractionhistoryGetallenterpriseinteractions200Example:
summary: Default copilot.interactionHistory.getAllEnterpriseInteractions 200 response
x-microcks-default: true
value:
'@odata.context': example_value
'@odata.nextLink': https://www.example.com
value:
- id: abc123
appClass: example_value
interactionType: userPrompt
conversationType: example_value
requestId: '500123'
sessionId: '500123'
createdDateTime: '2026-01-15T10:30:00Z'
etag: example_value
locale: example_value
attachments: {}
contexts: {}
links: {}
mentions: {}
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/subscriptions:
post:
operationId: copilot.changeNotifications.createSubscription
summary: Microsoft Copilot Create Subscription for Copilot Interaction Notifications
description: >-
Create a change notification subscription to monitor Copilot interactions
across Microsoft 365 in real time. Enables proactive compliance checks,
anomaly detection, and auditing of AI interactions. The resource path
for Copilot interactions is
/copilot/interactionHistory/getAllEnterpriseInteractions.
tags:
- Change Notifications
externalDocs:
url: https://learn.microsoft.com/en-us/microsoft-365-copilot/extensibility/api/ai-services/change-notifications/aiinteraction-changenotifications
security:
- oauth2:
- AIInteraction.Read.All
parameters:
- $ref: '#/components/parameters/authorizationHeader'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionRequest'
examples:
copilotInteractionSubscription:
summary: Subscribe to Copilot interaction changes
value:
changeType: created
notificationUrl: https://contoso.azurewebsites.net/api/notifications
resource: /copilot/interactionHistory/getAllEnterpriseInteractions
expirationDateTime: '2025-04-01T11:00:00.0000000Z'
clientState: secretClientState
responses:
'201':
description: Subscription created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Subscription'
examples:
CopilotChangenotificationsCreatesubscription201Example:
summary: Default copilot.changeNotifications.createSubscription 201 response
x-microcks-default: true
value:
id: abc123
resource: example_value
changeType: example_value
notificationUrl: https://www.example.com
expirationDateTime: '2026-01-15T10:30:00Z'
clientState: example_value
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
securitySchemes:
oauth2:
type: oauth2
description: >-
OAuth 2.0 authorization using Microsoft identity platform (Azure AD).
Requires a Microsoft 365 Copilot license for each user accessing
Copilot API functionality.
flows:
authorizationCode:
authorizationUrl: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
tokenUrl: https://login.microsoftonline.com/common/oauth2/v2.0/token
scopes:
Files.Read.All: Read all files the user can access
Sites.Read.All: Read items in all site collections
ExternalItem.Read.All: Read external items from Copilot connectors
Chat.Read: Read user chat messages
AIInteraction.Read.All: Read all AI interactions for compliance
parameters:
authorizationHeader:
name: Authorization
in: header
required: true
description: 'Bearer token obtained via OAuth 2.0. Format: Bearer {token}'
schema:
type: string
pattern: ^Bearer\s.+$
schemas:
RetrievalRequest:
type: object
required:
- queryString
- dataSource
properties:
queryString:
type: string
maxLength: 1500
description: >-
Natural language query string used to retrieve relevant text
extracts. Should be a single sentence. Avoid spelling errors in
context-rich keywords.
example: example_value
dataSource:
type: string
enum:
- sharePoint
- oneDriveBusiness
- externalItem
description: >-
Indicates whether extracts should be retrieved from SharePoint,
OneDrive, or Copilot connectors.
example: sharePoint
dataSourceConfiguration:
$ref: '#/components/schemas/DataSourceConfiguration'
filterExpression:
type: string
description: >-
Keyword Query Language (KQL) expression with queryable properties to
scope retrieval. Supports AND, OR, NOT, and inequality operators.
Supported SharePoint/OneDrive properties include Author,
FileExtension, Filename, FileType, InformationProtectionLabelId,
LastModifiedTime, ModifiedBy, Path, SiteID, and Title.
example: example_value
resourceMetadata:
type: array
items:
type: string
description: >-
List of metadata fields to return for each item. Only retrievable
metadata properties can be included. By default, no metadata is
returned.
example: []
maximumNumberOfResults:
type: integer
minimum: 1
maximum: 25
default: 25
description: >-
Number of results to return. Must be between 1 and 25. Defaults to
25.
example: 10
DataSourceConfiguration:
type: object
description: Additional configuration for applicable data sources.
properties:
externalItem:
type: object
description: Configuration for Copilot connectors retrieval.
properties:
connections:
type: array
description: List of specific Copilot connector connections to retrieve from.
items:
type: object
properties:
connectionId:
type: string
description: The identifier of the Copilot connector connection.
example: example_value
RetrievalResponse:
type: object
properties:
retrievalHits:
type: array
description: Collection of retrieval results with text extracts.
items:
$ref: '#/components/schemas/RetrievalHit'
example: []
RetrievalHit:
type: object
properties:
webUrl:
type: string
format: uri
description: The URL of the source document.
example: https://www.example.com
extracts:
type: array
description: Collection of relevant text extracts from the document.
items:
$ref: '#/components/schemas/RetrievalExtract'
example: []
resourceType:
type: string
description: >-
The type of resource. Values include listItem (for SharePoint/OneDrive)
and externalItem (for Copilot connectors).
enum:
- listItem
- externalItem
example: listItem
resourceMetadata:
type: object
additionalProperties:
type: string
description: >-
Metadata fields for the resource, as requested via the
resourceMetadata parameter. Keys and values depend on the requested
fields.
example: example_value
sensitivityLabel:
$ref: '#/components/schemas/SensitivityLabel'
RetrievalExtract:
type: object
properties:
text:
type: string
description: The relevant text extract from the document.
example: example_value
relevanceScore:
type: number
format: double
minimum: 0
maximum: 1
description: >-
Cosine similarity between the queryString and the extract, normalized
to the 0-1 range. May be absent for Copilot connectors results.
example: 42.5
SensitivityLabel:
type: object
description: Information protection sensitivity label applied to the document.
properties:
sensitivityLabelId:
type: string
description: The unique identifier of the sensitivity label.
example: '500123'
displayName:
type: string
description: The display name of the sensitivity label.
example: example_value
toolTip:
type: string
description: Tooltip text describing the sensitivity label.
example: example_value
priority:
type: integer
description: The priority of the sensitivity label.
example: 10
color:
type: string
description: The color code associated with the sensitivity label.
example: example_value
SearchRequest:
type: object
required:
- query
properties:
query:
type: string
maxLength: 1500
description: Natural language query to search for relevant files.
example: example_value
pageSize:
type: integer
minimum: 1
maximum: 100
default: 25
description: Number of results to return per page (1-100). Default is 25.
example: 10
dataSources:
$ref: '#/components/schemas/CopilotSearchDataSourcesConfiguration'
CopilotSearchDataSourcesConfiguration:
type: object
description: Configuration for data sources to include in the search.
properties:
oneDrive:
type: object
description: OneDrive data source configuration.
properties:
filterExpression:
type: string
description: >-
KQL expression to scope the search to specific OneDrive paths or
properties.
resourceMetadataNames:
type: array
items:
type: string
description: List of metadata field names to return for each search result.
example: example_value
SearchResponse:
type: object
properties:
'@odata.nextLink':
type: string
format: uri
description: URL to retrieve the next page of results, if available.
example: https://www.example.com
totalCount:
type: integer
description: Total number of matching results.
example: 10
searchHits:
type: array
description: Collection of search result items.
items:
$ref: '#/components/schemas/SearchHit'
example: []
SearchHit:
type: object
properties:
webUrl:
type: string
format: uri
description: The URL of the matching document.
example: https://www.example.com
preview:
type: string
description: A preview snippet of the matching content.
example: example_value
resourceType:
type: string
description: The type of resource (e.g., driveItem).
example: example_value
resourceMetadata:
type: object
additionalProperties:
type: string
description: Metadata fields for the resource, if requested.
example: example_value
ChatConversationRequest:
type: object
required:
- prompt
properties:
prompt:
type: string
description: >-
Natural language prompt to send to Microsoft 365 Copilot to start a
conversation.
example: example_value
enableWebSearch:
type: boolean
default: true
description: >-
Whether to enable web search grounding for this message. Defaults to
true. Must be toggled off per message if not desired.
example: true
fileReferences:
type: array
description: >-
Optional OneDrive and SharePoint file references to provide as
additional context.
items:
type: object
properties:
url:
type: string
format: uri
description: The URL of the file to reference.
example: []
ChatConversationResponse:
type: object
properties:
conversationId:
type: string
description: The unique identifier for the conversation for multi-turn use.
example: '500123'
message:
$ref: '#/components/schemas/ChatMessage'
ChatMessageRequest:
type: object
required:
- prompt
properties:
prompt:
type: string
description: Natural language prompt to continue the conversation.
example: example_value
enableWebSearch:
type: boolean
default: true
description: Whether to enable web search grounding for this message.
example: true
ChatMessageResponse:
type: object
properties:
message:
$ref: '#/components/schemas/ChatMessage'
ChatMessage:
type: object
properties:
id:
type: string
description: The unique identifier for the message.
example: abc123
body:
type: object
properties:
contentType:
type: string
description: The content type of the body (e.g., text, html).
content:
type: string
description: The text content of the Copilot response.
example: example_value
citations:
type: array
description: Sources referenced in the Copilot response.
items:
type: object
properties:
title:
type: string
description: The title of the cited source.
url:
type: string
format: uri
description: The URL of the cited source.
snippet:
type: string
description: A relevant snippet from the cited source.
example: []
createdDateTime:
type: string
format: date-time
description: The timestamp when the message was created.
example: '2026-01-1
# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/microsoft-copilot/refs/heads/main/openapi/microsoft-copilot-openapi.yml