Basics

This guide explains how the API works at a high level — what the data pipeline looks like, what each layer produces, and which endpoints give you access to it.

How the system works

The API is built around a single pipeline: articles come in, get matched to assets and macro themes, and are progressively enriched into higher-level outputs — sentiment indices, events, insights, signals, and forecasts.

Articles → Headlines → Sentiment indices → Events → Insights / Signals / Forecasts

Everything flows from the same underlying article data. The further down the pipeline, the more processed and opinionated the output.

Step 1 — Headlines

Permutable continuously ingests news articles and identifies which assets and macroeconomic themes each one is relevant to. The result is headline-level data: the raw article matched to a ticker or macro topic, enriched with sentiment and topic classifications.

This is the most granular data in the API. You get the actual headline, its sentiment score, the topic it covers, and when it was published.

Endpoints:

• GET /v1/headlines/feed/live/ticker/{ticker} — live headlines for a ticker
• GET /v1/headlines/feed/historical/ticker/{ticker} — historical headlines for a ticker
• GET /v1/headlines/feed/live/macro — live macro-level headlines

Step 2 — Sentiment indices

Those headlines are fed into targeted sentiment and topic models, which aggregate the signal across many articles over time into a quantitative index. Rather than reading individual headlines, you get a single numeric value that reflects the overall sentiment state for an asset or macro theme at any point in time.

These indices are the primary input for systematic strategies — they're clean, numeric, and available historically for backtesting.

Endpoints:

• GET /v1/headlines/index/ticker/live/{ticker} — live sentiment index for a ticker
• GET /v1/headlines/index/ticker/historical/{ticker} — historical sentiment index for a ticker
• GET /v1/headlines/index/macro/live/global/{model_id} — live global macro sentiment index for a model
• GET /v1/headlines/index/macro/historical/global/{model_id} — historical global macro sentiment index for a model
• GET /v1/headlines/index/macro/live/regional/{model_id} — live regional macro sentiment index for a model
• GET /v1/headlines/index/macro/historical/regional/{model_id} — historical regional macro sentiment index for a model

Historical index data for bulk model development is also available as a CSV download via the Permutable Platform.

Step 3 — Events

In parallel, the same headlines are processed by Permutable's models to extract structured events — discrete, market-relevant occurrences identified from the news. Each event has a topic, a directional label, and a timestamp. Examples: a supply disruption, a central bank decision, a sanctions announcement.

Events are the bridge between raw news and actionable intelligence. They're more structured than headlines but more granular than insights.

Endpoints:

• GET /v1/events/live/ticker/{ticker} — live events for a ticker
• GET /v1/events/historical/ticker/{ticker} — historical events for a ticker

Step 4 — Insights, signals, and forecasts

Events and sentiment data are then used by Permutable's models to generate the highest-level outputs:

• Insights — AI-generated narrative summaries of market conditions over a chosen lookback window (weekly, monthly, quarterly, yearly). Designed for discretionary traders who want a written briefing.
• Signals — Aggregated directional views (bullish / bearish / neutral) derived from the underlying sentiment and event data. A quick read on where the data is pointing.
• Forecasts — Forward-looking model outputs for a ticker.

Endpoints:

• GET /v1/insights/analyst/{ticker} — narrative insight for a ticker
• GET /v1/signals — directional signal for one or more tickers
• GET /v1/forecasts/{ticker} — forecast for a ticker

Taxonomy

Before calling any data endpoint, use the taxonomy endpoints to discover what's available — tickers, sectors, countries, languages, and sources.

Endpoints:

• GET /v1/taxonomy/tickers — all available tickers
• GET /v1/taxonomy/sectors — tickers grouped by sector
• GET /v1/taxonomy/countries — available countries
• GET /v1/taxonomy/languages — available languages
• GET /v1/taxonomy/sources — available news sources
• GET /v1/ticker/search — search for a ticker by keyword

Authentication

All endpoints require your API key in the x-api-key header. There is no OAuth or token exchange — just a static key per environment.

Your API key does not expire automatically. It remains valid until rotated or revoked. Contact the Permutable team if you need to rotate or revoke a key.

Error responses

All endpoints return standard HTTP status codes. The table below covers the errors you are most likely to encounter.

Error responses include a JSON body with a detail field describing the problem, except for 400 responses which return a plain-text validation message, and 429 responses which are returned by the API infrastructure.

{ "detail": "Permission denied" }

See Rate Limits for details on request quotas and how to handle 429 errors.

Next steps

• Which endpoint should I use? — map your use case to the right endpoint
• Rate Limits — understand your monthly quota and per-second limits
• Pagination — fetch large historical datasets page by page
• Deprecated Endpoints — endpoints being removed on 2026-05-01 and their replacements
• Changelog — release notes and deprecation notices
• API Reference — explore and run every endpoint interactively in the browser
• Systematic Workflow — use indices for quantitative model inputs and backtesting
• Discretionary Workflow — use headlines, events, insights, and signals for active trading decisions
• Recipes — end-to-end worked examples