Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 37 ยท Development and Security

Web Services API and CLI

Automate Joomla: enable the core REST API, authenticate with API tokens, create and read articles as JSON:API, and use the joomla.php CLI and Task Scheduler for jobs.

Clicking in the administrator is fine for one article. It is a poor way to import 500 articles, to publish from another system, to build a mobile app on top of Joomla or to run maintenance at night. Joomla offers two automation interfaces in the core: a REST API (Web Services) for other programs, and a command-line interface (CLI) for administrators and scripts. Joomla also has a Task Scheduler for recurring jobs.

Joomla cannot run on this site, so the requests and commands below are shown read-only, and the TryIt blocks are JavaScript stand-ins that build requests and parse responses locally. No network calls are made.

The Web Services API

Since Joomla 4 the API lives under /api/index.php/v1/... on your domain. It follows the JSON:API convention: requests and responses use the media type application/vnd.api+json, and every resource has a type, an id and attributes.

Enabling it

  1. Make sure the Web Services plugins you need are enabled in System > Plugins (group Web Services), for example Web Services - Content and Web Services - Users. They register the routes.
  2. Enable API Authentication - Token (group API Authentication) and User - Joomla API Token (group User). The first accepts tokens; the second adds a token tab to user profiles.
  3. Open a user (Users > Manage), go to the Joomla API Token tab, enable it and copy the token. Treat it like a password: anyone holding it acts as that user, with that user's permissions. For automation, create a dedicated account with only the rights needed (see Permissions and Inheritance).
  4. Always use HTTPS. Tokens sent over plain HTTP can be read by anyone on the path.

There are also Basic Auth plugins, but tokens are preferable because you can revoke them without changing the password.

Reading articles

HTTP
GET /api/index.php/v1/content/articles?page[limit]=5&page[offset]=0&filter[search]=launch HTTP/1.1
Host: example.com
Accept: application/vnd.api+json
Authorization: Bearer YOUR_TOKEN

The response is a JSON document with a data array, links for pagination and meta with the total. Each item looks like this (abbreviated):

JSON
{
  "type": "articles",
  "id": "17",
  "attributes": {
    "id": 17,
    "title": "Launch Day",
    "alias": "launch-day",
    "state": 1,
    "catid": 2
  }
}

A single article is at /v1/content/articles/17. Other common endpoints are /v1/content/categories, /v1/users, /v1/menus/site/items and /v1/config/application; the full list depends on the enabled plugins and extensions (components can add their own).

Creating and changing content

POST creates, PATCH updates and DELETE removes:

HTTP
POST /api/index.php/v1/content/articles HTTP/1.1
Content-Type: application/json
Accept: application/vnd.api+json
Authorization: Bearer YOUR_TOKEN

{
  "title": "Hello from the API",
  "alias": "hello-from-the-api",
  "articletext": "<p>Created by a script.</p>",
  "catid": 2,
  "language": "*",
  "state": 1
}

A success returns status 201 Created with the new article. Errors use standard codes: 401 no or bad token, 403 the user lacks the permission, 404 unknown resource, 422 validation failed, with an errors list that says which field.

The API applies the same permissions and validation as the administrator, so the token's user must be allowed to create articles in that category.

JS Build a Joomla API request

Press Run (or Ctrl + Enter) to see the console output here.

No output.

This stand-in only builds the request description. It does not contact any server, and the token is a placeholder: never paste a real token into an online editor.

JS Read a JSON:API response

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The command line

Joomla ships a console application. From the site's root folder, on a host where you have shell access:

Terminal
php cli/joomla.php list              # every command your version offers
php cli/joomla.php help core:update  # help for one command

Commands vary by version and installed extensions; run list to see yours. Frequently useful ones in Joomla 4 and 5 include:

Command Purpose
site:down / site:up Put the site into or out of offline mode
core:check-updates Is a newer Joomla release available?
core:update Update Joomla core
cache:clean Clear expired cache entries
extension:list List installed extensions
user:add and user:reset-password Create a user or reset a password
config:get Read a configuration value
database:export Export the database to a file
scheduler:run Run due scheduled tasks

The CLI is the practical way to update on a schedule, put up a maintenance page for a deploy and recover access when you are locked out of the administrator, because user:reset-password works without logging in. Run it as the same system user that owns the site files, otherwise new files may get the wrong owner.

JS A toy CLI dispatcher

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Task Scheduler

Joomla 4.1 introduced the Task Scheduler (System > Scheduled Tasks). A task is a plugin of the task group that does something, such as clear old logs, check for updates or send a notification, and you give it a schedule. Tasks can run in two ways:

  • Lazy scheduler: Joomla checks for due tasks while visitors browse. Simple, but timing depends on traffic.
  • Web or system cron: a real cron job calls the CLI (php cli/joomla.php scheduler:run) or a URL, which is more reliable for exact times.

A typical cron line, running every minute:

TEXT
* * * * * /usr/bin/php /var/www/example/cli/joomla.php scheduler:run

Use the system cron for anything that matters, for example nightly backups. Link these ideas with Security Hardening and Updates.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which header normally carries a Joomla API token?

    The token is sent as a bearer token (or in X-Joomla-Token) over HTTPS.
  2. 2. What status code means the token's user lacks the permission?

    403 Forbidden: authenticated but not allowed. 401 means no valid credentials.
  3. 3. Which command helps you regain access when locked out of the administrator?

    The CLI runs with server access, so it can reset a password without logging in.
  4. 4. Why prefer system cron over the lazy scheduler for nightly backups?

    The lazy scheduler needs traffic to trigger tasks; cron does not.

Summary

  • The Web Services API lives under /api/index.php/v1/ and speaks JSON:API.
  • Enable the Web Services and token plugins, create a token for a limited user and always use HTTPS.
  • POST, PATCH and DELETE apply the same permissions and validation as the admin.
  • php cli/joomla.php list shows the console commands: update, cache, users, config, database, offline mode, scheduler.
  • Use the Task Scheduler with a real cron job for dependable recurring work.

Next: Security Hardening and Updates