Yes, you can create and update Modula galleries over HTTP. Modula 3.0 registers its gallery operations with the WordPress Abilities API, and that gives you a WordPress gallery REST API.
Say your booking app should turn each finished shoot into a draft gallery. With the Modula REST API, that’s one POST request. We make Modula, and we ran these requests against Modula 3.0.16 and Pro 3.0.18 in October 2026.
The short version
- Create an Application Password for a real user.
- POST to
modula/create-gallerywith a title and image IDs. - GET
modula/read-galleryfor its currentrevision. - POST changes to
modula/update-gallerywith that revision.

Which Modula API should you use?
Use Modula’s Abilities REST routes for anything outside WordPress. They’re the supported way to write galleries, and they validate every value. The Abilities API, core’s registry of plugin operations, arrived in WordPress 6.9 (dev note, November 2025).
| Route | Use it for |
|---|---|
/wp-json/wp-abilities/v1/abilities/modula/<operation>/run | Scripts and other apps |
wp_get_ability( 'modula/create-gallery' )->execute( [...] ) | PHP inside WordPress, as the current user |
| MCP (Model Context Protocol) tools | AI assistants |
/wp-json/wp/v2/modula-gallery | Reading published galleries, never writing |
What you need before your first request
The Modula REST API needs WordPress 6.9+, the free Modula 3.0 plugin and a real user’s Application Password:
- WordPress 6.9+ and Modula 3.0. Albums (Trio and up), presets (Business), ZIP import and Pro types or settings need Modula Pro.
- A user who can create galleries, upload files and edit your images.
create-gallerychecks upload rights even when you upload nothing. - An Application Password from Users → Profile → Application Passwords. By default, WordPress offers them only over HTTPS or on a site marked local (
WP_ENVIRONMENT_TYPE).
Good to know
Keep it secret. Store the password in server environment variables, never in browser JavaScript, and revoke it when you’re done. The examples read $WP_USER and $WP_APP_PASSWORD (say, admin and xxxx xxxx xxxx xxxx xxxx xxxx).
Skip the password under Modula → Settings → AI: it belongs to the Modula agent and works only over MCP.
How the requests work
Every Modula operation runs at /wp-json/wp-abilities/v1/abilities/modula/<operation>/run. The HTTP method follows what it does:
- Reads: GET, input in the query string (
?input[id]=123). Give cURL-gso the brackets survive. - Changes: POST, with a JSON body:
{"input": {…}}. - Trash and delete: DELETE, input in the query string.
Each change needs a request_id you invent: 16–128 letters, digits, hyphens or underscores. Use a new one per change. Resending the same ID with the same input returns the stored result, not a second change.
Good to know
Check status, not the HTTP code. Refusals arrive as HTTP 200. Only succeeded means it worked, so watch for rejected, conflict, forbidden, uncertain and partial.

Types are strict: "12" for an integer earns a 400.
modula/discover lists every operation (over 100 with Pro) and the settings your plan allows.
Create a gallery
modula/create-gallery takes a title, a status (draft or publish) and up to 100 Media Library image IDs:
curl -s -X POST "https://example.com/wp-json/wp-abilities/v1/abilities/modula/create-gallery/run" \
-u "$WP_USER:$WP_APP_PASSWORD" \
-H "Content-Type: application/json" \
-d '{"input": {
"request_id": "beach-gallery-create-0001",
"title": "Beach weekend",
"status": "draft",
"attachment_ids": [101, 102, 103]
}}'
You get back (trimmed):
{
"status": "succeeded",
"code": "",
"message": "",
"gallery": {
"id": 123,
"status": "draft",
"editor_url": "https://example.com/wp-admin/post.php?post=123&action=edit",
"shortcode": "[modula id=\"123\"]"
}
}
The new gallery opens in the 3.0 editor as Masonry: 3 columns, 10 px gaps. Paste the shortcode anywhere, or pick another embed option.
Create it as publish with Standalone’s Galleries get their own page on (Trio and up), and you also get a public_url.
Need to upload the images first?
modula/upload-image takes a filename and content_base64, up to 8 MiB (or your site’s lower limit) and 40 megapixels. Add a gallery id and revision to drop the image into it. New IDs come back in intake.attachment_ids.
For big files or bulk uploads, send the raw file to core media and use the id it returns:
curl -s -X POST "https://example.com/wp-json/wp/v2/media" \
-u "$WP_USER:$WP_APP_PASSWORD" \
-H "Content-Disposition: attachment; filename=sunset.jpg" \
-H "Content-Type: image/jpeg" \
--data-binary @sunset.jpg
Read a gallery and its revision
modula/read-gallery returns everything a change needs:
curl -s -g -u "$WP_USER:$WP_APP_PASSWORD" \
"https://example.com/wp-json/wp-abilities/v1/abilities/modula/read-gallery/run?input[id]=123&input[per_page]=100"
You get grouped settings, up to 100 items per page and a 64-character revision. Items carry IDs, titles, alt text and links, but no image URLs.
You’ll send that revision with every change. If the gallery changed since your read, you get conflict / stale_revision and nothing saves. Each success returns the new revision, so you can chain calls.
One catch: modula/list-galleries defaults to status=any, trash included, so pass input[status]=publish.
Change the layout and settings
modula/update-gallery changes only what you send. This body works on the free plugin: Justified grid, a 12 px Desktop gap, a 220 px Row height and a new title.
{"input": {
"request_id": "beach-gallery-layout-0002",
"id": 123,
"revision": "REVISION_FROM_READ_GALLERY",
"metadata": { "title": "Beach weekend, day one" },
"settings": {
"general": { "type": "justified-grid" },
"layout": { "gutter": 12, "gridRowHeight": 220 }
}
}}
A bad value gets a 400 that names the field and its range. Masonry, Uniform grid, Fit grid and Parallax set their Columns in layout.gridType, a string from "1" to "12".

