You’ve deployed declarative agents, custom engine agents, and third-party Copilot apps across your tenant. You have no programmatic record of what’s actually there, who owns each one, which are blocked, or what changed since last week — and your only view is a browser screen you cannot query. The Microsoft 365 Copilot Package Management API is the programmatic handle on that population: six /beta endpoints that enumerate every Copilot app and agent in the tenant, return structured metadata for each, and let an admin block, unblock, or reassign a package from code.

⚠️ Preview: Every endpoint described in this post lives under /beta. The Microsoft documentation states that use of these APIs in production is not supported. Treat everything here as a foundation for governance automation you can prototype and plan against — not as a production control plane. Verify the reference pages before you build, because beta surfaces can change before they reach general availability.

After reading this post, you will be able to:

• ✅ Query your entire tenant’s Copilot agent inventory programmatically using the six /beta endpoints
• ✅ Filter that inventory by agent type (DeclarativeAgent, CustomEngineAgent, Bots), host surface, or last-modified date
• ✅ Use the block, unblock, and reassign action endpoints to enforce governance decisions from code
• ✅ Understand exactly where the API stops short of the Agent Registry UI — and why you still need both

No programmatic inventory means no automated governance. When the only view of installed agents is a UI screen, every governance activity that depends on that view becomes manual: the quarterly audit, the offboarding check, the “what changed this week” review. Manual governance does not scale with agent count, and agent count is the variable that is growing.

Agent sprawl outpaces the people responsible for it. Declarative agents, custom engine agents, and bots each enter the tenant through different authoring and acquisition paths. An admin who is accountable for all of them has no single query that returns all of them — until they have an API that does.

403 errors with a valid token waste real engineering hours. Teams that hold the correct Graph permission scope still hit access-denied responses because the API gates on a separate license and an admin role that the scope alone does not satisfy. Without a clear failure taxonomy, those hours go into guesswork.

A preview API on a governance roadmap is a planning hazard. Building a control plane on endpoints that carry a “not supported in production” banner is a decision, not a default. Admins need to know exactly which constraints are real today so they can decide what to automate now and what to defer.

What This API Actually Does — and Why the Admin Center Screen Isn’t Enough

The Package Management API is the programmatic equivalent of the Agent Registry view in the Microsoft 365 admin center. Where the registry shows an admin a list of installed Copilot apps and agents on screen, the API returns that same population as structured data you can query, filter, store, and act on from code.

It exposes six endpoints under a single base path: https://graph.microsoft.com/beta/copilot/admin/catalog/packages. Through them, an admin can list every package in the tenant, retrieve detailed metadata for a single package, update a package’s access settings, and run three governance actions — block, unblock, and reassign. A “package” here is any Copilot app or agent registered in the tenant catalog, spanning the full agent taxonomy that admin tooling already surfaces.

The value over the UI is integration, not novelty. The registry answers “what is installed?” for a human looking at a browser. The API answers the same question for a scheduled job, a compliance dashboard, or an alerting pipeline. That distinction is the entire reason the API exists, and it is also why the API is not a replacement for the registry — a point this post returns to in the section on the Agent Registry gap.

⚠️ Preview: The entire /beta/copilot/admin/catalog/packages surface is in preview. The reference documentation was last updated on 2026-05-01 and still carries the production-not-supported disclaimer on the individual endpoint pages.

💡 Insight: The registry and the API are fed from the same underlying catalog — they diverge not in what data they see, but in what they can do with it. The UI surfaces risk signals from Defender, Purview, and Entra that the API does not return. Running both surfaces in parallel is not redundancy; it is the complete picture.

What this means for you: if your governance process currently depends on manually checking the Agent Registry screen, this API is the foundation for automating that check — with the preview constraints understood upfront.

Four Gates You Must Clear Before the First Call Returns Anything

Most of the friction teams report with this API is not in the request shape — it is in the gate conditions that have to be true before any request succeeds. Clearing them upfront is faster than discovering them one 403 at a time.

Step 1 — Confirm the license gate

A Microsoft Agent 365 license is required to use any Package Management API endpoint. This is not stated only on the overview page — it appears as a prerequisite on every individual endpoint page. A valid Graph permission scope does not substitute for the license. This is the requirement most teams miss, and it is the first thing to check when a call returns 403.

Note: The relationship between Microsoft 365 Copilot (the per-user license) and Microsoft Agent 365 is not clearly articulated in the verified documentation. What is documented is that a Microsoft Agent 365 license is required to call these endpoints. Confirm the current licensing model against the official Microsoft Agent 365 page before assuming any bundling.

