API Reference

Star Signal API delivers AI-extracted market signals from financial astrology publishers as structured JSON. Every insight includes topic, outlook, timeframe, confidence level, plain-English summary, and source attribution.

The API is a simple REST interface — no SDK required. One x-api-key header is all you need.

Authentication

All endpoints except /health and /insights/demo require an API key passed in the x-api-key request header.

bash

curl https://api.starsignal.io/api/v1/insights \
  -H "x-api-key: YOUR_API_KEY"

API keys are shown only once at issuance. If you lose your key, contact us — we will revoke the old key and issue a new one.

Request a free API key →

Base URL

text

https://api.starsignal.io

All endpoints are prefixed with /api/v1.

Rate Limits

Plan	Calls / month	Notes
Free	100	Manual approval, key emailed within 24h
Starter	10,000	$49 / month
Pro	100,000	$149 / month, webhook alerts
Demo endpoint	Unlimited	Max 5 results, no key required

Exceeding your monthly quota returns a 429 Too Many Requests response. Usage resets on the first day of each calendar month.

Errors

All errors return JSON with an error field describing the problem.

json

{ "error": "Invalid or missing API key" }

Status	Meaning
200	Success
400	Bad request — missing or invalid parameter
401	Unauthorized — API key missing or invalid
429	Rate limit exceeded — monthly quota reached
500	Server error — try again in a moment

GET /api/v1/health No auth

Returns service status, last ingestion timestamp, total insights cached, and per-source feed health. Useful for uptime monitoring and verifying data freshness before making insights requests.

bash

curl https://api.starsignal.io/api/v1/health

Response

json

{
  "status":          "ok",
  "lastFetch":       "2026-06-01T08:00:00.000Z",
  "insightsCached":  47,
  "sources": [
    {
      "name":        "Astrodoc Anil",
      "url":         "https://astrodocanil.com/feed",
      "status":      "ok",
      "lastFetched": "2026-06-01T08:00:12.000Z",
      "error":       null
    }
  ]
}

GET /api/v1/insights x-api-key required

Returns all current market insights. Supports filtering by topic, outlook, and confidence. Results are sorted: featured → verified → newest first. Low-confidence insights are excluded by default.

Query parameters

Parameter	Type		Description
topic	string	optional	Filter to a single topic. See Topics for valid values.
outlook	string	optional	Filter to a single outlook. One of `bullish` `bearish` `volatile` `cautious` `stable`.
limit	integer	optional	Max number of insights to return. No default cap when omitted.
sort	string	optional	`date_asc` or `date_desc` to sort by `published_date`.
lang	string	optional	Pass `es` to receive `summary` fields translated to Spanish by Claude AI. All other fields remain in English.
confidence	string	optional	Pass `all` to include low-confidence insights (excluded by default).

bash

# All insights
curl https://api.starsignal.io/api/v1/insights \
  -H "x-api-key: YOUR_KEY"

# Filter by topic and outlook
curl "https://api.starsignal.io/api/v1/insights?topic=crypto&outlook=bullish" \
  -H "x-api-key: YOUR_KEY"

# Spanish summaries
curl "https://api.starsignal.io/api/v1/insights?lang=es&limit=10" \
  -H "x-api-key: YOUR_KEY"

Response

json

{
  "count":    3,
  "insights": [ /* array of Insight objects */ ]
}

GET /api/v1/insights/demo No auth

Returns up to 5 medium/high-confidence insights without requiring an API key. Useful for quick integration tests, demos, and landing page widgets. Supports topic and outlook filters. Not rate-limited.

bash

curl "https://api.starsignal.io/api/v1/insights/demo?topic=gold"

GET /api/v1/insights/summary x-api-key required

Returns an overall market sentiment score and a plain-English narrative summary generated by Claude AI, synthesizing all current insights into a single market-wide view.

bash

curl https://api.starsignal.io/api/v1/insights/summary \
  -H "x-api-key: YOUR_KEY"

Response

json

{
  "overall_sentiment": "cautious",
  "score":             42,   // 0 (bearish) → 100 (bullish)
  "summary":           "Markets show mixed signals this week...",
  "insight_count":     47
}

The Insight object

Every item returned by /insights and /insights/demo has the following shape:

idstring (uuid)Unique identifier

topicstringMarket area — see Topics

symbolstring | nullTicker symbol when applicable (e.g. BTC, NVDA)

outlookstringbullish bearish volatile cautious stable

timeframestringHuman-readable forecast window (e.g. "Q3 2026", "April 9–13")

period_startstring | nullISO date parsed from timeframe

