Public API Reference

Base URL: https://rankfabric-edge.grocerybundles.workers.dev

Authentication

All endpoints require an API key passed via:

• Header: Authorization: Bearer sk_live_xxxxx
• Header: X-API-Key: sk_live_xxxxx
• Query: ?api_key=sk_live_xxxxx

---

Keywords

Track Keyword

Start tracking a keyword for SERP rankings.

POST /api/keywords/track

Request:

{
  "project_id": "proj_abc123",
  "keyword": "best seo tools",
  "location_code": 2840,
  "language_code": "en",
  "device": "desktop"
}

Response:

{
  "success": true,
  "keywords_tracked": 1,
  "keywords": [
    {
      "keyword_id": "kw_xyz789",
      "keyword_text": "best seo tools",
      "status": "tracking",
      "serp_queued": true
    }
  ],
  "serp_tracking": {
    "orchestration": "workflow",
    "keywords_queued": 1
  },
  "estimated_completion": "2025-12-24T00:05:00.000Z"
}

Parameter	Type	Required	Description
project_id	string	Yes	Project ID
keyword	string	Yes	Keyword to track
location_code	number	No	Google location code (default: 2840 = US)
language_code	string	No	Language code (default: "en")
device	string	No	"desktop" or "mobile" (default: "desktop")

---

Get Project Keywords

List all keywords tracked for a project.

GET /api/project-keywords?project_id={id}&channel={channel}

Response:

{
  "success": true,
  "keywords": [
    {
      "keyword_id": "kw_xyz789",
      "keyword_text": "best seo tools",
      "search_volume": 12000,
      "cpc": 4.50,
      "competition": 0.65,
      "keyword_difficulty": 45,
      "current_rank": 7,
      "ranking_domain": "example.com",
      "tracking_since": "2025-12-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 50,
    "limit": 100,
    "offset": 0,
    "has_more": false
  }
}

Parameter	Type	Required	Description
project_id	string	Yes	Project ID
channel	string	No	Filter by channel (e.g., "google_serp")
status	string	No	Filter by status (default: "active")
limit	number	No	Results per page (default: 100)
offset	number	No	Pagination offset

---

Get Keyword Overview

Get detailed metrics for keywords.

POST /api/keywords/overview

Request:

{
  "keywords": ["seo tools", "keyword research"],
  "location_code": 2840,
  "language_code": "en"
}

Response:

{
  "success": true,
  "keywords": [
    {
      "keyword": "seo tools",
      "search_volume": 22000,
      "cpc": 8.50,
      "competition": 0.78,
      "competition_level": "HIGH",
      "keyword_difficulty": 67,
      "search_intent": "informational",
      "monthly_searches": [
        {"year": 2025, "month": 11, "search_volume": 24000},
        {"year": 2025, "month": 10, "search_volume": 21000}
      ]
    }
  ]
}

---

Rankings

Get Rankings

Get SERP rankings for tracked keywords.

GET /api/rankings?project_id={id}&keyword_id={keyword_id}

Response:

{
  "success": true,
  "rankings": [
    {
      "keyword_id": "kw_xyz789",
      "keyword_text": "seo tools",
      "domain": "example.com",
      "rank_absolute": 7,
      "ranking_url": "https://example.com/seo-tools",
      "is_featured_snippet": false,
      "check_ts": 1703376000000,
      "year_week": "2025-W52"
    }
  ]
}

---

Assets

Onboard Asset

Add a new asset (website, app, or local business) to a project.

POST /api/assets

Request (Website):

{
  "project_id": "proj_abc123",
  "asset_type": "website",
  "url": "https://example.com"
}

Request (App):

{
  "project_id": "proj_abc123",
  "asset_type": "app",
  "app_id": "com.example.app",
  "platform": "google_play"
}

Response:

{
  "success": true,
  "asset_id": "ast_xyz789",
  "orchestration": "workflow",
  "workflow_id": "wf_abc123",
  "status_url": "/api/admin/workflow/asset-onboard/wf_abc123"
}

Parameter	Type	Required	Description
project_id	string	Yes	Project ID
asset_type	string	Yes	"website", "app", or "local_business"
url	string	For website	Website URL
app_id	string	For app	App store ID
platform	string	For app	"apple" or "google_play"
cid	string	For local_business	Google CID

---

Projects

List Projects

GET /api/projects

Response:

{
  "success": true,
  "projects": [
    {
      "id": "proj_abc123",
      "name": "My SEO Campaign",
      "created_at": "2025-12-01T00:00:00.000Z"
    }
  ]
}

Create Project

POST /api/projects

Request:

{
  "name": "My SEO Campaign"
}

---

Domains

Get Domain Summary

GET /api/domains/{domain}/summary

Response:

{
  "domain": "example.com",
  "backlinks_count": 1250,
  "referring_domains_count": 340,
  "ranked_keywords_count": 890,
  "onboard_status": "complete",
  "last_updated": "2025-12-23T12:00:00.000Z"
}

---

Error Responses

All errors follow this format:

{
  "error": "Error type",
  "message": "Human-readable description",
  "details": "Additional context (optional)"
}

Status	Meaning
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
404	Not Found - Resource doesn't exist
429	Rate Limited - Too many requests
500	Server Error - Something went wrong

---

Rate Limits

• Standard: 100 requests/minute
• Burst: 10 requests/second

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1703376060

---

Location Codes

Common Google location codes:

Code	Location
2840	United States
2826	United Kingdom
2036	Australia
2124	Canada
2276	Germany
2250	France

Full list available at DataForSEO Locations.