GET
Search photos by text

Authorizations

x-api-key
string
header
required

Pass your Pexafy API key in this header.

Get your API key at pexafy.com/dashboard/api-keys/create.

Query Parameters

q
string | null

Your search query in plain language — full descriptive sentences work best (e.g. two people sharing a bench in comfortable silence), though short queries like mountain sunset are fine too. Up to 500 characters. Optional if you provide at least one filter instead.

Maximum string length: 500
color_name
string | null

Keep only photos whose dominant color matches this name (e.g. blue, red, teal). Call GET /api/v1/facets/colors (see the Facets section) to get the list of available color names. Cannot be combined with color_hex.

color_hex
string | null

Keep only photos close to this hex color (e.g. #1E90FF). Cannot be combined with color_name. Use color_tolerance to widen or tighten the match.

color_tolerance
integer | null

How far a photo's colour may sit from the one you asked for, from 0 (strict) to 255 (very loose). Defaults to 20. Applies to both color_hex and color_name: for a hex it is the radius around that exact shade, for a name it widens or narrows the colour family. How far a photo's colour may sit from the one you asked for, from 0 (strict) to 255 (very loose). Defaults to 20. Applies to both color_hex and color_name: for a hex it is the radius around that exact shade, for a name it widens or narrows the colour family. The published spec used to say it applied to color_hex only, which was never true of the code.

Required range: 0 <= x <= 255
orientation
string[] | null

Keep only photos with these shapes: landscape, portrait and/or square. Repeat the parameter to pass several. See GET /api/v1/facets/orientations.

source
string[] | null

Keep only photos from these providers (e.g. Pexels, Unsplash, Pixabay). Repeat the parameter to pass several. Call GET /api/v1/facets/sources to list every available source.

license_type
string[] | null

Keep only photos with these license types (e.g. free). Call GET /api/v1/facets/licenses to list the available license types.

per_page
integer | null

Number of photos per page, from 1 to 100. Defaults to 20.

Required range: 1 <= x <= 100
limit
integer | null

Maximum TOTAL number of results to return across all pages — NOT the page size (use per_page for that). e.g. limit=4 with per_page=2 returns two pages of 2 results, then stops. Omit for no cap.

Required range: 1 <= x <= 100
score_threshold
number | null

Minimum relevance a photo must reach to appear, from 0 to 1. Raise it (e.g. 0.3) to keep only strong matches and drop loosely related photos; leave it unset to get the widest set of results.

Required range: 0 <= x <= 1
cursor
string | null

Token used to fetch the next page. Take the pagination.next_cursor value from a previous response and pass it back here. See the Pagination guide.

fields
string | null

Comma-separated list to return only the fields you need (e.g. photo_id,urls,attribution), which makes responses smaller. Omit to get every field your plan allows.

after_date
string | null

Only return photos published on or after this date, formatted YYYY-MM-DD.

sort_by
enum<string> | null

Order of the results: relevance (default — best match first) or newest (most recently added first).

Available options:
relevance,
newest
photographer
string | null

Only return photos from this photographer's username. Use GET /api/v1/facets/photographers/suggest to find usernames.

Response

Successful Response

success
boolean
data
object[]
meta
object
error
object | null
pagination
object | null