Subindex

Verified Research Engine · subindex.ai · Launch App

Subindex generates, validates, and updates research tables by synthesizing hundreds of calls to Perplexity and Claude. Give it a prompt or an existing table and it returns structured, verified answers across an entire research domain — not just a single query, but a complete field of questions answered at once.

How to Access

GUI → API: The web GUIs are ideal for exploring and refining your use case. Once you know what you want, the MCP server or REST API is the better path — faster, repeatable, and fully automatable.

Table of Contents

• Get Your API Key
• Download Examples
• Quick Start: MCP
• Option A: Direct HTTP connection to Railway (recommended)
• Option B: Local install via uvx
• Option C: Smithery
• What to Ask Your Agent
• Workflows
• 1. Validate an Existing Table
• 2. Generate a Table from a Prompt
• 3. Update a Table
• 4. Fact-Check Text or Documents
• Environment Variables
• Direct REST API
• API Endpoint Reference
• MCP Prompts
• MCP Tool Reference
• Key Behaviors
• Pricing
• Links

Get Your API Key

Get your API key at [subindex.ai/account](https://subindex.ai/account). New accounts receive $20 in free credits.

Download Examples

All scripts require Python 3.10+ and pip install requests.

Or clone the full example set:

# Download all examples at once
curl -O https://subindex-storage.s3.amazonaws.com/website_downloads/examples/subindex_client.py \
     -O https://subindex-storage.s3.amazonaws.com/website_downloads/examples/01_validate_table.py \
     -O https://subindex-storage.s3.amazonaws.com/website_downloads/examples/02_generate_table.py \
     -O https://subindex-storage.s3.amazonaws.com/website_downloads/examples/03_update_table.py \
     -O https://subindex-storage.s3.amazonaws.com/website_downloads/examples/04_reference_check.py
pip install requests
export SUBINDEX_API_KEY=sbx_live_...

Quick Start: MCP

The MCP server lets any AI agent drive the full Subindex workflow autonomously — no scripting required.

Option A — Direct HTTP connection to Railway (recommended for Claude Code)

Connects directly to the hosted Subindex server over HTTP. No local install, no uvx, no package management — just one command.

Claude Code:

claude mcp add subindex \
  --transport http \
  https://mcp-server-subindex-production.up.railway.app/ \
  --header "X-Api-Key: sbx_live_your_key_here"

Via config file (.mcp.json in your repo root, or claude_desktop_config.json):

{
  "mcpServers": {
    "subindex": {
      "type": "http",
      "url": "https://mcp-server-subindex-production.up.railway.app/",
      "headers": {
        "X-Api-Key": "sbx_live_your_key_here"
      }
    }
  }
}

Why HTTP over uvx? The HTTP connection runs on Railway — always up to date, no local Python environment needed, and no version drift between the package you installed and the live server. Recommended for Claude Code and any project-level config.

Option B — Local install via uvx

Runs the server locally on your machine using uvx. Useful for Claude Desktop or offline/air-gapped environments.

Claude Code:

claude mcp add subindex uvx mcp-server-subindex \
  -e SUBINDEX_API_KEY=sbx_live_your_key_here

Claude Desktop — add to claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "subindex": {
      "command": "uvx",
      "args": ["mcp-server-subindex"],
      "env": {
        "SUBINDEX_API_KEY": "sbx_live_your_key_here"
      }
    }
  }
}

Project config (shared repo) — add .mcp.json to your repo root. Each person uses their own key; no key is committed to the repo:

{
  "mcpServers": {
    "subindex": {
      "command": "uvx",
      "args": ["mcp-server-subindex"],
      "env": {
        "SUBINDEX_API_KEY": "${SUBINDEX_API_KEY}"
      }
    }
  }
}

OpenAI Codex CLI — add to your Codex config file (~/.codex/config.toml on macOS/Linux, %USERPROFILE%\.codex\config.toml on Windows):

[mcp_servers.subindex]
command = "uvx"
args = ["mcp-server-subindex"]

