RockGroup
API ReferenceRESTv1

Sentiment API
Reference

Programmatic access to the Rock Group AI Sentiment Engine — scored financial signals from press releases, market news, and SEC 8-K filings in real time.

Contents
  1. 01.Overview
  2. 02.Authentication
  3. 03.Base URL & Format
  4. 04.Endpoints
  5. 05.Filtering & Pagination
  6. 06.Errors
  7. 07.Rate Limits
  8. 08.Getting API Access
01. Overview

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 access is currently in limited preview. Contact us via the API Access page or the contact form to request credentials.

02. Authentication

API Keys

All API requests must include your API key in the Authorization header using Bearer token format.

Authorization: Bearer rg_your_api_key_here

API keys are issued and managed via the API Dashboard. Each key can be scoped to specific endpoints and rate limits. Keys can be revoked at any time.

Keep your key private. Do not expose your API key in client-side code, public repositories, or browser consoles. If compromised, revoke it immediately via the API Dashboard and generate a replacement.

03. Base URL & Format

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.

04. Endpoints

Available endpoints

GET/api/v1/sentiment

Returns the most recent AI-scored signals from all three data streams (press releases, news, SEC 8-K). Optionally filtered by data source, ticker, or score range.

Query Parameters
sourcestringOptional"pr" | "news" | "sec" — filter by data source
tickerstringOptionalFilter by stock ticker symbol. Case-insensitive. Example: AAPL
min_scorenumberOptionalMinimum sentiment score (-5 to 10). Default: no minimum
max_scorenumberOptionalMaximum sentiment score (-5 to 10). Default: no maximum
limitintegerOptionalNumber of results to return. Max: 100. Default: 20
offsetintegerOptionalPagination offset. Default: 0
Example Request
curl -X GET \
  "https://rockhewn.com/api/v1/sentiment?source=pr&min_score=7&limit=10" \
  -H "Authorization: Bearer rg_your_api_key_here"
Example Response
{
  "data": [
    {
      "id": "abc123",
      "source": "pr",
      "ticker": "NVDA",
      "headline": "NVIDIA Reports Record Q4 Revenue...",
      "score": 9.1,
      "direction": "BULLISH",
      "justification": "Earnings significantly beat consensus estimates with record data centre revenue.",
      "scored_at": "2026-06-19T14:32:00Z",
      "price_at_score": 148.72,
      "volume": 42800000,
      "rvol": 2.4
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}
Response Fields
idstringUnique identifier for the signal
sourcestringData source: "pr" | "news" | "sec"
tickerstringStock ticker symbol
headlinestringTitle / headline of the article or filing
scorenumberAI sentiment score from -5.0 to 10.0
directionstring"BULLISH" | "BEARISH" | "NEUTRAL" | "MIXED"
justificationstringOne-sentence AI reasoning for the score
scored_atstringISO 8601 timestamp when the signal was scored
price_at_scorenumber?Share price at score time (if available)
volumenumber?Total daily volume at score time (if available)
rvolnumber?Relative volume vs. 20-day average (if available)
05. Filtering & Pagination

Working with large result sets

Use limit and offset for pagination. The response always includes a total field with the count of matching records.

# Page 1: first 20 results
GET /api/v1/sentiment?source=sec&limit=20&offset=0

# Page 2: next 20 results
GET /api/v1/sentiment?source=sec&limit=20&offset=20

Score filtering lets you focus on actionable signals. Common patterns:

# Only major catalysts (score ≥ 8)
GET /api/v1/sentiment?min_score=8

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

# All signals for a ticker
GET /api/v1/sentiment?ticker=AAPL&limit=50
06. Errors

Error responses

All errors return a JSON body with an error field.

{
  "error": "Invalid or expired API key"
}
400Bad RequestInvalid query parameter value or missing required field
401UnauthorizedMissing or invalid Authorization header / API key
403ForbiddenAPI key does not have permission for this endpoint
429Too Many ReqsRate limit exceeded — see X-RateLimit-Remaining header
500Server ErrorInternal error — retry with exponential backoff
07. Rate Limits

Request limits

Rate limits are enforced per API key. Each response includes headers showing your current usage:

X-RateLimit-Limit:     60
X-RateLimit-Remaining: 57
X-RateLimit-Reset:     1718806800
Free tier60 requests / minute · 1,000 / day
Pro tier300 requests / minute · 20,000 / day
EnterpriseCustom — contact us

When you exceed the rate limit, requests return HTTP 429. Implement exponential backoff: wait 1s, then 2s, then 4s before retrying.

08. Getting API Access

How to get an API key

1
Sign up

Create an account on the Rock Group platform via the API Sign Up page.

2
Request access

API access is currently in limited preview. Use the API Access page to request credentials and describe your intended use case.

3
Generate your key

Once approved, log in to the API Dashboard to generate your first API key. You can create multiple keys for different environments (dev, prod).

4
Start making requests

Include your key in the Authorization header of every request. Monitor usage in the API Dashboard.

Ready to integrate?

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

↑ Back to top