Creating an OpenAPI Specification for Microsoft 365 Copilot Declarative Agents to Interact with SharePoint Lists

Introduction

In this blog post, I demonstrate how to create an OpenAPI specification for interacting with a SharePoint list using Microsoft Graph for integration with Microsoft 365 Copilot Declarative Agents. The list in question was created using the tracker template. This approach allows you to define and document API interactions, making it easier to integrate with tools like Microsoft 365 Agents Toolkit (previously known as Teams Toolkit) or Copilot for automation and extensibility.

Scenario

We aim to create an OpenAPI YAML file to interact with the following endpoint:

Endpoint:
https://graph.microsoft.com/v1.0/sites/{siteid}/lists/{listId}/items

Method:
POST

The request body is based on a list created using the issue tracker template.

Request Body:

{
  "fields": {
    "Title": "Widget",
    "Description": "Work to be done",
    "Progress": "In Progress",
    "Priority": "Low",
    "StartDate": "2025-04-15",
    "DueDate": "2025-04-15",
    "AssignedTo0": "i:0#.f|membership|reshmee@reshmee.onmicrosoft.com",
    "Notes": "The benefits are tremendous"
  }
}

Methods attempted

  • Kiota, Microsoft 365 Agents Toolkit and DevProxy I initially tried using Kiota, Microsoft 365 Agents Toolkit (previously known as Teams Toolkit), and Dev Proxy to generate a streamlined OpenAPI spec for retrieving and creating list items. However, these tools did not provide the desired level of simplicity for this specific use case.

  • Copilot

I used Copilot to generate the OpenAPI spec with a simple prompt: Generate OpenAPI spec using the details specified in the section scenerio section, Copilot generated a tailored OpenAPI spec. This approach was suggested by Lee Ford when we were collaborating on a joint PnP sample.

OpenAPI Specification

Below is the OpenAPI YAML file that defines the interaction with the Microsoft Graph API for creating a new item in a SharePoint list. Please find the full openapi spec from Declarative Agent - Volunteering App

info:
  title: Microsoft Graph API
  description: API to interact with SharePoint lists via Microsoft Graph
  version: 1.0.0
servers:
- url: https://graph.microsoft.com/v1.0
paths:
  /sites/{siteid}/lists/{listid}/items:
    get:
      summary: Retrieve volunteer tracker items associated with the user
      operationId: getListItems
      tags:
      - SharePoint
      parameters:
      - name: filter
        in: query
        description: Filter items by assigned user lookup ID
        required: true
        schema:
          type: string
          example: "fields/AssignedTo0LookupId eq {userId}"
          default: "fields/AssignedTo0LookupId eq {userId}"
      - name: expand
        in: query
        description: Expand fields in response
        required: false
        schema:
          type: string
          example: fields
          default: fields
      - name: siteid
        in: path
        description: The ID of the SharePoint site
        required: true
        schema:
          type: string
          default: "${{SITE_ID}}"
      - name: listid
        in: path
        description: The ID of the SharePoint list
        required: true
        schema:
          type: string
          default: "${{LIST_ID}}"
      responses:
        '200':
          description: Successful retrieval of list items
          content:
            application/json:
              schema:
                type: object
                properties:
                  '@odata.context':
                    type: string
                    description: Metadata context URL
                  value:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Item ID
                        createdDateTime:
                          type: string
                          format: date-time
                          description: Creation timestamp
                        lastModifiedDateTime:
                          type: string
                          format: date-time
                          description: Last modification timestamp
                        webUrl:
                          type: string
                          format: uri
                          description: Web URL of the item
                        createdBy:
                          type: object
                          properties:
                            user:
                              type: object
                              properties:
                                email:
                                  type: string
                                  description: Creator email
                                id:
                                  type: string
                                  description: Creator ID
                                displayName:
                                  type: string
                                  description: Creator name
                        lastModifiedBy:
                          type: object
                          properties:
                            user:
                              type: object
                              properties:
                                email:
                                  type: string
                                  description: Modifier email
                                id:
                                  type: string
                                  description: Modifier ID
                                displayName:
                                  type: string
                                  description: Modifier name
                        fields:
                          type: object
                          properties:
                            Title:
                              type: string
                              description: Title of the item
                            Description:
                              type: string
                              description: Description of the item
                            Progress:
                              type: string
                              description: Progress status
                            Priority:
                              type: string
                              description: Priority level
                            StartDate:
                              type: string
                              format: date-time
                              description: Start date
                            DueDate:
                              type: string
                              format: date-time
                              description: Due date
                            AssignedTo0LookupId:
                              type: string
                              description: Assigned user lookup ID
                            Created:
                              type: string
                              format: date-time
                              description: Creation timestamp
                            Modified:
                              type: string
                              format: date-time
                              description: Modification timestamp
                            AuthorLookupId:
                              type: string
                              description: Author lookup ID
                            EditorLookupId:
                              type: string
                              description: Editor lookup ID
                            Attachments:
                              type: boolean
                              description: Whether attachments exist
    post:
      summary: Create a new volunteer tracker item in SharePoint list
      operationId: createListItem
      tags:
      - SharePoint
      parameters:
      - name: siteid
        in: path
        description: The ID of the SharePoint site
        required: true
        schema:
          type: string
          default: "${{SITE_ID}}"
      - name: listid
        in: path
        description: The ID of the SharePoint list
        required: true
        schema:
          type: string
          default: "${{LIST_ID}}"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                fields:
                  type: object
                  properties:
                    Title:
                      type: string
                      example: Widget
                    Description:
                      type: string
                      example: Work to be done
                    Progress:
                      type: string
                      example: In Progress
                    Priority:
                      type: string
                      example: Low
                    StartDate:
                      type: string
                      format: date
                      example: '2025-04-15'
                    DueDate:
                      type: string
                      format: date
                      example: '2025-04-15'
                    AssignedTo0LookupId:
                      type: string
                      example: i:0#.f|membership|user@tenant.onmicrosoft.com
                    Notes:
                      type: string
                      example: The benefits are tremendous
      responses:
        '201':
          description: Item created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Unique identifier for the created item
                  fields:
                    type: object
                    description: Fields of the created item

        "400":
          description: Bad request due to invalid parameters
        "401":
          description: Unauthorized, invalid authentication token
        "403":
          description: Forbidden, insufficient permissions
