---
title: "Search Avatars Route"
method: GET
path: "/api/v1/avatars-lib/search"
tags: ["avatarsLib", "avatarsLib"]
---

# Search Avatars Route

`GET /api/v1/avatars-lib/search`

## Query parameters

- `gender` string[], nullable — e.g. Male, Female (multi-value)
- `age_range` AgeRangeBand[], nullable — 18-24 / 25-34 / 35-44 / 45-54 / 55+ (multi-value; personas span ranges)
- `age_min` integer, nullable — Tighter targeting than age_range
- `age_max` integer, nullable — Tighter targeting than age_range
- `ethnicity` string[], nullable — e.g. SouthAsian, Mixed (multi-value)
- `vibe_expression` string[], nullable — Soft signal, multi-value
- `setting` string, nullable — Soft signal, e.g. 'home interior', 'studio backdrop'
- `apparent_class_context` string, nullable — Soft signal
- `wardrobe` string, nullable — Soft signal, freetext contains
- `tags` string[], nullable — Matches any (multi-value)
- `shot_type` string[], nullable — headshot / waist-up / full body (multi-value)
- `angle` string[], nullable — front / three-quarter / profile (multi-value)
- `orientation` string[], nullable — portrait / landscape (multi-value)
- `resolution_band` 'low' | 'medium' | 'high' | 'ultra' — Ordinal quality tiers for AvatarsLib.resolution_band, low-to-high. ASSUMPTION: the model stores resolution_band as freeform text (whatever the generation pipeline writes), so this ordering is a guess at the real vocabulary. If the pipeline actually emits different band labels (e.g. sd/hd/2k/4k), update this single list -- everything else (the "min acceptable" filter) derives from its order, not its names.
- `q` string, nullable — Free-text persona description, searched across vibe_expression/wardrobe/setting/tags/review_notes
- `include_unusable` boolean — Include rows with usable_as_reference=false
- `include_inactive` boolean — Include rows with active=false
- `limit` integer — People per page (added for a bounded response; not in the original spec)
- `offset` integer

## Response `200`

Successful Response

- unknown

## 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)