---
title: "Ai Search Endpoint"
method: POST
path: "/api/v1/remy/ai-search"
tags: ["remy", "remy"]
---

# Ai Search Endpoint

`POST /api/v1/remy/ai-search`

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

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

> 15 revisions in range; 1 not diffed.

- **2026-09-16** `dda5cf04b73d` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/brandbooster/apis/fastapi/changes/api/v1/remy/ai-search/post.md)

---

[API](https://skmtc.dev/brandbooster/apis/fastapi.md) · [All operations](https://skmtc.dev/brandbooster/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc.dev/brandbooster/apis/fastapi/revisions/7ba0627b6b4c?raw)