Authentication & Requests
1.
X-Api-Key: gr_prod_xxxxxxxxxxxx (Recommended / Standard)
2.
Authorization: ApiKey gr_prod_xxxxxxxxxxxx
How to Get & Use Your API Key
- Sign Up or Log In: If you do not have an account yet, sign up or log into GuinRank.
- Navigate to your Profile Dashboard ➔ and select the API Keys tab.
- Click "Create New Key" and provide a descriptive name for your application or tool.
- 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.
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.
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:
Workspace Owner
Root authority. Full privileges across all tools, articles, billing, invoices, member invitation, and master API key generation.
Team Manager
Administrative member. Can manage team members, generate member API keys, create/delete articles, and run all analytical tools.
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.
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.
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
2xmultiplier 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:
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
langId and ISO codes.
GET /api/lookup/countries
JSON
countryId for Keyword Analyzer.
GET /api/lookup/research-locations
JSON
GET /api/lookup/engines
JSON
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]
• 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""youtube""bing""amazon"Keyword Analyzer & Content Optimizer
Analyzes a target keyword in real-time, extracting competitor metrics, N-Grams, suggested keywords, and top 10 Google search results.
| Field | Type | Required | Description |
|---|---|---|---|
| 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" |
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"
}'
Saves and updates article content, metadata, and live SEO score in the Content Optimizer editor.
| Field | Type | Description |
|---|---|---|
| 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
Creates a new article and links it to an existing keyword and project directory. For team members, validates against their assigned MaxProjects quota.
| Field | Type | Required | Description |
|---|---|---|---|
| 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
Generates a scoped API Key for an authorized team member. Inherits the member's assigned role (Manager, Editor, or Viewer) and quota boundaries.
| Field | Type | Description |
|---|---|---|
| name | string | Descriptive label for the key (e.g. "Omar MCP Cursor Key") |
Web Scraper & SERP Engine
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.
| Field | Type | Required | Description |
|---|---|---|---|
| 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) |
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
}'
Live SERP scraper collecting ranking URLs, titles, and snippets across Google, Bing, or DuckDuckGo for competitive intelligence.
| Field | Type | Required | Description |
|---|---|---|---|
| keyword | string | Yes | Target search query (e.g. "best coffee machine 2026") |
| engine | string | Optional | Search engine: "Google" (default), "Bing", "DuckDuckGo" |
| countryCode | string | Optional | ISO country code (e.g. "us", "eg", "sa") |
| pages | int | Optional | Number of SERP pages to fetch (default: 1) |
curl -X POST "https://sync.guinrank.com/api/scraper/search" \
-H "X-Api-Key: gr_prod_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"keyword": "best coffee machine 2026",
"engine": "Google",
"countryCode": "us",
"pages": 1
}'
Launches a background asynchronous Deep Crawl Job to recursively fetch, index, and extract pages across an entire target domain.
| Field | Type | Required | Description |
|---|---|---|---|
| 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) |
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
Generates related keyword ideas from a seed keyword with monthly search volumes, CPC, Keyword Difficulty (KD), and search intent classification.
| Field | Type | Required | Description |
|---|---|---|---|
| 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) |
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"
}'
Generates long-tail keyword suggestions across multiple engines (Google, YouTube, Bing, Amazon) with alphabetical expansions and intent classification.
| Parameter | Type | Required | Description |
|---|---|---|---|
| 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) |
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"
Backlinks Intelligence & Cleanup Forensic Engine
Audits the live link graph for a target domain or URL. Checks the high-efficiency compressed database cache before calling live providers. Returns granular backlink items, referring domains, toxic link footprints, and anchor distribution.
| Field | Type | Required | Description |
|---|---|---|---|
| target | string | Yes | Target domain or URL (e.g. "example.com") |
| mode | string | Optional | Audit mode: "as_is", "exact", or "subdomains" (default: "as_is") |
| limit | int | Optional | Max backlink items to retrieve (default: 100) |
| offset | int | Optional | Pagination offset (default: 0) |
| forceRefresh | bool | Optional | Bypasses cache to force fresh live audit |
Retrieves stored backlink audit datasets for a target domain, multi-signal toxic link evaluations, risk scores, and currently applied disavow / safe rules.
| Parameter | Type | Required | Description |
|---|---|---|---|
| target | string | Yes | Target domain name (e.g. "example.com") |
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.
| Field | Type | Required | Description |
|---|---|---|---|
| sourceUrl | string | Yes | Source webpage URL hosting the backlink |
| targetUrl | string | Yes | Target URL being linked to |
| anchor | string | Optional | Anchor text expected on the page |
| mode | string | Optional | Investigation mode: "Quick", "Standard", or "Deep" |
| forceRefresh | bool | Optional | Bypasses 14-day cache to force fresh re-fetch (costs 1 credit) |
| reuseDomainEvidenceOnly | bool | Optional | Reuses domain-level intelligence from sibling links |
Executes batch forensic investigation across multiple backlink source pages. Only charges 1 credit for un-cached external fetches (cache hits are 0 credits).
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.
Saves or updates a cleanup decision rule for a domain or specific URL (Disavow, Safe, Review, Ignore).
Removes an applied cleanup decision rule by rule ID.
Generates and downloads the certified Google Search Console Disavow TXT file, fully compliant with Google RFC formatting.
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.
Generates a polite, professional, and personalized outreach email template to request manual backlink removal from the hosting webmaster.
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.
Triggers live backlink data refresh from data providers for the domain. Deducts paid credits.
Restricted & Sensitive Endpoints (UI / JWT Only)
| Method | Endpoint | Security 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. |