Table of content
At a glance
- What you can do: give Semji's agents controlled access to your Drupal content.
- Who it's for: workspace owners and Drupal administrators.
- Compatibility: Drupal 8.7 and newer, the version that brought JSON:API into Drupal core.
Prerequisites
- Drupal 8.7 or newer, live, public, and served over HTTPS.
- The JSON:API and HTTP Basic Authentication (basic_auth) modules enabled. Both ship with Drupal.
- JSON:API set to read-write. This is the most common blocker, since it's read-only by default.
- A Drupal account dedicated to Semji, allowed to view, create, and edit the target content types, and delete them if you enable the Delete tool. On sites that use Paragraphs, also grant the matching Paragraphs permissions.
How to connect your Drupal site
1) Prepare your Drupal site
Three settings to handle on the Drupal side before connecting Semji.
Enable the modules. On the modules page (Extend menu, /admin/modules), enable JSON:API and HTTP Basic Authentication. Both come with Drupal.
Allow writing. In Configuration → Web services → JSON:API (/admin/config/services/jsonapi), select "Accept all JSON:API create, read, update, and delete operations". Without this, Semji can read your content but cannot create or edit it.
Create an account for Semji. Under People (/admin/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. You can also give it read access to field configuration: Semji uses it to better understand your site's structure, but works without it.
Tip ✅: if publishing fails, the first setting to check is almost always JSON:API's write permission.
2) Connect from Semji
You must be a workspace owner, since the connection applies to the whole team. In Semji, open Settings → Integrations, go to the CMS tab, and click Connect on the Drupal row.
Fill in the three fields:
- Site URL: your site's exact address over HTTPS, e.g. https://your-site.com. Enter the address your site actually uses: if it switches from example.com to www.example.com, enter the www version. Semji does not follow redirects.
- Username: the Drupal account created in step 1.
- Password: that account's password.
Click Next. Semji immediately checks that these credentials work on your site.
3) Pick the Drupal tools
Choose what AI agents can do on your site. All three groups are enabled by default:
- Read: browse, read, and inspect the site's content and structure.
- Write: create and update content.
- Delete: delete content. Note that this action is irreversible.
4) Save
Click Save. The Drupal row now shows as connected.
What Semji can do once connected
| Tool group | What it does |
|---|---|
| Read | List content types, spot their fields and text formats, list and read content as it's stored, for faithful edits |
| Write | Create and update content. New content is created as a draft, unless you explicitly ask an agent to publish. Existing tags are reused, new ones are created. Paragraphs-based layouts are supported |
| Delete | Permanently delete a piece of content. The agent always asks for confirmation first |
Good to know ℹ️: by default, Semji works on the article content type, in the basic_html text format. If your site uses Content Moderation, Semji applies the "published" and "draft" states instead of the plain status. For a different content type, format, or custom states, contact Semji support.
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 calls your site's JSON:API directly. If a firewall or protection like Cloudflare sits in front of your Drupal, it must let these calls through, or the connection fails.
On Cloudflare, create a rule that lets through (Skip action) requests coming from Semji's IP addresses whose path starts with /jsonapi/.
Semji IP addresses to allow:
-
63.34.75.122
-
63.35.78.179
-
54.228.104.165
-
18.200.156.37
-
34.248.117.83
-
52.213.28.177
Heads-up ⚠️: a firewall block looks just like a credentials error. When a protection layer answers "403 Forbidden" on /jsonapi, Semji shows an invalid-credentials error even though your username and password are correct. If you're sure of the credentials, check the firewall first.
Troubleshooting
"Invalid Drupal credentials. Check the username and the password." Drupal refused the connection. Possible causes: the username or password is wrong, the basic_auth module isn't enabled (Drupal then treats the request as an anonymous visitor), or a firewall is blocking the request before it reaches Drupal.
"Could not connect to the Drupal site. Check the credentials, the site URL, and that the JSON:API and Basic Auth modules are enabled." Semji couldn't reach your site. The most common causes:
- The JSON:API module is disabled: /jsonapi returns a 404.
- The address redirects. Semji does not follow redirects, so enter the final address, for example the www version.
- The site is unreachable: a DNS problem, host down, or a non-public site.
- A firewall shows an anti-bot verification page that Semji can't get past.
- The site responds too slowly: the response must arrive within 10 seconds.
Publishing fails with a 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.
An agent reports a permission error: "Drupal authentication or permission error: the API account cannot create or update this content." The account created for Semji lacks the needed rights on this content type. On Paragraphs sites, also check its Paragraphs permissions.
Errors shown before you even submit the form:
- "Please enter a valid URL." The text you entered isn't a web address.
- "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." Local or internal sites are rejected, the site must be public.