Explain API
Explain answers 'what is this symbol doing, and why?' in plain English. It reads the Market Brain over daily price and volume and returns a grounded, cited explanation carrying LyraMind's trust envelope.
What it returns
The response wraps the product envelope (api_version, powered_by, disclaimer) around an explanation object: headline, what (the plain-language condition), why, context (the top 'what changed' note), and risks (up to three). It also returns symbol, available, confidence, and provider.
Every answer includes a trust block: confidence, confidence_label, sources, evidence, reasoning, data_mode, freshness, and a compliance status. When there is not enough price history, available is false and the trust block is marked ungrounded.
When to use it
Reach for Explain when an agent or app needs a human-readable interpretation of a single name before showing it to a user or acting on it. It is the lightest primitive: one call, one narrative.
Results are cached for 5 minutes per symbol and audience. Set audience to retail or pro to hint the tone; the underlying read is the same.
Notes and honesty
The read is deterministic and offline-safe: with POLYGON_API_KEY set it uses live daily candles, otherwise it falls back to labeled sample data and reports the provider in data_mode and freshness. This is educational context only, never investment advice or a price prediction, as the disclaimer on every response states.
- explanation.headline: one-line read of the symbol
- explanation.what / why / context: plain-language condition and drivers
- explanation.risks: up to three risk notes from the Market Brain
- confidence and provider: engine confidence plus the data source
- trust: confidence, sources, evidence, data_mode, freshness, compliance
- available flag: false when price history is insufficient
curl -s https://api.lyramindos.com/v1/explain -H 'Content-Type: application/json' -H 'x-api-key: YOUR_KEY' -d '{"symbol":"AAPL","audience":"retail"}'Questions
Do I need an API key?
No. Anonymous calls are allowed and metered per client IP. Adding an org or platform key raises your per-minute rate limit; the response headers report your tier and remaining quota.
Is this investment advice?
No. Explain is educational context and probabilities only. Every response carries a disclaimer and a compliance block stating no advice and no prediction.
What happens with an unknown or thin ticker?
The call still returns 200 with available:false, an honest headline, and an ungrounded trust block, so callers never get a fabricated read.