# AI & Abilities API

> Four WordPress Abilities API abilities for AI agents and MCP clients: list categories, find images, tag images and create gallery pages, with REST methods.

Source: https://wispgallery.com/docs/abilities/

On WordPress 6.9 and newer, Wisp Gallery registers four **abilities** with the WordPress Abilities API. AI agents and MCP clients can use them to find untagged photos, tag them and build a gallery page – with the same permissions as a person doing it by hand.

## The abilities

All four are in the category `wisp-gallery` and shown in REST.

| Ability | Input | Permission |
| --- | --- | --- |
| `wisp-gallery/list-categories` 
read-only | – | `upload_files` |
| `wisp-gallery/find-images` 
read-only | `category`, `search`, `untagged`, `limit` (up to 500, default 50) | `upload_files` |
| `wisp-gallery/tag-images` | `attachment_ids`, `categories` (names or slugs, created if missing), `mode`: add, remove or replace | `upload_files`, `assign_terms`, and `edit_post` for each image |
| `wisp-gallery/create-gallery` | `title`, `attachment_ids` or `category`, `layout`, `filter`, `columns`, `status`: draft or publish | `edit_pages` (and `publish_pages` to publish) |

### list-categories

Lists the Gallery Categories with their ID, name, slug and number of items.

### find-images

Finds Media Library images by Gallery Category (name or slug), by search text (title, caption and description), or only those without any category (`untagged: true`).

### tag-images

Adds, removes or replaces Gallery Categories on images. `add` (the default) keeps existing categories, `remove` takes the given ones away, `replace` sets exactly these. Missing categories are created in add and replace mode, if the user may create categories. The whole call is refused if the user can’t edit one of the images; IDs that aren’t images are skipped and reported.

### create-gallery

Creates a page with a gallery of the given images – or of every image in a category – optionally with filter buttons above it. `layout` is one of the five layouts (masonry by default), `columns` 1–8, and the page is a **draft** unless `status` is `publish`. It returns the page ID, edit link and view link.

## Over REST

Abilities are listed at `/wp-json/wp-abilities/v1/abilities` and run at `/wp-json/wp-abilities/v1/abilities/<name>/run`. Core picks the HTTP method from each ability’s annotations:

| Ability | Annotations | Method |
| --- | --- | --- |
| `list-categories`, `find-images` | read-only | `GET`, input as `?input[…]` query parameters |
| `tag-images` | destructive, idempotent | `DELETE`, input as query parameters |
| `create-gallery` | – | `POST`, with a JSON body `{"input": {…}}` |

For example, with an application password:

```
curl -u admin:APP_PASSWORD \
  "https://example.com/wp-json/wp-abilities/v1/abilities/wisp-gallery/find-images/run?input[untagged]=1&input[limit]=20"

curl -u admin:APP_PASSWORD -X POST \
  -H "Content-Type: application/json" \
  -d '{"input":{"title":"Architecture","category":"architecture","layout":"rows","filter":false}}' \
  https://example.com/wp-json/wp-abilities/v1/abilities/wisp-gallery/create-gallery/run
```

## With an AI agent

Any client that speaks the Abilities API – for example through an MCP adapter for WordPress – sees the four abilities with their descriptions and input schemas. A typical request:

1. “Find my untagged photos” → `find-images` with `untagged`.
2. The agent looks at the images and proposes categories → `tag-images`.
3. “Make a portfolio page of the architecture photos with filter buttons” → `create-gallery`, as a draft for you to review.

> The abilities check the same capabilities as the admin screens. An agent working as an Author can tag the Author’s own uploads with existing categories, but can’t create categories or pages. Nothing is published unless the agent asks for it and the user may publish pages.

On WordPress versions before 6.9 the abilities are simply not registered; everything else works as usual.

Further reading: [Letting AI agents build galleries](https://wispgallery.com/blog/ai-abilities/) on the blog, with example calls.