---
title: "API Documentation"
date: 2026-05-24
author: "Jeroen Moolenschot"
---

# API Documentation

Client Response Gallery exposes a lightweight HTTP API for creating galleries and uploading photos from external tools such as Adobe Lightroom. All requests are authenticated with an API key.  
  
The API is not a REST API in the strict sense: it uses Joomla's standard front-end routing. Every endpoint is a `GET` or `POST` request to your Joomla site's `index.php`.

 
## Configuration

 Set your API key in the Joomla administrator under **Components > Client Response Gallery > Configuration > API**.  
  
The API key must be non-empty for any request to succeed. If the field is left blank, every request returns `401 Unauthorized`.

 
## Authentication

 Every request must include the API key in a custom HTTP header:  
  
`X-API-Key: your-api-key`  
  
A missing or incorrect key returns:  
  
`HTTP/1.1 401 Unauthorized`  
  
`{`  
`"success": false,`  
`"message": "Unauthorized"`  
`}`

 
## Base URL

 [https://yoursite.com/index.php?option=com_clientresponsegallery&task=&format=json](https://yoursite.com/index.php?option=com_clientresponsegallery&task=&format=json)  
  
Replace `` with the task name listed for each endpoint below.

 
## Endpoints

 
### List galleries

 Returns all published galleries.  
  
`GET /index.php?option=com_clientresponsegallery&task=api.galleries&format=json`  
  
**Request headers**

 
|  |  |  |
| --- | --- | --- |
| **Header** | **Required** | **Value** |
| `X-API-Key` | Yes | Your API key |

 **Response — success**  
  
`{`  
`"success": true,`  
`"galleries": [`  
`{ "id": "1", "title": "Wedding 2025", "alias": "wedding-2025" },`  
`{ "id": "2", "title": "Family Portraits", "alias": "family-portraits" }`  
`]`  
`}`

 The `galleries` array is sorted by title ascending. Unpublished galleries are excluded.

 
### Upload photo

 Uploads a photo to an existing gallery. The file is processed (resized, watermarked) according to the component's Batch Upload settings before being saved.  
  
`POST /index.php?option=com_clientresponsegallery&task=api.upload&format=json`  
  
**Request headers**

 **Request headers**

 
|  |  |  |
| --- | --- | --- |
| **Header** | **Required** | **Value** |
| `X-API-Key` | Yes | Your API key |
| `Content-Type` | Yes | `multipart/form-data` |

 **Request body (multipart/form-data)**

 
|  |  |  |  |
| --- | --- | --- | --- |
| **Field** | **Type** | **Required** | **Description** |
| `gallery_id` | integer | Yes | ID of the target gallery |
| `file` | file | Yes | The image to upload |

 Accepted file types: `jpg`, `jpeg`, `png`, `webp`. The file content is validated with `getimagesize()` — renaming a non-image file will not bypass the check.  
  
If a file with the same name already exists in the gallery folder, a timestamp suffix is appended automatically.  
  
**Response — success**  
  
`{`  
`"success": true`  
`}`  
  
**Response — error**  
  
`{`  
`"success": false,`  
`"message": "Gallery not found"`  
`}`  
  
Possible error messages:

 
|  |  |
| --- | --- |
| Message | Cause |
| `Missing gallery_id or file` | One of the required fields is absent |
| `Upload error` | PHP reported an upload error |
| `Invalid upload` | File did not pass `is_uploaded_file()` check |
| `Invalid file type` | Extension is not jpg/jpeg/png/webp |
| `Invalid file content` | File content does not match an accepted image format |
| `Gallery not found` | No published gallery exists with the given ID |
| `Failed to save file` | Server could not write the file to disk |
| `Database error` | Photo record could not be inserted |

 
### Create gallery

 Creates a new gallery and its folder under `images/clientresponsegallery/`. The gallery is published immediately. The alias is generated from the title and guaranteed to be unique.  
  
`POST /index.php?option=com_clientresponsegallery&task=api.create&format=json`  
  
  
**Request headers**

 
|  |  |  |
| --- | --- | --- |
| **Header** | **Required** | **Value** |
| `X-API-Key` | Yes | Your API key |
| `Content-Type` | Yes | `multipart/form-data` |

 **Request body (multipart/form-data)**

 
|  |  |  |  |
| --- | --- | --- | --- |
| **Field** | **Type** | **Required** | **Description** |
| `title` | string | Yes | Gallery title |
| `description` | string | No | Gallery description (HTML allowed) |
| `password` | string | No | Password required to access the gallery |
| `selection_min` | integer | No | Minimum number of photos the client must select (0 = no minimum) |
| `selection_max` | integer | No | Maximum number of photos the client may select (0 = no maximum) |
| `selection_min_message` | string | No | Warning shown when client selects too few photos. Supports `` and `` placeholders |
| `selection_max_message` | string | No | Warning shown when client selects too many photos. Supports `` and `` placeholders |

 **Response — success**  
`{`  
`"success": true,`  
`"gallery": {`  
`"id": "7",`  
`"title": "Spring Session 2025",`  
`"alias": "spring-session-2025"`  
`}`  
`}`  
  
Use the returned `id` immediately in subsequent Upload photo requests.  
  
**Response — error**  
  
`{`  
`"success": false,`  
`"message": "Title is required"`  
`}`

 
## Error handling

 All error responses other than authentication failures return HTTP `200` with `"success": false` and a `message` field. Only `401 Unauthorized` uses a non-200 status code.  
  
All responses include:  
  
`Content-Type: application/json; charset=utf-8`  
`Access-Control-Allow-Origin: *`

 
## Example: upload a photo with cURL

 `curl -X POST "https://yoursite.com/index.php?option=com_clientresponsegallery&task=api.upload&format=json" \`  
`-H "X-API-Key: your-api-key" \`  
`-F "gallery_id=3" \`  
`-F "file=@/path/to/photo.jpg"`

 
## Example: create a gallery with cURL

 `curl -X POST "https://yoursite.com/index.php?option=com_clientresponsegallery&task=api.create&format=json" \`  
`-H "X-API-Key: your-api-key" \`  
`-F "title=Spring Session 2025" \`  
`-F "password=secret123" \`  
`-F "selection_min=5" \`  
`-F "selection_max=20"`