Web Services API in Joomla

2. JSON:API - the Format Joomla Speaks

2.1 A Shared Convention

Joomla does not invent its own response shape. It follows JSON:API, a public convention for how a REST response should look. Because the format is standard, many existing client libraries already understand it, and the structure is the same for articles, users, or any other resource.

2.2 The Shape of a Single Item

A request for one article returns a data object with a type, an id, and an attributes block that holds the actual fields:

{
  "links": { "self": "https://example.test/api/index.php/v1/content/articles/1" },
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "Welcome to my site",
      "alias": "welcome-to-my-site",
      "state": 1,
      "catid": 2,
      "introtext": "..."
    }
  }
}

2.3 The Shape of a List

A list request returns data as an array of those objects, plus a meta block with the total count and links for paging through the results. Knowing this shape once means you can read every list the API returns, whatever the resource.

4. Authentication - Proving Who You Are

4.1 No Form, No Session

The website remembers you with a session cookie after you log in once. The API has no login form and keeps no session. A program must prove who it is on every single request. Joomla supports two methods, both handled by the api-authentication plugin group.

4.2 Token Authentication (Recommended)

Each user gets a personal token, a long secret string, and sends it as a header on every call. No password ever leaves the server, and a token can be revoked on its own without changing the user's password.

curl -H "X-Joomla-Token: <your-token>" \
     https://example.test/api/index.php/v1/content/articles

# Joomla also accepts the standard Authorization header (Bearer is case-sensitive):
curl -H "Authorization: Bearer <your-token>" \
     https://example.test/api/index.php/v1/content/articles

To make tokens work, enable two plugins and generate a token:

1. Enable the User - Joomla API Token plugin (it adds the token field to user profiles).
2. Enable the API Authentication - Token plugin (it reads the header on each request).
3. Open the user's profile, find the Joomla API Token tab, and generate a token. Copy it once: Joomla stores only a seed, so it cannot show the token to you again.

By default only Super Users may use a token. Widen this through the allowedUserGroups parameter of the User - Joomla API Token plugin, and keep that list as narrow as the job allows.

4.3 Basic Authentication

The API Authentication - Web Services Basic plugin lets a client send a username and password with each request, using standard HTTP Basic auth:

curl -u myusername:mypassword \
     https://example.test/api/index.php/v1/content/articles

It is simple, but it sends the real account password on every call. Use it only over HTTPS, and prefer tokens for anything long-lived, because a leaked password is far more damaging than a leaked token you can revoke.

4.4 Public Routes

A few routes can be marked public, which means they answer without any credentials. Most write routes are never public. Read routes are public only when the component's Web Services plugin opts in. Treat public access as the exception, not the rule, and never expose write methods that way.

6. Querying Lists

6.1 Paging Through Results

A list does not return every row at once. Joomla pages the results using the JSON:API offset notation. You control the window with two query parameters:

curl -H "X-Joomla-Token: <your-token>" \
  "https://example.test/api/index.php/v1/content/articles?page[limit]=20&page[offset]=0"

The meta block in the response tells you the total count, so you know how many pages there are.

6.2 Sorting

Order a list with list[ordering] for the column and list[direction] for the way (asc or desc). Joomla checks the column against the model's allowed filters, so you cannot sort by an arbitrary field:

"...?list[ordering]=created&list[direction]=desc"

6.3 Filtering

Narrow a list with filter[...] parameters. The available filters depend on the component, and they match the same filters the backend list uses. For articles you can, for example, filter by category or by published state:

"...?filter[catid]=2&filter[state]=1"

6.4 Choosing Fields

To keep a response small, ask for only the fields you need with the JSON:API fields parameter, naming the resource type:

"...?fields[articles]=title,catid,state"

Remember to URL-encode the square brackets and to quote the whole URL in your shell, or the brackets and ampersands will be misread.

8. Under the Hood (Developer View)

8.1 The Request Journey

An API request travels a clear path from URL to JSON:

/api/index.php   →  API application boots
                 →  ApiRouter matches the URL to a route
                 →  an api-authentication plugin checks the token
                 →  the component's ApiController runs (list/item/add/...)
                 →  a ListModel/AdminModel fetches or saves the data
                 →  a JsonapiView + serializer build the JSON:API response

8.2 Routes Come From Plugins

The API has no fixed route table. Each Web Services plugin listens for the onBeforeApiRoute event and registers its own routes when the router is built. The com_content plugin, for example, does this:

public function onBeforeApiRoute(BeforeApiRouteEvent $event): void
{
    $router = $event->getRouter();

    $router->createCRUDRoutes(
        'v1/content/articles',
        'articles',
        ['component' => 'com_content']
    );
}

The helper createCRUDRoutes() is the reason most resources share the same five-verb shape. One call expands into all five REST routes:

GET    v1/content/articles        → articles.displayList
GET    v1/content/articles/:id    → articles.displayItem
POST   v1/content/articles        → articles.add
PATCH  v1/content/articles/:id    → articles.edit
DELETE v1/content/articles/:id    → articles.delete

