3.1 Install Bruno

Download and install Bruno from the official website: https://www.usebruno.com

Note: if you already have Bruno installed, make sure you update it to the latest version

3.2 Install the Collection

4.1 Terminology

Some basic terminology first when working with APIs. You are probably familiar with the acronym CRUD (Create / Read / Update / Delete). The corresponding requests are the following:

• Create = post
• Read = get
• Update = patch
• Delete = del

4.2 A simple GET Request

When you make API calls a good start is always to run a simple GET request, especially if you have little experience (a POST request is not complicated, but there are already more chances to run into errors because you would forget some required Parameters, because you put a wrong Category ID, …).

• in the left sidebar click on Joomla Web Services API to expand the Collection
• click on Content Articles to see all possible requests on Articles
• click on the the first option, ie GET content/articles, which retrieves a List of Articles
• send the request
  • either by clicking on the right arrow icon at the top right of your screen, next to the </> [Generate Code] and the floppy disk [Save] icons
  • or by using the keyboard shortcut, ie CTRL+ENTER

If everything is fine, on the Response tab you should then see

• a green status 200 OK
• and below the Response should contain the list of Articles of your Joomla website in JSON format (note that by clicking on the JSON button you could display the same Response in other formats like HTML, XML etc)

4.3 Using Parameters in Requests

On the Params tab, you see that we have a number of ready-to-use parameters

• filter for (according to the context for example) Author, Category, Language, …
• list for Ordering and Direction

In the following example

• I check filter[category] and put 12 as value (because I do have a Category having ID 12 of course)
• I check filter[search] and put Star Wars

When I run the request I then get the following result

4.4 Using Variables in Requests

Let’s now choose an another action, for example Content Articles > GET content/articles/{article_id}

On the newly opened Tab, note the URL which is mentioned after the GET: {{base_url}}/v1/content/articles/{{article_id}} where the Variable

• {{base_url}} is green because we have already set a Value above
• {{article_id}} is red because we have not yet set any Value

Simply click on the red {{article_id}} and in the popup you can specify the Value of an existing Article (in my case: 212) and press Enter key

Note the {{article_id}} which was red has now become green

If you want to assign another value, simply

• click on {{article_id}} again
• or go on the Tab Vars where you see all Variables and where you can
  • either uncheck the current Value ({{article_id}} will become red again)
  • either change its value

When I run the request I then get the following result

4.5 Making your Variables “global”

If for some reason you want to make a Variable “global”

• go to our Environment (where we already configured base_url and api_key)
  • click on the Joomla Web... button at the top right of Bruno
  • click on Configure button
• add a new line with for example
  • article_id (without the double curly brackets) as Name
  • the desired Value

4.6 A simple POST request

• click on Content Articles to see all possible requests on Articles
• click on the the 2nd option, ie POST content/articles

By default, the example Body is the following

{
  "alias": "",
  "articletext": "",
  "catid": 0,
  "language": "",
  "metadesc": "",
  "metakey": "",
  "title": ""
}

But note that the only necessary fields are the following:

{
  "articletext": "",
  "catid": 2,
  "language": "",
  "title": "test post 2"
}

In particular

• must be present + must have a real Value
  • title
  • catid
• must be present in the body but can be empty (ie with "" as Value)
  • articletext
  • language. Note: when you want to put a value
    • * stands for All
    • en-GB for English
    • fr-FR for French etc (just like in your Joomla database)

Should you totally remove "articletext": "", from the Body then you would indeed get the following error:

{
  "errors": [
    {
      "title": "Save failed with the following error: Field 'introtext' doesn't have a default value",
      "code": 400
    }
  ]
}

4.7 articletext vs introtext + fulltext

As you know, in Joomla

• introtext stands for the text in the Editor before the Read more button
• fulltext stands for the text in the Editor after the Read more button

Actually, articletext is “smart” and will separate your Value into introtext and fulltext when detecting <hr id="system-readmore"> in the Value.

So in the Body you can use the combination that suits you the most:

