API plugin manifest schema 2.1 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 2.1 schema used by API plugin manifest files. For more information about API plugins, see API plugins for Microsoft 365 Copilot.

Important

The latest version of the API plugin manifest schema is version 2.2. We recommend new plugins use the latest schema version.

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.

Property	Type	Description
schema_version	String	Required. The schema version. Previous versions are v1 and v2. Must be set to v2.1.
name_for_human	String	Required. A short, human-readable name for the plugin. It MUST contain at least one nonwhitespace character. Characters beyond 20 MAY be ignored. This property is localizable.
namespace	String	Deprecated. Optional.
description_for_model	String	Optional. The description for the plugin that is provided to the model. This description should describe what the plugin is for, and in what circumstances its functions are relevant. Characters beyond 2048 MAY be ignored. This property is localizable.
description_for_human	String	Required. A human-readable description of the plugin. Characters beyond 100 MAY be ignored. This property is localizable.
logo_url	String	Optional. A URL used to fetch a logo that MAY be used by the orchestrator. Implementations MAY provide alternative methods to provide logos that meet their visual requirements. This property is localizable.
contact_email	String	Optional. An email address of a contact for safety/moderation, support, and deactivation.
legal_info_url	String	Optional. An absolute URL that locates a document containing the terms of service for the plugin. This property is localizable.
privacy_policy_url	String	Optional. An absolute URL that locates a document containing the privacy policy for the plugin. This property is localizable.
functions	Array of Function object	Optional. A set of function objects describing the functions available to the plugin. Each function object name MUST be unique within the array. The order of the array isn't significant. If the functions property isn't present and there's an OpenAPI runtime, the functions are inferred from the OpenAPI operations.
runtimes	Array of OpenAPI runtime object	Optional. A set of runtime objects describing the runtimes used by the plugin.
capabilities	Plugin capabilities object	Optional. Describes capabilities of the plugin.

Function object

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

The function object contains the following properties.

Property	Type	Description
id	String	Optional.
name	String	Required. A string that uniquely identifies this function. Runtime objects MAY reference this identifier to bind the runtime to the function. When the function is bound to an OpenAPI runtime, the value must match an operationId value in the OpenAPI description. Value must match the ^[A-Za-z0-9_]+$ regular expression.
description	String	Optional. A description better tailored to the model, such as token context length considerations or keyword usage for improved plugin prompting.
parameters	Function parameters object	Optional. An object that contains properties that describe the parameters of a function in a runtime agnostic way. It mirrors the shape of json-schema but only supports a small subset of the JSON schema capabilities. If the parameters property isn't present, functions described by a runtime object of type OpenApi use the OpenAPI description to determine the parameters. Each member in the JSON object is a function parameter object that describes the semantics of the parameter.
returns	Return object OR Rich return object	Optional. Describes the semantics of the value returned from the function.
states	Function states object	Optional. Defines state objects for orchestrator states.
capabilities	Function capabilities object	Optional. Contains a collection of data used to configure optional capabilities of the orchestrator while invoking the function.

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.

Property	Type	Description
type	String	Optional. The JSON Schema type. Must be set to object.
properties	Function parameters properties object	Required. An object that maps parameter names to their definitions.
required	Array of String	Optional. The names of properties that are required parameters. Unlike in JSON Schema, the values in this array MUST match the names listed in the properties property.

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.

Property	Type	Description
Name matching ^[A-Za-z0-9_]+$	Function parameter object	Optional. The parameter definition that corresponds to the parameter that matches the property name.

Function parameter object

An object that describes the semantics of a function parameter.

The function parameter object contains the following properties.

Property	Type	Description
type	String	Required. Specifies the parameter's type. Possible values are: string, array, boolean, integer, number.
items	Function parameter object	Optional. A function parameter object that describes a single element in an array. MUST only be present when type is array.
enum	Array of String	Optional. An array of valid values for this parameter. MUST only be present when type is string.
description	String	Optional. A description of the parameter.
default	Array, Boolean, String, Number, Integer	Optional. A value of the type specified by the type property that indicates the value the API uses when a value for an optional parameter isn't provided.

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.

Property	Type	Description
type	String	Required. Specifies the type of the value returned by the API. Possible values are: string.
description	String	Optional. A description of the value returned by the API.

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.

Property	Type	Description
$ref	String	Required. Must be set to https://copilot.microsoft.com/schemas/rich-response-v1.0.json.

Function states object

Defines state objects for orchestrator states.

The function states object contains the following properties.