Step 2 — Verify the admin role

The AI Admin or Global Admin role is required to call the API. The Microsoft Agent 365 Graph API documentation states these roles explicitly. The agent prerequisites page also lists Global Reader as a governance role for the admin center UI — but whether Global Reader can call the read endpoints via the API is inconsistent across the documented sources. Treat Global Reader API access as unconfirmed until Microsoft clarifies it.

Step 3 — Understand the authentication split

The read endpoints (List, Get) accept delegated permissions only — a work or school account. Application permissions (service principals) are not supported for the read side. The write endpoints (block, unblock, update, reassign) do support the CopilotPackages.ReadWrite.All application permission in addition to delegated access. This split is the single most important architectural constraint for automation planning.

⚠️ Preview: Because the read endpoints accept delegated authentication only, you cannot drive them from a background service principal today. Any unattended inventory job has to run in a delegated user context, which is a real constraint for fully automated pipelines. The write endpoints do support application permissions — see the action section below.

Step 4 — Confirm cloud eligibility

The API is available on the global commercial cloud only. US Government L4 (GCC), L5 (DOD), and China operated by 21Vianet are not supported. For sovereign-cloud admins, the Agent Registry UI is the only governance surface the documentation supports today.

The table below is the quick-reference summary of all four gate conditions:

✅ Quick win: Before building any automation, run a manual delegated call against List using the Graph Explorer with your admin account. If it returns data, your license and role are confirmed. If it returns 403, you have a license or role problem — not a scope problem.

What this means for you: the four gates above represent at least three separate teams to coordinate — licensing, identity/IAM, and your own admin role assignment — so start the access verification early, not after the code is written.

Six Operations — and the One Permission Boundary That Shapes How You Use Them

The API surface is small and navigable. Six operations cover read, update, and the three governance actions. The table below is the canonical map; the sections that follow expand the data model and the action shapes.

All paths are relative to https://graph.microsoft.com. The permission split follows the read/write boundary: the two GET endpoints require delegated work-or-school permissions and do not support application permissions, while the PATCH and the three POST action endpoints support the CopilotPackages.ReadWrite.All application permission in addition to delegated access.

List returns the package collection. Get returns the richer detail resource for a single package. Update is a PATCH that changes a narrow set of access fields. Block and unblock toggle a package’s availability and return no body. Reassign changes a package’s owner. Each is covered in detail below.

💡 Insight: The permission boundary — delegated-only for reads, application-permission-capable for writes — means you can automate enforcement actions (block, reassign) with a service principal, but you cannot automate the inventory query that identifies what to enforce against. This asymmetry shapes every automation design built on this API today.

What this means for you: the one permission boundary in this API forces a hybrid architecture — a human-context read pass feeding an automated write pass — until Microsoft extends application permissions to the read endpoints.

What Comes Back: The copilotPackage Data Model

To plan queries and decide what to store, you need the shape of what List returns. The copilotPackage resource is the per-package record, and Get returns an extended version of it.

The two enum-typed properties matter most for governance logic.

The type property is a packageType enum with the values microsoft, external, shared, custom, and unknownFutureValue. This is where you distinguish a first-party Microsoft package from an external one or an internally built custom one.

The availableTo and deployedTo properties both use the packageStatus enum, with the values none, some, all, and unknownFutureValue. A package with availableTo set to all is available tenant-wide — a useful signal to flag for review.

The isBlocked Boolean is the programmatic equivalent of the blocked/unblocked state an admin sees in the admin center. It is the property your governance logic reads to know a package’s current availability, and the block and unblock actions are what flip it.

What Get adds: copilotPackageDetail

Calling Get against a single package returns the copilotPackageDetail resource, which extends copilotPackage with deeper metadata you would not pull for every package in a list:

The elementDetails array is the lowest-level view the API offers — the raw definition of each element a package contains. It is the right place to look when a list-level type filter is not specific enough.

What this means for you: the List endpoint gives you the fields needed for broad inventory queries; Get gives you the depth needed for per-package compliance review or access-scoping decisions — call them in sequence, not interchangeably.

Three Filters, One Pattern: How to Query Your Entire Agent Inventory

The List endpoint supports the OData $filter parameter, and the documentation defines exactly three filterable values. These three are the building blocks of every inventory query.

The elementTypes filter is what makes this useful for agent governance specifically. Its three values — Bots, DeclarativeAgent, and CustomEngineAgent — cover the full agent taxonomy visible from admin tooling, so an admin can narrow a tenant-wide list down to just declarative agents, just custom engine agents, or just bots.

