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.

Connecting Claude? You don't need a key at all: add the MCP server as a connector and sign in with your Rayana AI account — see MCP.

Connecting an agent with a key? Use Pair an agent on the account page instead of pasting a key into a chat window: it shows a short code your agent redeems itself with rayana_ai_complete_setup. Pairing issues a new key and retires the current one, so anything already using a key will need the new value.

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 query-string key option — always send it as a header, and never share it or commit it to a public repo.

The MCP server accepts the same header, and also supports OAuth sign-in: a client such as Claude sends you to sign in with your Rayana AI account and is then connected without ever handling a key. Either way, what you can reach is set by your subscription tier.

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 and needs a Pro or Elite subscription. Connect by signing in (OAuth), or with an API key.

Claude (claude.ai, Desktop, mobile) — sign in

1. Open Settings → Connectors → Add custom connector and enter https://mcp.rayana.ai/mcp.
2. Choose Sign in when needed. Leave the OAuth client fields and request headers empty.
3. Ask Claude a research question. The first research call asks you to sign in with your Rayana AI account and approve access; after that it just works.

Plans and pricing answer before you sign in, so you can check what each tier includes first.

Claude Code — sign in

claude mcp add --transport http rayana-ai https://mcp.rayana.ai/mcp

Then run /mcp in Claude Code and sign in to rayana-ai.

With an API key instead — Claude Code

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

With an API key instead — config file

For an MCP client configured from a file that accepts custom headers:

{
  "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 research 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.

Three tools that work before you sign in

So an agent whose principal hasn't subscribed isn't at a dead end. Tool discovery is open too — any client can list the roster before it signs in or has a key.

• rayana_ai_plans()
  Tiers, prices, limits — no sign-in needed
• rayana_ai_start_checkout(tier, interval)
  A link for a human to open and subscribe
• rayana_ai_complete_setup(code)
  For key-based clients: trades a pairing code for an API key (rotates the account's key; OAuth connections are unaffected)

A human completes the purchase — an agent can't accept the Terms on your behalf, and Rayana AI never accepts, routes or executes securities orders.

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