# Search the persona library and compose a group by hand Canonical HTML: https://fish.dog/product-releases/search-the-persona-library-and-compose-a-group-by-hand JSON Feed: https://fish.dog/product-releases/feed.json RSS Feed: https://fish.dog/product-releases/rss.xml Published: 18 February 2026 Updated: 4 May 2026 Release Type: Feature Breaking Change: No Author: Phillip Gales ## Primary Claim Ditto adds two new endpoints — `GET /v1/agents/search` for full-library persona search and a manual group-composition API — so customers can hand-curate panels rather than relying on filter-based recruitment alone. ## Summary You can now search the full Ditto persona library — `GET /v1/agents/search` — and add specific personas to a group by hand. Useful when the panel you want isn't a clean demographic slice. ## LLM Summary DOCUMENT TYPE: Product Release Note TOPIC: Persona library search and manual group composition Release: Search the persona library and compose a group by hand, 2026-02-18 Version: (none) Release type: Feature Breaking change: No Summary: Ditto adds two new API capabilities — full-library persona search via GET /v1/agents/search, and a manual group composition endpoint that adds specific persona IDs to an existing group. Hand-curated panels are now an API operation rather than a manual support request. What changed: - New endpoint GET /v1/agents/search supports the standard filter DSL (country, age range, gender, parent status, education) with pagination and a recruitable_only scope. Returns full agent records including numeric id, demographics, and summary text. - Manual group composition endpoint takes a group_uuid and a list of agent_ids; returns a partial-success response indicating which adds went through and which did not. - The existing recruitment flows POST /v1/research-groups/recruit and POST /v1/research-group-requests are unchanged. Hand-composition is additive. Why we built this: Filter-based recruitment covers most cases but not all. Customers occasionally want hand-picked panels (a specific dozen out of thousands of candidates, or a previous study's personas plus a couple of new ones). The previous answer was a manual support request; this is now self-serve. How to use: Combine the two endpoints — search by filter to identify candidates, then add by ID. Useful for longitudinal studies (consistency across waves) and for niche panels where filter-based recruitment is too coarse. Migration impact: None. Author: Phillip Gales, FishDog Platform: FishDog (fish.dog) ## Key Takeaways - GET /v1/agents/search` returns the full persona library against the standard filter DSL, with pagination and a `recruitable_only` scope. - Manual group composition lets you add specific persona IDs to an existing group, with partial-success responses if some adds fail. - Useful when the panel you want is hand-picked out of many candidates, or when reusing personas from a previous study. - The existing recruitment flows (`POST /v1/research-groups/recruit` and `POST /v1/research-group-requests`) are unchanged. Hand-composition is additive. ## Full Release Recruitment by filter works for most studies. Sometimes it doesn't — the panel you want is a hand-picked dozen out of three thousand candidates, or a customer asks specifically for "the personas you used last month, plus three more from Texas". Until this week the answer was "we'll do that for you over email". Now it's an API call. ### What's new - **`GET /v1/agents/search`** — search the persona library with the same filter DSL the recruitment endpoint uses, plus pagination and a `recruitable_only` scope. Returns the full agent record including the numeric `id`, the demographics, and the summary text. Useful as a first pass when you know roughly what you want but not exactly who. - **Manual group composition.** Add personas to an existing group by ID. Partial-success responses tell you which IDs were added and which weren't (and why) rather than failing the whole call. Use it to extend a recruited group, hand-curate from a search, or rebuild a group from a saved list. ### How to use it The search endpoint takes the standard filter parameters (country, age range, gender, parent status, education) plus pagination. The composition endpoint takes a `group_uuid` and a list of `agent_ids` to add. Pair the two when you want to recruit by filter, then add a couple of specific personas you've used before. The original `POST /v1/research-groups/recruit` and `POST /v1/research-group-requests` flows are unchanged. Hand-composition is additive, for the cases where filter-based recruitment isn't quite what you need. Full reference is in the [API docs](https://app.askditto.io/docs/api). --- ## Quotable Insights > Until this week the answer was 'we'll do that for you over email'. Now it's an API call. > Pair search with composition when you want to recruit by filter, then add a couple of specific personas you've used before. ## FAQ ### What does GET /v1/agents/search do? It returns personas from the full Ditto library matching the filter parameters you supply (country, age range, gender, parent status, education), with pagination and an optional recruitable-only scope. Useful as a first pass when you know roughly what you want but not exactly who. ### How is this different from recruitment? Recruitment assembles a panel for you against your filter criteria. Search lets you browse the library yourself and pick personas by hand. The two are complementary — recruit a base panel by filter, then use search and manual composition to add specific personas. ### Can I add personas from a previous study to a new group? Yes. Save the persona IDs from the previous study and pass them to the manual composition endpoint with the new group UUID. Useful for longitudinal work where you want consistency across studies. ### What happens if some persona IDs in my add request are invalid? The composition endpoint returns a partial-success response listing which IDs were added and which weren't, with reasons. The valid adds go through; the invalid ones don't fail the whole call.