[mcp_servers.subindex.env]
SUBINDEX_API_KEY = "sbx_live_your_key_here"

Then restart Codex and verify:

codex mcp list

Option C — Smithery

Smithery is an MCP registry that works with Claude Code and other MCP-compatible clients including OpenClaw.

Step 1 — Install and log in:

npx -y @smithery/cli@latest login
npx -y @smithery/cli@latest mcp add subindex/subindex --client claude-code

Step 2 — Authenticate with your API key:

Open your MCP client (e.g. Claude Code), go to /mcp, click subindex → Authenticate, and enter your Subindex API key in the Smithery page that opens.

Smithery login is a one-time step. You must log in before adding servers, or authentication will not be set up correctly.

What to Ask Your Agent

Once the MCP server is installed, describe your task in plain English. The agent drives the full workflow, pausing only when your input is genuinely needed.

Validate a table:

"Validate companies.xlsx using Subindex. Interview me about what each column means, then run the preview. If the results look good, approve the full validation."

Generate a table:

"Use Subindex to generate a table of the top 20 US hedge funds with columns: fund name, AUM, primary strategy, founding year, and HQ city. Approve the full validation when the preview looks right."

Re-run validation on the same table:

"Re-run update_table on job session_20260217_103045_abc123 to get an updated validation pass."

Fact-check a document:

"Use Subindex to fact-check this analyst report." (paste the text or share the file path)

Workflows

1. Validate an Existing Table

Minimum rows: Subindex is designed for tables with 4 or more data rows. Fewer rows may produce low-quality results.

Full flow: upload → interview → preview → refine → approve → download

upload_file(filename, file_type, file_size [, file_path])   ← omit file_path on HTTP/Railway transport; run returned curl_command instead
  → start_table_validation(session_id, s3_key, filename)
      ┌── match found (score ≥ 0.85) → [preview auto-queued; response has preview_queued=true + job_id]
      └── no match → interview auto-started
            → wait_for_conversation / poll get_conversation
              → send_conversation_reply  (if AI asks questions)
              → [interview complete → preview auto-queued]

  → wait_for_job(job_id or session_id)  ← blocks until preview_complete
      → [optional] refine_config(conv_id, session_id, instructions)
      → approve_validation(job_id, cost_usd)
      → wait_for_job(job_id)            ← blocks until completed
      → get_results(job_id)

Key behavior: The preview is always auto-queued — after the interview finishes (trigger_config_generation=true), or when a config match is found (match_score ≥ 0.85, response includes preview_queued: true and job_id). Call wait_for_job(session_id) directly in all cases (see Config reuse).

Upload interview auto-approval: The interview may auto-approve in a single turn. If the conversation response has user_reply_needed: false and status: approved, proceed to wait_for_job(session_id) immediately — no reply is needed, even if the AI's message appears to ask for confirmation.

Skip the interview with `instructions` (fire-and-forget config generation):

Pass instructions to start_table_validation to bypass the interactive interview. The AI reads the table structure + your instructions and generates a config directly, then auto-triggers the preview — no clarifying questions needed.

start_table_validation(session_id, s3_key, filename,
  instructions="This table lists hedge funds. Validate AUM, strategy, and HQ city. Use Bloomberg and SEC filings.")
  → response includes instructions_mode=true
  → wait_for_job(session_id)          ← config generation + preview tracked automatically
  → approve_validation(job_id, cost_usd)
  → wait_for_job(job_id)
  → get_results(job_id)

Cost gate: Config generation and the 3-row preview are free. Full validation is charged at approve_validation — you always see the cost estimate at preview_complete before anything is billed. If your balance is insufficient, approve_validation returns an insufficient_balance error with the required amount.

Refine the config before approving by calling refine_config. This adjusts how columns are validated (sources, strictness, interpretation) — it cannot add or remove columns:

refine_config(conversation_id, session_id,
  "Use SEC filings as the primary source for revenue. Require exact match for ticker symbols.")

A new preview runs automatically after refinement.

Python script: examples/01_validate_table.py