security:
- azureaadv2: []
components:
  securitySchemes:
    azureaadv2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: >-
                        https://login.microsoftonline.com/${{TEAMS_APP_TENANT_ID}}/oauth2/v2.0/authorize
          tokenUrl: >-
                        https://login.microsoftonline.com/${{TEAMS_APP_TENANT_ID}}/oauth2/v2.0/token
          scopes:
            User.Read: Read user profile
            Directory.Read.All: Read directory data
            SharePoint.ReadWrite.All: Read and write items in all site collections

Notes

Any parameters specified in the path directly , e.g. filter from sites/{siteid}/lists/{listid}/items?$filter=fields/AssignedTo0LookupId eq {userID}&$expand=fields are ignored unless explicitly specified as listed parameters

Key Highlights

  1. Dynamic Parameters: The siteId and listId are defined as path parameters, making the API reusable for different SharePoint sites and lists.

  2. Request Body: The fields object in the request body allows you to specify the properties of the SharePoint list item, such as Title, Description, Progress, and more.

  3. Response Handling: The specification includes responses for success (201) and common error scenarios (400, 401, 403).

  4. Authentication To enable authentication, the OpenAPI YAML includes a section for OAuth client registration.

  • Open the openapi.yml file, look for the securitySchemes property. The tenantid: refers to a variable automatically populated by Microsoft 365 Agents Toolkit (previously known as Teams Toolkit) within the .env file.
    security:
    - azureaadv2: []
    components:
      securitySchemes:
        azureaadv2:
          type: oauth2
          flows:
            authorizationCode:
              authorizationUrl: >-
                                https://login.microsoftonline.com/${{TEAMS_APP_TENANT_ID}}/oauth2/v2.0/authorize
              tokenUrl: >-
                                https://login.microsoftonline.com/${{TEAMS_APP_TENANT_ID}}/oauth2/v2.0/token
              scopes:
                User.Read: Read user profile
                Directory.Read.All: Read directory data
                SharePoint.ReadWrite.All: Read and write items in all site collections

Register OAuth Client in Teams Developer Portal In the Teams developer portal under Tools, create a new OAuth client registration with the following information (replace tenantid with your own value)

App settings

  • Registration name: MsGraphList
  • Base URL: https://graph.microsoft.com/v1.0
  • Restrict usage by org: My organization only
  • Restrict usage by app: Any Teams app (when agent is deployed, use the Teams app ID).

OAuth settings

Save the information. A new OAuth registration key will be generated.

Open the ai-plugin.json file and replace the auth property by the following, using the key from the previous step. You can also use the ${{OAUTH2_REGISTRATIONKEY}} token defined the .env.dev file:

```json
"auth": {
    "type": "OAuthPluginVault",
    "reference_id": "ZTRhNDM5YjQtM2..."
},
```

Demo

View Demo Video “Declarative agent for volunteering app”) how it has been used

Sample solution

Download the Solution I built with Lee Ford to give it a go.

Conclusion

By leveraging OpenAPI specifications, you can streamline interactions with SharePoint lists using Microsoft Graph to integrate with Microsoft 365 Copilot Declarative agents.

References