Its fourth argument, $publicGets, decides whether the two GET routes answer without authentication. It defaults to false.

8.3 The Controller and View

Each component has a slim API layer under api/components/com_xxx/. A controller extends ApiController and reuses the same models as the backend. It reads the paging, ordering, and filter parameters from the request, runs the model, and hands the result to a JsonapiView. A serializer then turns the Joomla object into the JSON:API type / id / attributes shape.

api/components/com_content/src/
├─ Controller/ArticlesController.php   (extends ApiController)
├─ View/Articles/JsonapiView.php       (renders JSON:API)
└─ Serializer/ContentSerializer.php    (maps fields to attributes)

Because the API reuses the existing models, the same validation, access checks, and events that run in the backend also run for an API call. The API is a new face on the same engine, not a parallel one.

8.4 Tables Involved

8.5 Adding Your Own Endpoint

To expose a custom component over the API, you write a small webservices plugin that registers routes on onBeforeApiRoute, and an API controller, view, and serializer under your component's api/ folder. You never patch the core or touch the existing routes. This is the same mechanism every core component uses, which means a third-party extension can join the API as a first-class citizen.

10. Going Further: Headless, AI, and Scale

Once the API is the way your content leaves Joomla, a bigger question follows: what consumes it? This is where Joomla stops being only a website and becomes a content platform. The same JSON you have been calling can feed a decoupled frontend, an AI assistant, or a fleet of channels at once.

• Headless Joomla. Drop Joomla's own rendering and let a separate frontend (React, Vue, Next.js, a mobile app) draw the pages from the API. Joomla becomes a pure content store.
• AI and RAG. Because every article is clean JSON, Joomla makes a natural source of truth for chatbots and Retrieval-Augmented Generation pipelines that answer from your own content.
• Performance and scale. A busy API setup leans on paging, caching (Redis, Varnish, CDN), rate limiting, and token rotation to stay fast and safe.

These topics are an architecture subject in their own right, so they have their own companion piece. For the full picture - decoupled frontends, a Next.js example, AI chatbots, RAG and vector databases, MCP, AI agents, caching, and SEO for a decoupled site - see the separate Focus On article on using Joomla as a headless website. This article stays focused on the API itself: how it works, how to call it, and how to secure it.

12. Common Mistakes and Pitfalls

12.1 The API Is Off

Symptom: every call returns an error, even a simple read.

Fix: enable the Web Services API in System → Global Configuration. It is off by default on a new site.

12.2 The Component Plugin Is Disabled

Symptom: one resource returns 404 while another works fine.

Fix: enable the matching webservices plugin. Without it, that component registers no routes.

12.3 The Token Is Rejected (401)

Symptom: a token that looks correct is refused as unauthorised.

Fix: check three things. The API Authentication - Token plugin must be enabled, the user must belong to a group listed in allowedUserGroups, and the account must not be blocked or pending activation. Remember that the Bearer keyword is case-sensitive.

12.4 The Shell Eats the URL

Symptom: paging or filtering is ignored, or the shell throws an error.

Fix: wrap the whole URL in quotes and escape the ampersand. Square brackets and & have special meaning in most shells, so "...?page[limit]=20&page[offset]=0" needs the quotes.

12.5 Forgetting the Content-Type

Symptom: a POST or PATCH creates nothing, or the body is ignored.

Fix: send Content-Type: application/json with every write, and make sure the body is valid JSON.

12.6 Expecting the API to Bypass Permissions

Symptom: a call is refused even though the token is valid.

Fix: the user behind the token needs the same permission they would need in the backend. Grant the right group access; do not look for an API-only override, because there is none.

14. Quick Reference

BASE URL     https://example.test/api/index.php/v1/...

VERBS        GET     read (list or single item)
             POST    create
             PATCH   update (only the fields you send)
             DELETE  remove

AUTH         X-Joomla-Token: <token>        (recommended)
             Authorization: Bearer <token>   (Bearer is case-sensitive)
             curl -u user:pass               (Basic, HTTPS only)

ACL          core.create  core.edit  core.edit.state  core.delete
             401 = not authenticated   403 = not authorised

LIST QUERY   page[limit]=20  page[offset]=0
             list[ordering]=created  list[direction]=desc
             filter[catid]=2  filter[state]=1
             fields[articles]=title,catid,state

ENDPOINTS    v1/content/articles      v1/content/categories
             v1/users                 v1/users/groups
             v1/menus/site/items      v1/contacts
             v1/banners               v1/tags
             v1/media/files           v1/extensions

ENABLE       Global Config        turn the API on
             webservices plugin   per component (routes)
             api-auth + user      Token plugins (login)

SCALE        page large lists, request only needed fields
             caching, CDN, rate limiting: see the headless article

DIAGNOSE     SELECT name, folder, enabled FROM #__extensions
             WHERE folder IN ('webservices','api-authentication');