Joomla REST API for Beginners: The Foundation of AI Automation

Joomla REST API for beginners â the foundation of AI automation

Details: Category: AI & Automation; 09 October 2026

Every AI automation workflow built on top of Joomla — MCP servers, AI agents, custom integrations — ultimately runs through one thing: the Joomla REST API. It's the layer that lets external tools read and write data on your site without touching the database directly.

If you've used Joomla for years but never touched the API, this guide is for you. We'll cover what it is, how to enable it, how authentication works, the key endpoints you'll actually use, and how it all connects to AI automation.

What Is the Joomla REST API?

A REST API (Representational State Transfer Application Programming Interface) is a standardized way for software systems to communicate over HTTP. Instead of clicking buttons in a UI, you make HTTP requests — GET, POST, PATCH, DELETE — to specific URLs called endpoints, and get structured data (JSON) back.

The Joomla REST API was introduced as a core feature in Joomla 4.0. It exposes Joomla's content and configuration as API endpoints, meaning any application that can make HTTP requests — a custom script, an AI assistant, a third-party integration — can read and manage your Joomla site programmatically.

Before Joomla 4, achieving this required third-party extensions with inconsistent implementations. Now it's built in, stable, and actively maintained by the Joomla project.

Enabling the Joomla REST API

Good news: the Joomla REST API is enabled by default in Joomla 4 and 5. You don't need to install anything. However, there are two things to verify before making your first request:

1. Check that the API Plugin is Enabled

In your Joomla backend, go to System → Plugins and search for "API Authentication". You'll find two relevant plugins:

API Authentication — Joomla Token: Enables token-based authentication (recommended)
API Authentication — Basic Auth: Enables username/password authentication (avoid in production)

Make sure "Joomla Token" is enabled. Disable Basic Auth unless you specifically need it for testing.

2. Verify Your .htaccess Allows API Routes

If you're on Apache with mod_rewrite, your Joomla .htaccess file should already handle API routing. If requests to /api/index.php/v1/ return 404, check that mod_rewrite is active and your .htaccess is in place.

Authentication: Joomla API Tokens

The Joomla REST API uses token-based authentication. Every request must include a valid token in the Authorization header. Here's how to generate one:

In the Joomla backend, go to Users and open the user account you want the API to act as
Click the Joomla API Token tab
Click Generate (or the toggle to enable token generation)
Copy the token — you won't be able to see it again after leaving the page

This token grants the same permissions as the user account it belongs to. A Super Admin token can do anything; a more restricted user account limits what the API can read or write.

Security best practice: Create a dedicated API user with only the permissions your integration needs. Never use your personal Super Admin account for automated API access.

Include the token in every API request as a Bearer token:

Authorization: Bearer YOUR_API_TOKEN_HERE

The Base URL Structure

All Joomla API endpoints follow this pattern:

https://your-site.com/api/index.php/v1/{resource}

The v1 indicates API version 1 — the current stable version. Resources map to Joomla content types: articles, categories, tags, menus, media, and more.

Key Endpoints You'll Actually Use

Here are the most useful endpoints for content management and AI automation:

Articles

GET    /api/index.php/v1/content/articles          # List articles
GET    /api/index.php/v1/content/articles/{id}     # Get one article
POST   /api/index.php/v1/content/articles          # Create article
PATCH  /api/index.php/v1/content/articles/{id}     # Update article
DELETE /api/index.php/v1/content/articles/{id}     # Delete article

Media

GET    /api/index.php/v1/media/files               # List media files
POST   /api/index.php/v1/media/files               # Upload a file

Menus

GET    /api/index.php/v1/menus                     # List menus
GET    /api/index.php/v1/menus/{id}/items          # List menu items
POST   /api/index.php/v1/menus/{id}/items          # Create menu item

Making Your First API Call

Let's make a real request to list your Joomla articles. Using curl from the command line:

curl -X GET \
  "https://your-site.com/api/index.php/v1/content/articles?page[limit]=5" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

You'll get a JSON response with an items array containing your articles, plus meta with pagination info and links for navigating pages.

To create an article:

curl -X POST \
  "https://your-site.com/api/index.php/v1/content/articles" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My First API Article",
    "alias": "my-first-api-article",
    "articletext": "<p>Hello from the API!</p>",
    "catid": 11,
    "state": 0,
    "language": "en-GB"
  }'

A successful response returns the full article object including its new id.

Filtering and Pagination

The API supports query parameters for filtering results. The most useful ones:

# Pagination
?page[limit]=20&page[offset]=0

# Filter by category
?filter[catid]=11

# Filter by state (0=unpublished, 1=published, 2=trashed)
?filter[state]=1

# Search by title
?filter[search]=joomla+security

# Sort results
?list[ordering]=created&list[direction]=desc

Combine filters to build precise queries — for example, all published articles in a specific category sorted by creation date.

Working with Article State

Joomla uses numeric values for article state:

Value	State
1	Published
0	Unpublished
2	Archived
-2	Trashed

To publish an existing article via the API:

curl -X PATCH \
  "https://your-site.com/api/index.php/v1/content/articles/44" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"state": 1}'

How the REST API Powers Joomla MCP

Now that you understand the API, the logic behind a Joomla MCP server becomes clear. The MCP server is essentially a structured wrapper around these REST API calls:

The AI assistant receives a natural language instruction ("create an article about Joomla security")
The MCP server translates that into the appropriate API call (POST to /api/index.php/v1/content/articles)
The response comes back as JSON, which the MCP server formats for the AI to understand
The AI reports back in plain language ("Article created with ID 44")

Every tool in the Joomla MCP server — create_article, upload_media, list_categories — is a thin, well-typed layer over one or more REST API calls. Understanding the API helps you understand what the MCP server can and can't do, and how to troubleshoot when something goes wrong.

Common Mistakes to Avoid

Using the wrong content type header: Always send Content-Type: application/json with POST and PATCH requests. Missing this header is the most common cause of mysterious 400 errors.
Forgetting to URL-encode filter values: Spaces in filter values must be encoded as + or %20.
Confusing articletext with introtext: When creating articles via the API, use articletext for the full body or supply separate introtext and fulltext fields. Mixing these up results in blank articles.
Not handling pagination: By default, the API returns a limited number of results. Always check meta.total-pages and paginate if you need the full dataset.
Storing tokens in code: Never hardcode API tokens in scripts or commit them to version control. Use environment variables.

Testing Your API Setup

Before building any integration, verify your setup with a simple read request. A GET to list categories is safe (read-only, no side effects) and confirms authentication is working:

curl -X GET \
  "https://your-site.com/api/index.php/v1/content/categories" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

If you get a JSON response with your categories, you're ready to build. If you get a 401, your token is wrong or the authentication plugin is disabled. If you get a 404, check your base URL and .htaccess configuration.

For more on setting up a local environment to test safely before touching a live site, see our guide on setting up a Joomla dev environment.

Conclusion

The Joomla REST API has been production-ready since Joomla 4, but most Joomla users have never used it directly. Understanding it — even at a basic level — gives you a much clearer mental model of how AI automation tools like the Joomla MCP server actually work, and what's possible when you connect your site to an AI assistant.

Whether you're building a custom integration, debugging an MCP connection, or just curious about what's happening under the hood — the REST API is the right place to start.

Need help building an API-powered workflow for your Joomla site? The ThePixel team can help you design and implement it.

Vivi City Network – Multisite Travel Platform Rebuilt

Vivi City Network – Global Travel Comparison Platform Redesign

Multifamily Insiders: Comprehensive Website Redesign and Optimization