API Reference

Build powerful integrations with RankAgent AI's RESTful API

Getting Started

Authentication

All API requests require authentication using an API key. Include your API key in the request header:

Authorization: Bearer YOUR_API_KEY

Get your API key from your account settings dashboard after logging in.

Base URL

All API endpoints are relative to the base URL:

https://api.rankagentai.io/v1

Core Endpoints

GET/users/:id

Retrieve user profile information including creator stats and verification status.

Parameters

id (string, required) - User ID

Response Example

{
  "id": "usr_123456",
  "name": "John Creator",
  "type": "creator",
  "verified": true,
  "stats": {
    "followers": 125000,
    "engagement_rate": 4.8,
    "avg_views": 85000
  },
  "platforms": ["youtube", "instagram", "tiktok"]
}
GET/analytics/:userId

Fetch detailed analytics data for a specific user across all connected platforms.

Parameters

userId (string, required) - User ID
startDate (string, optional) - Start date (YYYY-MM-DD)
endDate (string, optional) - End date (YYYY-MM-DD)

Response Example

{
  "userId": "usr_123456",
  "period": {
    "start": "2025-01-01",
    "end": "2025-01-31"
  },
  "metrics": {
    "total_views": 2150000,
    "total_engagement": 98500,
    "engagement_rate": 4.58,
    "follower_growth": 12500,
    "avg_watch_time": "8:24"
  },
  "platforms": {
    "youtube": { "views": 1200000, "engagement": 58000 },
    "instagram": { "views": 650000, "engagement": 28000 },
    "tiktok": { "views": 300000, "engagement": 12500 }
  }
}
POST/scan/content

Perform an AI-powered SEO scan on a specific piece of content.

Request Body

{
  "url": "https://youtube.com/watch?v=example",
  "platform": "youtube",
  "options": {
    "deep_scan": true,
    "include_recommendations": true
  }
}

Response Example

{
  "scan_id": "scn_789012",
  "url": "https://youtube.com/watch?v=example",
  "score": 87,
  "metrics": {
    "seo_score": 85,
    "engagement_quality": 92,
    "content_authenticity": 94
  },
  "recommendations": [
    "Optimize video title for search keywords",
    "Add more relevant tags",
    "Improve thumbnail contrast"
  ]
}
GET/search/creators

Search for creators based on various criteria including niche, engagement rate, and follower count.

Query Parameters

niche (string, optional) - Creator niche/category
min_followers (integer, optional) - Minimum follower count
min_engagement (float, optional) - Minimum engagement rate
verified_only (boolean, optional) - Show verified creators only

Response Example

{
  "results": [
    {
      "id": "usr_123456",
      "name": "TechReviewer Pro",
      "niche": "technology",
      "verified": true,
      "followers": 250000,
      "engagement_rate": 5.2,
      "platforms": ["youtube", "instagram"]
    }
  ],
  "total": 147,
  "page": 1,
  "per_page": 20
}

Rate Limits & Best Practices

Rate Limits

Free Tier:100 requests/hour
Pro Tier:1,000 requests/hour
Enterprise:Custom limits

Rate limit headers are included in every response to help you track your usage.

Best Practices

  • →Cache responses when possible to reduce API calls
  • →Use webhooks for real-time updates instead of polling
  • →Implement exponential backoff for retries
  • →Keep your API keys secure and rotate regularly
  • →Monitor rate limit headers in responses

Error Codes

400

Bad Request

The request was malformed or missing required parameters

401

Unauthorized

Invalid or missing API key

403

Forbidden

You don't have permission to access this resource

404

Not Found

The requested resource doesn't exist

429

Too Many Requests

Rate limit exceeded - please slow down your requests

500

Internal Server Error

Something went wrong on our end - please try again later

Need Help with Integration?

Our developer support team is here to help you build amazing integrations with RankAgent AI API.