search_assets
Locate media assets by applying filters, tags, and advanced query operators to retrieve exactly what you need.
Instructions
Search for assets using filters and advanced query operators.
ADVANCED SEARCH QUERY SYNTAX (for the 'q' parameter):
Basic: Just type a term to search all fields (e.g., "dog")
Exclude: Use NOT or minus to exclude (e.g., "NOT dog" or "-dog")
Combine: Use AND, OR, NOT (e.g., "dog AND cat", "dog OR cat", "dog NOT cat")
Field search: Use field:value syntax (e.g., "tag_text:nature", "filename.keyword:IMG_1234.jpg")
Wildcards: Use * (zero or more chars) or ? (single char) (e.g., "tag_text:part*", "tag_text:?artial")
Existence: Use field:** to find assets with any value, NOT field:** for empty (e.g., "NOT tag_text:**" finds untagged assets)
Complex: Use parentheses for grouping (e.g., "(dog OR cat) AND ext:jpg")
NOTE on multi-word queries: the API uses Elasticsearch cross_fields, so a multi-word query like "red barn" can match if "red" appears in one field and "barn" appears in another. Quote phrases ("red barn") to require both terms in the same field.
Sort: pass either 'order' or its alias 'direction' (asc/desc). Results have an implicit id:asc tiebreaker (except when using a custom sort).
COMMON SEARCH FIELDS:
tag_text: Keywords/tags
filename.keyword: Exact filename
description: Asset description
title: Asset title
ext: File extension
creator_text: Creator/photographer name
copyright: Copyright text
city, state, country: Location fields
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Search query with optional advanced operators (AND, OR, NOT, field:value, wildcards) | |
| gps | No | Filter for assets with GPS data | |
| ids | No | Filter by specific asset IDs | |
| exts | No | Filter by file extensions | |
| page | No | Page number | |
| tags | No | Filter by tags | |
| guids | No | Filter by specific asset GUIDs | |
| aspect | No | ||
| rating | No | Filter by rating range [min, max] | |
| per_page | No | Results per page (max 100) | |
| created_at | No | Date range [start, end] in ISO 8601 | |
| has_people | No | ||
| captured_at | No | Date range [start, end] in ISO 8601 | |
| lightbox_id | No | Filter by lightbox ID | |
| has_alt_text | No | ||
| include_meta | No | Include full EXIF/IPTC metadata | |
| collection_id | No | Filter by collection ID | |
| include_totals | No | Include aggregate counts | |
| storage_folder_id | No | Filter by storage folder ID | |
| include_renditions | No | Include available sizes/formats |