ShareStructure grades, in your product

Quick start

curl -H "Authorization: Bearer sk_live_…" \
  https://www.sharestructure.io/api/v1/issuers/FFAI

Every response carries links.assessment (the page your users can click through to) and an attribution block. See Attribution.

Authentication

Secret keys (sk_live_…) go in the Authorization: Bearer header from your server. Never ship them to a browser. Publishable keys (pk_live_…) work only on the badge image and are safe in HTML. A bad or revoked key returns 401 invalid_key.

Every key is issued under the API Terms.

Endpoints

• GET/api/v1/issuers/{ticker}

  One issuer

  • ticker (path, required)
• GET/api/v1/issuers

  Batch lookup, up to 50 tickers

  • tickers (query, required) — Comma-separated
• GET/api/v1/changes

  Issuers re-assessed since a timestamp

  • since (query, required) — Within the last 30 days
  • limit (query)
  • cursor (query)
• GET/api/v1/red-flag-categories

  Recurring red-flag categories (free text, 5+ issuers, most common first)

• GET/api/v1/me

  The calling key: scopes, limits, current usage

• GET/embed/badge/{ticker}.svg

  Dilution-risk badge image (publishable key via ?key=)

  • ticker (path, required)
  • key (query, required) — pk_live_…

The issuer object

Numbers are raw (shares, dollars, percents), never formatted. Fields marked scope: flags or scope: narrative appear only when your key has that scope; otherwise they are omitted. links.badge_svg needs ?key= with your publishable key appended.

• tickerstring
• namestring | null
• exchangestring | null
• assessed_atstring | null
  ISO 8601, when the engine last graded this issuer
• assessment_triggerstring | null
• dilutionobject
  • scoreinteger | null
  • ratingstring | null
    Engine label; normally LOW | MODERATE | ELEVATED | HIGH | EXTREME. Treat as a label, not an enum.
  • confidencestring | null · HIGH | MEDIUM | LOW
    Confidence in the float estimate
• floatobject
  • reportednumber | null
    Data-service float at request time, cached up to 1 hour
  • reported_as_ofstring | null
  • estimatednumber | null
    ShareStructure's filing-based float
  • effective_supplynumber | null
    Estimated float plus near-term sellable overhang: convertibles at current price, in-the-money warrants, registered resale. Excludes registered-but-unsold ATM/shelf capacity.
  • fully_dilutednumber | null
  • pending_overhang_pctnumber | null
    Registered and convertible shares that could enter the float, as a percent of the current float
  • statusstring · CONFIRMED | OVERSTATED | UNDERSTATED | ASSESSMENT_STALE | UNVERIFIED | NO_REPORTED_FLOAT
• reverse_splitsarray
  • datestring | null
  • ratiostring | null
• atmobject | null
  • activeboolean
    From the engine; true even when remaining_capacity_usd is unknown
  • remaining_capacity_usdnumber | null
  • baby_shelf_cap_usdnumber | null
    One-third of public float value per 12 months (Form S-3 I.B.6) when float value < $75M
• red_flagsarray
  scope: flags
  • severitystring
  • categorystring
  • timeframestring | null
  • shares_involvednumber | null
• counterpartiesarray
  scope: flags
  • namestring
  • rolestring | null
  • high_riskboolean
• summarystring | null
  scope: narrative. The engine's thesis, verbatim.
• active_mechanismsarray
  scope: narrative
• linksobject
  • assessmentstring
  • badge_svgstring
    Append ?key=<your publishable key>. Secret keys are not accepted on the badge.
• attributionobject
  • requiredboolean
  • textstring
  • linkstring

Definitions

Reported float

The number a market-data service publishes. Often stale for small caps that are actively issuing.

Estimated float

Our reconstruction from SEC filings: the reported float adjusted for issuance, conversions, and registrations the feed has not yet absorbed. Sanity-gated against the latest cover-page share count.

Effective supply

Estimated float plus what can realistically hit the market near term: convertibles at the current price, in-the-money warrants, registered resale. It deliberately excludes registered-but-unsold ATM and shelf capacity, which is throttled by volume and the baby-shelf rule.

Pending overhang %

Registered and convertible shares that could enter the float, as a percent of the current float. Above 50% we flag it; above 100% the overhang exceeds the float.

Float status

CONFIRMED when the reported and estimated floats agree within 10%; OVERSTATED / UNDERSTATED otherwise; ASSESSMENT_STALE when shares outstanding have grown more than 10% since we assessed, so the reported float is likely the more current number; UNVERIFIED when we have no estimate; NO_REPORTED_FLOAT when the data service has none.

Rate limits and caching

Per-key limits are returned on every response in X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. A batch call counts once per minute and once per ticker per day. Over the limit returns 429 with Retry-After. Grades change at most a few times a day per ticker; cache responses for five minutes or poll /changes.

Attribution

Section 2 of the API Terms requires that any display of ShareStructure data show Powered by ShareStructure.io, linked to links.assessment or attribution.link, inside the same component as the data. The badge satisfies this on its own:

<a href="https://www.sharestructure.io/scanner/FFAI?utm_source=YOURSITE&utm_medium=api">
  <img src="https://www.sharestructure.io/embed/badge/FFAI.svg?key=pk_live_…" width="260" height="44" alt="FFAI dilution risk — ShareStructure.io">
</a>

Errors

{ "error": "not_found", "message": "No assessment for XYZ." }

invalid_key 401 · bad_request / bad_ticker 400 · not_found 404 · rate_limited / daily_limit 429 · internal_error 500

Request a key

Tell us what you are building and where the credit will sit. We read every request by hand and reply from hello@sharestructure.io. Keys are issued under the API Terms.

Changelog

1.0.0 · 2026-09 · Initial release.