Quickstart

Make your first API call in minutes. This guide walks you through setting your API key, finding a ticker, and pulling live market data.

Get an API key

Contact the Permutable team to get access. Once you have a key, export it as an environment variable — all requests read it from there.

export PERMUTABLE_API_KEY="your_api_key_here"

$env:PERMUTABLE_API_KEY = "your_api_key_here"

setx PERMUTABLE_API_KEY "your_api_key_here"

Keep your key secure

Never hardcode your API key in source code. If your key is committed to a repository or exposed in client-side code, revoke it immediately and request a new one.

Follow these practices to keep your key safe:

Use environment variables — as shown above, read the key from the environment at runtime rather than writing it directly into your code.
Use a secrets manager in production — tools such as AWS Secrets Manager, HashiCorp Vault, or your cloud provider's equivalent store keys outside your codebase and inject them securely at deploy time.
Do not share keys across environments — use a separate key for development, staging, and production so a leaked development key cannot affect production data.
Rotate keys periodically — your key does not expire automatically, but rotating it regularly limits the window of exposure if it is ever compromised. Contact the Permutable team to rotate or revoke a key.

Try it interactively

Before writing any code, you can explore and run every endpoint directly in the API Reference. Enter your API key once and fire requests straight from the browser.

Find a ticker

Every endpoint is scoped to a ticker symbol. Search for the asset you want to track and note the ticker field in the response — you'll use it in every subsequent call.

curl "https://copilot-api.permutable.ai/v1/ticker/search" \
  -H "x-api-key: $PERMUTABLE_API_KEY" \
  -G --data-urlencode "keywords=brent crude"

Invoke-RestMethod `
  -Uri "https://copilot-api.permutable.ai/v1/ticker/search?keywords=brent+crude" `
  -Headers @{ "x-api-key" = $env:PERMUTABLE_API_KEY }

import os, requests

resp = requests.get(
    "https://copilot-api.permutable.ai/v1/ticker/search",
    headers={"x-api-key": os.environ["PERMUTABLE_API_KEY"]},
    params={"keywords": "brent crude"},
)
print(resp.json())

Common tickers for reference:

Asset	Ticker
Brent Crude	`BZ_COM`
WTI Crude	`CL_COM`
Natural Gas	`NG_COM`
Gold	`QO_COM`

Make your first calls

Live headlines

The latest news for a ticker, each pre-scored with sentiment.

curl "https://copilot-api.permutable.ai/v1/headlines/feed/live/ticker/BZ_COM" \
  -H "x-api-key: $PERMUTABLE_API_KEY"

Invoke-RestMethod `
  -Uri "https://copilot-api.permutable.ai/v1/headlines/feed/live/ticker/BZ_COM" `
  -Headers @{ "x-api-key" = $env:PERMUTABLE_API_KEY }

import os, requests

resp = requests.get(
    "https://copilot-api.permutable.ai/v1/headlines/feed/live/ticker/BZ_COM",
    headers={"x-api-key": os.environ["PERMUTABLE_API_KEY"]},
)
print(resp.json())

Trading signals

An aggregated directional view for a ticker.

curl "https://copilot-api.permutable.ai/v1/signals?tickers=BZ_COM" \
  -H "x-api-key: $PERMUTABLE_API_KEY"

Invoke-RestMethod `
  -Uri "https://copilot-api.permutable.ai/v1/signals?tickers=BZ_COM" `
  -Headers @{ "x-api-key" = $env:PERMUTABLE_API_KEY }

import os, requests

resp = requests.get(
    "https://copilot-api.permutable.ai/v1/signals",
    headers={"x-api-key": os.environ["PERMUTABLE_API_KEY"]},
    params={"tickers": ["BZ_COM"]},
)
print(resp.json())

Analyst insights

A narrative market summary for a ticker. Choose a lookback window: weekly, monthly, quarterly, or yearly.

curl "https://copilot-api.permutable.ai/v1/insights/analyst/BZ_COM?analyst_type=weekly" \
  -H "x-api-key: $PERMUTABLE_API_KEY"

Invoke-RestMethod `
  -Uri "https://copilot-api.permutable.ai/v1/insights/analyst/BZ_COM?analyst_type=weekly" `
  -Headers @{ "x-api-key" = $env:PERMUTABLE_API_KEY }

import os, requests

resp = requests.get(
    "https://copilot-api.permutable.ai/v1/insights/analyst/BZ_COM",
    headers={"x-api-key": os.environ["PERMUTABLE_API_KEY"]},
    params={"analyst_type": "weekly"},
)
print(resp.json())

Systematic index

The live quantitative sentiment index for a model. Replace {model_id} with the ID from your Permutable contact.

curl "https://copilot-api.permutable.ai/v1/indices/live/{model_id}" \
  -H "x-api-key: $PERMUTABLE_API_KEY"

Invoke-RestMethod `
  -Uri "https://copilot-api.permutable.ai/v1/indices/live/{model_id}" `
  -Headers @{ "x-api-key" = $env:PERMUTABLE_API_KEY }

import os, requests

model_id = "your_model_id"
resp = requests.get(
    f"https://copilot-api.permutable.ai/v1/indices/live/{model_id}",
    headers={"x-api-key": os.environ["PERMUTABLE_API_KEY"]},
)
print(resp.json())

The Core 6

Most new users only need six endpoints to get started. They follow the same order as the data pipeline — from raw news through to actionable outputs.

#	Endpoint	What it gives you
1	`GET /v1/ticker/search`	Find the ticker symbol for any asset
2	`GET /v1/headlines/feed/live/ticker/{ticker}`	Raw headline-level data tagged with topic and scored with sentiment
3	`GET /v1/headlines/index/ticker/live/{ticker}`	Aggregated sentiment index built from those headlines
4	`GET /v1/events/feed/live/ticker/{ticker}`	Structured market events extracted from the news
5	`GET /v1/signals`	Aggregated directional signal (bullish / bearish / neutral)
6	`GET /v1/insights/analyst/{ticker}`	Automated market analysis for a ticker

Not sure which to use for your workflow? See Which endpoint should I use?.

Next steps

Which endpoint should I use? — map your use case to the right endpoint
Basics — core concepts and how the API is structured
Systematic Workflow — integrate live index data into quantitative models
Discretionary Workflow — use headlines, events, insights, and signals for discretionary trading

For end-to-end examples, see the Recipes section.