Skip to main 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 the permissions listed in Permissions for the API account. A plain editor role is not enough — see that section for why.
  • To let agents write meta descriptions: the Metatag module, plus a Meta tags field on each content type concerned. See Meta descriptions.
  • 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.
  • You are a workspace owner in Semji. The connection is shared with the whole workspace.
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.

​
Step 1 — Prepare your Drupal site

1

Enable the required modules

In the Drupal admin, go to Extend and enable JSON:API and HTTP Basic Authentication. Both ship with Drupal core.
2

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”.
3

Create a dedicated role and user for Semji

Under People → Roles, create a role (e.g. Semji API) and grant it the permissions listed in Permissions for the API account. Then, under People, create an account (e.g. semji-api) with a strong password and assign it that role.Do not reuse a plain editor role: it lacks the permission Semji needs to set the publication status, and every write fails with a 403.
4

Add a Meta tags field, if you want meta descriptions

Only if agents should write meta descriptions — see Meta descriptions for the full procedure.

​
Permissions for the API account

Grant these to the role you created for Semji. Replace article with each content type agents will work on.
administer nodes is required on content types that do not use Content Moderation. Semji always states the publication status explicitly, so content is never published by accident — and Drupal reserves writing the status field to that permission. Without it, every create and update fails with “The current user is not allowed to POST the selected field (status). The ‘administer nodes’ permission is required.”On a content type governed by Content Moderation, Semji writes the moderation state instead, so administer nodes is not needed — grant the transition permissions of your workflow instead.

​
About administer node fields

This one is optional but recommended. With it, Semji reads your content types’ field definitions directly and knows exactly which field holds what. Without it, Semji falls back to inspecting an existing piece of content to infer the structure — which works, but is less precise and needs at least one existing item per content type. Drupal flags this permission as restricted, because the same permission also allows adding and deleting fields through the admin UI. If your security policy rules that out, leave it off: the integration works without it.

​
Meta descriptions

Drupal core has no meta description field. Semji writes meta descriptions through the Metatag contributed module, which most Drupal SEO setups already use.
1

Install and enable Metatag

Install the module the way you normally install contributed modules, then enable it under Extend.
2

Add a Meta tags field to each content type

Go to Structure → Content types → your type → Manage fields → Create a new field, and pick the Meta tags field type. Any label and machine name work — Semji identifies the field by its type, not its name.
Once the field exists, pass the meta description to an agent like any other instruction (“write the meta description too”) — Semji formats and stores it for you. On an update it merges into the tags already on the item, so a meta title you wrote by hand is preserved.
If a content type has no Meta tags field, agents write the content normally and tell you the meta description could not be saved. They never fall back to pasting it into the body.

​
Step 2 — Connect from Semji

1

Open the CMS integrations

In Semji, go to Settings → Integrations, open the CMS tab, and click Connect on the Drupal row.
2

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

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).
4

Activate

Click Activate. The Drupal row now shows as connected.

​
What Semji can do once connected

​
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:
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/.
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.

​
Troubleshooting

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.
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.
“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.
“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.”
Check whether the account has administer nodes. Drupal reserves writing the status field to that permission, and Semji always states the publication status explicitly, so an account without it fails on every create and update — even though reading works fine and the connection test passes. See Permissions for the API account.
If your site is in maintenance mode, Drupal answers 503 on /jsonapi for every account without the “Use the site in maintenance mode” permission — which the API account normally does not have. You can browse the site yourself because your admin session bypasses it. Turn maintenance mode off under Configuration → Development → Maintenance mode, or grant that permission to the Semji role.
Two distinct cases:
  • No meta description field on this content type — install Metatag and add a Meta tags field, as described in Meta descriptions.
  • Drupal accepted the write but stored nothing — Semji could not read your field definitions and guessed the wrong format. Grant administer node fields to the API account, or set that one meta description by hand.
In both cases the rest of the content is written normally.
  • “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.