> ## Documentation Index
> Fetch the complete documentation index at: https://docs.handauncle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Visual Embeds API

> Manage visual embed images that attach to AI chat responses.

Visual embeds are quote images that get attached to AI responses based on semantic
matching. Each embed belongs to a category and stores a GCS image URL plus optional
quote text.

### Quick facts

* Base path: `/api/v1/visual-embeds`
* MongoDB collections: `visual_embeds`, `visual_categories`
* Auto-seeds from hardcoded manifest on first startup
* Service caches DB results for 5 minutes

### Surface area

| Action      | Endpoint                                                             | Description                                    |
| ----------- | -------------------------------------------------------------------- | ---------------------------------------------- |
| List        | [`GET /api/v1/visual-embeds`](./visual-embeds/list)                  | All embeds, optionally filter by `category_id` |
| Get         | [`GET /api/v1/visual-embeds/{id}`](./visual-embeds/get)              | Single embed by MongoDB ID                     |
| Create      | [`POST /api/v1/visual-embeds`](./visual-embeds/create)               | Add new embed                                  |
| Bulk create | [`POST /api/v1/visual-embeds/bulk`](./visual-embeds/bulk-create)     | Add multiple embeds                            |
| Update      | [`PATCH /api/v1/visual-embeds/{id}`](./visual-embeds/update)         | Modify embed                                   |
| Delete      | [`DELETE /api/v1/visual-embeds/{id}`](./visual-embeds/delete)        | Remove embed                                   |
| Categories  | [`GET /api/v1/visual-embeds/categories`](./visual-embeds/categories) | List all categories                            |

See the endpoint pages for request bodies, parameter constraints, and example
responses pulled directly from the OpenAPI schema.

### Categories

| ID                     | Display Name         | Keywords                                   |
| ---------------------- | -------------------- | ------------------------------------------ |
| `AssetAllocation`      | Asset Allocation     | asset allocation, portfolio mix, rebalance |
| `Debt_Fix_Income`      | Debt & Fixed Income  | debt, fixed income, bonds                  |
| `EmergencyFund`        | Emergency Fund       | emergency fund, liquidity                  |
| `Goal_Based_Investing` | Goal-Based Investing | goal based, education goal                 |
| `Insurance`            | Insurance            | insurance, term insurance                  |
| `Mutual_Funds`         | Mutual Funds         | mutual fund, sip, index fund               |
| `Portfolio_Review`     | Portfolio Review     | portfolio review                           |
| `Real_Estate`          | Real Estate          | real estate, property                      |
| `Retirement_Planning`  | Retirement Planning  | retirement, corpus                         |
| `Tax_Planning`         | Tax Planning         | tax, 80C, deduction                        |

### How it works

1. Chat service generates AI response
2. Visual Planner (LLM) decides if visual should attach
3. Visual Embed Service queries `visual_embeds` by category
4. Business rules checked in Redis (max 3/session, no repeats)
5. Visual URL attached to response

Images stored in GCS: `gs://handa-visuals/{Category}/{filename.png}`