AI Decoupled turns Drupal's AI assistants and agents into web addresses your own app can call. Build your interface in React, Vue, or a mobile app, and let Drupal do the AI work behind it.

Drupal's AI module lets you configure chatbots, assistants, and AI agents inside your site. Out of the box, those are designed to appear on a page that Drupal itself renders. That works well until your front-end lives somewhere else — a JavaScript single-page app, a mobile app, a static site, or another server entirely.

This module bridges that gap. You pick an AI assistant or agent you have already configured, choose which user roles may use it, and it becomes a normal HTTP endpoint at an address like /api/ai/support-bot. Your app sends a question and gets an answer back as JSON — or as a live stream of text that appears word by word, the way people now expect a chatbot to behave.

Nothing is exposed until you say so. Every endpoint you create is something you deliberately configured, restricted to the roles you chose.

Features

Create endpoints through the admin interface. No code required. Go to Configuration → AI → AI Decoupled, click Add endpoint, pick which AI you want to expose, tick the roles allowed to call it, and save. The endpoint is live immediately.

Works with whichever AI you have set up. AI agents, AI assistants, or the direct model access that ships with this module. If you install a third-party AI processor later, it appears in the list automatically — this module does not need to know about it in advance.

Live streaming responses. When the underlying AI supports it, answers stream back token by token using server-sent events, so your interface can display text as it is generated rather than waiting for the whole reply.

Rate limiting per endpoint. Set how many requests are allowed in a given window, counted per user, per IP address, or both. Each endpoint has its own budget, so a busy public endpoint cannot exhaust a private one.

Role-based access, enforced three ways. A caller needs a site-wide permission, membership of one of the roles you selected on that specific endpoint, and approval from the AI's own access rules. All three must agree.

Predictable errors. Every failure — including permission denials and unknown addresses — comes back as JSON with a machine-readable error code, never as a Drupal error page. Front-end code can rely on the shape of what it receives.

Deployable configuration. Endpoints are stored as Drupal configuration, so they export with drush config:export and move between your development, staging, and production sites like any other setting.

When would I use this?

A decoupled or headless Drupal site. Your content lives in Drupal and your front-end is Next.js, Nuxt, Astro, or similar, and you want an AI chat feature in it.
A mobile app backed by Drupal. Give the app a support chatbot without embedding a web view.
Server-to-server automation. Another system needs to ask one of your configured AI agents to perform a task, and authenticate with a token rather than a browser session.
Several audiences, different AIs. Expose a public FAQ bot with a tight rate limit and an internal research agent restricted to staff, side by side, each configured independently.

Post-Installation

Enabling the module adds no endpoints and changes nothing about your site until you create one. There is no new content type and no text format to configure.

1. Grant the permission. Go to People → Permissions and give Access the AI Decoupled API to the role your API callers will use. This is a master switch — without it, every request is refused no matter how an endpoint is configured.

2. Create an endpoint. Go to Configuration → AI → AI Decoupled (/admin/config/ai/decoupled) and click Add endpoint. You will choose:

Label and machine name — the machine name becomes the web address, so support_bot gives you /api/ai/support_bot.
Chat Executor — which AI to expose. Selecting one reveals that AI's own settings below it.
Allowed roles — who may call this specific endpoint. At least one is required.
Rate limiting — optional, but required if you allow anonymous callers.
Advanced → Stream — whether streamed responses are permitted here.

3. Set up authentication. Requests must authenticate with a credential, not a browser session — this is deliberate, and it is what makes the endpoints safe to call from outside Drupal. Enable Drupal core's HTTP Basic Authentication module for testing, or install Simple OAuth for production.

4. Try it. With HTTP Basic enabled:

curl -u user:password \
  -H 'Content-Type: application/json' \
  -d '{"messages":[{"role":"user","text":"Hello"}]}' \
  https://example.com/api/ai/support_bot

Two things worth knowing before you build against it

Streaming is not guaranteed on every AI. The direct model access included with this module streams reliably. AI agents never stream — they reason in several steps and return a finished answer. AI assistants stream only on ordinary conversational turns; a turn that triggers an action does not. Your client should check the response's Content-Type header rather than assuming, and the module will quietly send a normal JSON response rather than failing when streaming is unavailable.

Anonymous callers cannot have saved conversations. Drupal stores conversation history against a browser session, and a token-authenticated client does not have one. If you need an endpoint open to anonymous users, use a stateless AI and have your app send the full conversation with each request. The module reports this honestly rather than appearing to work and silently forgetting everything.

Full documentation of every endpoint, request and response shape, error code, CORS setup, and proxy configuration for streaming is in the module's README.

Additional Requirements

AI is the only required dependency. It provides the chat processors this module exposes, and the connection to whichever AI provider you use.

You will also need at least one AI provider module configured with credentials — for example AI Provider OpenAI, or any other provider supported by the AI ecosystem.

To authenticate callers you need an authentication provider: Drupal core's HTTP Basic Authentication module, or Simple OAuth.

Recommended modules/libraries

Simple OAuth — token-based authentication. Recommended over HTTP Basic for anything in production.
AI Agents — adds AI agents as an available executor, for multi-step reasoning and tool use.
AI Chatbot (a submodule of AI) — adds AI assistants as an available executor, for conversational assistants with saved history and actions.
AI Metering or AI usage limits — token budgets and cost control. These enforce at the provider level, so endpoints created here inherit their limits automatically, and this module reports an exceeded budget as a clean HTTP 402.

Neither AI Agents nor AI Chatbot is required. With neither installed, the module still works using its own built-in direct model access.

Similar projects

AI Chatbot (a submodule of AI) provides the DeepChat widget and an endpoint built for it. Use AI Chatbot when you want a chat widget on a page that Drupal renders. Use AI Decoupled when the interface lives outside Drupal. The practical differences: AI Chatbot's endpoint requires a CSRF token and a browser session, returns HTML that has already been rendered and filtered, and is configured per widget placement. This module requires no CSRF token, returns the model's raw text for your client to render, and is configured per endpoint.

JSON:API and RESTful Web Services (both in core) expose Drupal's content entities over HTTP, and are the right tool for reading and writing content. Neither is suitable for this job, because both build a complete response before sending it — which makes streamed responses impossible. That constraint is why this module uses its own routes rather than building on them.

Supporting this Module

This module is maintained on a volunteer basis. Issue reports, patches, and reviews are all genuinely useful contributions.

Community Documentation

The module's README covers every endpoint in detail, including request and response shapes, the full list of error codes, the security model, CORS configuration, and what to check if streamed responses arrive all at once instead of progressively.

AI Decoupled