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

# Drupal

> Connect Gradial to Drupal to read, search, create, update, and preview content without leaving your workflow.

Connect a Drupal site once and Gradial can read, search, create, update, delete, export, and preview content from a single flow — no context switch into the Drupal admin.

***

## What You Can Do

<CardGroup cols={2}>
  <Card title="Discovery" icon="list">
    List and describe Drupal resource types — nodes, blocks, paragraphs, media, taxonomy — with field shapes and worked examples so the agent never guesses field names.
  </Card>

  <Card title="Search and read" icon="magnifying-glass">
    Find entities by title, path alias, UUID, or page-only filters. Read a full entity with relationship resolution, body field shapes, and stored snapshots.
  </Card>

  <Card title="Authoring" icon="pen-nib">
    Create new entities, update fields (including formatted text with value/format preservation), and delete entities. Multi-value, relationship, and reference fields stay JSON:API-shaped.
  </Card>

  <Card title="Media" icon="photo-film">
    List and read media entities. Upload new media (images, documents) and reference them in content payloads.
  </Card>

  <Card title="Bulk content push" icon="layer-group">
    Push a staged directory of payloads for relationship-heavy migrations where dependent entities must be created in order.
  </Card>

  <Card title="Migration mode" icon="arrows-rotate">
    A dedicated content-migration workflow enforcing 1:1 source preservation, source-inventory files, asset upload before referencing, and rendered-page QA before completion.
  </Card>
</CardGroup>

***

## Prerequisites

* Admin access to your Drupal site to enable modules and create credentials
* Drupal's **JSON:API** module enabled (ships as core in Drupal 10/11)
* A Gradial organization **Administrator** role to complete setup

***

## How to Connect

<Steps>
  <Step title="Prepare your Drupal site">
    Make sure **JSON:API** is enabled in Drupal (**Extend → JSON:API**). Drupal 10/11 ships it as a core module.

    Then choose the auth method that fits your site:

    **Basic (simplest)**

    1. Enable Drupal core's **Basic Auth** module.
    2. Create a dedicated editor/admin user for Gradial with JSON:API access permissions for the bundles you want to author.
    3. Note the username and password.

    **API Key Header**

    1. If your site uses a custom auth module (e.g., `key_auth`, JWT, an SSO header, or a CDN-issued token), generate a token scoped to the Gradial editor account.
    2. Note the token, header name, and prefix.

    **Custom Headers**
    Use this when the upstream needs more than one header or when you front Drupal with a proxy that injects its own auth.

    <Warning>
      Always create a dedicated Gradial user or token rather than reusing a real editor's credentials. Grant only the JSON:API permissions for the bundles you want available in Gradial.
    </Warning>
  </Step>

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

    | Field                             | Value                                                                                    |
    | --------------------------------- | ---------------------------------------------------------------------------------------- |
    | **Integration Name**              | A display name (e.g., `United Rentals NL`)                                               |
    | **Drupal Base URL**               | Your site's origin — the JSON:API root (e.g., `https://drupal-united-rentals.ddev.site`) |
    | **Authentication Method**         | Basic, API Key Header, or Custom Headers                                                 |
    | **Preview Base URL** *(optional)* | If rendered pages are served from a different host than the JSON:API root                |

    4. Click **Connect** to validate. Gradial probes JSON:API, lists available resource types, and surfaces them so you can confirm which types should be treated as pages.
    5. Click **Save**.
  </Step>

  <Step title="Assign to an Environment">
    1. Go to **Settings → Environments** and select the Gradial Environment where Drupal should be available.
    2. Add the Drupal integration to that Environment.
    3. Repeat for any additional Environments.
  </Step>
</Steps>

***

## How It Fits Into Broader Workflows

| Use case                     | How to use it                                                                                                              |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Content authoring**        | Author Drupal pages and components from the same Gradial thread that produced the brief, copy, or designs                  |
| **Design-system migrations** | Remap source pages onto a customer's Drupal component model while preserving copy, imagery, hierarchy, links, and CTAs 1:1 |
| **Asset upload**             | Upload source assets into Drupal media before referencing them in pages so the destination site stays self-contained       |
| **Rendered-page QA**         | Use Gradial preview to QA the actual rendered Drupal page (not just JSON), gating completion on rendered-page checks       |

**Example workflow — Port a page to Drupal:**

1. Capture the source page (live HTML, screenshots, or export) into a source inventory listing sections, copy, CTAs, images, and downloads.
2. Discover the target model by listing and describing the target content types.
3. Upload source images, capturing the returned media UUIDs.
4. Stage the new entity payload and create the page.
5. Re-read the entity and inspect the snapshot and preview; iterate on field mappings until rendered-page QA passes.
6. Publish (or keep in draft) and hand the preview URL back to the requester.

***

## Support

Contact your Gradial onboarding lead or email [support@gradial.com](mailto:support@gradial.com) for help with setup.