• articletext alone
• introtext alone
• both introtext + fulltext
• [ but not fulltext without introtext being present. It can be empty though]

4.8 Basic Custom Fields

Suppose you have a Custom Field of Type Text, having

• My Own Custom Field as Title
• my-own-custom-field as Name (Alias)

Then in the Body of the API Request you would simply add the following line in order to feed the Custom Field with the Value lorem ipsum:

"my-own-custom-field": "lorem ipsum",

4.9 More advanced Custom Fields or Tags

• for more advanced Custom Fields, see
  • https://slides.woluweb.be/api/#special-fields-like-images-or-custom-fields-or-type-subform-or-urls
  • https://slides.woluweb.be/api/#fields-with-potentially-multiple-values-like-custom-fields-of-type-list-or-checkbox
  • https://slides.woluweb.be/api/#fields-with-potentially-multiple-values-like-custom-field-of-type-articles-field-by-regular-labs
• for Tags see
  • https://slides.woluweb.be/api/#tags

Example: suppose you want to POST or PATCH an Article having a Custom Field of Type Checkboxes. In the following example its Name is cinecheck. If the Values I want to check are respectively 12, V, F, L and H then the Body of the API Request should be as follows. In particular note that you should not surround the JSON of the Custom Field with quotes.

{
    "title":"Demo from Bruno",
    "cinecheck":{"0":"12","1":"V","2":"F","3":"L","4":"H"},
    "note":"don't surround the JSON of the Custom Field of Type Checkboxes with quotes"
}

4.10 Other Fields

Actually, if you need to add any Field (native Field or Custom Field) in a Post Request, the easiest way is to first do a Get Request in order to see

• what the Label is
• and how the Value is formatted (example: dates are formatted like yyyy-mm-dd hh:mm:ss)

The following example illustrates how to add Fields like

• access
• created_by
• state
• … and associations (when you have a multilingual website you can indeed associate Articles between the different languages)

{
    "title": "lorem ipsum",
    "articletext": "",
    "catid": 2,
    "language": "en-GB",
    "state": 1,
    "access": 3,
    "created_by": 100,
    "associations": {
        "nl-NL": "13",
        "fr-FR": "14"
    }
}

4.11 What if you POST an Article and the Alias is already taken in the given Category?

With J!4.x, J!5.x and J!6.0.x, you will get an error message if you POST an Article for which the Alias is already taken in the given Category. This can sometimes be annoying when you are automating Article creation.

But as of J!6.1 (release date: mid-April 2026) you won’t have to worry about that in your workflow because Joomla will automatically adapt the Alias. Example: if the Alias my-test-article-1 is already taken, it will give my-test-article-1.

Thanks to Nicola Galgano (aka @alikon) for improving this!

Want to know more about this? Check

• the Pull Request of Nicola
  • https://github.com/joomla/joomla-cms/pull/46144
• and the corresponding Issue I had posted
  • https://github.com/joomla/joomla-cms/issues/45470

4.12 A POST request to upload an image in a given folder

• click on Media Files to see all possible requests on Media
• click on the the second option, ie POST Add Media file
• in the Body
  • for the Path if you put for example
    • /banners/joomlacamp26.png the media will be uploaded in the /banner/ folder… under the /files/ folder
    • local-images:/banners/joomlacamp26.png the media will be uploaded in the /banner/ folder… under the /images/ folder
  • for the Content you should put your media file in base64 format. Example for our demo:
    • go to an online base64 converter like https://www.base64-image.de
    • upload your image
    • click on the </> Code button
    • copy the result… but without the initial data:image/svg+xml;base64,
    • paste

{
  "path": "local-images:/banners/tiny.png",
  "content": "iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX///+/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII"
}

{
  "errors": [
    {
      "title": "File exists and overwriting not requested: /banners/joomlacamp26.png",
      "code": 400
    }
  ]
}

4.13 A DEL request to delete an Article

Similarly to the workflow when deleting an Article from the Backend, in order to delete an Article via the Web Services

• one must first Patch it with State on -2 (ie Trashed) in order to put it in Trash
• and only then that Article can be really deleted