Sentiment API
Reference

What is the Sentiment API?

The Sentiment API gives you programmatic access to the same scored financial signals that power the Live AI Sentiment Engine dashboard. Every press release, news article, and SEC 8-K filing processed by the Rock Group scoring pipeline is available via API within seconds of being scored.

API Keys

All API requests must include your API key in the Authorization header using Bearer token format. An X-API-Key header carrying the bare key is accepted as an equivalent.

Authorization: Bearer rh_your_api_key_here

# equivalent
X-API-Key: rh_your_api_key_here

Keys are issued with an rh_ prefix and are managed from the API Dashboard. The key carries your plan, which determines both your rate limit and the maximum number of results a single request may return. Keys can be revoked at any time and stop working immediately.

Making requests

Base URL:  https://rockhewn.com/api/v1

Content-Type:  application/json
Accept:        application/json

All responses are JSON. Successful responses return HTTP 200. Errors return a JSON object with an error key and an appropriate HTTP status code.

Available endpoints

curl -X GET \
  "https://rockhewn.com/api/v1/sentiment?source=pr&score_min=7&limit=10" \
  -H "Authorization: Bearer rh_your_api_key_here"

{
  "data": [
    {
      "article_id": "abc123",
      "source": "pr",
      "ticker": "NVDA",
      "scored_at": "2026-06-19T14:32:00Z",
      "sentiment": "BULLISH",
      "sentiment_score": "9.1",
      "pr_title": "NVIDIA Reports Record Q4 Revenue...",
      "author": "Business Wire",
      "pr_published": "2026-06-19T14:31:12Z",
      "justification": "Earnings significantly beat consensus with record data centre revenue."
    }
  ],
  "meta": {
    "count": 1,
    "has_more": false,
    "response_time_ms": 84,
    "plan": "pro",
    "rate_limit_remaining": "4987"
  }
}

Common to every row, whatever the stream:

Additional fields, which depend on the stream — a press-release row and an SEC row do not carry the same keys:

And the meta object on every successful response:

Working with results

Score filtering is the fastest way to cut the volume down to what is worth acting on:

# Only major catalysts (score >= 8)
GET /api/v1/sentiment?score_min=8

# Negative signals only
GET /api/v1/sentiment?score_max=-1

# One stream, one name
GET /api/v1/sentiment?source=sec&ticker=AAPL&limit=50

# A date range (paid plans; ignored on Free)
GET /api/v1/sentiment?date_from=2026-08-01&date_to=2026-08-14

Signals are pushed to the dashboard within about a second of scoring and are queryable here immediately afterwards. Polling every few seconds is reasonable; polling every 100ms will only spend your rate limit.

Error responses

All errors return a JSON body with an error field.

{
  "error": "Invalid API key",
  "message": "Your API key is invalid or has been revoked."
}

Request limits

Limits are enforced per API key, on a rolling hourly window. Two separate things are limited: how many requests you may make, and how many rows a single request may return.

A limitabove your plan’s maximum is silently reduced to it rather than rejected, so check meta.count against what you asked for. Your remaining allowance is reported on every successful response as meta.rate_limit_remaining.

# On a 429 the response carries:
X-RateLimit-Remaining: 0
Retry-After:           3600

When you exceed the limit, requests return HTTP 429 until the window rolls over. Honour Retry-After, and back off exponentially — 1s, then 2s, then 4s — for any 5xx.

How to get an API key

Rock Group · Sentiment API Documentation · v1 · Last updated August 2026
Questions? Contact us