API Reference
Developer documentation for integrating with the Rival Radar API.
Authentication required
All API endpoints require authentication via a session token obtained through the NextAuth login flow. API routes return 401 for unauthenticated requests.
Authentication
Rival Radar supports two authentication methods:
- Session-based - For browser requests using NextAuth.js session cookies
- API Keys - For server-to-server integrations and MCP clients
API Keys
API keys are the recommended method for external integrations, scripts, and AI assistants (Claude Desktop, ChatGPT, Cursor). Generate keys in Settings → API Keys.
Keys use the format rr_live_xxxxx and are shown once on creation. Store them securely. Keys can be revoked at any time.
Example: API key authenticationbash
# API key auth (recommended for integrations)
curl -X GET https://userivalradar.com/api/analyses \
-H "Authorization: Bearer rr_live_your_api_key_here"
# Session-based auth (browser)
curl -X GET https://userivalradar.com/api/analyses \
-H "Cookie: next-auth.session-token=YOUR_SESSION_TOKEN"
# Responses use standard HTTP status codes
# 200 - Success
# 401 - Authentication required
# 403 - Insufficient permissions
# 429 - Rate limitedAPI key security
Never commit API keys to version control or share them publicly. If a key is compromised, revoke it immediately in Settings → API Keys.
Core Endpoints
Analyses
GET /api/analyseshttp
GET /api/analyses
# List all analyses for the organization
# Response: { analyses: Analysis[] }
GET /api/analyses/[id]
# Get a specific analysis by ID
# Response: { analysis: Analysis }
POST /api/analyses
# Create a new analysis (trigger competitor research)
# Body: { company: string }
# Response: { analysis: Analysis }
DELETE /api/analyses/[id]
# Delete an analysis
# Response: { success: boolean }Sales Coach
POST /api/coachhttp
POST /api/coach
# Send a coaching query
# Body: {
# message: string,
# threadId?: string,
# dealContext?: {
# competitor?: string,
# dealSize?: string,
# stage?: string
# }
# }
# Response: streaming text/event-streamWin/Loss
Win/Loss APIhttp
GET /api/winloss
# List win/loss records for the organization
POST /api/winloss
# Record a deal outcome
# Body: {
# competitor: string,
# outcome: "won" | "lost",
# dealValue?: number,
# notes?: string
# }
GET /api/winloss/insights
# Get AI-generated insights from win/loss dataNews
News APIhttp
GET /api/news
# List competitor news articles
# Query params: competitor, category, sentiment, limit, offset
GET /api/news/[id]
# Get a specific news article with full AI analysisKnowledge Base
Knowledge Base APIhttp
GET /api/knowledge-base
# List uploaded documents
POST /api/knowledge-base/upload
# Upload a document
# Body: multipart/form-data with file
DELETE /api/knowledge-base/[id]
# Delete a documentField Notes
Field Notes APIhttp
GET /api/notes?search=&folder=&type=&sort=newest&page=1&limit=50
# List notes with filtering, search, and pagination
POST /api/notes
# Create a note
# Body: { title, content, noteType, visibility, folderId, tags[], competitors[] }
PATCH /api/notes/[id]
# Update a note (partial update)
DELETE /api/notes/[id]
# Delete a note
POST /api/notes/[id]/ai
# AI actions: { action: "summarize" | "suggest-tags" | "generate-landmines" }
POST /api/notes/bulk
# Bulk operations: { action: "archive"|"pin"|"move"|"delete", noteIds[] }
POST /api/notes/export
# Export notes: { noteIds[], format: "csv" | "markdown" }
# Folders
GET /api/notes/folders
POST /api/notes/folders { name }
PATCH /api/notes/folders/[id] { name }
DELETE /api/notes/folders/[id]Integration Endpoints
Salesforce
Salesforce Integration APIhttp
GET /api/integrations/salesforce/auth
# Initiate Salesforce OAuth flow
GET /api/integrations/salesforce/status
# Check connection status
POST /api/integrations/salesforce/disconnect
# Disconnect SalesforceGong
Gong Integration APIhttp
GET /api/integrations/gong/auth
# Initiate Gong OAuth flow
GET /api/integrations/gong/status
# Check connection status
GET /api/integrations/gong/calls
# List analyzed callsSlack
Slack Integration APIhttp
GET /api/integrations/slack/auth
# Initiate Slack OAuth flow
GET /api/integrations/slack/status
# Check connection status
GET /api/integrations/slack/channels
# List available Slack channels
GET /api/integrations/slack/settings
# Get push notification settings
PUT /api/integrations/slack/settings
# Update push notification settings
POST /api/integrations/slack/disconnect
# Disconnect SlackCalendly
Calendly Integration APIhttp
GET /api/integrations/calendly/auth
# Initiate Calendly OAuth flow
GET /api/integrations/calendly/status
# Check connection status
GET /api/integrations/calendly/events
# List upcoming events
POST /api/integrations/calendly/disconnect
# Disconnect CalendlyWebhooks
Rival Radar receives webhooks from integrated services. These endpoints are public (authenticated via service-specific signatures):
POST /api/integrations/slack/commands- Slack slash command handler (verified via Slack signature)POST /api/integrations/calendly/webhooks- Calendly event notificationsPOST /api/webhooks/stripe- Stripe billing events
Rate Limits
API requests are subject to rate limiting. Analysis and coach endpoints are additionally governed by your plan's monthly quotas. If you exceed your quota, you'll receive a 403 response with a message indicating the quota type and limit.
Error Handling
All API errors follow a consistent format:
Error response formatjson
{
"error": "Human-readable error message",
"code": "MACHINE_READABLE_CODE",
"message": "Additional context (optional)"
}Common error codes:
UNAUTHORIZED- No valid sessionFORBIDDEN- Insufficient permissions or planSESSION_REVOKED- Session was revoked by another device loginQUOTA_EXCEEDED- Monthly quota exhaustedNOT_FOUND- Resource doesn't exist