RivalHound API Documentation

The RivalHound API allows you to programmatically access your brand monitoring data, integrate with existing workflows, and build custom applications.

Authentication

API Keys

Enterprise customers receive API keys for accessing the RivalHound API. Contact our sales team to upgrade to an Enterprise plan.

# Include your API key in the Authorization header
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.rivalhound.com/v1/brand-mentions

Rate Limits

• Starter Plan: Not available
• Pro Plan: Not available
• Enterprise Plan: 1000 requests per hour

Core Endpoints

Brand Mentions

Retrieve brand mentions across AI platforms.

GET /v1/brand-mentions

Parameters:

• brand (string) - Brand name to query
• platform (string) - AI platform (chatgpt, google-ai, perplexity, etc.)
• start_date (date) - Start date for results
• end_date (date) - End date for results
• limit (integer) - Number of results (max 100)

Response:

{
  "data": [
    {
      "id": "mention_123",
      "brand": "YourBrand",
      "platform": "chatgpt",
      "query": "best project management tools",
      "response": "AI response text...",
      "sentiment": "positive",
      "cited": true,
      "timestamp": "2024-12-15T10:30:00Z"
    }
  ],
  "meta": {
    "total": 45,
    "page": 1,
    "per_page": 20
  }
}

Competitor Analysis

Compare your brand against competitors.

GET /v1/competitor-analysis

Parameters:

• brand (string) - Your brand name
• competitors (array) - List of competitor brands
• platform (string) - AI platform to analyze
• date_range (string) - Analysis period (7d, 30d, 90d)

Visibility Score

Get your brand’s visibility score.

GET /v1/visibility-score

Response:

{
  "brand": "YourBrand",
  "overall_score": 87,
  "platform_scores": {
    "chatgpt": 92,
    "google_ai": 78,
    "perplexity": 85,
    "claude": 91
  },
  "trend": "+12%",
  "last_updated": "2024-12-15T10:30:00Z"
}

Webhooks

Enterprise customers can configure webhooks for real-time notifications.

Setup

1. Configure webhook URL in your dashboard
2. Choose events to subscribe to
3. Verify webhook endpoint security

Events

• mention.created - New brand mention detected
• sentiment.changed - Significant sentiment shift
• competitor.mentioned - Competitor tracking update

SDKs and Libraries

JavaScript/Node.js

npm install @rivalhound/node-sdk

import { RivalHound } from '@rivalhound/node-sdk';

const client = new RivalHound({
  apiKey: 'your-api-key'
});

const mentions = await client.brandMentions.list({
  brand: 'YourBrand',
  platform: 'chatgpt'
});

Python

pip install rivalhound-python

from rivalhound import RivalHound

client = RivalHound(api_key='your-api-key')
mentions = client.brand_mentions.list(
    brand='YourBrand',
    platform='chatgpt'
)

Error Handling

HTTP Status Codes

• 200 - Success
• 400 - Bad Request (invalid parameters)
• 401 - Unauthorized (invalid API key)
• 403 - Forbidden (insufficient permissions)
• 429 - Rate Limit Exceeded
• 500 - Internal Server Error

Error Response Format

{
  "error": {
    "code": "invalid_parameter",
    "message": "Brand name is required",
    "details": "The 'brand' parameter cannot be empty"
  }
}

Need Help?

• Contact our API support team
• Check our troubleshooting guide
• Join our developer community (coming soon)

Note: API access is available exclusively to Enterprise customers. Contact sales to learn more about Enterprise features.