API Documentation

The Concept

SentimentWiki provides asset-specific sentiment analysis. Unlike generic sentiment models, our API understands context — "OPEC cuts production" is bullish for oil but might be bearish for airlines.

# The dream API
sentiment = sentiment_of("OPEC announces surprise production cut", security="OIL")
# → { direction: "BULLISH", magnitude: 0.85, relevance: 0.95, confidence: 0.92 }

Full interactive reference: /docs (Swagger UI) · /redoc (ReDoc)

Endpoints

POST /v1/analyze

Analyze the sentiment of a headline or text for a specific security. Uses Claude Haiku with catalog context (known inversions, price drivers, key entities).

Request

POST https://sentimentwiki.io/v1/analyze
Content-Type: application/json

{
    "text": "OPEC announces surprise production cut of 1M bpd",
    "security": "OIL"
}

Response

{
    "direction": "BULLISH",
    "magnitude": 0.85,
    "relevance": 0.95,
    "confidence": 0.92,
    "reasoning": "Production cuts reduce supply, typically bullish for oil prices",
    "model_version": "haiku-4-5",
    "latency_ms": 1327,
    "request_id": "60b3e648-bf86-494c-b1e1-090c6bf2c460"
}

cURL Example

curl -X POST https://sentimentwiki.io/v1/analyze \
  -H "Content-Type: application/json" \
  -d '{"text": "EIA reports large storage draw", "security": "NATGAS"}'

Authentication

Anonymous requests are allowed up to 100/day per IP. Register for a free API token to get a named key and manage your usage:

Get a free API token →

Pass your token in the Authorization header:

Authorization: Bearer swk_free_<your_token>

---

POST /v1/queue/ingest

Batch ingest headlines into the label queue from external pipelines. Deduplicates automatically. Max 1000 items per request.

Requires: X-Ingest-Token header (contact us for access).

Symbol mapping

External label	SentimentWiki symbol
GAS	NATGAS (Henry Hub)
LNG	LNG (global seaborne)
OIL	OIL (WTI/Brent)

Request

POST https://sentimentwiki.io/v1/queue/ingest
Content-Type: application/json
X-Ingest-Token: <token>

{
    "items": [
        {
            "text": "US natural gas storage falls more than expected",
            "asset_class": "GAS",
            "source_url": "https://theguardian.com/...",
            "source_date": "2024-03-15",
            "source": "theguardian.com"
        }
    ]
}

Response

{
    "inserted": 1,
    "skipped_duplicate": 0,
    "skipped_unknown_security": 0,
    "total_received": 1
}

Rate Limits

Tier	Daily limit	Scopes
Anonymous	100	analyze
Free	500	read, label
Basic	2,000	read, label
Pro	10,000	read, label, analyze
Enterprise	100,000	all