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

# Connect Drupal to Semji

> Step-by-step guide to connect your Drupal site to Semji through JSON:API and Basic Auth, so AI agents can read, create, and update content.

Semji connects to Drupal through the **JSON:API** core module, authenticating
every request with **HTTP Basic Auth**. Once connected, Semji's AI agents can
explore your content model, list and read content, create and update it, and
— if you allow it — delete it.

Compatible from **Drupal 8.7** (the version where JSON:API joined Drupal core).

## Prerequisites

* **Drupal 8.7 or newer**, served over **HTTPS** and reachable from the
  **public internet**.
* The **JSON:API** core module enabled.
* The **HTTP Basic Authentication** (`basic_auth`) core module enabled.
* For publishing and updating: JSON:API set to read-write — check **"Accept
  all JSON:API create, read, update, and delete operations"** under
  `/admin/config/services/jsonapi`. JSON:API ships **read-only by default**;
  this is the most common blocker.
* A dedicated Drupal user account for Semji with permission to view, create,
  and edit the content types agents will work on (and delete, if you enable
  the Delete tool). If your site uses **Paragraphs**, also grant the account
  the relevant Paragraphs type permissions.
* If a firewall, WAF, or anti-bot protection (Cloudflare, Akamai, Sucuri, …)
  sits in front of your site, it must **allow Semji's IP addresses** — see
  [Firewalls and IP allowlisting](#firewalls-and-ip-allowlisting).
* You are a **workspace owner** in Semji. The connection is shared with the
  whole workspace.

<Note>
  Availability of the Drupal integration depends on your Semji plan. If the
  **Connect** button opens an upgrade dialog instead of the connection form,
  contact your account manager.
</Note>

## Step 1 — Prepare your Drupal site

<Steps>
  <Step title="Enable the required modules">
    In the Drupal admin, go to **Extend** and enable **JSON:API** and **HTTP
    Basic Authentication**. Both ship with Drupal core.
  </Step>

  <Step title="Allow write operations">
    Go to **Configuration → Web services → JSON:API**
    (`/admin/config/services/jsonapi`) and select **"Accept all JSON:API
    create, read, update, and delete operations"**.
  </Step>

  <Step title="Create an API user for Semji">
    Under **People**, create a dedicated account (e.g. `semji-api`) with a
    strong password and a role that can view, create, and edit the target
    content types. Optionally grant field-configuration read access — Semji
    uses it to discover your content model more precisely, and degrades
    gracefully without it.
  </Step>
</Steps>

## Step 2 — Connect from Semji

<Steps>
  <Step title="Open the CMS integrations">
    In Semji, go to **Settings → Integrations**, open the **CMS** tab, and
    click **Connect** on the Drupal row.
  </Step>

  <Step title="Enter your credentials">
    Fill in the three fields:

    * **Site URL** — the canonical HTTPS base URL of your site, e.g.
      `https://your-site.com`. Semji does not follow redirects, so use the
      exact URL your site resolves to (`www` vs non-`www` matters).
    * **Username** — the Drupal login of the API account created in step 1.
    * **Password** — that account's password.

    Click **Next**. Semji tests the connection live by calling
    `GET /jsonapi` on your site and verifying that Drupal authenticates the
    account.
  </Step>

  <Step title="Pick the Drupal tools">
    Choose what AI agents can do on your site. All groups are enabled by
    default:

    * **Read** — browse, read, and inspect the site's content and structure.
    * **Write** — create and update content on the site.
    * **Delete** — delete content from the site (destructive).
  </Step>

  <Step title="Activate">
    Click **Activate**. The Drupal row now shows as connected.
  </Step>
</Steps>

## What Semji can do once connected

| Tool group | What it does                                                                                                                                                                                                |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Read       | List content types, discover a type's fields and text formats, list and read content (including the raw stored HTML for lossless edits)                                                                     |
| Write      | Create and update content — new content is created as **draft** unless you explicitly ask an agent to publish; tags are matched or created in the `tags` vocabulary; Paragraphs-based layouts are supported |
| Delete     | Permanently delete a piece of content (agents ask for explicit confirmation first)                                                                                                                          |

### Content defaults

Out of the box, Semji targets the **`article`** content type with the
**`basic_html`** text format. On sites using **Content Moderation**, Semji
writes the `published` / `draft` moderation states instead of the raw status
field. Contact Semji support if your site needs different defaults (another
content type, text format, or custom moderation state names).

## Manage or disconnect

From **Settings → Integrations → CMS**, the Drupal row offers:

* **Manage tools** — enable or disable each tool group.
* **Disconnect** — remove the integration for the whole workspace.

## Firewalls and IP allowlisting

Semji's servers call your Drupal JSON:API directly. If your site sits behind
Cloudflare or another WAF, you must allow those calls or the connection will
fail.

Semji's servers reach the internet through a fixed set of outbound IP addresses. If a firewall, WAF, or anti-bot protection (Cloudflare, Akamai, Sucuri, …) sits in front of your site, it can block Semji's requests — typically with a `403 Forbidden` — before they ever reach your CMS, even when your credentials are correct.

Allow the following Semji IP addresses:

```text theme={null}
63.34.75.122
63.35.78.179
54.228.104.165
18.200.156.37
34.248.117.83
52.213.28.177
```

On **Cloudflare**, create a WAF custom rule with the **Skip** action matching
requests where the source IP is one of the addresses above and the path
starts with `/jsonapi/`.

<Warning>
  A WAF answering `403 Forbidden` on `/jsonapi` makes Semji report **"Invalid
  Drupal credentials"** even though your username and password are correct.
  If you are sure of the credentials, check the firewall first.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="&#x22;Invalid Drupal credentials. Check the username and the password.&#x22;">
    Drupal did not authenticate the request. Either the username or password
    is wrong, the **`basic_auth`** module is not enabled (Drupal then treats
    the request as anonymous), or a WAF is blocking the request with a `403`
    before it reaches Drupal.
  </Accordion>

  <Accordion title="&#x22;Could not connect to the Drupal site. Check the credentials, the site URL, and that the JSON:API and Basic Auth modules are enabled.&#x22;">
    Frequent causes:

    * **JSON:API module disabled** — `/jsonapi` returns 404.
    * **The URL redirects.** Semji follows no redirects: if
      `https://example.com` redirects to `https://www.example.com`, enter the
      `www` URL.
    * **The site is unreachable** — DNS failure, host down, or the domain
      resolves to a private network address.
    * **A WAF challenge page** — an HTML anti-bot response is not valid
      JSON:API and fails the connection.
    * **The site is too slow** — responses must arrive within 10 seconds.
  </Accordion>

  <Accordion title="Publishing fails with a JSON:API read-only error">
    *"Drupal JSON:API is configured to accept only read operations."* — an
    administrator must enable **"Accept all JSON:API create, read, update,
    and delete operations"** under `/admin/config/services/jsonapi`.
  </Accordion>

  <Accordion title="An agent reports a permission error">
    *"Drupal authentication or permission error: the API account cannot
    create or update this content."* — the API account lacks create/edit
    permission on the target content type. For Paragraphs-based sites:
    *"check Paragraphs Type Permissions for the API account."*
  </Accordion>

  <Accordion title="URL validation errors before submitting">
    * *"Please enter a valid URL."* — the value does not parse as a URL.
    * *"The site URL must start with https\://."* — HTTP sites cannot be
      connected.
    * *"The site URL points to a private or reserved address, which is not
      allowed."* — localhost and private-network hosts are rejected; the site
      must be publicly reachable.
  </Accordion>
</AccordionGroup>

## Related

* [Sync drafts to your CMS](/guides/sync-drafts-to-cms) — API-based publishing flow, if you prefer to drive the sync yourself.