Property	Type	Description
reasoning	State object	Optional. The state in which the model can call functions and do computations.
responding	State object	Optional. The state in which the model can generate text that is shown to the user. The model can't invoke functions in the responding state.
disengaging	State object	Optional.

State object

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

The state object contains the following properties.

Property	Type	Description
description	String	Optional. Describes the purpose of a function when used in a specific orchestrator state.
instructions	Array, String	Optional. A string or an array of strings that are used to provide instructions to the orchestrator on how to use this function while in a specific orchestrator state. Providing a single string indicates the intent to provide a complete set of instructions that would override any built-in function prompts. Providing an array of strings indicates the intent to augment the built-in function prompting mechanism.
examples	Array, String	Optional. A string or an array of strings that are used to provide examples to the orchestrator on how this function can be invoked.

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.

Property	Type	Description
confirmation	Confirmation object	Optional. Describes a confirmation dialog that SHOULD be presented to the user before invoking the function.
response_semantics	Response semantics object	Optional. Describes how the orchestrator can interpret the response payload and provide a visual rendering.

Confirmation object

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

The confirmation object contains the following properties.

Property	Type	Description
type	String	Optional. Specifies the type of confirmation. Possible values are: None, AdaptiveCard.
title	String	Optional. The title of the confirmation dialog. This property is localizable.
body	String	Optional. The text of the confirmation dialog. This property is localizable.

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.

Property	Type	Description
data_path	String	Required. A JSONPath RFC9535 query that identifies a set of elements from the function response to be rendered using the template specified in each item.
properties	Response semantics properties object	Optional. Allows mapping of JSONPath queries to well-known data elements. Each JSONPath query is relative to a result value.
static_template	Object	Optional. A JSON object that conforms with the Adaptive Card Schema and templating language. This Adaptive Card instance is used to render a result from the plugin response. This value is used if the template_selector isn't present or fails to resolve to an adaptive card.
oauth_card_path	String	Optional.

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.

Property	Type	Description
title	String	Optional. Title of a citation for the result.
subtitle	String	Optional. Subtitle of a citation for the result.
url	String	Optional. URL of a citation for the result.
thumbnail_url	String	Optional. URL of a thumbnail image for the result.
information_protection_label	String	Optional. Data sensitivity indicator of the result contents.
template_selector	String	Optional. A JSONPath expression to an Adaptive Card instance to be used for rendering the result.

OpenAPI runtime object

Describes how the plugin invokes OpenAPI functions.

The OpenAPI runtime object contains the following properties.

Property	Type	Description
type	String	Required. Identifies this runtime as an OpenAPI runtime. Must be set to OpenApi.
auth	Runtime authentication object	Required. Authentication information required to invoke the runtime.
run_for_functions	Array of String	Optional. The names of the functions that are available in this runtime. If this property is omitted, all functions described by the runtime are available. Provided string values can contain wildcards. More than one runtime MUST NOT declare support for the same function either implicitly or explicitly.
spec	OpenAPI specification object	Required. Contains the OpenAPI information required to invoke the runtime.

OpenAPI specification object

Contains the OpenAPI information required to invoke the runtime.

The OpenAPI specification object contains the following properties.

Property	Type	Description
url	String	Optional. The URL to fetch the OpenAPI specification, called with a GET request. This member is required unless api_description is present.
api_description	String	Optional. A string that contains an OpenAPI description. If this member is present, url isn't required and is ignored if present.
progress_style	String	Optional. The progress style that is used to display the progress of the function. Possible values are: None, ShowUsage, ShowUsageWithInput, ShowUsageWithInputAndOutput.

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.

Property	Type	Description
type	String	Optional. Specifies the type of authentication required to invoke a function. Possible values are: None, OAuthPluginVault, ApiKeyPluginVault.
reference_id	String	Optional. A value used when type is OAuthPluginVault or ApiKeyPluginVault. The reference_id value is acquired independently when providing the necessary authentication configuration values. This mechanism exists to prevent the need for storing secret values in the plugin manifest.

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.

Property	Type	Description
conversation_starters	Array of Conversation starter object	Optional. Conversation starters that can be displayed to the user for suggestions on how to invoke the plugin.

Conversation starter object

An example of a question that the plugin can answer.

The conversation starter object contains the following properties.

Property	Type	Description
text	String	Required. The text of the conversation starter. This property is localizable.
title	String	Optional. The title of the conversation starter. This property is localizable.

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.1",
  "name_for_human": "Contoso Real Estate",
  "description_for_human": "Find up-to-date, detailed real estate properties for sale on the market",
  "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": {
    "conversation_starters": [
      {
        "title": "Available listings",
        "text": "What listings are available in my area?"
      }
    ]
  },
  "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