> ## 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.

# AI Baseline

> API for querying SEC filing evidence, agent-ready context, and metadata summaries.

Use the AI Baseline API to ask natural-language questions about S\&P 500 SEC filings and receive rendered evidence, metadata summaries, dashboards, or ready-to-feed agent context.

## Base URL

```text theme={null}
https://api-beta.ai-baseline.xyz/v2/sandp_500/
```

Every request must include your API key:

```bash theme={null}
-H "X-API-Key: $AI_BASELINE_API_KEY"
```

## Endpoints

| Endpoint                | Purpose                                                                       |
| ----------------------- | ----------------------------------------------------------------------------- |
| `POST /query`           | Query S\&P 500 filing evidence and return the requested response sections.    |
| `GET /metadata-filters` | List the metadata-filter fields and operators available for S\&P 500 filings. |

## Minimal Query

```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?"
  }'
```

This request defaults to `mode: "basic"` and `effort: "medium"`. It returns rendered `evidence`, `evidence_instructions`, `evidence_budget`, and `summary` by default.

## Response Shape

`/query` returns a response with a stable `request_id` and optional top-level sections:

<table>
  <colgroup>
    <col style={{ width: "18rem" }} />

    <col />
  </colgroup>

  <thead>
    <tr>
      <th>Section</th>
      <th>Contains</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code style={{ whiteSpace: "nowrap" }}>evidence</code></td>
      <td>Grounding text selected by <code>include.evidence\_format</code>; rendered evidence includes a source-key footer, while XML evidence omits it.</td>
    </tr>

    <tr>
      <td><code style={{ whiteSpace: "nowrap" }}>evidence\_instructions</code></td>
      <td>Guidance for downstream LLMs on how to use the returned evidence. Returned by default when evidence is included.</td>
    </tr>

    <tr>
      <td><code style={{ whiteSpace: "nowrap" }}>agent\_context</code></td>
      <td>Derived Markdown context block for direct handoff to another LLM or agent.</td>
    </tr>

    <tr>
      <td><code style={{ whiteSpace: "nowrap" }}>metadata\_distribution</code></td>
      <td>Metadata distribution keyed by canonical field names, with readable display names and metric values inside each entry.</td>
    </tr>

    <tr>
      <td><code style={{ whiteSpace: "nowrap" }}>metadata\_dashboard</code></td>
      <td>Rendered ASCII summary of the metadata distribution.</td>
    </tr>

    <tr>
      <td><code style={{ whiteSpace: "nowrap" }}>summary</code></td>
      <td>Selected mode, effort, filters, warnings, and evidence-path count.</td>
    </tr>

    <tr>
      <td><code style={{ whiteSpace: "nowrap" }}>coverage</code></td>
      <td>Task-aware requirement coverage for <code>agentic\_research</code>, including missing or budget-omitted inputs.</td>
    </tr>

    <tr>
      <td><code style={{ whiteSpace: "nowrap" }}>evidence\_budget</code></td>
      <td>Deterministic evidence token estimate, optional requested cap, available and returned chain counts, and truncation status.</td>
    </tr>

    <tr>
      <td><code style={{ whiteSpace: "nowrap" }}>retrieval\_plan</code></td>
      <td>Retrieval query plan for <code>agentic\_research</code>.</td>
    </tr>
  </tbody>
</table>

## Example Response Sections

Responses always include `request_id`. By default, `/query` returns rendered `evidence`, `evidence_instructions`, `evidence_budget`, and `summary`. Other top-level sections are returned when enabled by `include` or by the selected query mode. The examples below are abbreviated to show their structure.

### `request_id`

```json theme={null}
{
  "request_id": "req_2xYk9mA3..."
}
```

### `evidence`

The API returns `evidence` as a string. With `evidence_format: "rendered"`, the formatted evidence includes a trailing `<source_key>` quick reference. `relevance_score` is a system-derived integer from 0 to 10 that indicates how closely the evidence chain matches the query. `confidence_score` reflects the system's confidence in the specific fact captured by that entry. An entry can cite multiple sources: all cited sources support the shared `<consensus>` claim, while each source can contribute distinct `<observed_epistemic_statuses>` and `<additional_context>`.

Returned JSON field:

```json theme={null}
{
  "evidence": "<source_registry>\n  <source id=\"AAPL_10K_2025_ITEM-1A\" ... />\n</source_registry>\n\n<entity_glossary>\n  ...\n</entity_glossary>\n\n<evidence_chain relevance_score=\"9\">\n   ...\n</evidence_chain>\n\n<source_key>\n  ...\n</source_key>"
}
```