To list only the packages that run on the Copilot host — the Copilot agents, as opposed to every Microsoft 365 app in the catalog — the documented filter is:

GET /beta/copilot/admin/catalog/packages?$filter=supportedHosts/any(h:h eq 'Copilot') HTTP/1.1
Host: graph.microsoft.com
Authorization: Bearer {token}

The lastModifiedDateTime filter with gt is the basis for change detection: query for packages modified since your last run, and you have a list of what is new or changed without diffing the entire catalog yourself.

Only $filter is documented for the List endpoint. The $select, $orderby, $top, and $skip parameters are not documented in the verified sources, and pagination behavior — including @odata.nextLink — is not specified. For large tenants, the pagination model is an open question; see the Known Limitations section.

💡 Insight: Three filters sounds limited, but composed together they cover the core governance queries: what Copilot-host agents exist (supportedHosts), what type they are (elementTypes), and what changed since the last audit run (lastModifiedDateTime). The constraint is not the filter set — it is the unknown pagination behavior for tenants with large agent populations.

What this means for you: these three filters are sufficient for building a practical weekly governance report today; the unknown pagination ceiling is the risk to validate before committing to a large-tenant rollout.

Block, Unblock, Reassign: Turning Inventory into Enforcement

The three POST action endpoints are what turn this from a reporting API into a governance one. They are also the endpoints where application permissions apply, which means the write side can — within the license and role gates — be driven from automation in a way the read side cannot.

Block removes a package’s availability. It is a POST with no request body and returns 204 No Content:

POST /beta/copilot/admin/catalog/packages/{id}/block HTTP/1.1
Host: graph.microsoft.com
Authorization: Bearer {token}

Unblock restores availability. It mirrors the block pattern — a POST with no body — and is used to reverse a block.

Note: The block endpoint’s request and response shape (POST, no body, 204) is verified. The dedicated unblock reference page was not independently verified during research; its existence is confirmed in the overview table and its behavior is assumed to mirror block. Confirm the unblock specifics against its own reference page before building automation that depends on them.

Reassign changes a package’s owner. Unlike block and unblock, it requires a request body — a single userId parameter holding the GUID of the new owner — and returns 204 No Content:

POST /beta/copilot/admin/catalog/packages/{id}/reassign HTTP/1.1
Host: graph.microsoft.com
Authorization: Bearer {token}
Content-Type: application/json
{
  "userId": ""
}

The Update (PATCH) endpoint is narrower than its name suggests. It allows setting allowedUsersAndGroups and acquireUsersAndGroups — arrays of packageAccessEntity objects, each with a resourceType and resourceId. Identity-level fields such as manifestId, manifestVersion, and version are not updatable after creation. PATCH is for adjusting who can access and acquire a package, not for rewriting its identity.

For all four write operations, the CopilotPackages.ReadWrite.All application permission is supported in addition to delegated access — the one part of the API surface where a service principal is documented to work.

✅ Quick win: The block action is a single POST with no body and returns 204 — the fastest path to removing a package’s availability when a compliance review fails or an owner offboards. No additional payload construction required.

What this means for you: the write endpoints are the enforcement layer — they are where the API pays off after an inventory query has identified a package that needs action.

Five Governance Workflows You Can Build Against This API Today

The endpoints become governance when you compose them into the workflows an admin already runs. The patterns below use only documented properties and filters.

1. Periodic tenant inventory. Run List on a schedule, store the returned copilotPackage records, and you have a point-in-time inventory you can compare across runs. Because the read endpoints are delegated-only today, this job runs in a delegated user context rather than as a background service principal.
2. Detecting newly deployed agents. Filter List by lastModifiedDateTime with the gt operator against the timestamp of your last run. Narrow further with elementTypes eq 'DeclarativeAgent' to catch newly deployed declarative agents specifically. This is the change-detection pattern without a full-catalog diff.
3. Flagging tenant-wide availability for review. A package whose availableTo property is all is available across the tenant. Surfacing those packages from a List response gives a review queue of the broadest-reach packages — the ones most worth a second look.
4. Reading current block state. The isBlocked Boolean tells your logic whether a package is currently blocked. Combined with elementTypes, you can build a view of which agent types are unblocked and available right now.
5. Blocking on offboarding or failed review. When a package fails a compliance review, or when an owner offboards, the block action removes its availability with a single POST. Reassign moves ownership of a package whose owner is leaving to a new owner by GUID. Together they cover the offboarding case: reassign what should persist, block what should not.

