API plugin manifest schema for Microsoft 365 Copilot

API plugins enable Microsoft 365 Copilot to interact with REST APIs described by an OpenAPI description. The OpenAPI description in an API plugin describes the REST APIs that Copilot can interact with. In addition, an API plugin includes a plugin manifest file that provides metadata about the plugin, such as the plugin's name, description, and version. The plugin manifest also includes information about the plugin's capabilities, such as the APIs it supports and the operations it can perform.

The following article describes the schema used by API plugin manifest files. For more information about API plugins, see API plugins for Microsoft 365 Copilot.

JSON schema

The schema described in this document can be found in JSON Schema format here.

Conventions

Relative references in URLs

Unless specified otherwise, all properties that are URLs MAY be relative references. Relative references in the manifest document are relative the location of the manifest document.

String length

Unless specified otherwise, all string properties SHOULD be limited to 4K characters. This string length doesn't confer any acceptable size for the entire document. Implementations a free to impose their own practical limits on manifest length.

Unrecognized properties

JSON objects defined in this document support only the described properties. Unrecognized properties in any JSON object SHOULD make the entire document invalid.

String localization

Localizable strings can use a localization key instead of a literal value. The syntax is [[key_name]], where key_name is the key name in the localizationKeys property in your localization files. For details on localization, see Localize your agent.

Localized string example

{
    "schema_version": "v2.1",
    "name_for_human": "[[plugin_name]]",
    "description_for_human": "[[plugin_description]]"
}

Plugin manifest object

The root of the plugin manifest document is a JSON object that contains properties that describe the plugin.

The plugin manifest object contains the following properties.

Function object

Information related to how the model should interact with a function.

The function object contains the following properties.

Function object example

{
  "functions": [
    {
      "name": "add_todo",
      "description": "Adds a new Todo",
      "parameters": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string"
          }
        },
        "required": [
          "description"
        ]
      },
      "returns": {
        "type": "string"
      }
    }
  ]
}

Function parameters object

An object that is used to identify the set of parameters that can be passed to the function. This object is structured to mirror the shape of a JSON Schema object but it only supports a subset of JSON Schema keywords.

The function parameters object contains the following properties.

Function parameters object example

{
  "type": "object",
  "properties": {
    "param1": {
      "type": "string"
    },
    "param2": {
      "type": "number"
    }
  },
  "required": [
    "param1"
  ]
}

Function parameters properties object

An object that maps parameter names to their definitions.

The function parameters properties object contains the following properties.

Function parameter object

An object that describes the semantics of a function parameter.

The function parameter object contains the following properties.

Function parameter example

{
  "type": "string",
  "description": "The color of the item",
  "enum": [
    "green",
    "blue",
    "orange"
  ]
}

Return object

Contains the semantics of the value returned from the function.

The return object contains the following properties.

Rich return object

Indicates that the function returns a response that is compatible with the Rich Responses protocol.

The rich return object contains the following properties.

Function states object

Defines state objects for orchestrator states.

The function states object contains the following properties.

State object

Contains specific instructions for when a function is invoked in a specific orchestrator state.

The state object contains the following properties.

State object example

{
  "functions": [
    {
      "name": "searchEmails",
      "description": "search for Emails from using 3S search Service",
      "states": {
        "reasoning": {
          "description": "\n# `searchEmails(**params) -> str` returns the emails from user's inbox based on search query.",
          "instructions": [
            "Examine the output of `searchEmails(**params) -> str`.",
            "Do not include any information that is not present in the JSON results.",
            "Exclude any irrelevant data from the JSON results",
            "Determine if the response contains an error field.",
            "If an error is present, provide the error code and error message extracted from the response JSON.",
            "If there is no error, extract and include as much relevant information as possible from the JSON result to meet the user's needs."
          ],
          "examples": []
        }
      }
    }
  ]
}

Function capabilities object

Contains a collection of data used to configure optional capabilities of the orchestrator while invoking the function.

The function capabilities object contains the following properties.

Confirmation object

Describes how the orchestrator asks the user to confirm before calling a function.

The confirmation object contains the following properties.

Response semantics object

Contains information to identify semantics of response payload and enable rendering that information in a rich visual experience using adaptive cards.

The response semantics object contains the following properties.

Static template example

{
  "functions": {
    "capabilities": {
      "response_semantics": {
        "data_path": "$.resources",
        "properties": {
          "title": "$.name",
          "subtitle": "$.location",
          "url": "$.href",
          "information_protection_label": "$.ipLabel"
        },
        "static_template": {
          "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
          "type": "AdaptiveCard",
          "version": "1.5",
          "body": [
            {
              "type": "TextBlock",
              "text": "${name}",
              "weight": "Bolder"
            },
            {
              "type": "TextBlock",
              "text": "${description}"
            }
          ],
          "action": [
            {
              "type": "Action.OpenUrl",
              "title": "View",
              "text": "${href}"
            }
          ]
        }
      }
    }
  }
}

Dynamic template example

{
  "functions": {
    "capabilities": {
      "response_semantics": {
        "data_path": "$.attachments",
        "properties": {
          "title": "$.title",
          "subtitle": "$.subtitle",
          "url": "$.url",
          "thumbnail_url": "$.thumbnailUrl",
          "template_selector": "$.template"
        }
      }
    }
  }
}

Response semantics properties object

Allows mapping of JSONPath queries to well-known data elements. Each JSONPath query is relative to a result value.

The response semantics properties object contains the following properties.

OpenAPI runtime object

