---
estimated_steps: 6
estimated_files: 3
skills_used: []
---

# T01: Add suggestions endpoint and integration test

Add `GET /api/v1/search/suggestions` endpoint that returns popular search terms derived from technique page titles (by view_count), popular sub-topic names (by technique_count), and creator names. Response schema: `SuggestionsResponse` with `suggestions: list[SuggestionItem]` where each item has `text: str` and `type: Literal['topic', 'technique', 'creator']`. Returns 8-12 items. Add integration test mocking DB data to verify the endpoint returns correctly shaped suggestions.

Steps:
1. Add `SuggestionItem` and `SuggestionsResponse` schemas to `backend/schemas.py`
2. Add `GET /suggestions` route to `backend/routers/search.py` that queries TechniquePage (top 4 by view_count), sub-topics from the topics router pattern (top 4 by technique_count), and Creator names (top 4 by view_count). Deduplicate and return up to 12 items.
3. Add integration test in `backend/tests/test_search.py` that seeds creators, technique pages, and verifies the suggestions endpoint returns the expected shape and types.
4. Run tests to confirm pass.

## Inputs

- ``backend/routers/search.py` — existing search router to add suggestions endpoint to`
- ``backend/schemas.py` — existing schemas to add SuggestionItem and SuggestionsResponse`
- ``backend/tests/test_search.py` — existing test file with seed helpers and fixtures`
- ``backend/models.py` — TechniquePage, Creator models for the query`
- ``backend/routers/topics.py` — reference for how sub-topic aggregation is done`

## Expected Output

- ``backend/schemas.py` — SuggestionItem and SuggestionsResponse schemas added`
- ``backend/routers/search.py` — GET /suggestions endpoint added`
- ``backend/tests/test_search.py` — integration test for suggestions endpoint added`

## Verification

cd backend && python -m pytest tests/test_search.py -v -k suggestion