export SUBINDEX_API_KEY=sbx_live_...
python examples/01_validate_table.py companies.xlsx
python examples/01_validate_table.py companies.xlsx --refine "Add LinkedIn URL column"

 Fire-and-forget: provide instructions to skip the interview entirely
python examples/01_validate_table.py companies.xlsx \
    --instructions "This table lists hedge funds. Validate AUM, strategy, and HQ city."

Which mode to use: Always try file_path first. If the server can read the file (stdio/uvx transport), upload completes in one step. If you get "File not found" (HTTP/Railway transport — server is remote), call again without file_path to receive a presigned S3 URL and a ready-to-run curl_command. The two-step path requires shell access to run curl; Claude Desktop users should use the uvx transport so file_path works.

2. Generate a Table from a Prompt

Describe the table you want — rows, columns, scope — and Subindex builds and validates it from scratch. Designed for tables with 4 or more rows.

start_table_maker("Top 20 US biotech companies: name, ticker, market cap, lead drug, phase")
  → wait_for_conversation / poll get_conversation
    → send_conversation_reply  (if AI asks clarifying questions)
    → [table builds → preview auto-queued]

  → wait_for_job(session_id)          ← spans table-maker + preview phases
    → approve_validation(job_id, cost_usd)
    → wait_for_job(job_id)
    → get_results(job_id)

Auto-approve: The agent can auto-approve the preview and proceed to full validation without human intervention. The preview table is included inline in the preview_complete response.

Cost: ~$0.05/cell (standard), up to ~$0.25/cell (advanced). $2 minimum per run.

Skip confirmation with `auto_start=True` (fire-and-forget generation):

Pass auto_start=True to skip the AI's clarifying questions and structure-confirmation step. The AI generates the table immediately from the message alone. Use when your message fully describes the desired table.

start_table_maker(
  "Top 20 US hedge funds: fund name, AUM, primary strategy, founding year, HQ city",
  auto_start=True)
  → wait_for_conversation(conversation_id, session_id)
      ← returns trigger_execution=true on first response (no Q&A)
  → wait_for_job(session_id)          ← table building + preview
  → approve_validation(job_id, cost_usd)
  → wait_for_job(job_id)
  → get_results(job_id)

Why `wait_for_conversation` with `auto_start=True`? Even though there is no Q&A, wait_for_conversation is still required — it returns trigger_execution: true in a single blocking call (no reply needed), signaling that the table-maker has started. Calling wait_for_job before this call returns would be premature, as the table-maker may not have been triggered yet.

Cost gate: Table building and the 3-row preview are free. Full validation is charged at approve_validation — you always see the cost estimate at preview_complete before anything is billed. If your balance is insufficient, approve_validation returns an insufficient_balance error with the required amount.

Python script: examples/02_generate_table.py

python examples/02_generate_table.py "Top 10 US hedge funds: fund name, AUM, strategy, HQ city"
python examples/02_generate_table.py --prompt-file my_spec.txt

 Fire-and-forget: skip clarifying Q&A and generate immediately from the prompt
python examples/02_generate_table.py --auto-start "Top 10 US hedge funds: fund name, AUM, strategy, HQ city"

3. Update a Table (Re-run Validation Pass)

Re-run validation on a completed job — no re-upload or manual edits needed. The table iterates automatically, re-validating the same data with the same config to pick up any changes in source data.

If you want to incorporate manual edits to the output file, re-upload the edited file via upload_file + start_table_validation — a matching config will be found automatically (score ≥ 0.85).

update_table(source_job_id)           ← re-validates existing enriched output
  → wait_for_job(new_job_id)          ← blocks until preview_complete
    → approve_validation(new_job_id, cost_usd)
    → wait_for_job(new_job_id)
    → get_results(new_job_id)

Python script: examples/03_update_table.py

python examples/03_update_table.py session_20260217_103045_abc123
python examples/03_update_table.py session_20260217_103045_abc123 --version 2

4. Fact-Check Text or Documents (Chex)