Same value, expanded:

```xml theme={null}
<source_registry>
  <source id="AAPL_10K_2025_ITEM-1A" type="10-K" date="2025-10-31" sec_fiscal_year="FY-2025" sec_fiscal_year_end="09-27" sec_form_type="10-K" sec_gics_sector="Information Technology" sec_gics_sub_industry="Technology Hardware, Storage &amp; Peripherals" sec_item_tag="10K-Item-1A" sec_ticker="AAPL" />
</source_registry>

<entity_glossary>
  <entity>
    <name>Apple Inc. manufacturing and logistical outsourcing risk</name>
    <description>Risk theme describing Apple Inc.'s dependency on third-party outsourcing partners for component manufacturing, product assembly, and logistical services.</description>
  </entity>
</entity_glossary>

<evidence_chain relevance_score="9">
   <entry confidence_score='High' sources='AAPL_10K_2025_ITEM-1A'>
      <observed_epistemic_statuses>
      * FACT [AAPL_10K_2025_ITEM-1A]
      </observed_epistemic_statuses>
      <consensus>
      Apple Inc. disclosed a dependency on outsourcing partners for component manufacturing, product assembly, and logistical services, often located outside of the U.S.
      </consensus>
      <additional_context>
      * Risk: significant uncertainties [AAPL_10K_2025_ITEM-1A]
      * Risk: reduced direct control over production and distribution [AAPL_10K_2025_ITEM-1A]
      </additional_context>
   </entry>
   <entry confidence_score='Medium' sources='AAPL_10K_2025_ITEM-1A'>
      <observed_epistemic_statuses>
      * PREDICTION [AAPL_10K_2025_ITEM-1A]
      </observed_epistemic_statuses>
      <consensus>
      Apple Inc. anticipates that future disruptions in component availability could impact operating results.
      </consensus>
      <additional_context>
      * Risk: inability to obtain components on commercially reasonable terms [AAPL_10K_2025_ITEM-1A]
      </additional_context>
   </entry>
</evidence_chain>

<source_key>
  AAPL_10K_2025_ITEM-1A: sec_fiscal_year=FY-2025, sec_fiscal_year_end=09-27, sec_form_type=10-K, sec_gics_sector=Information Technology, sec_gics_sub_industry=Technology Hardware, Storage &amp; Peripherals, sec_item_tag=10K-Item-1A, sec_ticker=AAPL
</source_key>
```

### `evidence_instructions`

`evidence_instructions` is returned by default when `evidence` is included. This top-level string contains guidance for how a downstream LLM should use the returned evidence to generate a grounded answer. It is separate from the evidence content itself. Set `include.evidence_instructions` to `false` to omit it.

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

Set `include.agent_context` to `true` to return `agent_context`. This top-level object is intended for direct handoff to another LLM or agent. It is a derived convenience payload, not the canonical evidence contract. Clients building custom prompts or UIs should use `evidence` and `evidence_instructions` directly.

Request `agent_context` without duplicating the raw top-level evidence fields:

```json theme={null}
{
  "query": "What supply chain risks did Apple disclose in its 10-K Item 1A filings?",
  "include": {
    "evidence": false,
    "evidence_instructions": false,
    "agent_context": true
  }
}
```

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

`content_type` is currently always `"text/markdown"`. `text` combines the evidence-use instructions with the selected evidence format. With `evidence_format: "rendered"`, the context includes rendered evidence; with `evidence_format: "xml"`, it includes XML evidence with the same public XML formatting behavior as top-level `evidence`. For `agentic_research`, the context also contains the `coverage` assessment and `source_fields` includes `"coverage"`.

### `metadata_distribution`

This abbreviated example shows two distribution metrics keyed by canonical field names. `evidence_paths` is the evidence-path count. Metric entries include `display_name` plus `values` for distributions, or `value` for text summaries. The `...` entry marks omitted metrics and is not returned literally.

```json theme={null}
{
  "metadata_distribution": {
    "evidence_paths": 8,
    "sec_ticker": {
      "display_name": "Ticker Symbols",
      "values": {
        "AAPL": 100.0
      }
    },
    "sec_form_type": {
      "display_name": "SEC Form Types",
      "values": {
        "10-K": 100.0
      }
    },
    "...": {
      "display_name": "Additional metric",
      "values": {}
    }
  }
}
```

### `metadata_dashboard`

