StockSavvy API

Programmatic access to real-time SEC filing analysis — the same AI summaries, sentiment scores, and company data that power StockSavvy.ai. A REST API that returns JSON.

Base URL

https://api.stocksavvy.ai/api/v1

Authentication

Every request must include your API key. Send it in either the X-API-Key header or as a bearer token. Keep your key secret — treat it like a password.

curl https://api.stocksavvy.ai/api/v1/filings \
  -H "X-API-Key: sk_live_your_key_here"

# or, equivalently:
curl https://api.stocksavvy.ai/api/v1/filings \
  -H "Authorization: Bearer sk_live_your_key_here"

Rate limits

Free

100 filings / day

Metered by filings returned, not requests: a /filings?limit=20 page spends 20. Company and sentiment lookups cost 1 each. The quota resets at midnight US Eastern time; exceeding it returns HTTP 429.

Paid

Unlimited requests

No rate limit. Billed via subscription.

Throttled responses include a Retry-After header with the number of seconds until your quota resets.

Endpoints

Method	Path	Description
GET	/filings	List / filter filings — each item includes the full AI analysis (summary, positives, negatives, risks, …), same as the detail endpoint. Query params: company (slug), filing_type, sentiment (bullish\|neutral\|bearish), keyword, limit (1–100), bookmark (pagination cursor).
GET	/filings/{company_slug}/{filing_slug}	A single filing with its full AI analysis, sentiment, and keywords.
GET	/companies	List or search companies. Query params: search (name/ticker/CIK), limit (1–100), after (pagination cursor, browse mode).
GET	/companies/{slug}	A single company profile (symbol, exchange, sector, market cap, CIK).
GET	/companies/{slug}/sentiment	Daily sentiment history + the current trend (slope, direction, r²) for a company.
GET	/sentiment/screener	Companies ranked by recent sentiment trend. Params: direction (changing\|rising\|falling), limit (1–200), min_r2 (0–1), min_points.

Recipes

Every example below is a runnable curl. Always quote the URL so your shell does not treat ? or & as special characters.

1. Find a company (and its slug) by name or ticker

Company-scoped calls need a company slug. Search by ticker or name to get it — matches are ranked by market cap, so the primary company comes first. Here the top result is Apple Inc, slug apple-inc-nasdaq.

curl "https://api.stocksavvy.ai/api/v1/companies?search=apple" \
  -H "X-API-Key: sk_live_your_key_here"

2. Get a company profile

Full profile (symbol, exchange, sector, market cap, CIK) for one company by slug.

curl "https://api.stocksavvy.ai/api/v1/companies/apple-inc-nasdaq" \
  -H "X-API-Key: sk_live_your_key_here"

3. List the latest filings

The newest filings across every company we cover, most recent first. Every item carries its full analysis, so one call gives you both the feed and the breakdown. Each filing returned counts toward your daily quota.

curl "https://api.stocksavvy.ai/api/v1/filings?limit=10" \
  -H "X-API-Key: sk_live_your_key_here"

4. All 8-K filings for a company

Scope the feed to one company (by slug) and one filing type. Swap filing_type for any value in the list below (10-k, form-4, and so on).

curl "https://api.stocksavvy.ai/api/v1/filings?company=apple-inc-nasdaq&filing_type=8-k&limit=20" \
  -H "X-API-Key: sk_live_your_key_here"

5. Only bullish filings

Filter by sentiment bucket: bullish, neutral, or bearish. Combine it with company or filing_type as needed.

curl "https://api.stocksavvy.ai/api/v1/filings?sentiment=bullish&limit=10" \
  -H "X-API-Key: sk_live_your_key_here"

6. Search filings by keyword

Match filings whose extracted keywords contain a term, e.g. dividend, acquisition, or guidance.

curl "https://api.stocksavvy.ai/api/v1/filings?keyword=dividend&limit=10" \
  -H "X-API-Key: sk_live_your_key_here"

7. One filing with full AI analysis

Build the path from the company_slug and filing_slug found in every feed item. The analysis field holds the LLM breakdown; sentiment and sentiment_scale summarise it.

curl "https://api.stocksavvy.ai/api/v1/filings/apple-inc-nasdaq/apple-posts-record-q1-revenue-eps-driven-by-iphone-services" \
  -H "X-API-Key: sk_live_your_key_here"

8. Companies whose sentiment is rising (or falling)

The screener ranks companies by their recent sentiment trend slope (points/day). direction = rising, falling, or changing (biggest movers either way). Filter out noisy fits with min_r2 (0–1).

curl "https://api.stocksavvy.ai/api/v1/sentiment/screener?direction=rising&min_r2=0.5&limit=10" \
  -H "X-API-Key: sk_live_your_key_here"

9. A company's sentiment over time

Daily average sentiment plus the current trend (slope, direction, r²) — for charting how a company's sentiment has moved.

curl "https://api.stocksavvy.ai/api/v1/companies/apple-inc-nasdaq/sentiment" \
  -H "X-API-Key: sk_live_your_key_here"

Filing types

Pass any of these to the filing_type parameter:

8-k10-k10-qs-1f-120-f13-f13-g13-dform-4def-14a

In responses the filing_type field shows the SEC label (e.g. 8-K, Form 4).

Pagination

Filings — each response includes a bookmark. Pass it back as ?bookmark=… for the next page; a value of -1 means no more results.
Companies (browse) — each response includes next. Pass it back as ?after=…; when next is null you have reached the end. Search results are a single ranked page.

Example response

GET /filings?limit=1 — every feed item carries the full analysis object (the same one the single-filing endpoint returns). Its exact keys vary by filing type; the analysis below is abridged.

{
  "data": [
    {
      "company_slug": "apple-inc-nasdaq",
      "filing_slug": "apple-posts-record-q1-revenue-eps-driven-by-iphone-services",
      "complete_slug": "apple-inc-nasdaq/apple-posts-record-q1-revenue-eps-driven-by-iphone-services",
      "company_name": "Apple INC",
      "symbol": "AAPL",
      "exchange": "NASDAQ",
      "exchange_country": "US",
      "filing_type": "8-K",
      "sec_title": "8-K - Apple Inc. (0000320193)",
      "sec_link": "https://www.sec.gov/Archives/edgar/data/...",
      "title": "Apple Posts Record Q1 Revenue and EPS Driven by iPhone and Services",
      "excerpt": "Apple reported record first-quarter revenue of ...",
      "category": 0,
      "page_count": 12,
      "pdf_file": "https://api.stocksavvy.ai/media/filings/apple-8k.pdf",
      "price_sensitive": true,
      "released_at": "2026-07-10T20:05:00+00:00",
      "keywords": ["revenue", "iPhone", "services", "EPS"],
      "sentiment_scale": 8,
      "sentiment": "bullish",
      "analysis": {
        "summary": ["Record Q1 revenue of $XXB, up XX% YoY.", "Services reached an all-time high."],
        "sentiment_scale": { "score": 8, "explanation": "Broad-based beat with strong guidance." },
        "positives": ["Record Services revenue", "Gross margin expansion"],
        "negatives": ["Greater China revenue declined"],
        "risks": ["FX headwinds", "Regulatory pressure in the EU"],
        "future_outlook": "Management guided next-quarter revenue above consensus.",
        "keywords": ["revenue", "iPhone", "services", "EPS"]
      }
    }
  ],
  "bookmark": "12345",
  "count": 1
}

Getting a key

See plans and pricing, or create and manage keys on your account page. Free keys work immediately. Questions? hello@stocksavvy.ai.