Repository navigation
Add a core/media-query ability (read-only Media Library coverage) #1062
Description
Split out from #40, as requested there on 2026-07-16, so the media abilities can be planned and tracked on their own.
What problem does this address?
The WordPress 7.2 roadmap commits the AI team to "expand read-only coverage to resources such as media, taxonomies, and comments." Today the core/read-* set covers settings, content (posts and pages), and users; nothing lets an agent or an MCP client discover what is in the Media Library, so the most common editorial asks ("find the hero image we used for the spring campaign", "which attachments have no alt text") cannot be answered through abilities.
Proposal
Add a single read ability following the read/manage pattern from the merge proposal and the shape core/read-content already established:
- Name:
core/media-query - Category:
content - Input:
id(single attachment) or list arguments:search,mime_type(family or exact),parent(attached post),author,date_query(deferred, as for content),per_page,page,orderby,order. Returnstotalandtotal_pagesalongsideitemsso callers can page. - Output per item: id, title, alt text, caption, description, mime type, file size, dimensions where applicable, source URL, available sizes (name, URL, dimensions), parent post id, author id, dates, and
metalimited to registered,show_in_restmeta. No file contents. - Permission: mirrors the REST
wp/v2/mediaread checks:upload_filesfor listing, per-itemread_poston the attachment, unattached items visible only to users who canupload_files. Private parents hide their attachments unless the caller can read the parent. - Annotations:
readonly: true,idempotent: true,destructive: false. - Exposure:
public => falseby default like the other core reads;show_in_restopt-in.
Out of scope here: uploading, editing, or deleting attachments (core/manage-media, tracked separately), and image generation.
Why this shape
- One ability instead of
find-media-items+get-media-itemkeeps the tool count down for agents, the argument WordPress Core Abilities #40 settled on for settings. - Reusing the REST media controller's query and permission logic (the pattern [Verification utility] Compare the core read abilities against the REST API #931 is comparing for the existing reads) keeps behaviour identical between REST and abilities and avoids a second permission model.
Acceptance
- Unit tests for: listing with each filter, single item by id, pagination totals, unattached items hidden from a contributor, attachment of a private post hidden from a subscriber,
show_in_restmeta only. - Abilities Explorer shows and can execute it.
- Exposed through the MCP Adapter as a tool with correct annotations.
- Added to the WordPress Core Abilities #40 checklist and to
docs/abilities.md(or wherever the core reads are documented).
Path to core
Prototype here per the 7.1 deferral decision; open the Trac ticket once the shape has settled, alongside core/content-query (#64606) and core/users-query (#64657).
Activity
sarthaknagoshe2002 commentedon Sep 28, 2026
I would love to take this on!
The proposal makes complete sense. I will start scaffolding
core/read-mediawiring the input arguments directly into the existing REST media controller logic to ensure the permission model (upload_filesfor listing,read_postfor attachments) remains identical.jeffpaul commentedon Sep 29, 2026
@sarthaknagoshe2002 you'll likely want to verify approach with @jorgefilipecosta first to ensure what's planned aligns with his decided approach for abilities broadly-speaking
sarthaknagoshe2002 commentedon Sep 29, 2026
Hi @jeffpaul and @jorgefilipecosta,
Thanks for the ping! I have the implementation and test suite ready locally. To make sure it aligns with Jorge's approach across the core abilities suite (mirroring the patterns established in
core/read-content#739 andcore/read-users), here is a summary of the approach taken:1. Shape & Schema
core/read-mediaregistered in thecontentcategory (gated under the Custom Abilities experiment withwp_abilities_api_initpriority11to cleanly override core copies).oneOf):id): Returns the media object directly.search,mime_type,parent,author,per_page,page,orderby,order): Returns{ items, total, total_pages }.additionalProperties: falseon each branch with branch-local defaults omitted from schema (handled via runtime fallbacks) for clean client-side validator compilation.2. Permissions (Parity with REST
wp/v2/media)upload_filescapability (subscribers and contributors cannot list the media library).read_poston the parent post (attachments of private posts are hidden unless the caller has read access to the parent).upload_filesandread_poston the attachment (hides unattached private media from non-owner authors).3. Output & Efficiency
id,title,alt_text,caption,description,mime_type,file_size,dimensions(width,height),source_url,available_sizes,parent,author,date,date_gmt,modified,modified_gmt, andmeta.captionanddescriptionto preventthe_content/wpautop/autoembedfilters from injecting HTML wrappers (like<p class="attachment">).available_sizes: Structured array of image sub-sizes (thumbnail,medium,full, etc.) for images; empty array for non-image attachments.metastrictly to registered post meta withshow_in_rest => true.readonly: true,idempotent: true,destructive: false,open_world: false.4. Tests & Quality
show_in_restmeta, and core override behavior.executeAbility( 'core/read-media', ... )from@wordpress/abilitiesin the browser.@jorgefilipecosta, please let me know if this approach sounds good or if there are any specific adjustments you'd like made. If everything looks good, I can push the branch and open the PR right away!
[-]Add a core/read-media ability (read-only Media Library coverage)[/-][+]Add a `core/media-query` ability (read-only Media Library coverage)[/+]gziolo commentedon Oct 1, 2026
I’ve updated the title and description to reflect yesterday’s Core AI chat and the direction @jorgefilipecosta shared in the draft proposal. We’re aligning the names of read-only abilities that query collections around
core/$collection-query, so this ability becomescore/media-query.jeffpaul commentedon Oct 4, 2026
For those following along here, please give a review of #1098 to help keep things moving along, thanks!