--- title: "Ai Search Endpoint" method: POST path: "/api/v1/remy/ai-search" tags: ["remy"] --- # Ai Search Endpoint `POST /api/v1/remy/ai-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/remy/ai-search` - Auth: HTTP bearer Turn a plain-language creator brief into a scored, ranked creator table. A sufficiently specific brief returns a job id at once and queues the search — a deep search reads 600 creators through the model, which can outlast the 120s TimeoutMiddleware. Poll the status route. A plainly broad brief (for example, "give me 10 creators") instead returns `status=clarification_required`, no job id, and up to three structured questions. Submit the combined answers to this same endpoint with the returned `search_id` as `session_id`; the backend retains the original request and starts the job once the brief has a useful subject. `session_id` may identify an empty chat created by POST /ai-search/sessions; omit it to create and start a new persistent chat in this call. `platforms` and `size` come from the UI's own controls and override whatever the brief implied — a deliberate click beats an inference. `depth` caps how many candidates the scoring pass reads, which is what keeps cost flat as the corpus grows. `live_content=true` sources fresh creators from influencers.club and returns them in `discovered_creators` for the user to save; it is off by default because sourcing spends provider credits. Nothing it finds joins the roster on its own — POST /ai-search/{search_id}/save is what keeps a creator. ## Request body - AiSearchRequestDTO - `query` string, required - `session_id` string, uuid, nullable - `platforms` string[], nullable - `size` 'under_10k' | '10k_100k' | '100k_500k' | '500k_1m' | '1m_plus': The UI's Size selector. Values are FOLLOWER_BAND_BOUNDS keys, not tier names — the tier vocabulary (Nano/Micro/Mid/Macro) bands differently and would mis-filter against them. - `depth` 'quick' | 'balanced' | 'deep': How many candidates the scoring pass reads — the UI's Depth selector. - `live_content` boolean - `video_analysis` boolean - `ui_filters` AiSearchUiFiltersDTO: The filter bar under the brief. Only the fields the user changed are sent: those replace what the brief implied (an empty value means that filter was removed) and the rest still come from the brief. - `creator_countries` string[] - `audience_countries` string[] - `niches` string[] - `sub_niches` string[] - `followers_min` integer, nullable - `followers_max` integer, nullable - `gender` string, nullable - `last_post_days` string, nullable - `engagement_min` number, nullable - `average_likes_min` integer, nullable - `average_likes_max` integer, nullable - `reel_views_min` integer, nullable - `reel_views_max` integer, nullable - `follower_growth_min` number, nullable - `languages` string[] - `verified_only` boolean - `exclude_private` boolean - `has_brand_deals` boolean - `promotes_affiliate_links` boolean - `creator_ages` string[] - `bio_keywords` string[] - `average_comments_min` integer, nullable - `average_comments_max` integer, nullable - `posts_min` integer, nullable - `has_link_in_bio` boolean - `has_reels` boolean - `audience_gender` string, nullable - `audience_ages` string[] - `audience_languages` string[] - `creator_type` string, nullable - `audience_country_pcts` object - `audience_gender_pct` integer, nullable - `audience_age_pcts` object - `audience_language_pcts` object - `audience_interests` string[] - `audience_interest_pcts` object - `audience_credibility` string, nullable - `hashtags` string[] - `content_keywords` string[] - `video_title_keywords` string[] - `link_in_bio_contains` string[] - `video_description_links` string[] - `tagged_brands` string[] - `topics` string[] - `creator_has` string[] - `posting_frequency_min` number, nullable - `income_min` integer, nullable - `income_max` integer, nullable - `follower_growth_months` integer, nullable - `reels_percent_min` integer, nullable - `shorts_views_min` integer, nullable - `downloads_min` integer, nullable - `has_tiktok_shop` boolean - `is_monetizing` boolean - `has_shorts` boolean - `has_community_posts` boolean - `has_podcast` boolean - `has_courses` boolean - `has_membership` boolean - `has_merch` boolean - `streams_live` boolean - `extra_filters` object - `ai_keywords` string, nullable ## Response `200` Successful Response - AiSearchStartedDTO - `job_id` string, nullable - `search_id` string, required - `status` string, required - `message` string, nullable - `questions` AiSearchClarificationQuestionDTO[] - `id` string, required - `question` string, required - `options` AiSearchClarificationOptionDTO[] - `label` string, required - `value` string, required - `allow_multiple` boolean - `allow_free_text` boolean - `required` boolean - `can_skip` boolean ## Other responses - `422`: Validation Error ## Changes > 37 revisions in range; 1 not diffed. - **2026-11-02** `f84fc05f417b`: 47 info - added the new optional request property `ui_filters/anyOf[subschema #1: AiSearchUiFiltersDTO]/ai_keywords` - added the new optional request property `ui_filters/anyOf[subschema #1: AiSearchUiFiltersDTO]/audience_age_pcts` - added the new optional request property `ui_filters/anyOf[subschema #1: AiSearchUiFiltersDTO]/audience_ages` - added the new optional request property `ui_filters/anyOf[subschema #1: AiSearchUiFiltersDTO]/audience_country_pcts` - …43 more - **2026-10-30** `8e8c18c2dc35`: 1 info - added the new optional request property `ui_filters` - **2026-10-19** `05663804abc9`: 1 info - added the new optional request property `video_analysis` - **2026-09-16** `dda5cf04b73d`: 1 info - endpoint added [Operation history](https://skmtc.dev/brandbooster/apis/brandbooster-api/changes/api/v1/remy/ai-search/post.md) --- [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/02d28bde684c?raw)