AI Baseline

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

https://api-beta.ai-baseline.xyz/v2/sandp_500/

Every request must include your API key:

-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

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:

Section	Contains
`evidence`	Grounding text selected by `include.evidence_format`; rendered evidence includes a source-key footer, while XML evidence omits it.
`evidence_instructions`	Guidance for downstream LLMs on how to use the returned evidence. Returned by default when evidence is included.
`agent_context`	Derived Markdown context block for direct handoff to another LLM or agent.
`metadata_distribution`	Metadata distribution keyed by canonical field names, with readable display names and metric values inside each entry.
`metadata_dashboard`	Rendered ASCII summary of the metadata distribution.
`summary`	Selected mode, effort, filters, warnings, and evidence-path count.
`coverage`	Task-aware requirement coverage for `agentic_research`, including missing or budget-omitted inputs.
`evidence_budget`	Deterministic evidence token estimate, optional requested cap, available and returned chain counts, and truncation status.
`retrieval_plan`	Retrieval query plan for `agentic_research`.

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`

{
  "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:

{
  "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:

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

{
  "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:

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

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

{
  "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:

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

Same value, expanded:

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

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

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

{
  "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`

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

Get Started

Guides

API Reference

Base URL

Endpoints

Minimal Query

Response Shape

Example Response Sections

`request_id`

`evidence`

`evidence_instructions`

`agent_context`

`metadata_distribution`

`metadata_dashboard`

`summary`

`coverage`

`evidence_budget`

`retrieval_plan`

​Base URL

​Endpoints

​Minimal Query

​Response Shape

​Example Response Sections

​request_id

​evidence

​evidence_instructions

​agent_context

​metadata_distribution

​metadata_dashboard

​summary

​coverage

​evidence_budget

​retrieval_plan

Base URL

Endpoints

Minimal Query

Response Shape

Example Response Sections

`request_id`

`evidence`

`evidence_instructions`

`agent_context`

`metadata_distribution`

`metadata_dashboard`

`summary`

`coverage`

`evidence_budget`

`retrieval_plan`