AI Baseline

Use the AI Baseline API to ask natural-language questions about a knowledge base and receive rendered evidence, metadata summaries, dashboards, or ready-to-feed agent context. Each knowledge base belongs to an organization and uses a domain that defines how its material is interpreted and queried. These docs use the S&P 500 SEC filings knowledge base as a worked example. The same API serves other knowledge bases with their own data, domain, and access permissions. Start with organizations, knowledge bases, and domains to understand how they fit together.

Base URL

https://api.ai-baseline.dev/{org}/{base}/v2

org identifies the owning organization; base identifies the knowledge base within it. v2 selects the REST API contract. Use the exact identifiers supplied for your knowledge base. For the S&P 500 example, the organization is baseline and the knowledge base is sandp500:

https://api.ai-baseline.dev/baseline/sandp500/v2

Every request must include your API key:

-H "X-API-Key: $AI_BASELINE_API_KEY"

Endpoints

Endpoint	Purpose
`POST /query`	Query evidence from the selected knowledge base and return the requested response sections.
`GET /metadata-filters`	Discover metadata-filter fields and operators for the selected knowledge base.
`GET /corpus-overview`	Describe the selected knowledge base’s available material and coverage.

Append each endpoint to the base URL above. Corpus overview describes inventory and coverage; use query evidence to support factual answers.

Minimal Query

curl -X POST https://api.ai-baseline.dev/baseline/sandp500/v2/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`; both formats retain source metadata once and the same per-entry citation records.
`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`.

Response Privacy

Public query responses use a strict field allowlist. They never include internal retrieval diagnostics, graph entry points, evidence-chain diagnostic summaries, retrieval metadata, or resolved internal retrieval parameters. This applies to basic, research, and agentic_research responses, including streaming and error branches. This response contraction is a security and privacy hardening change. The request-side retrieval.max_evidence and retrieval.max_evidence_tokens controls remain supported; there is no response-side retrieval object.

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. Both evidence formats keep document metadata once in <source_registry> and use the same citation projection. Follow the inline citation guide for contributing-record attribution, short-link lifetime and missing-link behavior. 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>. Abbreviated JSON envelope:

{
  "evidence": "<source_registry>...</source_registry>\n<evidence_chain id=\"chain_1\" relevance_score=\"9\">...</evidence_chain>"
}

The expanded example below follows the Apple supply-chain question above. It illustrates evidence drawn from Apple’s 2024 and 2025 10-K Item 1A disclosures. Chain, entry and citation IDs are shortened for readability; actual responses use stable identifiers. The citation URLs are illustrative and are not working links.

<source_registry>
  <source id="AAPL_10K_2025_ITEM-1A" type="10-K" date="2025-10-31"
    title="Apple Inc. 2025 Form 10-K, Item 1A: Risk Factors"
    sec_ticker="AAPL" sec_fiscal_year="FY-2025" sec_item_tag="10K-Item-1A" />
  <source id="AAPL_10K_2024_ITEM-1A" type="10-K" date="2024-11-01"
    title="Apple Inc. 2024 Form 10-K, Item 1A: Risk Factors"
    sec_ticker="AAPL" sec_fiscal_year="FY-2024" sec_item_tag="10K-Item-1A" />
</source_registry>
<evidence_chain id="chain_1" relevance_score="9">
  <entry id="entry_1" confidence_score="High"
    sources="AAPL_10K_2025_ITEM-1A AAPL_10K_2024_ITEM-1A">
    <citations>
      <citation id="c1" source="AAPL_10K_2025_ITEM-1A" url="https://basl.ink/a7Km2Qx" />
      <citation id="c2" source="AAPL_10K_2025_ITEM-1A" url="https://basl.ink/b8Ln3Ry" />
      <citation id="c3" source="AAPL_10K_2024_ITEM-1A" url="https://basl.ink/c9Mo4Sz" />
    </citations>
    <observed_epistemic_statuses>
      <status citations="c1 c3" sources="AAPL_10K_2025_ITEM-1A AAPL_10K_2024_ITEM-1A">FACT</status>
    </observed_epistemic_statuses>
    <consensus citations="c1 c3">
      Apple outsources manufacturing and logistics, reducing its direct control
      over production and distribution.
    </consensus>
    <additional_context>
      <item citations="c2" sources="AAPL_10K_2025_ITEM-1A">
        Apple relies on partners primarily located in Asia for final assembly
        of substantially all its hardware products.
      </item>
    </additional_context>
  </entry>
</evidence_chain>

The consensus cites c1 and c3, passages from the 2025 and 2024 filings that support the shared claim. The additional-context item cites only c2, the passage from the 2025 filing supporting the assembly detail. Two passages from the same filing share a source ID but have separate citation IDs and URLs. Each supplied URL opens the retained document at its cited location; document metadata stays in the registry.

`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. Follow each claim’s contributing citation references and copy the supplied URLs verbatim into inline Markdown links with exact source labels. State missing evidence or unavailable links honestly."
}

`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 identifies the selected knowledge base’s domain. In this example, sandp_500 is the domain ID, while sandp500 is the knowledge-base ID in the URL. Several knowledge bases can use the same domain without sharing data or permissions.

{
  "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. To use AI Baseline in a chat application, follow Connect with Claude, Connect with ChatGPT, or Connect with MCP.

Get Started

Connect

Guides

API Reference

Base URL

Endpoints

Minimal Query

Response Shape

Response Privacy

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

​Response Privacy

​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

Response Privacy

Example Response Sections

`request_id`

`evidence`

`evidence_instructions`

`agent_context`

`metadata_distribution`

`metadata_dashboard`

`summary`

`coverage`

`evidence_budget`

`retrieval_plan`