Endpoints

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&section=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&section=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

Note

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

Warning

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
fixedOrder	all
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
fixedOrder	all
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
fixedOrder	all
id	all
level	entries
limit	all
offset	all
orderBy	all
postDate	entries
relatedTo	entries
notRelatedTo	entries
andRelatedTo	entries
andNotrelatedTo	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
email	users
fixedOrder	all
fullName	users
group	users
groupId	users
hasPhoto	users
id	all
limit	all
offset	all
orderBy	all
search	all
status	all

Commands

Learn about all of the commands of the craft query API

allRoutes

Learn how to effectively use the allRoutes API endpoint.

Useful links