WordPress Grid Integration

Last updated: July 17, 2026

A server-side WordPress integration can use ImageGrid for hosted grid_render jobs while keeping local rendering as a fallback. The integration stores the ImageGrid credential on the WordPress server, polls asynchronous jobs, and uses signed public tile templates only when CDN Delivery is active.

Before you connect

You need:

• an active ImageGrid Starter, Growth, or approved alpha-test account;
• an api_runtime key;
• a server-side WordPress integration that supports the ImageGrid API;
• outbound HTTPS access from WordPress to https://api.imagegrid.dev.

Keep the API key server-side. Do not place it in browser JavaScript, theme files, public WordPress options, screenshots, or support messages.

Connect from WordPress

1. Open the ImageGrid settings in your WordPress integration.
2. Enter https://api.imagegrid.dev and an ImageGrid runtime API key.
3. Test the connection.
4. Review the returned account state, remaining usage, effective limits, and CDN Delivery status.
5. Keep local safeguards at or below the effective limits returned by ImageGrid.
6. Render a small test grid before submitting a production workload.

If every remote submission needs review, keep automatic rendering disabled and submit jobs manually.

Plan and alpha-test limits

The public Starter and Growth plans use the same ImageGrid API with different capacity envelopes. Approved alpha testers can receive a separate account with an expiring runtime key. The default high-capacity test envelope matches Growth so integration testing exercises realistic limits without changing the public plan catalog.

Tester keys and operator access expire after 90 days by default and may be issued for 1–365 days. ImageGrid enforces the account contract even if local safeguards are configured higher.

Rendering and tile delivery

A normal asynchronous workflow is:

1. WordPress builds the grid manifest and submits the job.
2. ImageGrid queues and renders the standard Deep Zoom pyramid.
3. WordPress polls the job until it succeeds or fails.
4. The integration records the returned tileset and version metadata.
5. Public pages use local delivery unless the account has CDN Delivery and the job returns a signed public_tile_url_template.

CDN Delivery is separate from hosted rendering. It costs CA$5/month, includes 100 decimal GB per billing period, and has overage disabled by default. An account owner may set a CA$0–CA$25 monthly cap for CA$0.04 per whole GB beyond the included amount. Delivery pauses at the cap or when metering is stale; rendering can remain available.

Failure behavior

Keep local rendering available when ImageGrid is disabled, unavailable, outside the connected account limits, or not entitled for CDN delivery. A WordPress integration should surface a bounded administrator notice for unresolved rendering failures and may send a deduplicated email notification.

For a failed request or job:

• honor Retry-After on 429 responses;
• record the ImageGrid X-Request-ID, asset ID, job ID, and error code;
• never log the API key, signed URL query string, raw grid manifest, or full service payload;
• check the connected account for plan, quota, expiry, billing, and CDN state;
• use Errors for retry guidance, then contact ImageGrid if the problem continues.

Local development

Use http://host.docker.internal:18082 when WordPress and ImageGrid run in local containers. Public sites should use https://api.imagegrid.dev over HTTPS.

Keep live integration checks opt-in. Pass IMAGEGRID_API_URL and IMAGEGRID_API_KEY to the test process at runtime, avoid saving the credential, create a small grid render, poll it, validate the returned Deep Zoom metadata, and download an edge tile.