DEVELOPERS

A clean REST API on top of every filing.

Everything you see on DEHY is exposed at /api/v1. Bearer-authenticated, JSON, no SDK required. Designed to drop into your existing Bloomberg replacement, Slack alerting, or research notebook.

Authentication

Mint a key from your account settings. Pass it as a bearer token:

curl https://dehy.io/api/v1/filings \
  -H "Authorization: Bearer dh_live_..."

Keys are SHA-256 hashed at rest. You see the secret part exactly once on creation; after that, only the four-character prefix. Lose it and you mint a new one.

Rate limits

60 requests / minute on the free tier, 1,200 / minute on Studio. The current ceiling is echoed in the X-RateLimit-Limit header on every response. Hit it and you get a 429 with Retry-After: 60.

Endpoints

`GET /api/v1/filings`

Recent filings with attached DEHY Score where computed. Returns up to 100 per request; default 50.

{
  "filings": [
    {
      "accession": "0001127602-26-...",
      "formType": "4",
      "filedAt": "2026-05-24T18:42:11Z",
      "issuer": { "cik": "1321655", "name": "Palantir...", "ticker": "PLTR" },
      "dehyScore": {
        "score": 67,
        "direction": "sell",
        "algoVersion": "2026-05-01.v1",
        "breakdown": { ... }
      }
    }
  ]
}

`GET /api/v1/filings/:accession`

Single filing — header, issuer, reporter, full transaction array, attached score.

`GET /api/v1/filings/:accession/diff`

AI-annotated section diffs for long-form filings (10-Q / 10-K). Empty array if not yet generated. Includes per-section change counts, the model used, and a structured annotation.

`GET /api/v1/scores`

Top DEHY Scores across all ingested Form 4s. Useful as a daily signal feed without polling the full filings index.

`GET /api/v1/cot/markets`

Latest CFTC Commitments of Traders snapshot (Legacy Futures-Only), commercial / non-commercial breakdown plus week-over-week change.

`GET /api/v1/cot/markets/:code/history`

Weekly time-series for one market. Up to 520 weeks (~10y). Returns oldest-first; the report date is the canonical x-axis.

The DEHY Score

Every Form 4 carries a reproducible 0–100 score built from five sub-factors: historical pattern (25%), magnitude (25%), role weight (15%), plan dampener (20%), and cluster signal (15%). The algorithm is versioned — same inputs, same output. See methodology for the full math.

Stability

We version the URL prefix, not individual fields. Additive changes ship without notice; breaking changes ship as /api/v2. If a field becomes null instead of going away, it means we tried and couldn't compute — not that we removed it.