Watch out
One Pro setting sinks the whole request. Add "lightbox": { "loop": true } (Loop images) on the free plugin and nothing saves, not even the title. Drop the setting or upgrade, then retry with a new request ID.
{
"status": "rejected",
"code": "feature_unavailable",
"blockers": [{ "reason": "needs_pro", "feature": "modula-pro", "path": "lightbox.loop" }]
}
The 16 gallery types:
| Gallery type | Value | Plan |
|---|---|---|
| Masonry (default) | grid | Free |
| Uniform grid | uniform-grid | Free |
| Fit grid | fit-grid | Free |
| Justified grid | justified-grid | Free |
| Custom grid | custom-grid | Free |
| Tiles | creative-gallery | Free |
| Polaroid | polaroid | Free |
| Template | template | Free |
| Freeform | freeform | Pro, any plan |
| Bento | bento | Pro, any plan |
| Parallax | parallax-masonry | Pro, any plan |
| BnB | bnb | Pro, any plan |
| Showcase | showcase | Pro, any plan |
| Story | story | Pro, any plan |
| Slider | slider | Trio and up |
| Video gallery | video | Starter and up |
Add, remove, reorder and edit images
modula/update-gallery-images takes a request_id, id, revision and 1–100 changes, applied in order:
"changes": [
{ "action": "add", "id": 104 },
{ "action": "move", "id": 104, "before_id": 101 },
{ "action": "update", "id": 102, "fields": { "link": "https://example.com/beach-house/", "target": 1 } },
{ "action": "remove", "id": 103 }
]
Images you don’t name stay put. An update can set:
- Links:
linkandtarget, for custom links. - Custom grid tiles:
width(2–12),height,gridX,gridY,gridLocked. - Fit:
halign,valign,tile_image_fit(coverorcontain).
Good to know
Got 500–900 photos? Create the gallery with the first 100, then add 100 at a time, passing each answer’s revision to the next call.
Alt text, titles and captions
Alt text, titles and captions live in the Media Library, so a change shows in every gallery that uses the image.
Get the image’s revision from modula/read-attachment. Then POST request_id, id, that revision and a text object (title, alt, caption, description) to modula/update-attachment-text. An empty string clears a field.
WordPress gallery REST API examples in Python, JavaScript and PHP
The Python, JavaScript and PHP snippets below call the Modula REST API and ran on October 25, 2026. Python, with requests:
import os, requests
SITE = os.environ["WP_SITE"]
AUTH = (os.environ["WP_USER"], os.environ["WP_APP_PASSWORD"])
BASE = f"{SITE}/wp-json/wp-abilities/v1/abilities"
def read(ability, **params):
r = requests.get(f"{BASE}/{ability}/run", params={f"input[{k}]": v for k, v in params.items()}, auth=AUTH, timeout=30)
r.raise_for_status()
return r.json()
def change(ability, **payload):
r = requests.post(f"{BASE}/{ability}/run", json={"input": payload}, auth=AUTH, timeout=60)
r.raise_for_status()
result = r.json()
if result.get("status") != "succeeded":
raise RuntimeError(f"{result.get('status')}: {result.get('code')} {result.get('message')}")
return result
JavaScript, for Node 18+:
// Never run this in a browser: it carries the password.
const AUTH = 'Basic ' + Buffer.from(`${process.env.WP_USER}:${process.env.WP_APP_PASSWORD}`).toString('base64');
const BASE = `${process.env.WP_SITE}/wp-json/wp-abilities/v1/abilities`;
async function change(ability, input) {
const res = await fetch(`${BASE}/${ability}/run`, {
method: 'POST',
headers: { Authorization: AUTH, 'Content-Type': 'application/json' },
body: JSON.stringify({ input }),
});
if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
const result = await res.json();
if (result.status !== 'succeeded') throw new Error(`${result.status}: ${result.code} ${result.message}`);
return result;
}
PHP, from another WordPress site (check status yourself):
$auth = 'Basic ' . base64_encode( getenv( 'WP_USER' ) . ':' . getenv( 'WP_APP_PASSWORD' ) );
$response = wp_remote_post( getenv( 'WP_SITE' ) . '/wp-json/wp-abilities/v1/abilities/modula/create-gallery/run', array(
'timeout' => 60,
'headers' => array( 'Authorization' => $auth, 'Content-Type' => 'application/json' ),
'body' => wp_json_encode( array( 'input' => array( 'request_id' => 'beach-gallery-create-0001', 'title' => 'Beach weekend', 'status' => 'draft', 'attachment_ids' => array( 101, 102, 103 ) ) ) ),
) );
$result = json_decode( wp_remote_retrieve_body( $response ), true ); // check $result['status']
Show the gallery on a page or in your own frontend
The WordPress REST API can create a page with the Modula block as its content:
curl -s -X POST "https://example.com/wp-json/wp/v2/pages" \
-u "$WP_USER:$WP_APP_PASSWORD" \
-H "Content-Type: application/json" \
-d '{"title": "Beach weekend", "status": "draft", "content": "<!-- wp:modula/gallery {\"id\":123} /-->"}'
A headless frontend needs image URLs, which read-gallery doesn’t return. Send up to 100 item IDs, in gallery order, to the media endpoint:
GET /wp-json/wp/v2/media?include=104,101,102&orderby=include&per_page=100&_fields=id,source_url,alt_text,media_details
Keep orderby=include, or you get upload-date order instead.
Published galleries have a shortcut: the public GET /wp-json/wp/v2/modula-gallery/123 needs no login, and its modulaImages carry url and src in gallery order.

