API & MCP

Getting started

1. Subscribe to Pro or Elite, then open your account page and click Regenerate key under "API key".
2. Copy the key immediately — it's shown exactly once. Only a hash is stored, so it can't be shown again; regenerating replaces it and invalidates the old one right away.
3. Call the REST API or connect an MCP client with it, below.

A first REST call:

curl https://api.rayana.ai/v1/rankings?lane=daily \
  -H "X-API-Key: YOUR_API_KEY"

Authentication

Every endpoint except /v1/health requires an X-API-Key header. There is no OAuth flow and no query-string key option — always send it as a header, and never share it or commit it to a public repo.

REST base

https://api.rayana.ai/v1

MCP endpoint

https://mcp.rayana.ai/mcp

Header

X-API-Key: YOUR_API_KEY

Tiers & rate limits

Your key's tier tracks your subscription and shapes both what an endpoint returns and how often you can call it. MCP itself requires Pro or higher, even for endpoints REST would serve to a Standard key.

Going over a limit returns 429 with a Retry-After header — back off and retry rather than hammering it.

REST endpoints

All under /v1. "Tier" is the minimum your key needs; a lower tier either gets a truncated response (rankings/signals/trends top-5) or a 403. Full request/response schemas are in the interactive reference at api.rayana.ai/docs.

POST /v1/search/hit is intentionally not listed — it's an internal signal-accrual endpoint for the site's own search box, not part of the public API surface.

MCP

The MCP server exposes the same data as read-only tools, so an agent can call it directly instead of you writing REST plumbing. It speaks Streamable HTTP at https://mcp.rayana.ai/mcp, authenticated the same way as REST — your X-API-Key passed as a connection header. Requires a Pro or Elite key.

Claude Code

claude mcp add --transport http rayana-ai \
  https://mcp.rayana.ai/mcp \
  --header "X-API-Key: YOUR_API_KEY"

Claude Desktop

Add to your MCP config (Settings → Connectors → Add custom connector, or edit the config file directly):

{
  "mcpServers": {
    "rayana-ai": {
      "url": "https://mcp.rayana.ai/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Any other MCP client that supports Streamable HTTP with custom headers connects the same way.

Tools

17 read-only tools — one endpoint's worth each, with a few related REST routes folded into a single tool via a view argument (rotation, trends, articles).

• rayana_ai_rankings(lane)
  Latest ranked candidate batch for a lane
• rayana_ai_lanes()
  Which lanes currently have a batch
• rayana_ai_signals(lane, limit)
  Latest aggregator-consensus batch
• rayana_ai_consensus(source?)
  Per-source consensus snapshots, one or all
• rayana_ai_ticker(symbol)
  Full per-ticker research view
• rayana_ai_ticker_price(symbol, period)
  Daily OHLC close history
• rayana_ai_ticker_analyst(symbol)
  Today's cached AI analyst read
• rayana_ai_ticker_articles(symbol)
  One ticker's article history
• rayana_ai_rotation(view, days)
  summary / laggards / discovered / members
• rayana_ai_trends(limit)
  Attention/virality leaderboard
• rayana_ai_trends_detail(view, limit?)
  sources / heat / search / video
• rayana_ai_market_brief(date?)
  Descriptive daily market brief
• rayana_ai_analyst_brief(date?)
  Broadcast portfolio-analyst brief
• rayana_ai_portfolios(include_retired)
  Model-portfolio shelf cards
• rayana_ai_portfolio(slug)
  One model portfolio's full detail
• rayana_ai_search(q, limit)
  Resolve free text to a known symbol
• rayana_ai_articles(slug?, limit?)
  Article feed, or one article's body

A Pro key gets a 403-style tool error from rayana_ai_portfolio for an Elite-only book slug — MCP access doesn't change what your tier can see, only how you can fetch it.

Errors

• 401 — Missing, invalid, or revoked API key
• 403 — Key's tier is below what's required
• 404 — Unknown symbol/slug, or nothing generated yet today
• 429 — Rate limit exceeded, see Retry-After
• 503 — Transient backend hiccup, retry