Developers
API Documentation
Bring Precision Sentiment, Market Alpha Analyzer and Strategic News Intel into your own apps with a simple REST API.
Overview
The Saffron Media API is a REST API that accepts and returns JSON. All requests go to this base URL over HTTPS:
https://api.saffronmg.com/v1
Authentication
Every request needs your API key in the Authorization header. Keep your key secret: use it only from your server, never in a web page or mobile app.
Authorization: Bearer YOUR_API_KEY
Don’t have a key yet? Email us to request API access.
Errors & Limits
We use standard HTTP status codes. Errors include a short message explaining what went wrong.
{ "error": { "code": "invalid_symbol", "message": "Symbol XYZQ was not found." } }
| 200 | Success. |
| 400 | Something in the request is missing or invalid. |
| 401 | Missing or invalid API key. |
| 404 | The resource or symbol wasn't found. |
| 429 | Too many requests. Wait and try again. |
| 500 | Something went wrong on our side. |
Requests are limited by plan. If you hit the limit you’ll get a 429; the Retry-After header says how many seconds to wait.
Precision Sentiment
Real-time NLP analysis of public opinion, capturing the nuance of human interaction across all digital channels.
/v1/sentiment/analyze
Analyze the sentiment and emotions of one or more pieces of text.
| Parameter | Type | Description |
|---|---|---|
| texts | array of strings | Required. Up to 100 texts per request. |
| language | string | Optional. ISO code such as en. Detected automatically if omitted. |
Example request
curl -X POST https://api.saffronmg.com/v1/sentiment/analyze \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"texts": ["Loving the new update, support was fantastic!"]}'
Example response
{
"results": [
{
"text": "Loving the new update, support was fantastic!",
"sentiment": "positive",
"score": 0.91,
"emotions": { "satisfaction": 0.62, "interest": 0.21, "anger": 0.01, "neutral": 0.16 }
}
]
}
/v1/sentiment/topics/{topic}
Get aggregated live sentiment for a topic, brand or keyword over a time window.
| Parameter | Type | Description |
|---|---|---|
| topic | string | Required. The topic, brand or keyword (in the URL). |
| window | string | Optional. 15m, 60m, 24h or 7d. Default 60m. |
| channels | string | Optional. Comma-separated, e.g. social,news,reviews. |
Example request
curl "https://api.saffronmg.com/v1/sentiment/topics/acme-corp?window=60m" \
-H "Authorization: Bearer YOUR_API_KEY"
Example response
{
"topic": "acme-corp",
"window": "60m",
"mentions": 12840,
"positive": 0.78,
"negative": 0.09,
"neutral": 0.13,
"emotions": { "satisfaction": 0.34, "interest": 0.25, "anger": 0.08, "neutral": 0.23 },
"alert": false
}
Market Alpha Analyzer
Proprietary algorithms provide high-probability stock predictions and dynamic risk assessments based on complex market data.
/v1/market/signals/{symbol}
Get the latest predictive signal for a stock symbol.
| Parameter | Type | Description |
|---|---|---|
| symbol | string | Required. Ticker symbol such as AAPL (in the URL). |
| horizon | string | Optional. 1d, 7d or 30d. Default 7d. |
Example request
curl "https://api.saffronmg.com/v1/market/signals/AAPL?horizon=7d" \
-H "Authorization: Bearer YOUR_API_KEY"
Example response
{
"symbol": "AAPL",
"horizon": "7d",
"signal": "BUY",
"confidence": 0.82,
"expected_move_pct": 3.4,
"generated_at": "2026-10-22T14:30:00Z"
}
/v1/market/risk
Run a risk assessment on a portfolio.
| Parameter | Type | Description |
|---|---|---|
| positions | array | Required. Each item has symbol and weight (weights add up to 1). |
| scenario | string | Optional. base, recession or rate_hike. Default base. |
Example request
curl -X POST https://api.saffronmg.com/v1/market/risk \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"positions": [{"symbol": "AAPL", "weight": 0.6}, {"symbol": "MSFT", "weight": 0.4}], "scenario": "base"}'
Example response
{
"scenario": "base",
"risk_score": 42,
"volatility_30d": 0.21,
"value_at_risk_95": -0.034,
"flags": []
}
Market signals are for informational and analytical purposes only and are not financial or investment advice. See our Terms & Conditions.
Strategic News Intel
Cut through global media noise with real-time strategic filtering to gain competitive and operational intelligence.
/v1/news/feed
Get a filtered, ranked feed of news stories.
| Parameter | Type | Description |
|---|---|---|
| industry | string | Optional. e.g. finance, energy, tech. |
| region | string | Optional. e.g. us, eu, apac. |
| min_impact | integer | Optional. Only stories with a strategic impact score of 0 to 100 at or above this value. |
| limit | integer | Optional. 1 to 100. Default 20. |
Example request
curl "https://api.saffronmg.com/v1/news/feed?industry=energy®ion=eu&min_impact=70" \
-H "Authorization: Bearer YOUR_API_KEY"
Example response
{
"items": [
{
"id": "nws_8f2a",
"headline": "EU proposes new limits on industrial gas imports",
"source": "Reuters",
"published_at": "2026-10-22T09:12:00Z",
"sentiment": "negative",
"impact_score": 84,
"entities": ["European Union", "Natural Gas"],
"url": "https://..."
}
],
"next_cursor": "c_19ab"
}
/v1/news/alerts
Create an alert that notifies your webhook when a matching story is published.
| Parameter | Type | Description |
|---|---|---|
| query | string | Required. Keywords, company or topic to watch. |
| min_impact | integer | Optional. Minimum impact score (0 to 100). Default 60. |
| webhook_url | string | Required. HTTPS address we POST matching stories to. |
Example request
curl -X POST https://api.saffronmg.com/v1/news/alerts \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "Acme Corp", "min_impact": 70, "webhook_url": "https://yourapp.com/hooks/news"}'
Example response
{
"id": "alr_3c91",
"query": "Acme Corp",
"min_impact": 70,
"webhook_url": "https://yourapp.com/hooks/news",
"status": "active"
}
Need Help Integrating?
Our team can help you get set up and tailor the API to your workflow.
Contact API Support