period_endstring | nullISO date parsed from timeframe

trend_typestring | null"Short Term Trend" or "Long Term Trend"

summarystring1–2 sentence plain-English conclusion. Translated when ?lang=es.

confidencestringlow medium high — see Confidence levels

source_namestringPublisher name

source_urlstringDirect link to the source article

published_datestringISO date the article was published

featuredbooleanTrue for Featured tier partners — sorted first

verifiedbooleanTrue for Verified tier partners — sorted second

Topics

Pass any of these strings to the topic query parameter (lowercase, exact match):

cryptogoldoilstock marketcurrenciesgeopoliticalbankingwarreal estatecommodities

Topics are extracted by Claude AI from article content and may expand as new sources are added.

Outlooks

Value	Meaning
bullish	Astrologer expects upward price movement or positive conditions
bearish	Astrologer expects downward price movement or negative conditions
volatile	High uncertainty or sharp swings expected in either direction
cautious	Muted or mixed signals; advises caution
stable	Consolidation or sideways movement expected

Confidence levels

Assigned by Claude AI based on how specific, concrete, and time-bound the astrologer's prediction is.

Level	Criteria
high	Specific asset, clear timeframe, concrete price target or directional call
medium	Clear outlook and topic with a reasonable timeframe — most insights fall here
low	Vague, general, or highly speculative — excluded from responses by default (pass `?confidence=all` to include)

cURL examples

bash

# Health check
curl https://api.starsignal.io/api/v1/health

# All insights
curl https://api.starsignal.io/api/v1/insights \
  -H "x-api-key: YOUR_KEY"

# Crypto — bullish only
curl "https://api.starsignal.io/api/v1/insights?topic=crypto&outlook=bullish" \
  -H "x-api-key: YOUR_KEY"

# Limit to 5 newest insights
curl "https://api.starsignal.io/api/v1/insights?sort=date_desc&limit=5" \
  -H "x-api-key: YOUR_KEY"

# Spanish summaries
curl "https://api.starsignal.io/api/v1/insights?lang=es" \
  -H "x-api-key: YOUR_KEY"

# Overall market sentiment
curl https://api.starsignal.io/api/v1/insights/summary \
  -H "x-api-key: YOUR_KEY"

Python examples

python

import requests

BASE    = "https://api.starsignal.io"
HEADERS = {"x-api-key": "YOUR_KEY"}

# Fetch all insights
res  = requests.get(f"{BASE}/api/v1/insights", headers=HEADERS)
data = res.json()
print(f"{data['count']} insights")

# Filter by topic
res  = requests.get(f"{BASE}/api/v1/insights", headers=HEADERS,
                    params={"topic": "crypto", "outlook": "bullish"})
for i in res.json()["insights"]:
    print(f"[{i['outlook'].upper()}] {i['topic']} — {i['summary'][:80]}…")

# Spanish summaries
res  = requests.get(f"{BASE}/api/v1/insights", headers=HEADERS,
                    params={"lang": "es"})
for i in res.json()["insights"]:
    print("[ES]", i["summary"])

# Market summary
s = requests.get(f"{BASE}/api/v1/insights/summary", headers=HEADERS).json()
print(s["overall_sentiment"], "—", s["summary"])

Node.js examples

javascript

const BASE    = "https://api.starsignal.io";
const HEADERS = { "x-api-key": "YOUR_KEY" };

// Fetch all insights
const res  = await fetch(`${BASE}/api/v1/insights`, { headers: HEADERS });
const data = await res.json();
console.log(`${data.count} insights`);

// Filter by topic and outlook
const params = new URLSearchParams({ topic: "gold", outlook: "bullish" });
const res2   = await fetch(`${BASE}/api/v1/insights?${params}`, { headers: HEADERS });
const data2  = await res2.json();
data2.insights.forEach(i =>
  console.log(`[${i.outlook.toUpperCase()}] ${i.topic} — ${i.summary.slice(0, 80)}…`)
);

// Spanish summaries
const res3  = await fetch(`${BASE}/api/v1/insights?lang=es`, { headers: HEADERS });
const data3 = await res3.json();
data3.insights.forEach(i => console.log("[ES]", i.summary));

// Market summary
const s = await fetch(`${BASE}/api/v1/insights/summary`, { headers: HEADERS })
  .then(r => r.json());
console.log(s.overall_sentiment, "—", s.summary);

API Reference

Authentication

Base URL

Rate Limits

Errors

Response

Query parameters

Response

Response

The Insight object

Topics

Outlooks

Confidence levels

cURL examples

Python examples

Node.js examples

Get your free API key