Stock Broker Analyzer API

The Stock Broker Analyzer API is a read-mostly REST API for Company Plan accounts. It gives your own systems programmatic access to exactly the data your Company Plan account already sees in the report UI — every broker in your subscribed market(s), every criterion, evidence, sentiment, and change history — plus your own account and quota state.

One write action exists: triggering an on-demand single-broker verify, the same quota-limited action available from your dashboard.

Base URL:

https://www.stockbrokeranalyzer.com/api/public/v1

Versioning: the version is part of the URL path (/v1). A future breaking change ships as /v2; /v1 keeps working unchanged.

Format: all requests and responses are JSON. All timestamps are ISO 8601 UTC.

Every request needs a bearer token, generated from your dashboard's "API Setup" tab. The token is shown once at creation time — we store only its hash, so if you lose it you'll need to generate a new one.

Authorization: Bearer sba_live_51a9c...

Opening the "API Setup" tab itself requires a fresh 6-digit code sent to your account's email, even within an already-signed-in session — once entered, it unlocks key management (viewing, creating, revoking) for the rest of that dashboard visit. Keys can mint standing credentials, so we want fresh proof it's really you before showing that tab at all, not just a logged-in browser tab.

Scope — chosen per key at creation time:

Expiration — also chosen at creation: 30 days, 90 days, 1 year, or never (not recommended). An expired key is rejected the same as a revoked one — there's no separate "expired" error, both just come back as unauthorized.

One token per company account per key. A token only ever has access to that company's own subscribed market(s) — never another company's data, and never anything beyond its own scope. There is no way to buy, upgrade, cancel, or otherwise change your subscription via the API — that always happens on the site itself, the same as any other customer.

API access itself requires an active subscription in at least one market — same as the report page's own paid/unlocked view, a company account with nothing currently subscribed has no key-management UI to use in the first place.

Two independent limits, protecting two different things:

Every response carries your current standing:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1755111600

Going over the limit returns 429 Too Many Requests with a Retry-After header (seconds until you can retry).

Use the since query parameter (ISO 8601 timestamp) on GET endpoints to only fetch data that changed after your last pull — cheap enough to poll as often as you like without approaching the limit.

Errors share one consistent shape:

{
  "error": {
    "code": "quota_exceeded",
    "message": "You've used all 5 on-demand verify runs for DE this month."
  }
}

Returns the latest published snapshot for a market you're subscribed to — the same data your Company Plan report page shows: every broker, every criterion rating with its evidence, sentiment findings, and the week's change log.

Path parameters

Query parameters

curl https://www.stockbrokeranalyzer.com/api/public/v1/reports/de \
  -H "Authorization: Bearer sba_live_51a9c..."

{
  "data": {
    "market": "de",
    "brokers": [
      {
        "id": "smartbroker",
        "name": "Smartbroker",
        "overall_score": 78.4,
        "categories": [
          {
            "id": "fees",
            "label": "Fees & Pricing",
            "criteria": [
              {
                "id": "custody_fee",
                "label": "Custody fee",
                "stars": 4,
                "confidence": "high",
                "source_tier": 1,
                "note": "No custody fee on the standard account.",
                "source_url": "https://..."
              }
            ]
          }
        ],
        "sentiment": { "score": 72, "signals": [ /* ... */ ] },
        "change_log": [ /* criteria changed since the previous snapshot */ ]
      }
    ]
  },
  "meta": {
    "report_date": "2026-08-10",
    "generated_at": "2026-08-10T06:03:11Z",
    "snapshot_version": 47,
    "week": "2026-W33"
  }
}

Same shape as one entry of the brokers array above, for one broker — useful once you only need to sync a single record instead of re-pulling the whole market.

{
  "data": {
    "company_name": "Acme Capital GmbH",
    "subscriptions": [
      { "market": "de", "status": "active", "started_at": "2026-02-01", "renews_at": "2026-09-01" }
    ]
  }
}

Read-only. There's no way to change any of this via the API — subscribing, upgrading, or cancelling always happens on the site.

{
  "data": [
    { "market": "de", "used": 2, "limit": 5, "resets_at": "2026-09-01T00:00:00Z" }
  ]
}

Check this before calling the trigger endpoint below, so your own system knows whether a call would actually succeed.

The one write action available. Same action as the "Re-check this broker" button on your dashboard — same monthly quota, same result. Verification takes a little while (it involves real source-checking, not a cache read), so this returns immediately with a run ID; poll GET /v1/runs/{run_id} for the result, or use a webhook (below) once available.

curl -X POST https://www.stockbrokeranalyzer.com/api/public/v1/brokers/smartbroker/verify \
  -H "Authorization: Bearer sba_live_51a9c..."

{
  "data": { "run_id": "run_8f2a1c", "status": "pending" }
}

This updates the broker's data inside your own report view immediately once it completes. It never affects the shared weekly snapshot other companies or visitors see — that only ever moves on the Monday run.

{
  "data": { "run_id": "run_8f2a1c", "status": "completed", "completed_at": "2026-08-13T10:04:02Z" }
}

status is one of pending, completed, or failed.

An optional alternative to polling. Once available, you'll be able to register a URL from your dashboard and receive a signed POST when:

• a new weekly snapshot is published for a market you're subscribed to, or
• an on-demand verify you triggered completes.

Every delivery will be signed (HMAC) so you can verify it genuinely came from us, carry a unique event ID so retried deliveries can be safely de-duplicated, and be retried with backoff if your endpoint is briefly unavailable. Not required — polling GET endpoints will always remain fully supported for anyone who'd rather not run a webhook receiver.

v1 — planned. Not yet released.