These patterns are foundations to prototype, not production runbooks — the preview constraints in the next two sections set the boundary on how far to take them today.

What this means for you: workflows 1 and 2 are the highest-value starting points for most tenants — periodic inventory plus change detection cover the majority of governance audit requirements without requiring any of the write-side automation.

What the API Won’t Tell You: The Agent Registry Gap That Still Matters

The Package Management API and the Agent Registry UI are complementary, not equivalent. Treating the API as a drop-in replacement for the registry is the most common way to misjudge what it gives you.

The Agent Registry lives in the Microsoft 365 admin center under Agents > All Agents > Registry. Beyond the inventory the API also exposes, the registry surfaces risk signals drawn from across the Microsoft security and compliance stack — signals the Package Management API does not return.

The registry’s risk signals are the substantive gap. It surfaces shadow agents, excessive permissions and prompt-injection signals from Defender, sensitive-data-access signals from Purview, conditional access violations from Entra, and compliance and retention gaps. None of these are part of the copilotPackage data model. The API tells you what exists and lets you act on it; the registry tells you which of those things are risky.

For bulk human review, the registry’s Export to CSV produces 30-plus columns per agent. For programmatic processing and integration, the API’s structured JSON is the better fit. The honest division of labor: use the API to automate inventory and enforcement, and use the registry UI for the risk picture the API cannot provide.

What this means for you: the API without the registry UI is an incomplete governance picture — plan your governance workflow to use both, with the API handling automation and the registry handling the risk signal review that requires human judgment.

Why Your 403 Probably Isn’t a Permissions Problem

The most common failure mode is a 403 Access Denied on the List endpoint from a caller who has a valid delegated token containing the CopilotPackages.Read.All scope. Real-world developer reports on Microsoft Learn Q&A confirm this exact case: correct scope, valid token, still denied.

The cause is that the Graph scope is necessary but not sufficient. The API gates on three independent conditions, and missing any one of them produces a denial even when the others are satisfied:

• License — a Microsoft Agent 365 license must be present on the calling context. A correct scope does not substitute for the license.
• Admin role — the caller needs the AI Admin or Global Admin role.
• Scope — the delegated token must carry the appropriate CopilotPackages permission.

Microsoft has not published a troubleshooting matrix that distinguishes a license-missing denial from a role-missing denial or a scope-missing denial. The three conditions above are the documented gate requirements and the confirmed real-world causes of access failures — but the specific status code returned for each missing condition is not documented.

The practical takeaway: when a call returns 403 with a token you believe is correct, check the license and the admin role before re-examining the scope. The scope is the part most teams get right and the license is the part most teams miss.

What this means for you: a 403 on this API is almost always a licensing or role problem, not a code problem — route it to your Microsoft account team or tenant admin first, not back to the developer.

What the API Won’t Do Yet — and What That Means for Your Rollout Plan

Consolidated here so a reader building a roadmap can see every constraint in one place.

⚠️ Preview: All six endpoints are /beta. The documentation states production use is not supported. The reference pages were last updated 2026-05-01.

• No application permissions on read endpoints. List and Get accept delegated work-or-school authentication only. Fully unattended inventory jobs cannot run as a service principal against the read side today. The write endpoints support CopilotPackages.ReadWrite.All application permission.
• No sovereign cloud support. The API is global commercial cloud only. GCC, DOD, and 21Vianet tenants are not supported.
• No published GA timeline. No public roadmap entry or GA date for the Package Management API was found in the verified sources as of June 2026. Do not plan against a graduation date; all endpoints remain in /beta.
• Global Reader API access is ambiguous. The Microsoft Agent 365 Graph API page states the API requires the AI Admin or Global Admin role. The agent prerequisites page lists Global Reader as a governance role in the admin center UI. These two statements are inconsistent on whether Global Reader can call the read endpoints via the API. Treat Global Reader API access as unconfirmed.
• OData support beyond $filter is undocumented. Only $filter (with its three documented values) is specified for List. $select, $orderby, $top, $skip, and pagination behavior including @odata.nextLink are not documented. For large tenants with many agents, the pagination model is a real open question — do not assume a behavior the sources do not state.
• Licensing relationship is unspecified. A Microsoft Agent 365 license is required. Whether it is included in, or separate from, a Microsoft 365 Copilot subscription is not clearly articulated in the verified sources.

Readiness checklist

Before building anything against this API, verify each item.

