Quick start

1. Get an API key

Sign up at ray9.ai/signup, then create a key in Settings → API keys. Every new org gets $1.00 of free credit automatically — about 200 SERP calls. The key is shown once: rk_ prefix + 32 lowercase alphanumeric characters. See Authentication for lifecycle and rotation.

2. Pick a path

Option A — MCP server (recommended)

Connect any MCP-compatible client (Claude Desktop, Cursor, VS Code, Goose, Windsurf) to Ray9's hosted MCP endpoint at https://api.ray9.ai/mcp. Once connected, your agent can call serp.search and usage.get as native tools.

Cursor example (~/.cursor/mcp.json):

{
  "mcpServers": {
    "ray9": {
      "url": "https://api.ray9.ai/mcp",
      "headers": {
        "Authorization": "Bearer rk_..."
      }
    }
  }
}

Then ask your assistant:

"What's ranking on Google for 'best crm 2026'?"

For per-client config (Claude Desktop, VS Code, Goose) and the stdio-shim option for older clients, see MCP server.

Option B — API (HTTP)

curl https://api.ray9.ai/v1/serp/search \
  -H "Authorization: Bearer rk_..." \
  -H "Content-Type: application/json" \
  -d '{ "keyword": "best crm 2026", "depth": 10 }'

Trimmed response:

{
  "requestId": "req_4f3a2c1b9e8d",
  "creditsCharged": 5,        // mils ($0.005)
  "creditsRemaining": 995,    // post-debit balance
  "results": [
    { "type": "organic", "rank": 1, "title": "Best CRM Software in 2026", "url": "https://example.com/best-crm", "domain": "example.com" }
    // …more results, plus query echo and totalResultsCount
  ]
}

For the full parameter list, response shape, and result-type taxonomy, see SERP.

3. ✅ Verify it worked

MCP: ask your agent "check my Ray9 usage" — it'll call usage.get and report your balance.

REST: call the usage endpoint:

curl https://api.ray9.ai/v1/usage \
  -H "Authorization: Bearer rk_..."

Either path reports creditsRemaining — you should see it reflect the SERP call you just made (1000 mils on a fresh free-tier org → 995 after one SERP call).

4. What's next

• Build something — recipes for rank tracking, keyword expansion, AI visibility.
• SERP reference — every parameter, result type, and error code.
• Concepts — Authentication, Errors, Rate limits, Billing.

Hit a wall? Email contact@ray9.ai with your requestId.