Submit any text, report, or document. Subindex checks each factual claim against authoritative sources and returns the same output format as standard table validation: an Excel (XLSX) file, an interactive viewer URL, and a metadata JSON.

Minimum claims: Subindex is designed for text with 4 or more factual claims. Fewer claims may produce low-quality results.

start_reference_check(text="...")           ← inline text (or auto_approve=True to skip the gate)
  or
upload_file(filename, "pdf", file_size [, file_path])   ← upload PDF/document first
  → start_reference_check(s3_key=s3_key)

→ wait_for_job(job_id)                ← spans extraction + 3-row preview; stops at preview_complete
  → preview_table (3 validated sample claims) + cost_estimate shown in response
  → approve_validation(job_id, approved_cost_usd=X)   ← triggers Phase 2
  → wait_for_job(job_id)              ← waits for completed
  → get_results(job_id)               ← download_url (XLSX) + interactive_viewer_url + metadata_url

Three-phase flow: Phase 1 (claim extraction, free) runs automatically, then a 3-row preview validates sample claims (free, auto-triggered). Both phases are tracked by a single wait_for_job call that stops at status=preview_complete. Review preview_table (3 validated sample claims with support level and citations) and cost_estimate, then call approve_validation to start Phase 2 (full validation, charged). Pass auto_approve=True to skip the gate and run straight through to completed.

Progress tracking: get_job_messages returns empty during claim extraction (Phase 1). Progress messages are available during the preview validation phase. wait_for_job handles both phases automatically.

Output: Excel (XLSX) file with per-claim rows. Support levels: SUPPORTED / PARTIAL / UNSUPPORTED / UNVERIFIABLE. Share interactive_viewer_url with human stakeholders — it renders sources and confidence scores in a clean UI.

Python script: examples/04_reference_check.py | Sample output: sample_outputs/reference_check_output.json

# Fact-check inline text
python examples/04_reference_check.py --text "Bitcoin was created by Satoshi Nakamoto in 2009."

# Fact-check a PDF
python examples/04_reference_check.py --file analyst_report.pdf

# Fact-check multiple documents concatenated
cat doc1.txt doc2.txt | python examples/04_reference_check.py --stdin

--stdin: Concatenates all piped content as a single inline text payload. All claims are attributed to the combined document.

Environment Variables

Direct REST API

All tools in the MCP server are thin wrappers over the REST API. You can call it directly from any language.

Base URL: https://api.subindex.ai/v1

Auth: Authorization: Bearer sbx_live_your_key_here

Response envelope:

{
  "success": true,
  "data": { ... },
  "meta": { "request_id": "...", "timestamp": "..." }
}

Python client (minimal)

import os, requests

BASE_URL = "https://api.subindex.ai/v1"
HEADERS  = {"Authorization": f"Bearer {os.environ['SUBINDEX_API_KEY']}"}

def api_get(path, **kwargs):
    r = requests.get(f"{BASE_URL}{path}", headers=HEADERS, **kwargs)
    r.raise_for_status()
    return r.json()["data"]

def api_post(path, **kwargs):
    r = requests.post(f"{BASE_URL}{path}", headers=HEADERS, **kwargs)
    r.raise_for_status()
    return r.json()["data"]

A full standalone client module is in examples/subindex_client.py.

API Endpoint Reference

Uploads

Presigned upload request:

{
  "filename": "companies.xlsx",
  "file_size": 2048000,
  "file_type": "excel",
  "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
}

Content types: excel → .xlsx, csv → .csv, pdf → .pdf

Confirm upload request (optional fields):

{
  "session_id": "session_20260305_...",
  "s3_key": "results/.../file.xlsx",
  "filename": "companies.xlsx",
  "instructions": "Validate AUM, strategy, and HQ city. Use Bloomberg and SEC filings as sources.",
  "config_id": "session_20260217_103045_abc123_config_v1_..."
}

instructions — if provided, bypasses the interactive upload interview. The AI generates the config directly from the table structure + instructions. Response includes instructions_mode: true and conversation_id. Use wait_for_job(session_id) to track progress — do NOT poll the conversation.

