v7.1.7 GitHub

GuinRank API Reference

Comprehensive technical guide to interact with GuinRank services and tools programmatically with Owner and Member role permissions.

v7.1.7 API Version
RESTful Architecture
JSON Response Format
RBAC Owner & Team Scopes

Authentication & Requests

Pass your API Key in the HTTP request headers using one of the following formats:
1. X-Api-Key: gr_prod_xxxxxxxxxxxx (Recommended / Standard)
2. Authorization: ApiKey gr_prod_xxxxxxxxxxxx

How to Get & Use Your API Key

  1. Sign Up or Log In: If you do not have an account yet, sign up or log into GuinRank.
  2. Navigate to your Profile Dashboard ➔ and select the API Keys tab.
  3. Click "Create New Key" and provide a descriptive name for your application or tool.
  4. Copy your generated secret key immediately (starts with gr_prod_...). It will not be shown again for security reasons.

Owner API Key

Generated directly from the account owner's Profile. Unrestricted access to all tools, projects, articles, team management, and billing data.

Full Workspace Access

Team Member API Key

Generated for a specific member via POST /api/team/{id}/api-key. Inherits the assigned member role (Manager, Editor, or Viewer) and operates strictly within their credit quota.

Scoped by Member Role & Quota

Multi-Tier Roles & Permissions (RBAC Architecture)

GuinRank enforces granular Role-Based Access Control (RBAC). API Keys distinguish between the Workspace Owner and individual Team Members based on their assigned role:

Owner

Workspace Owner

Root authority. Full privileges across all tools, articles, billing, invoices, member invitation, and master API key generation.

Manager

Team Manager

Administrative member. Can manage team members, generate member API keys, create/delete articles, and run all analytical tools.

Editor

Content Editor

Content producer. Can create, edit, and optimize articles and use keyword tools, consuming credits within assigned quota. Cannot delete articles or view billing.

Viewer

Read-Only Viewer

Analyst / Stakeholder. Read-only access to search and view existing articles, keyword analyses, and SERP reports. Cannot create, edit, or delete items.

RBAC Endpoint Permission Matrix