• [ ] Licensing: A Microsoft Agent 365 license is present on the tenant and the calling context
• [ ] Cloud eligibility: The tenant is on the global commercial cloud, not GCC, DOD, or 21Vianet
• [ ] Admin role: The calling identity holds AI Admin or Global Admin
• [ ] App registration: The app is registered with the CopilotPackages permissions it needs
• [ ] Permissions (read): Delegated CopilotPackages.Read.All for List and Get — application permissions will not work here
• [ ] Permissions (write): Delegated access, or CopilotPackages.ReadWrite.All application permission, for block, unblock, update, and reassign
• [ ] Preview governance: Stakeholders accept that all endpoints are /beta with no GA timeline and a production-not-supported banner

What this means for you: the checklist above is also the conversation to have with stakeholders before committing engineering time — every unchecked item is a project risk, not just a technical gap.

Now What? Your Next Three Steps

1. Run a manual inventory call today. Use Graph Explorer with your admin account and call GET /beta/copilot/admin/catalog/packages?$filter=supportedHosts/any(h:h eq 'Copilot'). The response either confirms your access is fully gated (you see data) or tells you which of the four prerequisite gates is not yet cleared (you see a 403). This is zero-code validation that costs five minutes.
2. Map your tenant against the readiness checklist. Work through the seven checklist items in the Known Limitations section and confirm which items are already true and which require action. Focus first on licensing (the most commonly missed gate) and cloud eligibility (a hard stop for GCC/DOD tenants).
3. Design your governance workflow before writing automation. Decide which of the five patterns in the Governance Workflows section fits your immediate need — periodic inventory or change detection are the right starting points for most tenants. Design the workflow with the delegated-auth constraint understood: a human-context read pass now, automated write-side enforcement once you have the package IDs you need to act on.

How to Navigate This Series

This series runs 13 posts across three phases:

• Phase 1 — Foundations and Governance (Posts 01–04): the landscape, auth and production readiness, rate limits and reliability, and usage reports.
• Phase 2 — Building with the Core APIs (Posts 05–09): this post on package management, Retrieval, Chat, Meeting Insights, and AI Interactions Change Notifications.
• Phase 3 — Agents and Extensibility (Posts 10–13): connectors, the agent taxonomy, Copilot Studio, and SPFx integration patterns.

This post is the first post in Phase 2, though it continues the admin-governance thread from Phase 1. For the API surface context behind it, see Post 01 — the landscape overview. For the delegated-versus-application permission foundations the prerequisites here depend on, see Post 02 — auth, permissions, and production readiness. For the adjacent admin-governance surface, see Post 04 — the usage reports API.

By role:

• IT admin / Copilot deployment lead: Post 01 → Post 02 → Post 04 → Post 05 (you are here) → continue through the rest of Phase 2
• Governance, risk, and compliance: Post 04 → Post 05 → Post 01 for context
• Developer building governance tooling: Post 01 → Post 02 → Post 05 → the rest of Phase 2 for the APIs you build on

The immediate next post is Post 06 — Grounding Your App in Organisational Content: The Microsoft 365 Copilot Retrieval API, the first developer-focused post in Phase 2.

References

All claims in this post trace to the following official Microsoft documentation:

1. Package Management API overview (preview) — https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/api/admin-settings/package/overview
2. List Copilot packages — https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/api/admin-settings/package/copilotpackages-list
3. Get Copilot package details — https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/api/admin-settings/package/copilotpackagedetail-get
4. Update Copilot package — https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/api/admin-settings/package/copilotpackagedetail-update
5. copilotPackage: block — https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/api/admin-settings/package/copilotpackage-block
6. copilotPackage: reassign — https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/api/admin-settings/package/copilotpackage-reassign
7. copilotPackage resource type — https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/api/admin-settings/package/resources/copilotpackage
8. Agent Registry in Microsoft 365 admin center — https://learn.microsoft.com/en-us/microsoft-365/admin/manage/agent-registry?view=o365-worldwide
9. Graph API for agent registry and agent details (Microsoft Agent 365 docs) — https://learn.microsoft.com/en-us/microsoft-agent-365/admin/graph-api
10. Prerequisites — Microsoft 365 Copilot agent governance — https://learn.microsoft.com/en-us/microsoft-365/copilot/agent-essentials/agent-prerequisites
11. Q&A: 403 on Copilot Packages API even with delegated token — https://learn.microsoft.com/en-gb/answers/questions/5827851/403-on-copilot-packages-api-even-with-delegated-to
12. Q&A: Request for requirements and permissions for /beta/copilot/admin/catalog/packages — https://learn.microsoft.com/en-in/answers/questions/5630798/request-for-requirements-and-permissions-for-graph