Overview

Quick Start

From zero to your first cited passages in a few minutes: get an API key, call POST /v1/retrieve, and pass the chunks straight into your model.

1. Get an API key#

Request access from the dashboard. You’ll receive a key prefixed with fa_live_. Treat it like a password — it authenticates every request and is tied to your usage and quota. See Authentication for details.

2. Make your first request#

Send a natural-language query to POST /v1/retrieve with your key in the Authorization header. Everything except query is optional.

curl

curl https://api.focusalpha.ai/v1/retrieve \
  -H "Authorization: Bearer fa_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What did management say about data center capex?",
    "filters": { "tickers": ["NVDA"], "year": 2025, "quarter": "Q1" },
    "top_k": 8
  }'

3. Read the response#

You get back an array of chunks, each with its text, a relevance score, a one-to-three sentence evidenceText span, and a source object with full provenance.

response.json

{
  "chunks": [
    {
      "id": "chunk_01",
      "text": "Data center revenue grew 25% sequentially to a record $22.6 billion...",
      "score": 0.18,
      "evidenceText": "Data center revenue grew 25% sequentially to a record $22.6 billion.",
      "source": {
        "documentTitle": "NVIDIA Q1 2025 Earnings Call",
        "documentType": "earnings_call",
        "ticker": "NVDA",
        "year": 2025,
        "quarter": "Q1",
        "filingType": null,
        "sourceUrl": null
      }
    }
  ],
  "meta": { "total": 8, "periodMismatch": null, "requestId": "req_a1b2c3" }
}

4. Feed the chunks to your model#

Concatenate the chunk text into your prompt and let your own LLM reason over it. Because each chunk carries a source, you can render citations in your UI and link back to the primary document.

example.ts

const res = await fetch("https://api.focusalpha.ai/v1/retrieve", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FOCUSALPHA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "What did management say about data center capex?",
    filters: { tickers: ["NVDA"], year: 2025, quarter: "Q1" },
    top_k: 8,
  }),
});

const { chunks } = await res.json();

// Build grounded context for your own model.
const context = chunks
  .map((c, i) => `[${i + 1}] (${c.source.documentTitle}) ${c.text}`)
  .join("\n\n");

// ...pass `context` into your Claude / GPT / open-model prompt.

Prefer no API plumbing?

If you work inside Claude Desktop or Claude Code, skip the REST layer entirely — mount our MCP server and the model calls retrieval for you.

Next steps#

Read the full Retrieve API reference for every filter and response field, or set up the MCP server for Claude.

PreviousIntroduction

Next Authentication