---
title: "Search"
method: GET
path: "/api/v1/freepik-assets/search"
tags: ["freepikAssets"]
---

# Search

`GET /api/v1/freepik-assets/search`

Search backgrounds by what is IN the image, not by which template wants it.

A template is a combination of these filters, so supporting a new layout costs
a new query string and no schema change:

  design_11 — opaque copy card, BLACK logo top-left
    /search?text_safe_black=top-left&tags=style:ugc

  design_07 — 78px WHITE type on the photo, white logo top-right, subject low
    /search?text_safe_white=top-left&text_safe_white=top-right
           &subject_top_min=0.24&tags=style:ugc

## Query parameters

- `subject_zone` string[], nullable — Repeat to accept several: &subject_zone=top-right&subject_zone=center
- `subject_top_min` number, nullable — Subject starts at or below this depth — keeps the top clear for a headline
- `subject_top_max` number, nullable
- `subject_left_min` number, nullable
- `subject_right_min` number, nullable
- `text_safe_white` string[], nullable — ALL listed zones must be safe for white type
- `text_safe_black` string[], nullable — ALL listed zones must be safe for black type
- `keywords` string[], nullable — ALL must be present
- `keywords_any` string[], nullable — ANY may match
- `q` string, nullable — Free text over the generated description
- `has_text` boolean, nullable
- `tags` string[], nullable — e.g. tags=style:ugc
- `orientation` string, nullable
- `licensed` boolean, nullable
- `status` string, nullable
- `min_width` integer, nullable
- `measured_only` boolean
- `include_descriptor` boolean — Adds ~9KB per row
- `order_by` string
- `limit` integer
- `offset` integer

## Response `200`

Successful Response

- FreepikAssetSearchResponseDTO
  - `total` integer, required — Matches before limit/offset
  - `returned` integer, required
  - `results` FreepikAssetSearchResultDTO[], required
    - `freepik_id` integer, nullable
    - `title` string, nullable
    - `ai_description` string, nullable
    - `keywords` string[], nullable
    - `preview_url` string, nullable
    - `my_url` string, nullable
    - `width` integer, nullable
    - `height` integer, nullable
    - `subject_zone` string, nullable
    - `subject_top` number, nullable
    - `subject_bottom` number, nullable
    - `subject_left` number, nullable
    - `subject_right` number, nullable
    - `text_safe_white` string[], nullable
    - `text_safe_black` string[], nullable
    - `has_text` boolean, nullable
    - `licensed` boolean
    - `usage_count` integer, nullable
    - `descriptor` object, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/brandbooster/apis/fastapi.md) · [All operations](https://skmtc.dev/brandbooster/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/brandbooster/fastapi/revisions/624917d53409/schema)