Skip to main content
With an API key and any HTTPS client, you can query S&P 500 SEC filing evidence in a single request. The examples below use curl.

​
1. Set Your API Key

Set your key as an environment variable: 
export AI_BASELINE_API_KEY="your-api-key"
Every request sends this key in the X-API-Key header.

​
2. Send a Query

Send a natural-language question to the /query endpoint: 
curl -X POST https://api-beta.ai-baseline.xyz/v2/sandp_500/query \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $AI_BASELINE_API_KEY" \
  -d '{
    "query": "What supply chain risks did Apple disclose in its 10-K filings?"
  }'
This request uses the default mode: "basic" and effort: "medium".

​
3. Read the Response

A successful default response includes a request_id, rendered evidence, evidence_instructions, and summary. It does not include answer unless you opt in to answer generation. 
{
  "request_id": "req_...",
  "evidence": "<source_registry>\n  ...\n</source_registry>\n\n<evidence_chain relevance_score=\"9\">\n  ...\n</evidence_chain>\n\n<source_key>\n  ...\n</source_key>",
  "evidence_instructions": "Use the evidence field as the grounded context for answer generation. Base factual claims only on the evidence, cite source IDs exactly as shown, and say when the evidence does not support an answer.",
  "summary": {
    "domain": "sandp_500",
    "mode": "basic",
    "effort": "medium",
    "evidence_count": 8
  }
}
summary.evidence_count is the number of retrieved evidence paths used as grounding for the response. It is not a count of SEC filings; one evidence path can include multiple filing statements. To request a generated answer from the API, set include.answer to true: 
{
  "query": "What supply chain risks did Apple disclose in its 10-K filings?",
  "include": {
    "answer": true
  }
}
When answer generation is enabled, the generated answer is returned in answer.text.

​
4. Discover Metadata Filters

Use GET /metadata-filters to inspect the supported metadata-filter fields, operators, limits, and optional categorical values. By default, research and agentic_research attempt to infer relevant metadata filters from the natural-language query. You can also provide metadata_filters explicitly when you know exact constraints, such as sec_ticker, sec_form_type, sec_fiscal_year, or sec_item_tag. Caller-provided metadata filters are treated as constraints, and the API may add filters inferred from the query. 
curl "https://api-beta.ai-baseline.xyz/v2/sandp_500/metadata-filters?include_values=true" \
  -H "X-API-Key: $AI_BASELINE_API_KEY"

​
5. Send a Query with Metadata Filters

Use research or agentic_research when you pass metadata filters. basic mode rejects non-empty metadata filters. 
curl -X POST https://api-beta.ai-baseline.xyz/v2/sandp_500/query \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $AI_BASELINE_API_KEY" \
  -d '{
    "query": "What supply chain risks did Apple disclose in Item 1A?",
    "mode": "research",
    "effort": "low",
    "metadata_filters": {
      "sec_ticker": "AAPL",
      "sec_form_type": "10-K"
    },
    "include": {
      "metadata_distribution": true,
      "analysis": true,
      "metadata_dashboard": true
    }
  }'