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

# Search Avatars Route

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

## Request

- Base URL: `https://api.brandbooster.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.brandbooster.ai/api/v1/avatars-lib/search`
- Auth: HTTP bearer

## 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/brandbooster-api.md) - [All operations](https://skmtc.dev/brandbooster/apis/brandbooster-api/llms.txt) - [OpenAPI document](https://skmtc.dev/brandbooster/apis/brandbooster-api/revisions/f84fc05f417b?raw)