WordPress REST API

The plugin registers its own namespace, vergeml/v1, at /wp-json/vergeml/v1/…. It is what the plugin's own screens are built on, and it is available to you for the same reason.

Media taxonomies are also exposed through core's REST API — media_category is registered with show_in_rest, so wp/v2/media reports which folders a file is in and wp/v2/media_category lists the folders themselves. If all you need is "which folders is this file in", use core's routes.

Authentication #

These are logged-in admin endpoints, not a public API. They authenticate the same way any WordPress REST route does:

• From the browser: the logged-in cookie plus a nonce in the X-WP-Nonce header, from wp_create_nonce( 'wp_rest' ).
• From outside: application passwords, or whatever authentication plugin your site uses.

Every route has a permission callback. There is no anonymous access to any of them.

Capabilities #

Assignment uses a coarse gate at the endpoint and then decides per object inside the handler, which is where it has always really been decided.

---

Folders and the tree #

/tree is the hot path and is built to stay flat: 4 queries whatever the folder count, measured from 200 to 2,000 folders. See Performance.

Smart folders and search #

Duplicates and setting aside #

There is no delete endpoint in the set-aside feature. See Set aside.

Importing #

The AI #

/ai-status never returns the licence key. It reports a boolean.

Folder sorting #

Folder talk and instructions #

/say-run takes a plan, never the text. Four verbs are allowed — move, tag, rename, create — and there is no delete in the file to reach.

Auto-filing #

Miscellaneous #

---

A worked example #

Read the tree from the browser:

fetch( wpApiSettings.root + 'vergeml/v1/tree', {
  headers: { 'X-WP-Nonce': wpApiSettings.nonce },
} )
  .then( r => r.json() )
  .then( tree => console.log( tree ) );

File two attachments into folder 42, keeping them where they already are:

fetch( wpApiSettings.root + 'vergeml/v1/assign', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-WP-Nonce': wpApiSettings.nonce,
  },
  body: JSON.stringify( {
    taxonomy:    'media_category',
    attachments: [ 1841, 1842 ],
    add:         [ 42 ],
  } ),
} );

/assign takes taxonomy (required), then attachments with add and remove lists — or a batch array carrying its own attachments per group. mode decides whether a drop moves or adds, and post_type says which list the caller is looking at, so the counts that come back are the ones it is showing.

The permission callback is a coarse gate. The real check is per attachment inside the handler, because a batch is a batch of separate permissions: one call naming forty files must not be authorised by whether the caller may edit the first.

Or skip all of it and use core, since folders are terms:

wp_set_object_terms( 1841, array( 42 ), 'media_category', true );

That last line is the whole argument for the taxonomy decision.