AI Baseline API

API for querying SEC filing evidence with grounded answers, evidence, 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, ready-to-feed agent context, or opt-in grounded answers.

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, and summary by default. To generate an answer, set include.answer to true.

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	Domain-owned 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.
retrieval_plan	Retrieval query plan for agentic_research.
answer	Generated answer grounded in retrieved filing evidence. Returned when include.answer is true.
analysis	Generated analysis of the retrieved sources and metadata. Returned when include.analysis is true.

Example Response Sections

Responses always include request_id. By default, /query returns rendered evidence, evidence_instructions, 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 domain-owned 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 domain-owned 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. source_fields lists the canonical response fields used to construct the payload.

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": []
  }
}

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"
        }
      }
    ]
  }
}

answer

answer is returned only when include.answer is true.

{
  "answer": {
    "text": "Apple disclosed supply chain risks related to supplier concentration, manufacturing disruptions, logistics constraints, and component availability."
  }
}

analysis

analysis is returned only when include.analysis is true.

{
  "analysis": {
    "text": "The retrieved evidence is concentrated in Apple's 10-K risk-factor sections, with repeated references to third-party suppliers and manufacturing dependencies."
  }
}

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