Resource / Feature Area Owner Manager Editor Viewer
Keyword Analyzer & Research Tools
/api/keyword-analyzer/*, /api/keyword-research/*
Full Full (Quota) Full (Quota) Read Cached Only
Articles & Projects (Search & Read)
/projects-management/article/search, /project/search
Allowed Allowed Allowed Allowed
Articles & Content Optimizer (Create / Save)
POST /projects-management/article, POST /content-optimizer/*/save
Allowed Allowed Allowed Forbidden 403
Article Deletion
DELETE /projects-management/article/{id}
Allowed Allowed Forbidden 403 Forbidden 403
Team Management & Member API Keys
GET /api/team, POST /api/team/{id}/api-key
Allowed Allowed Forbidden 403 Forbidden 403
Billing, Invoices & Workspace Settings
/api/billing/*, /api/me/api-keys
Allowed Forbidden 403 Forbidden 403 Forbidden 403
Web Scraper & Live SERP Engine
/api/scraper/extract, /api/scraper/search, /api/scraper/crawl
Allowed Allowed (Quota) Allowed (Quota) Forbidden 403

Quota Enforcement & Error Responses

When a Team Member API Key makes a request, credits are deducted from the Workspace Owner's account balance, subject to the member's monthly quota. If an action is forbidden or a quota is exceeded, the API immediately returns an HTTP 403 Forbidden status with a structured JSON error:

{
  "success": false,
  "error": "Only the workspace owner or authorized manager can perform this action."
}

Rate Limits & Credit Policies

Live Dynamic Sync (Cpanel)

Operational request limits and credit multipliers are continuously synchronized with our API Cloud Gateway and Control Panel (Cpanel). Any policy changes made by administrators in the Control Panel take effect automatically within 30 seconds.

Per-Second Limit
2 req / sec
Sliding 1-second request window per API key / IP.
Burst Window (10s)
5 req / 10 sec
Maximum burst allowed across any 10-second rolling window.
REST API Multiplier
2x Credit Cost
Applied to credit-consuming tools called via direct API.
MCP Server Multiplier
2x Credit Cost
Applied to tool executions requested by AI agents via MCP.

Project & Article Creation Policy (Exempt from Multipliers)

  • Project & Workspace Folders: Completely FREE (0 Credits). Creating folders and organizing projects does not consume credits and is never multiplied.
  • Article Creation: Counted on a 1:1 single-unit basis (1x) against the team member's assigned article allocation (MaxProjects). No multiplier is applied to project counts.
  • Multiplier Scope: The 2x multiplier strictly applies to computationally intensive analytical endpoints (e.g., Web Scraper, Domain Analysis, Keyword Tools, and SERP extraction).

HTTP 429 Rate Limit Response Specification

If an integration exceeds the rate limit, the API Gateway returns an HTTP 429 Too Many Requests with a standard Retry-After header indicating the number of seconds to back off:

Response 429 (Too Many Requests)
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 10

{
  "success": false,
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Limit is 5 requests per 10 seconds (and 2/sec) for API automation. Please slow down.",
  "retryAfter": 10
}

Languages, Countries & Geo Locations Explorer

Interactive live explorer for all supported languages, countries, and Google Ads Geo IDs — loaded dynamically from the Cache Server just as platform tools do.

Dynamic Lookup Endpoints

Call these programmatic endpoints to fetch real-time lookup dictionaries, or embed data.js directly into your client applications:

GET /api/lookup/languages JSON
List of all supported languages with numeric langId and ISO codes.
GET /api/lookup/countries JSON
List of countries with numeric countryId for Keyword Analyzer.
GET /api/lookup/research-locations JSON
Google Ads Geo Criterion IDs for Keyword Research cities & countries.
GET /api/lookup/engines JSON
Search engines supported across Keyword Generator and SERP Scraper.

Languages

0
Language Language ID (langId) ISO Code Direction
Fetching data from cache server...

Countries

0
Country Country ID (countryId) ISO Code
Fetching data from cache server...

Targeting Geo Locations (Countries & Cities) in Keyword Research

The Keyword Research tool connects to Google Ads Geo database (bundled also in data.js). You can target an entire country or a specific city/state with pinpoint accuracy:

1. Pass Location Names: locationNames

Pass country or city names in English. The system matches them automatically:

// Target an entire country:
"locationNames": ["Egypt"]
// Or target a specific city:
"locationNames": ["Cairo"]
// Or target multiple cities together:
"locationNames": ["Riyadh", "Jeddah"]

2. Pass Google Ads Criterion IDs: locationIds

Pass numeric Google Ads Criterion IDs in an array of numbers:

  • Egypt (Country): [2818] | Cairo (City): [1005388]
  • Saudi Arabia (Country): [2682] | Riyadh (City): [1012088]
  • United States (Country): [2840] | New York (City): [1023191]
  • United Arab Emirates: [2784] | Dubai (City): [1014044]
  • United Kingdom: [2826] | London (City): [1006886]
Programmatic Geo Lookups & Direct Database Download:

• Search for any city's ID by name: GET /api/lookup/research-locations?search=cairo
• Fetch all cities/regions for a specific country: GET /api/lookup/research-locations?countryIso=EG
• Download the direct JS database for offline/client usage: /script/data.js (contains LocalGeo for global regions and LangGeo for languages).

Search Engines in Keyword Generator

When calling GET /api/keyword-generator/run, the engine parameter determines the suggestion source:

"google"
Google search suggestions and top SERP autocomplete.
"youtube"
YouTube video and content search suggestions.
"bing"
Microsoft Bing search engine and Copilot suggestions.
"amazon"
Amazon commercial buyer intent suggestions.

Keyword Analyzer & Content Optimizer

POST /api/keyword-analyzer/analyze
Member+ 1 Credit

Analyzes a target keyword in real-time, extracting competitor metrics, N-Grams, suggested keywords, and top 10 Google search results.

Request Body Parameters (JSON)
FieldTypeRequiredDescription
keyword string Yes Seed keyword to analyze (e.g. "best coffee maker")
countryId int Yes Target country identifier (e.g. 1 for Egypt, 191 for USA)
langId int Yes Target language identifier (e.g. 1 for Arabic, 2 for English)
engine string Optional Search engine source, defaults to "google"
Code Examples
curl -X POST "https://sync.guinrank.com/api/keyword-analyzer/analyze" \
  -H "X-Api-Key: gr_prod_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "best coffee maker",
    "countryId": 191,
    "langId": 2,
    "engine": "google"
  }'
POST /api/content-optimizer/{idOrCode}/save
Editor / Manager Free

Saves and updates article content, metadata, and live SEO score in the Content Optimizer editor.

Request Body Parameters (JSON)
FieldTypeDescription
title string Main article H1 headline
body string Full article body content formatted as HTML or rich text
metaTitle string Meta title for search engine snippet
metaDescription string Meta description for search engine snippet
seoScore decimal GuinRank SEO optimization score (0 - 100)

Projects & Articles Management

POST /api/projects-management/article
Editor+ Project Quota

Creates a new article and links it to an existing keyword and project directory. For team members, validates against their assigned MaxProjects quota.

Request Body Parameters (JSON)
FieldTypeRequiredDescription
name string Yes Article title or name
keywordFK long Yes Foreign key ID of the analyzed keyword
projectFK long Optional Project directory ID (if omitted, saved in default root workspace)

Team & API Keys Management

POST /api/team/{id}/api-key
Manager / Owner

Generates a scoped API Key for an authorized team member. Inherits the member's assigned role (Manager, Editor, or Viewer) and quota boundaries.

Request Body Parameters (JSON)
FieldTypeDescription
name string Descriptive label for the key (e.g. "Omar MCP Cursor Key")

Web Scraper & SERP Engine

POST /api/scraper/extract
Member+ 1 Credit

Extracts high-fidelity article and content text from any webpage, stripping ads, navbars, and boilerplate markup, and converts it to Markdown, clean HTML, or plain text.

Request Body Parameters (JSON)
FieldTypeRequiredDescription
url string Yes Target webpage URL (e.g. "https://example.com/blog/article")
format string Optional Output format: "Markdown" (default), "Html", "PlainText"
useProxy bool Optional Routes request through smart proxy pool to bypass cloud protections (default: false)
Code Examples
curl -X POST "https://sync.guinrank.com/api/scraper/extract" \
  -H "X-Api-Key: gr_prod_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/article",
    "format": "Markdown",
    "useProxy": true
  }'
POST /api/scraper/crawl
Manager+ 5 Credits

Launches a background asynchronous Deep Crawl Job to recursively fetch, index, and extract pages across an entire target domain.

Request Body Parameters (JSON)
FieldTypeRequiredDescription
url string Yes Root starting website URL (e.g. "https://example.com")
maxPages int Optional Maximum total pages to crawl (default: 100)
maxDepth int Optional Maximum hyperlink depth level (default: 3)
respectRobotsTxt bool Optional Strictly honor robots.txt directives (default: true)
Job Status & Export

Returns a jobId immediately. You can track progress or retrieve exports using:
• GET /api/scraper/jobs/{jobId} to poll progress status.
• GET /api/scraper/export/json/{jobId} to download full crawled data in JSON or CSV.

Keyword Ideas & Research

POST /api/keyword-research/analyze
Member+ 1 Credit

Generates related keyword ideas from a seed keyword with monthly search volumes, CPC, Keyword Difficulty (KD), and search intent classification.

Request Body Parameters (JSON)
FieldTypeRequiredDescription
keyword string Yes Seed keyword to explore (e.g. "digital marketing")
locationNames string[] Optional Array of target country/city names (e.g. ["Saudi Arabia"] or ["Egypt"])
locationIds long[] Optional Array of Google Ads Criterion IDs (e.g. [2682] for Saudi Arabia, [2818] for Egypt)
langIso string Optional ISO language code (e.g. "ar" for Arabic, "en" for English)
forceUpdate bool Optional Bypass cache and fetch fresh live data (default: false)
Code Examples
curl -X POST "https://sync.guinrank.com/api/keyword-research/analyze" \
  -H "X-Api-Key: gr_prod_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "digital marketing",
    "locationNames": ["Saudi Arabia"],
    "langIso": "ar"
  }'
GET /api/keyword-generator/run
Member+ 1 Credit

Generates long-tail keyword suggestions across multiple engines (Google, YouTube, Bing, Amazon) with alphabetical expansions and intent classification.

Query Parameters
ParameterTypeRequiredDescription
keyword string Yes Seed query to expand (e.g. "seo")
engine string Optional Search engine: "google" (default), "youtube", "bing", "amazon"
langId int Optional Language ID (e.g. 1 for Arabic, 2 for English)
locId int Optional Country ID (e.g. 1 for Egypt, 187 for Saudi Arabia)
Code Examples
curl -X GET "https://sync.guinrank.com/api/keyword-generator/run?keyword=seo&engine=google&langId=1&locId=1" \
  -H "X-Api-Key: gr_prod_your_api_key_here"
GET /api/analysis/backlink-cleanup?target={domain}
Public / Auth 0 Credits (Free)

Retrieves stored backlink audit datasets for a target domain, multi-signal toxic link evaluations, risk scores, and currently applied disavow / safe rules.

Query Parameters
ParameterTypeRequiredDescription
targetstringYesTarget domain name (e.g. "example.com")
POST /api/analysis/backlink-cleanup/investigate
Member+ 1 Credit (0 if Cached)

Performs in-depth live forensic investigation of a single backlink source webpage. Uncovers why the backlink is there, exact placement, DOM context, spam patterns, platform footprints (WordPress, Shopify, etc.), and contact emails. Protected against SSRF and duplicate billing via request coalescing. Dual-tier 14-day cache.

Request Body Parameters (JSON)
FieldTypeRequiredDescription
sourceUrlstringYesSource webpage URL hosting the backlink
targetUrlstringYesTarget URL being linked to
anchorstringOptionalAnchor text expected on the page
modestringOptionalInvestigation mode: "Quick", "Standard", or "Deep"
forceRefreshboolOptionalBypasses 14-day cache to force fresh re-fetch (costs 1 credit)
reuseDomainEvidenceOnlyboolOptionalReuses domain-level intelligence from sibling links
POST /api/analysis/backlink-cleanup/investigate/batch
Member+ 1 Credit / fresh fetch

Executes batch forensic investigation across multiple backlink source pages. Only charges 1 credit for un-cached external fetches (cache hits are 0 credits).

POST /api/analysis/backlink-cleanup/investigate/estimate
Public / Auth 0 Credits (Free)

Calculates how many links in a proposed batch are already present in cache (0 Credits) versus how many need external fetching (1 Credit each), and checks quota availability.

POST /api/analysis/backlink-cleanup/rule
Authenticated 0 Credits (Free)

Saves or updates a cleanup decision rule for a domain or specific URL (Disavow, Safe, Review, Ignore).

DEL /api/analysis/backlink-cleanup/rule/{id}
Authenticated 0 Credits (Free)

Removes an applied cleanup decision rule by rule ID.

GET /api/analysis/backlink-cleanup/export-disavow?target={domain}
Authenticated 0 Credits (Free)

Generates and downloads the certified Google Search Console Disavow TXT file, fully compliant with Google RFC formatting.

POST /api/analysis/backlink-cleanup/verify-removal
Member+ 1 Credit

Re-checks if a requested toxic link has actually been deleted from the source page ("Check Again") without erasing historical notes. Returns: Removed, Still Present, or Source Unavailable.

POST /api/analysis/backlink-cleanup/removal-template
Public / Auth 0 Credits (Free)

Generates a polite, professional, and personalized outreach email template to request manual backlink removal from the hosting webmaster.

POST /api/analysis/backlink-cleanup/validate-disavow
Public / Auth 0 Credits (Free)

Validates disavow rules for Google Search Console RFC compliance, detecting syntax errors, duplicate entries, redundant sub-URLs, and accidental disavow of high-authority legitimate domains.

POST /api/analysis/backlink-cleanup/update
Member+ Paid Credits

Triggers live backlink data refresh from data providers for the domain. Deducts paid credits.

Restricted & Sensitive Endpoints (UI / JWT Only)

Security Policy: To protect accounts from automated takeover and unauthorized destruction, the following endpoints are strictly blocked from API Key and MCP invocations:
MethodEndpointSecurity Restriction
POST /api/me/change-password-otp Password changes require interactive UI flow and email OTP validation.
PATCH /api/me/change-password Restricted to interactive sessions with validated OTP tokens.
POST /api/me/delete-account-confirm Permanent account deletion is strictly restricted to Workspace Owner in web UI.
DEL /api/me/sessions/all Session revocation requires human interactive authentication.
POST /api/me/api-keys Master account API keys must be generated manually in the Profile web dashboard.