config_id — if provided, skips matching and the interview entirely. The specified config is applied immediately and the preview is auto-queued. Response includes preview_queued: true and job_id. Use wait_for_job(job_id) to track progress. The configuration_id for any completed job is returned by GET /jobs/{id}/results under job_info.configuration_id.

Conversations

Table Maker request body:

{
  "message": "Top 20 US hedge funds: fund name, AUM, primary strategy, founding year, HQ city",
  "auto_start": true
}

auto_start — if true, the AI skips clarifying questions and the structure-confirmation step, proceeding directly to table generation. The first get_conversation response will have trigger_execution: true. Use when your message fully describes the desired table.

Jobs

Job status values:

Account

MCP Prompts

Three built-in prompts act as workflow starters — select them from the prompt picker in your MCP client (Claude Code: / menu; Claude Desktop: the prompt icon) and fill in the arguments.

MCP Tool Reference

Every tool response includes a _guidance block with a plain-English summary and the exact next tool call(s) — enabling fully autonomous agent workflows.

Key Behaviors

Auto-queued preview

The preview is automatically queued in all three paths after start_table_validation:

To reuse a config from a different session, pass config_id to start_table_validation — the preview will be auto-queued immediately.

Config reuse

If start_table_validation returns match_score ≥ 0.85, the preview is automatically queued using the matched config. The response includes preview_queued: true and job_id — call wait_for_job(job_id) directly, no interview needed.

The configuration_id from any completed job's get_results response can be reused on future uploads of similar tables.

Cost confirmation gate

approve_validation requires approved_cost_usd matching the preview estimate. This prevents surprise charges. The estimate is in the preview_complete job status response under cost_estimate.estimated_total_cost_usd.

This gate applies regardless of whether instructions or auto_start was used — both only skip the interview/confirmation conversation, not the cost approval step. If your balance is insufficient when approve_validation is called, the API returns:

{ "error": "insufficient_balance", "required_usd": 4.20, "current_balance_usd": 1.50 }

Fire-and-forget shortcuts

Two optional flags let fully automated pipelines skip interactive steps:

These flags use different terminal signals: instructions= (a config-gen flow) causes trigger_config_generation: true on the conversation response; auto_start=True (a table-maker flow) causes trigger_execution: true. Both skip interactive Q&A but produce different fields — do not wait for trigger_execution when using the instructions= upload path. The preview_complete cost gate and approve_validation still apply.

Consuming results: humans vs AI agents

Output files generated per run:

get_results returns:

Recommended AI agent workflow:

1. At preview_complete: read the inline preview_table (markdown, 3 rows) from GET /jobs/{id} to survey the table structure and spot-check values. The AI agent can review this inline table and call approve_validation directly — no human approval step is required.
2. After full validation: fetch results.metadata_url → table_metadata.json. This contains every validated row.
3. Use rows[].row_key (stable SHA-256) to cross-reference rows between the markdown summary and the detailed JSON.
4. Per-cell fields in table_metadata.json:

• cells[col].value — validated value (legacy files may use full_value)
• cells[col].confidence — HIGH / MEDIUM / LOW / ID
• cells[col].comment.validator_explanation — reasoning
• cells[col].comment.key_citation — top authoritative source
• cells[col].comment.sources[] — all sources with url and snippet

Pricing

Credits are prepaid. Get $20 free at [subindex.ai/account](https://subindex.ai/account).

Standard validation is used for most tables. Advanced validation is selected automatically when the table requires more sophisticated reasoning (e.g., scientific data, complex financial metrics, or cells with high ambiguity).

Links

• MCP server (HTTP, recommended): claude mcp add subindex --transport http https://mcp-server-subindex-production.up.railway.app/ --header "X-Api-Key: sbx_live_..." — no install needed
• MCP server (PyPI/uvx): uvx mcp-server-subindex — for Claude Desktop or offline use
• Source: github.com/EliyahuAI/mcp-server-subindex
• Documentation: subindex.ai/mcp
• API reference: subindex.ai/api
• Account & credits: subindex.ai/account