§ Developers · v1 stable

One REST API for every analysis we publish.

Programmatic access to the full StockMarketAgent corpus — recommendations, fair-value bands, scenarios, sensitivity matrices, kill-scenario risk registers. Same data the website renders, structured for your pipeline. JSON in, JSON out.

Get an API key Open OpenAPI reference

§ 01

Quick start

Three steps. Two minutes. No SDK required.

Create a free or paid API key

Registered users can mint Free keys from /preferences → API. Growth and Enterprise keys add higher quotas and expanded report, valuation, and scoring scopes.

Authenticate

Send your key in the X-API-Key header. API-key responses carry X-RateLimit-Remaining and X-RateLimit-Reset.

Make your first request

Pull the latest MSFT analysis pack — same content the public analysis pipeline consumes, grouped into metadata, computed valuation outputs, sensitivity grids, scoring, and peer data.

# 1. Get an API key from /preferences → API
export SMA_KEY="sa_4f8a...redacted"

# 2. Pull the latest MSFT analysis pack
curl https://api.stockmarketagent.ai/api/v1/stocks/MSFT/analysis-pack \
  -H "X-API-Key: $SMA_KEY"

§ 02

Endpoints

Pulled live from the backend OpenAPI spec — stays in sync with the production surface automatically.

Method	Path	Description	Tier
GET	/v1/stocks/{ticker}/analysis-pack	Latest report headline — rating, fair-value range, confidence score.	Free
GET	/v1/stocks/screen	Filter the covered universe by valuation, quality, upside, and rating.	Growth
GET	/v1/stocks/{ticker}/valuation	Six valuation models plus the 5×5 sensitivity grid for one ticker.	Growth
POST	/v1/stocks/{ticker}/reports/generate	Trigger on-demand report generation. Returns a report id you can stream.	Growth
STREAM	/v1/stocks/{ticker}/reports/{id}/stream	Server-Sent Events — pushes per-phase progress while a report builds.	Growth
GET	/v1/r/{slug}	Public shared report payload. No auth required.	Free

Pagination is cursor-based via ?cursor=…. List responses include nextCursor when more is available. If-None-Match + ETag are honored on every report endpoint — refresh polling is essentially free. The full surface lives in the OpenAPI reference.

§ 03

Response schema

Stable, versioned, and shaped for analysis pipelines — not for rendering.

The analysis-pack endpoint returns one top-level JSON document with meta, computed model output, sensitivity data, scoring, and peer context. Collection endpoints use Laravel's data envelopes. Numeric fields use unsuffixed base units — USD for prices, decimals (0–1) for probabilities, integers for confidence scores.

What's in an analysis pack

The headline action plus a 0–100 confidence score, the low/mid/high fair-value range, and bull/base/bear scenarios with probabilities that sum to 1.0 when those models are available. For the full report envelope and all 14 reader sections, use /stocks/{ticker}/reports/latest?include=sections.

What's not

We don't bill the public website HTML as API content, and the analysis pack is not a rendered report. Use the report endpoint when you need the canonical prose sections and report metadata.

{
  "meta": {
    "ticker": "MSFT",
    "name": "Microsoft Corporation",
    "sector": "Technology",
    "generated_at": "2026-04-25T12:00:00Z"
  },
  "archetype": {
    "archetype": "mature_compounder",
    "archetype_label": "Mature compounder"
  },
  "score": {
    "rating_band": "Strong Buy",
    "confidence_score": 87,
    "six_factor_score": 82
  },
  "valuation_results": {
    "synthesis": {
      "fair_value_low": 480,
      "fair_value_mid": 545,
      "fair_value_high": 612,
      "currency": "USD"
    }
  },
  "sensitivity_results": {
    "ke_vs_terminal_growth": "5x5 matrix omitted for brevity"
  }
}

§ 04

Rate limits & pricing

Per-key, per-month. Burst capacity ≈ 2× sustained.

Tier

Free · $0/mo

Tier

Growth · $99/mo

Tier

Enterprise · Custom

Requests / month

100

Universe + analysis-pack only

Requests / month

1,000

All GET endpoints + valuation

Requests / month

Unlimited

Contractual SLA, dedicated capacity

Streaming

—

Polling only

Streaming

5 conn

SSE + webhooks

Streaming

100 conn

SSE + webhooks + redrive

API-key responses include X-RateLimit-Remaining and X-RateLimit-Reset headers. Exceeding the monthly key quota returns 429 with a Retry-After hint and an upgrade_url in the body — never the connection drop.

§ 05

Errors

Stable code field — branch on that, not the message.

{
  "error": {
    "code": "ticker_not_covered",
    "message": "ROOT is not in our coverage universe.",
    "docs": "https://stockmarketagent.ai/developers#errors",
    "request_id": "req_01JBN7T1Z9XKQ"
  }
}

Ready to integrate?

Start with the free tier — 100 requests/month, no card required. Upgrade in-product when production volume justifies it.

Create free account OpenAPI reference