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

# Search Insights

> POST /api/insights/search — semantic search over the Alchemist database.

## `POST /api/insights/search`

Searches the Alchemist database and returns ranked insights. Each insight includes the verbatim source excerpt it was derived from, the originating document, and relevance score.

Insights are embedded with **HyDE** — the index stores both the insight text and hypothetical questions it can answer. This makes focused keyword phrases and concise questions work well as queries.

### Authentication

`X-API-Key: alch_YOUR_KEY`

### Request body

```json theme={null}
{
  "query": "Fed dot plot rate path 2026",
  "source_name": "Federal Reserve",
  "since": "2026-01-01",
  "limit": 20
}
```

| Field         | Type             | Required | Description                                                                                                            |
| ------------- | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| `query`       | `string`         | Yes      | One focused concept — a concise question or 3–8 keyword phrase. Avoid conversational wrappers and multi-theme queries. |
| `source_name` | `string \| null` | No       | Partial, case-insensitive match on publishing organization. Use `GET /api/documents/filters` to see valid values.      |
| `since`       | `string (date)`  | No       | ISO 8601 date (`YYYY-MM-DD`). Only returns insights from documents published on or after this date.                    |
| `limit`       | `integer`        | No       | Max insights to return. Default `20`.                                                                                  |

### Response `200`

```json theme={null}
{
  "insights": [
    {
      "insight_id": "ins_01jwx9z3kq7f4vbr",
      "title": "Fed median dot unchanged at 3.875% for end-2026",
      "insight": "The March 2026 SEP showed the median federal funds rate projection for year-end 2026 held at 3.875%, unchanged from the December 2025 SEP.",
      "excerpts": [
        "The median projection for the federal funds rate at the end of 2026 remained at 3.875 percent, unchanged from the December 2025 projection."
      ],
      "doc_id": "doc_01jww8y2hp6e3uaq",
      "doc_title": "FOMC Summary of Economic Projections — March 2026",
      "source_url": "https://federalreserve.gov/monetarypolicy/files/fomcprojtabl20260320.pdf",
      "source_name": "Federal Reserve",
      "published_date": "2026-03-20",
      "score": 0.92
    }
  ]
}
```

| Field            | Type             | Description                                                       |
| ---------------- | ---------------- | ----------------------------------------------------------------- |
| `insight_id`     | `string`         | Unique insight identifier                                         |
| `title`          | `string`         | Short title for the insight                                       |
| `insight`        | `string`         | The extracted finding, written as a complete statement            |
| `excerpts`       | `string[]`       | Verbatim quotes from the source document that support the insight |
| `doc_id`         | `string`         | Parent document ID — use with `GET /api/documents/{doc_id}`       |
| `doc_title`      | `string`         | Title of the originating document                                 |
| `source_url`     | `string`         | Direct URL to the primary source                                  |
| `source_name`    | `string`         | Publishing organization                                           |
| `published_date` | `string \| null` | Publication date of the source document                           |
| `score`          | `float`          | Semantic relevance score (0–1). Higher is more relevant.          |

### Query writing guide

<AccordionGroup>
  <Accordion title="Good query patterns">
    | Pattern                | Example                                             |
    | ---------------------- | --------------------------------------------------- |
    | Concise question       | `"Did the March 2026 FOMC minutes signal a pause?"` |
    | Entity + metric        | `"AAPL 2025 revenue guidance"`                      |
    | Theme + source keyword | `"corn ending stocks USDA"`                         |
    | Policy + date          | `"Fed dot plot March 2026"`                         |
    | Sector + event         | `"natural gas inventory EIA weekly"`                |
  </Accordion>

  <Accordion title="Patterns to avoid">
    | Anti-pattern                                     | Why                                            |
    | ------------------------------------------------ | ---------------------------------------------- |
    | `"Tell me about the latest Fed meeting"`         | Conversational wrapper adds noise              |
    | `"Fed rates inflation corn energy stocks bonds"` | Multi-theme keyword soup dilutes the embedding |
    | `"What does Wall Street think?"`                 | Too vague — no entity to anchor the search     |
  </Accordion>

  <Accordion title="Refining a sparse result">
    If `search_insights` returns 0 or very few results:

    1. Try a more specific phrasing: `"Q4 2025 guidance"` → `"Q4 2025 revenue outlook earnings call"`
    2. Remove filters (`source_name`, `since`) and try again
    3. Try an alternative entity name or acronym: `"Bureau of Labor Statistics"` → `"BLS"`
    4. Call `GET /api/documents/filters` to confirm the source name you're filtering on is in the database
  </Accordion>
</AccordionGroup>

### Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.askalchemist.com/api/insights/search \
    -H "X-API-Key: alch_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "corn ending stocks revision downward",
      "source_name": "USDA",
      "since": "2026-01-01"
    }'
  ```

  ```python Python (httpx) theme={null}
  import httpx

  resp = httpx.post(
      "https://api.askalchemist.com/api/insights/search",
      headers={"X-API-Key": "alch_YOUR_KEY"},
      json={
          "query": "corn ending stocks revision downward",
          "source_name": "USDA",
          "since": "2026-01-01",
      },
  )
  data = resp.json()
  for i in data["insights"]:
      print(f"[{i['score']:.2f}] {i['title']}")
      print(f"  {i['insight']}")
      print(f"  Source: {i['source_name']} ({i['published_date']})")
      print()
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch("https://api.askalchemist.com/api/insights/search", {
    method: "POST",
    headers: {
      "X-API-Key": "alch_YOUR_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      query: "corn ending stocks revision downward",
      source_name: "USDA",
      since: "2026-01-01",
    }),
  });

  const { insights } = await res.json();
  ```
</CodeGroup>