Search Insights

`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

{
  "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`

{
  "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

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"`

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

Refining a sparse result

If search_insights returns 0 or very few results:

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

Examples

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"
  }'

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()

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();

Get Started

Add to Agents

MCP Reference

API Reference

`POST /api/insights/search`

Authentication

Request body

Response `200`

Query writing guide

Examples

​POST /api/insights/search

​Authentication

​Request body

​Response 200

​Query writing guide

​Examples

`POST /api/insights/search`

Authentication

Request body

Response `200`

Query writing guide

Examples