customQuery
Learn how to use the customQuery API endpoint.
The customQuery endpoint allows you to query addresses, assets, entries, and users directly via URL parameters. It returns a JSON response for easy consumption.
To use it, simply send a GET request to: ${PRIMARY_SITE_URL}/v1/api/queryApi/customQuery with some query params. This could look like that
/v1/api/queryApi/customQuery?elementType=entries§ion=home&one=1.
A full example with an access token might look like this:
curl --request GET \
--url 'https://your-site.ddev.site/v1/api/queryApi/customQuery?elementType=entries§ion=home&one=1' \
--header 'authorization: Bearer your-access-token'
GET Params
Each element type has its own set of available GET parameters. This ensures precise control over the query and enhances security. Internally, these parameters are filtered to prevent potential exploits.
Special Parameters
Below is a list of special GET parameters that are available in all element types.
| Params | Description | Possible Values |
|---|---|---|
| all | Fetch all elements | 1 |
| elementType | Specify the element type to query | addresses, assets, entries, users |
| includeAllEntry | Whether to include the full data of entries or just the minimal fields (title, URI, ID, and slug). | 1 for true and 0 for false |
| fields | Query specific field data by handle | string or array of field handles, use dot notation to filter out nested data, use * as a wildcard |
| one | Fetch a single element | 1 |
The following parameters are required: elementType and either one or all.
fields
The fields param is a simple filter, to minify the response returned to the client.
You can use a * in combination with fieldhandle.nestedFieldHandle, to filter out stuff that is not important.
includeAllEntry
The includeAllEntry defines how entry relations from an Entries field are returned.
If enabled, the customQuery endpoint will include full entry objects, otherwise only minimal data (title, URI, ID, slug) is returned.
To enable this setting globally you can use the includeAllEntry setting
If you use the includeAllEntry param, be sure that you don't have circular entry relations. This would end up in an endless loop.
Addresses
Below is a list of all available GET parameters for the addresses element type:
| Params | Element type |
|---|---|
| addressLine1 | addresses |
| addressLine2 | addresses |
| addressLine3 | addresses |
| fullName | addresses |
| id | all |
| limit | all |
| locality | addresses |
| offset | all |
| orderBy | all |
| organization | addresses |
| search | all |
Assets
Below is a list of all available GET parameters for the assets element type:
| Params | Element type |
|---|---|
| filename | assets |
| id | all |
| kind | assets |
| limit | all |
| offset | all |
| orderBy | all |
| search | all |
| site | assets |
| siteId | assets |
| volume | assets |
Entries
Below is a list of all available GET parameters for the entries element type:
| Params | Element type |
|---|---|
| id | all |
| level | entries |
| limit | all |
| offset | all |
| orderBy | all |
| postDate | entries |
| search | all |
| section | entries |
| sectionId | entries |
| site | entries |
| siteId | entries |
| slug | entries |
| status | all |
| type | entries |
| uri | entries |
Users
Below is a list of all available GET parameters for the users element type:
| Params | Element type |
|---|---|
| admin | users |
| authorOf | users |
| users | |
| fullName | users |
| group | users |
| groupId | users |
| hasPhoto | users |
| id | all |
| limit | all |
| offset | all |
| orderBy | all |
| search | all |
| status | all |