Saffron ϟ Media

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." } }
200Success.
400Something in the request is missing or invalid.
401Missing or invalid API key.
404The resource or symbol wasn't found.
429Too many requests. Wait and try again.
500Something 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.

Module 1

Precision Sentiment

Real-time NLP analysis of public opinion, capturing the nuance of human interaction across all digital channels.

POST /v1/sentiment/analyze

Analyze the sentiment and emotions of one or more pieces of text.

ParameterTypeDescription
textsarray of stringsRequired. Up to 100 texts per request.
languagestringOptional. 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 }
    }
  ]
}
GET /v1/sentiment/topics/{topic}

Get aggregated live sentiment for a topic, brand or keyword over a time window.

ParameterTypeDescription
topicstringRequired. The topic, brand or keyword (in the URL).
windowstringOptional. 15m, 60m, 24h or 7d. Default 60m.
channelsstringOptional. 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
}
Module 2

Market Alpha Analyzer

Proprietary algorithms provide high-probability stock predictions and dynamic risk assessments based on complex market data.

GET /v1/market/signals/{symbol}

Get the latest predictive signal for a stock symbol.

ParameterTypeDescription
symbolstringRequired. Ticker symbol such as AAPL (in the URL).
horizonstringOptional. 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"
}
POST /v1/market/risk

Run a risk assessment on a portfolio.

ParameterTypeDescription
positionsarrayRequired. Each item has symbol and weight (weights add up to 1).
scenariostringOptional. 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.

Module 3

Strategic News Intel

Cut through global media noise with real-time strategic filtering to gain competitive and operational intelligence.

GET /v1/news/feed

Get a filtered, ranked feed of news stories.

ParameterTypeDescription
industrystringOptional. e.g. finance, energy, tech.
regionstringOptional. e.g. us, eu, apac.
min_impactintegerOptional. Only stories with a strategic impact score of 0 to 100 at or above this value.
limitintegerOptional. 1 to 100. Default 20.

Example request

curl "https://api.saffronmg.com/v1/news/feed?industry=energy&region=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"
}
POST /v1/news/alerts

Create an alert that notifies your webhook when a matching story is published.

ParameterTypeDescription
querystringRequired. Keywords, company or topic to watch.
min_impactintegerOptional. Minimum impact score (0 to 100). Default 60.
webhook_urlstringRequired. 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