Developer
Public API
Authenticate, call endpoints, and handle errors against the ReachSurge REST API.
Overview
The ReachSurge REST API gives you programmatic access to your websites, analytics, citations, competitors, and Entity Authority data. Available on Starter and above. Base URL:
https://reachsurge.ai/api/v1
Generate and manage keys in Settings → API Keys. Full endpoint reference lives at Settings → API Keys → API Docs.
Authentication
Every request needs a Bearer token in the Authorization header. Pass your API key (the full string that starts with rs_live_ or rs_test_):
curl -H "Authorization: Bearer rs_live_YOUR_KEY" \
https://reachsurge.ai/api/v1/websites
Live keys (rs_live_*) hit your real data. Test keys (rs_test_*) are sandboxed and safe to commit to staging configs.
Rate limits
Limits are enforced per API key, both per-minute (burst protection) and per-day (quota).
| Plan | Per minute | Per day |
|---|---|---|
| Free | — | — |
| Starter | 60 | 500 |
| Growth | 300 | 1,000 |
| Enterprise | 1,000 | 10,000 |
Every response includes X-RateLimit-Remaining and X-RateLimit-Reset headers so you can pace your client. When you exceed a limit you'll get a 429 with a Retry-After value in seconds.
Endpoints
| Method | Path | Returns |
|---|---|---|
GET | /api/v1/websites | Your websites |
GET | /api/v1/analytics?websiteId=&from=&to= | Daily traffic + AI citations |
GET | /api/v1/citations?websiteId= | Per-engine citation feed |
GET | /api/v1/competitors?websiteId= | Share-of-voice + competitor list |
GET | /api/v1/authority?websiteId= | Entity Authority Score breakdown |
from and to accept ISO-8601 dates (2026-04-01) or unix seconds.
Error format
All errors return JSON with the same shape so your client can branch on error.code rather than parsing strings:
{ "error": { "code": "rate_limited", "message": "Rate limit exceeded. Retry after 42s" } }
| Status | error.code | When |
|---|---|---|
| 401 | unauthorized | Missing Authorization header |
| 401 | invalid_key | Key revoked or wrong format |
| 403 | forbidden | Key doesn't have the requested scope or plan |
| 404 | not_found | websiteId not in your team |
| 429 | rate_limited | Burst or daily quota exceeded — back off, then retry |
| 500 | server_error | Something on our side — safe to retry with exponential backoff |
Webhooks (push instead of poll)
For real-time events (new citation, backlink verified, authority score change), subscribe in Settings → Webhooks. Each delivery is signed with HMAC-SHA256 in the X-ReachSurge-Signature header — see the Webhooks article for verification code.
FAQ
Can I rotate a leaked key without downtime? Yes. Create a new key, deploy it to your client, then revoke the old one. Both keys work simultaneously until the old one is revoked.
What's the difference between live and test keys? Live keys read your production team data and count against your daily quota. Test keys read a sandbox dataset, never bill, and have a separate (smaller) quota. Use test keys in CI.
Do you have client libraries? Not officially yet. The API is plain REST + JSON — any HTTP client works. We're tracking demand for Node and Python SDKs; ping us via Contact if that would unblock you.