> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ai-baseline.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Request agent-ready evidence context from the AI Baseline API.

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:

```bash theme={null}
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:

```bash theme={null}
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:

```json theme={null}
{
  "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:

```js theme={null}
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`.

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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.

```bash theme={null}
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.

```bash theme={null}
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.