The API returns `metadata_dashboard` as a string.

Returned JSON field:

````json theme={null}
{
  "metadata_dashboard": "\n```text\n          ### METADATA DISTRIBUTION ###\nEvidence Paths: 8\n\n              [ EVIDENCE STRENGTH ]\nHigh           ████████████░░░░░░░░  62.5%\n...\n```"
}
````

Same value, expanded:

```text theme={null}
          ### METADATA DISTRIBUTION ###
Evidence Paths: 8

              [ EVIDENCE STRENGTH ]
High           ████████████░░░░░░░░  62.5%
Medium         ███████░░░░░░░░░░░░░  37.5%
Low            ░░░░░░░░░░░░░░░░░░░░   0.0%

                [ TICKER SYMBOLS ]
AAPL           ████████████████████ 100.0%

                [ SEC FORM TYPES ]
10-K           ████████████████████ 100.0%

                 [ FISCAL YEARS ]
FY-2025        ████████████████████ 100.0%

               [ FISCAL YEAR ENDS ]
09-27          ████████████████████ 100.0%

                [ SEC ITEM TAGS ]
10K-Item-1A    ████████████████████ 100.0%

                 [ GICS SECTORS ]
Information Te ████████████████████ 100.0%

             [ GICS SUB-INDUSTRIES ]
Technology Har ████████████████████ 100.0%
```

### `summary`

```json theme={null}
{
  "summary": {
    "domain": "sandp_500",
    "mode": "research",
    "effort": "medium",
    "submitted_metadata_filters": {
      "sec_ticker": "AAPL"
    },
    "applied_metadata_filters": {
      "sec_ticker": "AAPL",
      "sec_form_type": "10-K"
    },
    "evidence_count": 8,
    "warnings": []
  }
}
```

### `coverage`

`coverage` is returned for `agentic_research`. It compares the independently required retrieval inputs with the evidence chains actually delivered to the caller.

```json theme={null}
{
  "coverage": {
    "status": "partial",
    "requirement_count": 4,
    "covered_requirement_count": 3,
    "requirements": [
      {
        "id": "q1",
        "label": "Apple FY2024 net income",
        "query": "Apple FY2024 net income",
        "status": "covered",
        "retrieved_evidence_count": 2,
        "returned_evidence_count": 1
      },
      {
        "id": "q2",
        "label": "Apple FY2024 net sales",
        "query": "Apple FY2024 net sales",
        "status": "covered",
        "retrieved_evidence_count": 1,
        "returned_evidence_count": 1
      },
      {
        "id": "q3",
        "label": "Microsoft FY2024 net income",
        "query": "Microsoft FY2024 net income",
        "status": "covered",
        "retrieved_evidence_count": 1,
        "returned_evidence_count": 1
      },
      {
        "id": "q4",
        "label": "Microsoft FY2024 net sales",
        "query": "Microsoft FY2024 net sales",
        "status": "missing",
        "retrieved_evidence_count": 0,
        "returned_evidence_count": 0
      }
    ],
    "omitted_requirements": [],
    "limitations": ["missing_evidence"]
  }
}
```

Overall status is `complete`, `partial`, `none`, or `not_assessed`. Requirement status is `covered`, `missing`, or `omitted_by_budget`. Coverage means at least one complete delivered chain is associated with each planned requirement; it does not independently verify the contents of that chain.

### `evidence_budget`

`evidence_budget` is returned whenever `evidence` or `agent_context` is requested. `requested_max_tokens` is `null` when no token cap was supplied, which is the default.

```json theme={null}
{
  "evidence_budget": {
    "requested_max_tokens": null,
    "estimator": "chars_div_4_v1",
    "estimated_tokens": 8460,
    "available_evidence_count": 12,
    "returned_evidence_count": 12,
    "truncated": false
  }
}
```

Set a strict estimated-token cap with `retrieval.max_evidence_tokens`. The estimator is `ceil(projected evidence characters / 4)` and is not provider-exact. Budgeting keeps complete chains and includes their regenerated source registry in the estimate.

### `retrieval_plan`

```json theme={null}
{
  "retrieval_plan": {
    "queries": [
      {
        "query": "Apple 10-K Item 1A supply chain risks",
        "label": "Apple supply chain risks",
        "applied_metadata_filters": {
          "sec_ticker": "AAPL",
          "sec_form_type": "10-K"
        }
      }
    ]
  }
}
```

Start with the quickstart, then use the API reference for complete request and response schemas.