Redirects API

The Redirects API provides endpoints for managing URL redirects in Joomla.

Base URL

/api/index.php/v1/redirects

Endpoints Overview

Method	Endpoint	Description
GET	/redirects	Retrieve all redirects
GET	/redirects/{id}	Retrieve specific redirect
POST	/redirects	Create new redirect
PATCH	/redirects/{id}	Update redirect
DELETE	/redirects/{id}	Delete redirect

Retrieve all redirects

GET /api/index.php/v1/redirects

Response

{
    "data": [
        {
            "type": "redirects",
            "id": "1",
            "attributes": {
                "old_url": "/old-page",
                "new_url": "/new-page",
                "referer": "",
                "comment": "Page moved",
                "hits": 25,
                "published": 1,
                "created_date": "2024-01-15 10:30:00",
                "modified_date": "2024-01-15 10:30:00",
                "header": 301
            }
        }
    ]
}

Retrieve specific redirect

GET /api/index.php/v1/redirects/{id}

Parameters

Parameter	Type	Description
id	integer	Redirect ID

Example

curl -X GET "https://yoursite.com/api/index.php/v1/redirects/1" \
  -H "X-Joomla-Token: YOUR_API_TOKEN"

Create redirect

POST /api/index.php/v1/redirects

Request Body

{
    "old_url": "/old-url",
    "new_url": "/new-url",
    "comment": "Page moved to new location",
    "published": 1,
    "header": 301
}

Required fields

Field	Type	Description
old_url	string	Old URL path
new_url	string	New URL path

Optional fields

Field	Type	Default	Description
comment	string	""	Comment/note
published	int	1	Active (0=no, 1=yes)
header	int	301	HTTP redirect code

Example

curl -X POST "https://yoursite.com/api/index.php/v1/redirects" \
  -H "X-Joomla-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "old_url": "/blog/old-article",
    "new_url": "/news/new-article",
    "comment": "Blog moved to news",
    "header": 301
  }'

Update redirect

PATCH /api/index.php/v1/redirects/{id}

Request Body

{
    "new_url": "/other-new-url",
    "header": 302
}

Example

curl -X PATCH "https://yoursite.com/api/index.php/v1/redirects/1" \
  -H "X-Joomla-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "new_url": "/other-url",
    "comment": "URL updated"
  }'

Delete redirect

DELETE /api/index.php/v1/redirects/{id}

Example

curl -X DELETE "https://yoursite.com/api/index.php/v1/redirects/1" \
  -H "X-Joomla-Token: YOUR_API_TOKEN"

HTTP Redirect Codes

Code	Type	Description
301	Moved Permanently	Permanent redirect (SEO-friendly)
302	Found	Temporary redirect
303	See Other	Redirect after POST request
307	Temporary Redirect	Temporary, preserves HTTP method
308	Permanent Redirect	Permanent, preserves HTTP method

Best practice

Use 301 for permanent moves (SEO value is transferred) and 302 for temporary redirects.

Redirect States

Value	Status
-2	Trash
0	Inactive
1	Active
2	Archived

URL Format

Relative URLs (recommended)

{
    "old_url": "/old-page",
    "new_url": "/new-page"
}

Absolute URLs

{
    "old_url": "https://yoursite.com/old-page",
    "new_url": "https://yoursite.com/new-page"
}

External redirect

{
    "old_url": "/external-link",
    "new_url": "https://external-site.com/page"
}

Filtering

By publication status

GET /api/index.php/v1/redirects?filter[published]=1

By HTTP code

GET /api/index.php/v1/redirects?filter[header]=301

Search

GET /api/index.php/v1/redirects?filter[search]=blog

Bulk Create Redirects

#!/bin/bash
# Bulk create redirects from CSV

while IFS=',' read -r old new comment; do
    curl -X POST "https://yoursite.com/api/index.php/v1/redirects" \
      -H "X-Joomla-Token: YOUR_API_TOKEN" \
      -H "Content-Type: application/json" \
      -d "{
        \"old_url\": \"$old\",
        \"new_url\": \"$new\",
        \"comment\": \"$comment\",
        \"header\": 301
      }"
done < redirects.csv

Statistics

Each redirect tracks the number of hits in the hits field. This is useful to see which old URLs are still being visited.

Most used redirects

GET /api/index.php/v1/redirects?list[ordering]=hits&list[direction]=desc

info

The redirect component must be enabled in Joomla for redirects to work. Check this via System → Plugins → System - Redirect.