Update many galleries at once
modula/update-galleries changes up to 25 galleries per call, each with its own revision. This sets two columns on phones (Responsive → Mobile, default 1):
{"input": {
"request_id": "mobile-two-columns-0005",
"targets": [
{ "id": 123, "revision": "REVISION_123", "settings": { "responsive": { "mobileColumns": 2 } } },
{ "id": 124, "revision": "REVISION_124", "settings": { "responsive": { "mobileColumns": 2 } } }
]
}}
You get succeeded, or partial with per-gallery results, so you retry only the stale ones.
To reuse one gallery’s look, modula/duplicate-gallery (id, revision, status) makes “Copy of …” with its settings and images. It’s the free stand-in for Gallery Defaults (presets), a Business feature.
When something goes wrong
Most Modula API failures name their own fix. Rows without a number arrive as HTTP 200:
| What you see | What to do |
|---|---|
401/403 rest_ability_cannot_execute | Use a real user who has the rights |
403 modula_agent_mcp_only | Use a normal user’s Application Password |
405 rest_ability_invalid_method | GET reads, POST changes, DELETE trash/delete |
400 ability_invalid_input | Fix the field the message names |
400 modula_classic_unsupported | Convert the gallery to the new editor |
rejected / invalid_attachments | Use image IDs this user can edit |
rejected / feature_unavailable | Drop the setting, upgrade or enable it |
conflict / stale_revision | Read again, retry with a new request ID |
conflict / request_payload_mismatch | Use a new request ID |
uncertain | Recover it; don’t resend with a new ID |
Lost a response? Recover it
A change that timed out may still have worked. GET modula/recover-request with the same input[request_id] for the stored result, or not_found if Modula never saw it. Records last 30 days per user and site, so recover with the same account.
Stop writing to /wp/v2/modula-gallery
If an old script (or this guide’s old version) POSTs to /wp-json/wp/v2/modula-gallery, retire it. Tested on Modula 3.0:
- Creates make classic galleries. They don’t open in the new editor, and every Modula operation refuses them.
- A partial
modulaSettingsresets the rest. Sending{"type": "grid"}turned a Justified grid with 12 px gaps and Loop images into Masonry, 10 px, loop off. modulaImagesreplaces the whole list. It also writes titles, alt and descriptions into the Media Library.captionis ignored. Captions go indescription.- Newer types become
grid. Sendjustified-gridand you get Masonry.

Reading published galleries there is fine.
Let an AI assistant do it instead
Modula 3.0’s gallery operations also run as MCP tools, so you can describe a gallery instead of scripting it.
In Modula → Settings → AI, pick one of seven assistants (Claude Code, ChatGPT, Cursor…) under Connect an assistant, follow its steps, then allow Read & write or Read only. Full steps: Connect AI assistants to Modula.

Frequently asked questions
Yes. Modula 3.0 registers its operations with the WordPress Abilities API (WordPress 6.9+), at /wp-json/wp-abilities/v1/abilities/modula/<operation>/run.
Yes. The gallery operations, uploads included, are free. Albums, presets, ZIP import and Pro types or settings need Modula Pro.
Take the item IDs from modula/read-gallery (default 20 per page, max 100) to /wp-json/wp/v2/media?include=<ids>&orderby=include&per_page=100 and use each source_url.
Not until you move them. In Modula → Content, open the gallery’s Actions menu (⋮) and choose Convert to new editor. See Move a gallery to the new editor and back.
Yes, with the same request_id: Modula returns the stored result instead of repeating the change. A new ID could apply it twice.


