Blackhorse SentinelLog in

Developer API

Sentinel API

Score institutional and media language for deontic pressure, epistemic certainty, entropy, and drift versus a public baseline — programmatically. Every response is a signed, reproducible receipt. Get a key in your dashboard.

Ingest sources (dashboard)

The dashboard supports two ingest modes. Load from link fetches and extracts text server-side. Paste sends text you copy from any source — required for paywalled publishers.

SourceLoad from linkNotes
Institutional (.gov, Fed, ECB)YesHTML/PDF extraction, institutional segment
Podcast RSSYesShow notes / episode description
Public news (Reuters, BBC, NPR)OftenWorks when publisher allows datacenter fetch
Paywalled (Bloomberg, WSJ, FT)NoUse Blackhorse Reader extension or paste in dashboard

For paywalled publishers, install the Blackhorse Reader browser extension (Chrome + Safari). It captures article text from your logged-in browser tab and posts to /api/v1/capture (OAuth) or /api/v1/analyze (API key).

For API ingest without the extension, pass text directly — there is no URL fetch on /api/v1/analyze. Optional fields: sourceUrl, author, voiceSegment, contentKind.

Blackhorse Reader extension

The Reader extension extracts articles from Bloomberg, WSJ, FT, and Economist while you are logged in on the publisher site. Extraction runs locally in your browser; text is sent to Sentinel only when you click Analyze.

Connect via OAuth in the extension popup, or save a bhs_live_… API key. OAuth uses /api/v1/capture and counts against dashboard ingest quota. API keys use /api/v1/analyze and count against API quota.

Authentication

All requests use a Bearer API key over HTTPS. Keys are secret and server-side only — never embed them in a browser or mobile client. Pass the key in the Authorization header (or x-api-key).

Base URL
https://blackhorsesentinel.com/api/v1
Header
Authorization: Bearer bhs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Quotas & tiers

API calls are metered per calendar month against your plan. When you exceed the quota the API returns 402 quota_exceeded.

PlanAPI calls / month
Free analysis100
Pro50,000
EnterpriseUnlimited

Endpoints

POST /analyze

Score a document and store a report. Body fields: text (required), title, sourceOutlet, entity, author, sourceUrl, voiceSegment, contentKind (optional).

Pass entity matching corpus baseline keys exactly — e.g. Federal Reserve, European Central Bank, U.S. Congress, European Commission.

curl
curl -X POST https://blackhorsesentinel.com/api/v1/analyze \
  -H "Authorization: Bearer $SENTINEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "FOMC statement",
    "sourceOutlet": "FEDERAL_RESERVE",
    "entity": "Federal Reserve",
    "text": "The Committee will continue to assess..."
  }'
201 response
{
  "id": "9c2f...",
  "tier": "HIGH",
  "score": { "deonticScore": 0.42, "dominantDeontic": "obligation", "avgEpistemicScore": 0.61, ... },
  "drift": { "driftScore": 0.18, "baseline": { "entity": "Federal Reserve", "source": "corpus", ... } },
  "receipt": { "receiptId": "...", "sha256": "...", "signature": "...", "signedAt": "..." }
}

GET /reports

List your organization's reports, newest first. Optional ?limit= (1–200, default 50).

curl
curl https://blackhorsesentinel.com/api/v1/reports?limit=20 \
  -H "Authorization: Bearer $SENTINEL_API_KEY"

GET /reports/:id

Fetch a single report including the full score, drift, and signed receipt.

curl
curl https://blackhorsesentinel.com/api/v1/reports/9c2f... \
  -H "Authorization: Bearer $SENTINEL_API_KEY"

GET /usage

Check your remaining monthly quota.

curl
curl https://blackhorsesentinel.com/api/v1/usage \
  -H "Authorization: Bearer $SENTINEL_API_KEY"

Errors

Errors return JSON with an error message and a stable code.

401 unauthorized     — missing/invalid/revoked key
402 quota_exceeded   — monthly API quota reached (upgrade)
400 bad_request      — malformed JSON
400 no_text          — empty text field
413 text_too_large   — text exceeds 200,000 characters
404 not_found        — report id not in your org
500 internal         — unexpected server error

Client SDKs

TypeScript / JavaScript

install
npm install @blackhorse/sentinel-sdk
usage
import { SentinelClient } from "@blackhorse/sentinel-sdk";

const sentinel = new SentinelClient({ apiKey: process.env.SENTINEL_API_KEY! });

const report = await sentinel.analyze({
  title: "FOMC statement",
  sourceOutlet: "FEDERAL_RESERVE",
  entity: "Federal Reserve",
  text: "The Committee will continue to assess...",
});

console.log(report.tier, report.drift.driftScore);
const usage = await sentinel.usage();
console.log(usage.remaining);

Python

install
pip install blackhorse-sentinel
usage
from blackhorse_sentinel import SentinelClient

sentinel = SentinelClient(api_key="bhs_live_...")

report = sentinel.analyze(
    title="FOMC statement",
    source_outlet="FEDERAL_RESERVE",
    entity="Federal Reserve",
    text="The Committee will continue to assess...",
)

print(report["tier"], report["drift"]["driftScore"])
print(sentinel.usage()["remaining"])

Ready to build? Choose a plan or create an API key.