Describes how the plugin invokes OpenAPI functions.

The OpenAPI runtime object contains the following properties.

OpenAPI specification object

Contains the OpenAPI information required to invoke the runtime.

The OpenAPI specification object contains the following properties.

OpenAPI specification object example

{
  "runtimes":
  [
    {  
      "type": "OpenApi",
      "auth": {
        "type": "None"
      },
      "spec": {
        "url": "https://example.org/api/openapi.yaml",  
      }
    }
  ]
}  

Runtime authentication object

Contains information used by the plugin to authenticate to the runtime.

The runtime authentication object contains the following properties.

Runtime authentication object example

{
  "type": "OAuthPluginVault",
  "reference_id": "0123456-abcdef"
}

Plugin capabilities object

Describes capabilities of the plugin.

The plugin capabilities object contains the following properties.

Conversation starter object

An example of a question that the plugin can answer.

The conversation starter object contains the following properties.

Conversation starter object example

{
  "conversation_starters": [
    {
      "title": "Developer tasks",
      "text": "What issues are assigned to me?"
    }
  ]
}

Manifest example

Here's an example of a plugin manifest file that uses most of the manifest properties and object properties described in the article:

{
  "schema_version": "v2",
  "name_for_human": "{{ 'nameForHuman' | localize: 'en-us' }}",
  "description_for_human": "{{ 'descriptionForHuman' | localize: 'en-us' }}",
  "description_for_model": "Plugin for finding properties for sale. Use it whenever a user asks about real estate properties for sale on the market. This plugin can be used to search for properties in a particular city, and with a given number of bedrooms, bathrooms, and amenities.",
  "capabilities": {
    "localization": {
      "en-us": {
        "nameForHuman": {
          "message": "Contoso Real Estate",
          "description": "Name for human, in English"
        },
        "descriptionForHuman": {
          "message": "Find up-to-date, detailed real estate properties for sale on the market",
          "description": "Description for human, in English"
        }
      },
      "fr-fr": {
        "nameForHuman": {
          "message": "Contoso Immobilier",
          "description": "Name for human, in French"
        },
        "descriptionForHuman": {
          "message": "Trouvez des propriétés immobilières à vendre sur le marché",
          "description": "Description for human, in French"
        }
      }
    }
  },
  "functions": [
    {
      "name": "getListings",
      "description": "Get a list of properties matching the specified criteria",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string",
            "description": "The city to search properties in"
          },
          "bedrooms": {
            "type": "number",
            "description": "The number of bedrooms the property should have"
          },
          "bathrooms": {
            "type": "number",
            "description": "The number of bathrooms the property should have"
          },
          "amenities": {
            "type": "array",
            "description": "The list of amenities the property should have",
            "items": {
              "type": "string",
              "description": "One amenity the property should have",
              "enum": [
                "air conditioning",
                "balcony",
                "dishwasher",
                "elevator",
                "fireplace",
                "furniture",
                "garden",
                "gym",
                "heating",
                "jacuzzi",
                "laundry room",
                "microwave",
                "no furniture",
                "parking",
                "patio",
                "sauna",
                "swimming pool",
                "terrace",
                "wi-fi"
              ]
            }
          }
        }
      },
      "returns": {
        "type": "string",
        "description": "A list of properties"
      },
      "states": {
        "reasoning": {
          "description": "`getListings` returns a list of real estate properties for sale based on the specified criteria.",
          "instructions": [
            "If the user mentions a city in their question, only search in that city by using the city parameter.",
            "If the user asks for properties with things like parking space, heating, jacuzzi, or similar amenities, use the amenities parameter to filter the results.",
            "Only use the list of amenities provided in the amenities parameter enum. If the user asked for an amenity that is not in the list, find the closest match from the list, or ignore it if no match can be found.",
            "Determine if the response contains an error field.",
            "If an error is present, provide the error code and error message from the JSON response to the user.",
            "If there is no error, extract and include as much relevant information as possible from the JSON response to meet the users needs."
          ]
        }
      }
    },
    {
      "name": "saveSearch",
      "description": "Save a search for properties for sale",
      "parameters": {
        "type" : "object",
        "properties": {
          "city": {
            "type": "string",
            "description": "The city to search in"
          },
          "bedrooms": {
            "type": "number",
            "description": "The number of bedrooms"
          }
        },
        "required": [ "city" ]
      },
      "returns": {
        "type": "string",
        "description": "The unique ID for the saved search"
      },
      "states": {
        "responding": {
          "description": "`saveSearch` returns a unique ID that identifies the newly saved search.",
          "instructions": [
            "Examine the output of the `saveSearch` function.",
            "Extract the unique ID integer from the output and include it in your response to the user."
          ]
        }
      }
    },
    {
      "name": "deleteSavedSearch",
      "description": "Delete a previously saved search",
      "parameters": {
        "type" : "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "The unique ID of the saved search"
          }
        },
        "required": [ "id" ]
      },
      "returns": {
        "type": "string",
        "description": "True if the saved search was deleted, false otherwise"
      }
    }
  ],
  "runtimes": [
    {
      "type": "OpenApi",
      "auth": { "type": "none" },
      "run_for_functions": [ "getListings", "saveSearch", "deleteSavedSearch" ],
      "spec": { "url": "http://contoso.com/openapi.yaml" }
    }
  ],
  "logo_url": "http://contoso.com/logo.png",
  "contact_email": "contact@contoso.com",
  "legal_info_url": "https://contoso.com/legal/",
}

See also

• API plugins for Microsoft 365 Copilot