Banners API

The Banners API provides endpoints for managing banners and banner clients in Joomla.

Base URL

/api/index.php/v1/banners

Endpoints Overview

Banners

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

Banner Clients

Method	Endpoint	Description
GET	/banners/clients	Retrieve all clients
GET	/banners/clients/{id}	Retrieve specific client
POST	/banners/clients	Create new client
PATCH	/banners/clients/{id}	Update client
DELETE	/banners/clients/{id}	Delete client

Banner Categories

Method	Endpoint	Description
GET	/banners/categories	Retrieve all categories
POST	/banners/categories	Create new category
PATCH	/banners/categories/{id}	Update category
DELETE	/banners/categories/{id}	Delete category

Banners

Retrieve all banners

GET /api/index.php/v1/banners

Response

{
    "data": [
        {
            "type": "banners",
            "id": "1",
            "attributes": {
                "name": "Advertisement Banner",
                "alias": "advertisement-banner",
                "catid": 3,
                "cid": 1,
                "type": 1,
                "state": 1,
                "clickurl": "https://example.com",
                "custombannercode": "<img src=\"banner.jpg\">",
                "impressions_left": 0,
                "clicks": 25,
                "impmade": 1500
            }
        }
    ]
}

Create banner

POST /api/index.php/v1/banners

Request Body

{
    "name": "New Banner",
    "alias": "new-banner",
    "catid": 3,
    "cid": 1,
    "type": 1,
    "state": 1,
    "clickurl": "https://example.com",
    "custombannercode": "<a href=\"#\"><img src=\"images/banners/banner.jpg\" alt=\"Banner\"></a>",
    "description": "Banner description"
}

Required fields

Field	Type	Description
name	string	Banner name
catid	int	Category ID

Optional fields

Field	Type	Default	Description
alias	string	auto	URL-friendly name
cid	int	0	Client ID
type	int	0	Banner type (0=image, 1=custom)
state	int	1	Publication status
clickurl	string	""	Click-through URL
custombannercode	string	""	Custom HTML code
description	string	""	Description
imptotal	int	0	Total impressions (0=unlimited)

Example

curl -X POST "https://yoursite.com/api/index.php/v1/banners" \
  -H "X-Joomla-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Header Banner",
    "catid": 3,
    "clickurl": "https://example.com",
    "custombannercode": "<img src=\"banner.jpg\" alt=\"Banner\">"
  }'

Update banner

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

Example

curl -X PATCH "https://yoursite.com/api/index.php/v1/banners/1" \
  -H "X-Joomla-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "clickurl": "https://new-url.com",
    "state": 0
  }'

Delete banner

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

Banner Clients

Banner clients are advertisers who can have multiple banners.

Create client

POST /api/index.php/v1/banners/clients

Request Body

{
    "name": "Advertiser Inc",
    "contact": "John Smith",
    "email": "john@advertiser.com",
    "extrainfo": "Premium advertiser",
    "state": 1
}

Required fields

Field	Type	Description
name	string	Client name
contact	string	Contact person
email	string	Email address

Example

curl -X POST "https://yoursite.com/api/index.php/v1/banners/clients" \
  -H "X-Joomla-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Advertiser Inc",
    "contact": "John Smith",
    "email": "john@advertiser.com"
  }'

Banner Categories

Create category

POST /api/index.php/v1/banners/categories

Request Body

{
    "title": "Header Banners",
    "alias": "header-banners",
    "description": "Banners for the header section"
}

Banner Types

Type	Description
0	Image
1	Custom HTML code

Banner States

Value	Status
-2	Trash
0	Unpublished
1	Published
2	Archived

Filtering

By category

GET /api/index.php/v1/banners?filter[catid]=3

By client

GET /api/index.php/v1/banners?filter[cid]=1

By status

GET /api/index.php/v1/banners?filter[state]=1

Banner Statistics

Banners automatically track statistics:

Field	Description
impmade	Number of impressions
clicks	Number of clicks
impressions_left	Remaining impressions

info

Resetting statistics must be done through the Joomla administrator interface.