Made in Europe, buy from Europe.

Black Friday

65% off Annual plans

25% off Lifetime · 10 per week

Ends December 2

Get the deal →

9 min read

WordPress Gallery REST API: Create and Edit Modula Galleries

WordPress gallery REST API guide for Modula 3.0: create galleries, change layouts and images, and publish them with tested cURL, Python, JS and PHP code.

How to Create and Update Modula Galleries with the REST API

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

  1. Create an Application Password for a real user.
  2. POST to modula/create-gallery with a title and image IDs.
  3. GET modula/read-gallery for its current revision.
  4. POST changes to modula/update-gallery with that revision.
Four steps: an Application Password for a real user, POST create-gallery with a title and image IDs, GET read-gallery for the revision, then POST update-gallery with 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).

RouteUse it for
/wp-json/wp-abilities/v1/abilities/modula/<operation>/runScripts and other apps
wp_get_ability( 'modula/create-gallery' )->execute( [...] )PHP inside WordPress, as the current user
MCP (Model Context Protocol) toolsAI assistants
/wp-json/wp/v2/modula-galleryReading 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-gallery checks 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 -g so 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.

Three real update-gallery responses: a valid change returns HTTP 200 and succeeded, a reused revision returns HTTP 200 and conflict stale_revision, and an ID sent as a string returns HTTP 400.

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".

A gallery in the Modula 3.0 editor set to Justified grid, with Row height 220 px and Spacing 12 px

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 typeValuePlan
Masonry (default)gridFree
Uniform griduniform-gridFree
Fit gridfit-gridFree
Justified gridjustified-gridFree
Custom gridcustom-gridFree
Tilescreative-galleryFree
PolaroidpolaroidFree
TemplatetemplateFree
FreeformfreeformPro, any plan
BentobentoPro, any plan
Parallaxparallax-masonryPro, any plan
BnBbnbPro, any plan
ShowcaseshowcasePro, any plan
StorystoryPro, any plan
SlidersliderTrio and up
Video galleryvideoStarter 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: link and target, for custom links.
  • Custom grid tiles: width (2–12), height, gridX, gridY, gridLocked.
  • Fit: halign, valign, tile_image_fit (cover or contain).

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.

A real GET to /wp-json/wp/v2/modula-gallery/2556 with no login returns modulaImages with each image's id, full-size url and 1024-pixel 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 seeWhat to do
401/403 rest_ability_cannot_executeUse a real user who has the rights
403 modula_agent_mcp_onlyUse a normal user’s Application Password
405 rest_ability_invalid_methodGET reads, POST changes, DELETE trash/delete
400 ability_invalid_inputFix the field the message names
400 modula_classic_unsupportedConvert the gallery to the new editor
rejected / invalid_attachmentsUse image IDs this user can edit
rejected / feature_unavailableDrop the setting, upgrade or enable it
conflict / stale_revisionRead again, retry with a new request ID
conflict / request_payload_mismatchUse a new request ID
uncertainRecover 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 modulaSettings resets the rest. Sending {"type": "grid"} turned a Justified grid with 12 px gaps and Loop images into Masonry, 10 px, loop off.
  • modulaImages replaces the whole list. It also writes titles, alt and descriptions into the Media Library.
  • caption is ignored. Captions go in description.
  • Newer types become grid. Send justified-grid and you get Masonry.
Posting only type grid to the old modula-gallery route turned a Justified grid with 12 px gaps and Loop images into Masonry with 10 px gaps and loop off.

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.

Modula Settings → AI with the Claude Code connection steps and the Connected list

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.

Make your next gallery
the one people remember.