Resources & API Documentation

Integration Reference

Install from PyPI, score your first filing, and dive into guides for every integration surface.

Python 3.11+ · Apache-2.0 · PyPI · ReadTheDocs

GET STARTED VIEW USE CASES

HTTP API Endpoints

GET

/v1/company/{ticker}/disclosure-matrix

Filing-level component scores and overall disclosure risk score for one ticker.

Field	Type	Required
fiscal_year	integer	yes
form_type	string	yes
quarter	integer	no
compare	string	no
tier	string	no
scoring_model_version	string	no

POST

/v1/panel/disclosure-matrix

Batch-screen up to 25 tickers. Per-ticker errors collected; request does not fail-fast.

Field	Type	Required
tickers	string[]	yes
fiscal_year	integer	yes
form_type	string	yes
scoring_model_version	string	no

GET

/v1/company/{ticker}/disclosure-metrics

Raw text metrics, boolean risk flags, and section diffs without score aggregation.

Field	Type	Required
fiscal_year	integer	yes
form_type	string	yes
quarter	integer	no
compare	string	no
sections	string	no

Full API reference ↓ · HTTP guide on ReadTheDocs ↗

Get Started in Three Steps

Quickstart

New here? First Successful Run ↗ scores local HTML with no EDGAR setup.

Step 1: Install

pip install "disclosure-alpha"

For HTTP API and MCP:

pip install "disclosure-alpha[api,mcp]"

Full installation guide on ReadTheDocs ↗

Step 2: SEC User-Agent

Required for --ticker / EDGAR commands. Skip for local --html scoring.

export SEC_USER_AGENT="YourName [email protected]"

SEC EDGAR details on ReadTheDocs ↗

Step 3: Score a filing

CLI (local HTML, no network):

disclosure-alpha score --html tests/fixtures/sample_10k.html --form 10-K \
  | jq '{overall: .scores.overall_disclosure_risk_score, coverage: .scores.score_coverage_ratio}'

CLI (by ticker, requires EDGAR):

disclosure-alpha score --ticker AAPL --fiscal-year 2025 --form 10-K \
  | jq '.scores.overall_disclosure_risk_score'

Python:

from disclosure_alpha import score_filing_ticker
result = score_filing_ticker("AAPL", 2025, form_type="10-K")
print(result.scores.overall_disclosure_risk_score)

You should see a numeric score between 0 and 100. Lower values indicate lower disclosure risk on the component scale.

Understanding scores on ReadTheDocs ↗

Installation

Install Options

Extra	Purpose	Command
(base)	CLI + Python SDK	pip install "disclosure-alpha"
api	HTTP API server	pip install "disclosure-alpha[api]"
mcp	MCP servers for Cursor / Claude	pip install "disclosure-alpha[mcp]"
semantic	MiniLM embeddings (default uses TF-IDF)	pip install "disclosure-alpha[semantic]"
api,mcp	Full stack	pip install "disclosure-alpha[api,mcp]"

Pin a release:

pip install "disclosure-alpha==1.3.0[api,mcp]"

Versioning and reproducibility ↗

Verify entry points:

disclosure-alpha --help
disclosure-alpha-api --help          # requires [api]
disclosure-alpha-mcp-analyst --help  # requires [mcp]

Documentation

Find the right guide

Pick the guide that matches what you're trying to do.

Get started

First successful run

Score local HTML with no EDGAR setup — prove it works in five minutes.

First successful run →

Score in terminal

Run your first disclosure risk score from the CLI in minutes.

Quickstart →

Build a screener

Batch score up to 25 tickers via the HTTP panel API.

HTTP API reference →

Score in OpenBB Workspace

Connect Disclosure Alpha as a custom backend and run the Company widget.

OpenBB integration →

Understand the product

Understand the numbers

What each score means and how risk bands are defined.

Understanding scores →

See methodology

How we parse, measure, and combine disclosure signals.

Methodology overview →

Know what we claim

Scope, evidence, and known limitations of the scores.

Scope and claims →

Go deeper

Wire an agent

Connect Disclosure Alpha tools to MCP-compatible agents.

