Quickstart

With an API key and any HTTPS client, you can query evidence from a knowledge base in a single request. This quickstart uses S&P 500 SEC filings as the example. 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. Select Your Knowledge Base and API Key

The REST base URL is https://api.ai-baseline.dev/{org}/{base}/v2. Set it to the knowledge base you want to query and use an API key with access to that base. For the S&P 500 example:

export AI_BASELINE_API_KEY="your-api-key"
export AI_BASELINE_BASE_URL="https://api.ai-baseline.dev/baseline/sandp500/v2"

Every request sends this key in the X-API-Key header. The URL selects the knowledge base; the key authorizes access to it. For another base, change the URL and ask questions about its material. See knowledge-base selection.

2. Request Agent Context

For agent integrations, request agent_context from the /query endpoint:

curl -X POST "$AI_BASELINE_BASE_URL/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:

{
  "request_id": "req_...",
  "evidence": "<source_registry>\n  ...\n</source_registry>\n\n<evidence_chain relevance_score=\"9\">\n  ...\n</evidence_chain>",
  "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": {
    "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:

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. For citation-enabled connections, follow the inline citation guide: copy supplied URLs verbatim and cite only the records contributing to each claim. Links open the complete retained document at the cited location and expire after an absolute lifetime (30 minutes by default). Missing links do not invalidate evidence.

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.

{
  "request_id": "req_...",
  "evidence": "<source_registry>\n  ...\n</source_registry>\n\n<evidence_chain relevance_score=\"9\">\n  ...\n</evidence_chain>",
  "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.",
  "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:

{
  "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 on the same base URL to inspect the selected knowledge base’s supported metadata-filter fields, operators, limits, and optional categorical values. The SEC fields below apply to the S&P 500 example; discover the fields for each base before reusing filters. 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.

curl "$AI_BASELINE_BASE_URL/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.

curl -X POST "$AI_BASELINE_BASE_URL/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.

Get Started

Connect

Guides

API Reference

1. Select Your Knowledge Base and API Key

2. Request Agent Context

3. Hand It to Your Agent

4. Default Evidence Response

5. Discover Metadata Filters

6. Send a Query with Metadata Filters

​1. Select Your Knowledge Base and API Key

​2. Request Agent Context

​3. Hand It to Your Agent

​4. Default Evidence Response

​5. Discover Metadata Filters

​6. Send a Query with Metadata Filters

1. Select Your Knowledge Base and API Key

2. Request Agent Context

3. Hand It to Your Agent

4. Default Evidence Response

5. Discover Metadata Filters

6. Send a Query with Metadata Filters