RankSavanna API Documentation

Welcome to the RankSavanna API documentation. Our robust, RESTful architecture provides developers with programmatic access to enterprise-grade website analysis, deep technical SEO audits, and AI-driven competitor tracking intelligence. Whether you are building custom reporting dashboards, integrating SEO tools into your SaaS platform, or automating large-scale crawl tasks, our SEO API integration endpoints deliver lightning-fast, structured JSON responses.

This developer guide details the request and response formats, endpoint workflows, authentication protocols, and best practices to ensure seamless programmatic execution. Note that API access is exclusively available for users subscribed to our Pro and Enterprise plans.

Authentication & Security

The RankSavanna API requires a secure Bearer Token for all authenticated requests. This ensures that your SEO analysis and competitor data API endpoints remain private and secure. All API requests must include your private API token passed within the HTTP Authorization header. Unauthenticated requests or requests with invalid tokens will instantly trigger an HTTP 401 Unauthorized error.

Generating Your Token

To generate a new access token, navigate to your User Profile. Under the API Access section, you can issue new tokens, assign them specific names for easier rotation management, and revoke compromised keys immediately.

HTTP Header Example 
Authorization: Bearer YOUR_SECURE_API_TOKEN_HERE

Rate Limiting Protocols

To maintain high availability and blazing fast latency across our website analysis API infrastructure, we enforce strict programmatic rate limits. Continuous optimization prevents single-tenant abuse and guarantees stability when retrieving massive competitor keyword ranking API datasets.

  • Standard Rate: 2 requests per second (RPS).
  • Burst Capacity: Maximum burst of 20 concurrent requests.
  • Response Code: Exceeding allowed thresholds returns an HTTP 429 Too Many Requests status block.

Best Practice: Always implement exponential backoff and retry logic inside your integration client to gracefully handle 429 exceptions.

Account Analytics API

GET /api/v1/stats

Retrieve a high-level aggregate breakdown of your SEO analysis statistics. This endpoint returns total pages crawled, average HTTP response times, secure connection analytics, and the total volume of SEO issues identified across all historical sessions.

Response Configuration (JSON) 
{
  "total_pages": 1450,
  "avg_response_ms": 312,
  "https_count": 1380,
  "issues_count": 210,
  "unique_domains": 42
}

Crawl Sessions Lifecycle

GET /api/v1/sessions

Programmatically query active and historical SEO crawl sessions. Useful for tracking the asynchronous status of heavy enterprise crawling operations. You can monitor when deep technical audits move from pending to completed states.

Expected Output Format 
{
  "sessions": [
    {
      "ID": 42,
      "Label": "ecommerce-brand.com (+3 competitors)",
      "Status": "completed",
      "PageCount": 2500,
      "IsFree": false,
      "StartedAt": "2026-03-29T14:30:00Z"
    }
  ]
}

Deep Website Crawl Results

GET /api/v1/results

Pull paginated technical SEO data for specific URLs. This endpoint returns rich metadata, comprehensive HTTP status mapping, and proprietary computed SEO metrics mapping out content velocity and grading. Utilizing the domain filter allows targeted extraction of vast competitor keyword analytics structures.

Endpoint Query Parameters

Parameter Data Type Default Value Functional Description
page int 1 Pagination offset tracker sequence index.
limit int 25 Items returned per page (maximum execution cap set at 100).
domain string — Exact string match filter for targeted domain analytics routing.
Sample Structured Output 
{
  "results": [
    {
      "data": { 
          "ID": 101, 
          "URL": "https://example.com/ecommerce-strategy", 
          "StatusCode": 200, 
          "Title": "Advanced eCommerce SEO Architecture" 
      },
      "score": { 
          "overall": 92, 
          "grade": "A+" 
      }
    }
  ],
  "total": 450,
  "page": 1,
  "limit": 25
}

Programmatic File Retrieval & Export APIs

GET /api/v1/sessions/:id/export

Bypass HTML rendering engines entirely by programmatically initiating direct PDF binary downloads of comprehensive SEO reports. Perfect for automated client deliverable pipelines and archiving monthly technical health overviews.

Server transmits immediate binary sequence payloads configured with standard Content-Disposition: attachment headers overriding browser DOM manipulation pipelines.
POST /api/v1/sessions/:id/email

Execute asynchronous mail transport actions mapping specific SEO audit profiles and PDF documents directly into recipient SMTP gateways. Integrates effortlessly via standard RESTful POST payloads containing precise destination metadata structures.

POST Request Configuration (JSON) 
{
  "to": "senior.developer@ecommerce-startup.com",
  "subject": "Critical Technical Architecture Review Variables - Generated securely via RankSavanna platform API",
  "formats": ["pdf"]
}
Navigation Map
Architecture Node
v1 Production Core