Skip to main content
Connect a WordPress site once and Gradial can draft and update pages, posts, custom content types, templates, and media from a single flow — and edits respect the Gutenberg block model so a page Gradial touches still opens cleanly in the WordPress editor afterwards.

​
What You Can Do

Pages and posts

Browse, draft, and update pages and posts in either draft or published state. Edit Gutenberg blocks safely — block markers are preserved so the WordPress editor still treats the page as a real block document.

Custom post types

Discover the site’s custom post types and use them exactly like pages and posts. Create, read, update, and list entries for any custom post type exposed via the REST API.

Media library

Upload images and documents. Update media metadata (title, alt text, caption, description). Set featured images and insert image blocks with correct media references.

Layout and chrome

List and edit block templates and template parts (headers, footers, sidebars). Inspect and update widgets.

​
Prerequisites

  • Admin or Editor access to your WordPress site
  • WordPress REST API (/wp-json/wp/v2) accessible — required for self-hosted and WordPress VIP sites
  • A Gradial organization Administrator role to complete setup
WordPress.com hosted sites that don’t expose the standard REST API are not supported. This integration targets self-hosted and VIP-style sites where the REST API is reachable.

​
How to Connect

1

Get your authentication details from WordPress

Choose the auth method that matches how your site is set up:Application Password (recommended)
  1. Sign in to WordPress as the editor/admin account Gradial should use.
  2. Open Users → Profile → Application Passwords.
  3. Create a new application password named “Gradial” and copy the generated value.
  4. In Gradial, choose Basic auth and use the username + application password.
Bearer Token / JWT If the site uses a JWT or token-issuing plugin, generate a token scoped to the Gradial editor account. In Gradial, choose API Key Header, paste the token, and set the prefix to Bearer.Custom Headers Use this when the site is fronted by a proxy or CDN that needs extra headers, or when several headers must be sent together.OAuth2 Client Credentials For sites running an OAuth server plugin — supply the client ID, client secret, and token URL.
Always create a dedicated Gradial user or token rather than reusing a real editor’s credentials. Grant only the WordPress capabilities the team needs — typically Editor level.
2

Add the integration in Gradial

  1. In Gradial, go to Settings → Integrations.
  2. Find WordPress and click + Add.
  3. Fill in the connection details:
FieldValue
Integration NameA display name (e.g., Acme Marketing Site)
WordPress Site URLYour site’s public origin (e.g., https://wordpress.example.com)
Authentication MethodApplication Password, Bearer Token, Custom Headers, or OAuth2
REST API Base Path (optional)Defaults to /wp-json/wp/v2 — only change if the site uses a non-standard path
Preview Base URL (optional)The host serving rendered or preview pages, if different from the API origin
Default Author / Post Status (optional)Used when an authoring workflow does not specify them
  1. Click Save. Gradial validates that the site responds before the integration goes live.
3

Assign to an Environment

  1. Go to Settings → Environments and select the Gradial Environment where WordPress should be available.
  2. Add the WordPress integration to that Environment.
  3. Repeat for any additional Environments.

​
How It Fits Into Broader Workflows

Use caseHow to use it
Campaign landing pagesDraft the next campaign landing page in the same Gradial thread that produced the brief, copy, and creative
Image and media managementUpload generated or sourced imagery into the WordPress media library and drop it straight into the right page or post
Page updatesUpdate an existing page’s hero copy, swap an image, or insert a new section without breaking the block document
Content migrationCapture source pages, upload assets into WordPress, then assemble new pages using block-aware HTML preserving copy, structure, and links
Example — Draft a new campaign landing page:
  1. Ask Gradial to draft a new draft page with a title, slug, and body copy from the brief.
  2. Have Gradial upload the hero image into the WordPress media library.
  3. Ask Gradial to set the uploaded image as the page’s featured image and insert it as the hero block.
  4. Verify the draft by asking Gradial to look it up by slug.
  5. Open the page in the WordPress editor when reviewers are ready to publish.

​
Good to Know

  • Drafts need explicit lookups: WordPress REST list endpoints exclude drafts by default. Gradial knows to request status: draft and context: edit when verifying freshly created draft content.
  • Gutenberg block preservation: every Gradial edit keeps surrounding <!-- wp:* --> block markers intact — the difference between a clean page in the WordPress editor and a page that opens as one giant classic block.
  • Media uploads are size-capped: the integration accepts up to 25MB per upload. Larger assets need to go through the WordPress admin directly.
  • Production sites must use HTTPS: media source URLs Gradial pulls from are validated against HTTPS and blocked from private/internal hosts in production.

​
Support

Contact your Gradial onboarding lead or email [email protected] for help with setup.