Skip to main content

​
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
}
FieldTypeRequiredDescription
querystringYesOne focused concept — a concise question or 3–8 keyword phrase. Avoid conversational wrappers and multi-theme queries.
source_namestring | nullNoPartial, case-insensitive match on publishing organization. Use GET /api/documents/filters to see valid values.
sincestring (date)NoISO 8601 date (YYYY-MM-DD). Only returns insights from documents published on or after this date.
limitintegerNoMax 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
    }
  ]
}
FieldTypeDescription
insight_idstringUnique insight identifier
titlestringShort title for the insight
insightstringThe extracted finding, written as a complete statement
excerptsstring[]Verbatim quotes from the source document that support the insight
doc_idstringParent document ID — use with GET /api/documents/{doc_id}
doc_titlestringTitle of the originating document
source_urlstringDirect URL to the primary source
source_namestringPublishing organization
published_datestring | nullPublication date of the source document
scorefloatSemantic relevance score (0–1). Higher is more relevant.

​
Query writing guide

PatternExample
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"
Anti-patternWhy
"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
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

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