MCP setup →

Copy-paste examples

Committed JSON fixtures and Postman collections for integrators.

Examples gallery →

Troubleshoot

FAQ, common errors, and SEC EDGAR access setup.

On-site FAQ →

RTD troubleshooting

Installation errors and SEC EDGAR setup on ReadTheDocs.

FAQ on ReadTheDocs →

Questions about methodology or supported claims? On-site FAQ · Need exhaustive API reference or troubleshooting? Full documentation on ReadTheDocs ↗

Surfaces

Integration Surfaces

Deterministic Pipeline → CLIPython SDKHTTP APIOpenBB WorkspaceMCP AnalystMCP Builder

CLI

(base)

disclosure-alpha

Terminal workflows and local HTML scoring.

CLI guide →

Python SDK

(base)

import disclosure_alpha

Custom pipelines and Jupyter notebooks.

Python quickstart →

HTTP API

[api]

disclosure-alpha-api

REST services, dashboards, and screeners.

API reference →

OpenBB Workspace

[api,mcp]

disclosure-alpha-api

Disclosure Company widget, Copilot prompts, and in-app MCP in OpenBB.

OpenBB setup →

MCP Analyst

[mcp]

disclosure-alpha-mcp-analyst

Ticker + fiscal year tools in Cursor / Claude.

MCP setup →

MCP Builder

[mcp]

disclosure-alpha-mcp-builder

Raw HTML agent pipelines with full tool access.

MCP setup →

Reference

HTTP API Quick Reference

▶ All endpoints

Start server:

export SEC_USER_AGENT="YourName [email protected]"
disclosure-alpha-api
# listens on 0.0.0.0:8000

Product	Method	Path	Use when…
Health	GET	/health	Checking server before batch jobs
Filing Index	GET	/v1/company/{ticker}/filings	Listing available filings
Section Extractor	GET	/v1/company/{ticker}/sections	Debugging extraction
Disclosure Analytics	GET	/v1/company/{ticker}/disclosure-metrics	Raw metrics, flags, diffs
Disclosure Risk Score	GET	/v1/company/{ticker}/disclosure-matrix	Component scores for one ticker
Risk Flags	GET	/v1/company/{ticker}/disclosure-flags	Boolean risk events only
Filing Changes	GET	/v1/company/{ticker}/disclosure-changes	YoY diff details
Panel Screener	POST	/v1/panel/disclosure-matrix	Batch up to 25 tickers

Matrix-only tier param: lite (headline only), standard (components + metrics), analyst (full breakdown + provenance). Default scoring model: deterministic_scoring_v2.

The local API server has no built-in authentication — do not expose publicly without your own gateway. Production notes ↗

HTTP API reference HTTP guide on ReadTheDocs ↗ OpenAPI reference ↗

Agents

MCP setup

Install:

pip install "disclosure-alpha[mcp]"

Config snippet (Analyst bundle):

{
  "mcpServers": {
    "disclosure-alpha": {
      "command": "disclosure-alpha-mcp-analyst",
      "env": {
        "SEC_USER_AGENT": "YourName [email protected]"
      }
    }
  }
}

If Cursor cannot find the command, use the full venv path: "/path/to/.venv/bin/disclosure-alpha-mcp-analyst"

Full MCP guide on ReadTheDocs ↗

Collections

API Collections

disclosure-alpha-discovery.postman_collection.json: health + filings
disclosure-alpha-analytics.postman_collection.json: sections + metrics
disclosure-alpha-scores.postman_collection.json: disclosure matrix scores
disclosure-alpha-compliance.postman_collection.json: flags + changes
disclosure-alpha-panel.postman_collection.json: panel POST
disclosure-alpha-api.postman_collection.json: full API

Postman collections on GitHub →

Open Source

GitHub	alwank/disclosure-alpha
PyPI	disclosure-alpha
License	Apache-2.0

Research-oriented open-source software. See CONTRIBUTING.md for development setup.

Ready to score your first filing?

Install from PyPI, set your SEC User-Agent, and run the quickstart.

GET STARTED OPEN GITHUB