> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gradial.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WordPress

> Connect Gradial to WordPress to draft pages, posts, media, and templates while preserving the Gutenberg block model.

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

<CardGroup cols={2}>
  <Card title="Pages and posts" icon="file">
    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.
  </Card>

  <Card title="Custom post types" icon="list">
    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.
  </Card>

  <Card title="Media library" icon="images">
    Upload images and documents. Update media metadata (title, alt text, caption, description). Set featured images and insert image blocks with correct media references.
  </Card>

  <Card title="Layout and chrome" icon="table-columns">
    List and edit block templates and template parts (headers, footers, sidebars). Inspect and update widgets.
  </Card>
</CardGroup>

***

## 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

<Warning>
  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.
</Warning>

***

## How to Connect

<Steps>
  <Step title="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.

    <Warning>
      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.
    </Warning>
  </Step>

  <Step title="Add the integration in Gradial">
    1. In Gradial, go to **Settings → Integrations**.
    2. Find **WordPress** and click **+ Add**.
    3. Fill in the connection details:

    | Field                                         | Value                                                                           |
    | --------------------------------------------- | ------------------------------------------------------------------------------- |
    | **Integration Name**                          | A display name (e.g., `Acme Marketing Site`)                                    |
    | **WordPress Site URL**                        | Your site's public origin (e.g., `https://wordpress.example.com`)               |
    | **Authentication Method**                     | Application 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                           |

    4. Click **Save**. Gradial validates that the site responds before the integration goes live.
  </Step>

  <Step title="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.
  </Step>
</Steps>

***

## How It Fits Into Broader Workflows

| Use case                       | How to use it                                                                                                                            |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Campaign landing pages**     | Draft the next campaign landing page in the same Gradial thread that produced the brief, copy, and creative                              |
| **Image and media management** | Upload generated or sourced imagery into the WordPress media library and drop it straight into the right page or post                    |
| **Page updates**               | Update an existing page's hero copy, swap an image, or insert a new section without breaking the block document                          |
| **Content migration**          | Capture 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 [support@gradial.com](mailto:support@gradial.com) for help with setup.