HTTP API Guide¶

REST endpoints for filings, sections, metrics, scores, flags, changes, and batch panel screening.

Audience: Backend developers integrating the REST API. Before you start: pip install "disclosure-alpha[api]" (see Installation) and SEC EDGAR Setup.

Typical journeys¶

• Dashboard headline — GET /v1/company/{ticker}/disclosure-matrix?tier=lite for overall_disclosure_risk_score only

• Research workflow — tier=standard for overall + component scores with metrics attached

• Audit / debugging — tier=analyst with include=metrics,provenance for full score breakdown and input provenance

Interpret matrix JSON using Understanding Scores.

Annotated matrix response¶

Scores block from the committed minimal 10-K fixture (same shape as /disclosure-matrix):

    "extraction_confs": [
      0.35,
      0.35
    ],
    "diff_confs": [
      0.2,
      0.2
    ],
    "extraction_warnings": [],
    "required_sections_present": true,
    "has_prior": false
  },
  "scores": {
    "overall_disclosure_risk_score": 33.159052,
    "score_coverage_ratio": 0.7778,
    "confidence_score": 0.3426,
    "missing_components": [
      "disclosure_change_score",
      "event_severity_score"
    ],
    "components": {
      "risk_factor_intensity_score": 60.0,

• overall_disclosure_risk_score — headline 0–100 for sorting and dashboards

• score_coverage_ratio / missing_components — data quality before comparing tickers

• components — ten computed scores (nine headline-weighted plus specificity_quality_score); null means not computed (not zero)

With tier=lite, only the headline field is returned. With tier=analyst, add metrics and provenance arrays.

Endpoint map¶

Shared query params on ticker routes: fiscal_year, form_type, quarter (10-Q), compare (prior|none), sections (comma-separated filter).

Start the server¶

export SEC_USER_AGENT="YourName your@email.com"
disclosure-alpha-api
# listens on 0.0.0.0:8000 (override with HOST / PORT env)

Response tiers (matrix only)¶

Optional tier query param overrides include and fields:

Shared query params (sections, disclosure-metrics, disclosure-matrix):

Matrix-only params:

Example requests¶

curl "http://localhost:8000/v1/company/AAPL/disclosure-matrix?fiscal_year=2025&form_type=10-K"
curl "http://localhost:8000/v1/company/AAPL/disclosure-matrix?fiscal_year=2025&include="
curl "http://localhost:8000/v1/company/AAPL/disclosure-metrics?fiscal_year=2025&form_type=10-K&compare=none"
curl "http://localhost:8000/v1/company/AAPL/sections?fiscal_year=2025&sections=item_1a_risk_factors"

Panel batch semantics¶

• Max 25 tickers per request (422 if exceeded).

• Per-ticker errors collected (status: error); request does not fail-fast.

• Optional scoring_model_version in request body (default deterministic_scoring_v2; legacy deterministic_scoring_v1).

Sample panel response: Examples Gallery.

Postman collections¶

Import-ready collections and response examples: Examples Gallery.

OpenAPI¶

With disclosure-alpha-api running:

• Swagger UI: http://localhost:8000/docs

• OpenAPI JSON: http://localhost:8000/openapi.json

Endpoint reference (generated from schema): HTTP Endpoint Reference. Status codes: HTTP API (OpenAPI).

HTTP errors¶

See FAQ and Troubleshooting.

Related¶

• Understanding Scores

• Choose Your Surface

• HTTP Endpoint Reference

• HTTP API (OpenAPI)

• Production Notes

• Examples Gallery

• Section Taxonomy

• Environment Variables

• Deterministic Scoring Overview