Quickstart

With an API key and any HTTPS client, you can query S&P 500 SEC filing evidence in a single request. If another LLM or agent will generate the final response, request agent_context: a ready-to-feed Markdown payload that combines evidence-use instructions with grounding evidence. 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. Request Agent Context

For agent integrations, request agent_context from 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?",
    "include": {
      "agent_context": true
    }
  }'

This request uses the defaults: mode: "basic", effort: "medium", evidence: true, evidence_instructions: true, evidence_format: "rendered", and summary: true. It returns top-level evidence fields and evidence_budget for direct inspection, plus agent_context.text for direct handoff to another LLM or agent.

3. Hand It to Your Agent

A successful agent_context response includes the default evidence fields plus one context object for your LLM or agent runtime:

{
  "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.",
  "agent_context": {
    "content_type": "text/markdown",
    "text": "## Evidence Instructions\nUse the evidence field as the grounded context for answer generation...\n\n## Evidence\n<source_registry>\n  ...\n</source_registry>\n\n<evidence_chain relevance_score=\"9\">\n  ...\n</evidence_chain>",
    "source_fields": ["evidence_instructions", "evidence"]
  },
  "evidence_budget": {
    "requested_max_tokens": null,
    "estimator": "chars_div_4_v1",
    "estimated_tokens": 2460,
    "available_evidence_count": 8,
    "returned_evidence_count": 8,
    "truncated": false
  },
  "summary": {
    "domain": "sandp_500",
    "mode": "basic",
    "effort": "medium",
    "evidence_count": 8
  }
}

Given the response above, pass agent_context.text as the context for the downstream model call, alongside the original user question:

const question = "What supply chain risks did Apple disclose in its 10-K filings?";
const baselineResponse = /* response JSON from /query */;

const agentHandoff = {
  messages: [
    { role: "system", content: baselineResponse.agent_context.text },
    { role: "user", content: question }
  ]
};

// Send agentHandoff to your LLM or agent runtime.

Your agent should use agent_context.text as the grounded context for answer generation. It includes both the instructions for using the evidence and the evidence itself. 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.

4. Default Evidence Response

If you omit include.agent_context, the default response includes a request_id, rendered evidence, evidence_instructions, evidence_budget, and summary.

{
  "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.",
  "evidence_budget": {
    "requested_max_tokens": null,
    "estimator": "chars_div_4_v1",
    "estimated_tokens": 2460,
    "available_evidence_count": 8,
    "returned_evidence_count": 8,
    "truncated": false
  },
  "summary": {
    "domain": "sandp_500",
    "mode": "basic",
    "effort": "medium",
    "evidence_count": 8
  }
}

Evidence-use instructions are returned by default when top-level evidence is included. To omit them from the top-level response, set include.evidence_instructions to false:

{
  "query": "What supply chain risks did Apple disclose in its 10-K filings?",
  "include": {
    "evidence_instructions": false
  }
}

5. 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"

6. 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 its 10-K Item 1A filings?",
    "mode": "research",
    "effort": "medium",
    "metadata_filters": {
      "sec_ticker": "AAPL",
      "sec_form_type": "10-K"
    },
    "include": {
      "evidence": true,
      "evidence_format": "rendered",
      "evidence_instructions": true,
      "agent_context": false,
      "metadata_distribution": false,
      "metadata_dashboard": false,
      "summary": false
    },
    "retrieval": {
      "max_evidence": 25,
      "max_evidence_tokens": 12000
    }
  }'

Both retrieval controls are optional and must be positive when supplied. max_evidence_tokens is uncapped when omitted; the response still includes the deterministic evidence-size estimate.

Get Started

Guides

API Reference

1. Set Your API Key

2. Request Agent Context

3. Hand It to Your Agent

4. Default Evidence Response

5. Discover Metadata Filters

6. Send a Query with Metadata Filters

​1. Set Your API Key

​2. Request Agent Context

​3. Hand It to Your Agent

​4. Default Evidence Response

​5. Discover Metadata Filters

​6. Send a Query with Metadata Filters

1. Set Your API Key

2. Request Agent Context

3. Hand It to Your Agent

4. Default Evidence Response

5. Discover Metadata Filters

6. Send a Query with Metadata Filters