What it does

An API plugin gives a declarative agent the ability to call a REST API described by an OpenAPI (Swagger) document. Copilot reads the spec, picks the right operation, and calls it — read or write — as an action.

Key facts

• Driven by an OpenAPI 2.0/3.0 description plus a plugin manifest.
• Auth options: none, API key, OAuth 2.0; secrets handled via the manifest and, for OAuth, a registered app.
• Copilot chooses operations from the spec, so operation descriptions matter a lot for accuracy.
• Response size and operation count are bounded — trim large specs to the operations you actually need.
• Works inside declarative agents; not a standalone surface.

When to use / skip

Use when you need Copilot to do something in a system of record — create a ticket, look up an order, update a record. Skip for pure knowledge retrieval where a connector's index is cheaper and faster.

Configuration decisions

• Which operations to expose (fewer, well-described, beats a giant spec).
• Auth flow and consent model.
• How to phrase operation and parameter descriptions so the model calls them correctly.

Gotchas

• Vague OpenAPI descriptions lead to the wrong operation being called or wrong parameters passed — this is the number-one failure.
• Large specs overwhelm selection; prune aggressively.
• Write actions need confirmation UX thought through, or you'll get accidental changes.

Consultant notes

• Treat the OpenAPI spec as prompt engineering — description quality drives behaviour more than anything else.
• Write-back actions raise the governance bar: change control, auditing, and least-privilege auth all apply.
• No per-query grounding cost like a connector, but every call hits your API's own capacity and rate limits — size for it.

---

Review if plugin auth options or spec limits change.