---
title: "Search Library images"
method: POST
path: "/images/search"
tags: ["Images"]
---

# Search Library images

`POST /images/search`

## Request

- Base URL: `https://www.rainbrand.com/api/v1`
- URL: `https://www.rainbrand.com/api/v1/images/search`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer
  - OAuth 2
    - Authorization code: `https://www.rainbrand.com/api/auth/oauth2/authorize`
    - Token URL: `https://www.rainbrand.com/api/auth/oauth2/token`

Find Brand Library images by what they depict, such as product photos or packaging. Generated images are excluded.

## Request body

- object
  - `brandSessionId` string, uuid, required: Brand ID to search within
  - `query` string, required: Visual concept to search for. Plain noun phrases work best — e.g., 'drone in flight', 'team working at desks', 'product on white background'.
  - `limit` integer: Max results to return (default 10, max 50)
  - `cursor` string: Pagination cursor from a previous response's nextCursor
  - `maxDistance` number: Cosine-distance cutoff (smaller = stricter). The default of 0.7 works well for most queries. Use a higher value for broader matching or a lower value for stricter results. Distances above this threshold are excluded.

## Response `200`

OK

- object
  - `data` object, required
    - `query` string, required
    - `candidates` object[], required
      - `id` string, uuid, required
      - `url` string, required
      - `description` string, required
      - `width` number, nullable, required
      - `height` number, nullable, required
      - `aspectRatio` '1:1' | '2:3' | '3:2' | '3:4' | '4:3' | '4:5' | '5:4' | '9:16' | '16:9' | '21:9', nullable, required
      - `distance` number, required: Opaque relevance score; smaller = closer.
    - `nextCursor` string, nullable, required
    - `hasMore` boolean, required

## Other responses

- `400`: 400
- `401`: 401
- `403`: 403
- `422`: 422
- `429`: 429

---

[API](https://skmtc.dev/rainbrand/apis/rainbrand-api.md) - [All operations](https://skmtc.dev/rainbrand/apis/rainbrand-api/llms.txt) - [OpenAPI document](https://skmtc.dev/rainbrand/apis/rainbrand-api/revisions/012b8e9da4df?raw)