---
title: "Search Unsplash photos"
method: GET
path: "/api/v1/media/unsplash/search"
tags: ["unsplash"]
---

# Search Unsplash photos

`GET /api/v1/media/unsplash/search`

## Request

- Base URL: `https://slatehut.com`
- URL: `https://slatehut.com/api/v1/media/unsplash/search`
- Auth: HTTP bearer

Query params: `q` (search text), `page` (1-based), optional `orientation` (landscape|portrait|squarish), optional `color` (black_and_white|black|white|yellow|orange|red|purple|magenta|green|teal|blue). If `UNSPLASH_ACCESS_KEY` is unset, returns `unsplashConfigured: false` and empty results.

## Query parameters

- `q` string
- `page` integer
- `orientation` 'landscape' | 'portrait' | 'squarish'
- `color` 'black_and_white' | 'black' | 'white' | 'yellow' | 'orange' | 'red' | 'purple' | 'magenta' | 'green' | 'teal' | 'blue'

## Response `200`

Thumbnails and metadata; use `id` as `photoId` for import

- UnsplashSearchResponse
  - `unsplashConfigured` boolean, required: False when UNSPLASH_ACCESS_KEY is not set
  - `results` UnsplashSearchHit[], required
    - `id` string
    - `thumbUrl` string
    - `smallUrl` string: Preview URL (~400px), falls back to thumbUrl when absent
    - `regularUrl` string: Full-size CDN URL on images.unsplash.com when present
    - `description` string
    - `photographerName` string
    - `photographerUrl` string
    - `width` integer: Native pixel width of the source photo.
    - `height` integer: Native pixel height of the source photo.
    - `color` string: Dominant hex color from Unsplash (useful for theme matching).
  - `page` integer, required
  - `totalPages` integer, required

## Other responses

- `401`: Missing or invalid credentials
- `502`: Validation or conflict error

---

[API](https://skmtc.dev/slatehut/apis/slatehut-api.md) · [All operations](https://skmtc.dev/slatehut/apis/slatehut-api/llms.txt) · [OpenAPI document](https://skmtc.dev/slatehut/apis/slatehut-api/revisions/32dae277550c?raw)