Skip to main content

​
Prerequisites

  • A SuprKeywords account (sign up at suprkeywords.com/app).
  • At least one run (credit). Purchase run packs from the dashboard if needed.
  • Your primary domain and, optionally, competitor domains.

​
Base URL and authentication

  • Base URL (API): https://www.suprkeywords.com. All API endpoints live under /api/v1/ (e.g. https://www.suprkeywords.com/api/v1/jobs). The dashboard is at suprkeywords.com/app.
  • Authentication: For programmatic calls (curl, scripts, server-to-server), use an API key. Create one in the dashboard under Settings → API Keys (Agency plan required). Send it as Authorization: Bearer <your-api-key> or X-API-KEY: <your-api-key>. When using the dashboard in a browser, session cookies are used automatically.

​
Step 1: Create a job

POST /api/v1/jobs creates a new keyword research job and starts the pipeline. 
curl -X POST "https://www.suprkeywords.com/api/v1/jobs" \
  -H "Content-Type: application/json" \
  -d '{
    "primaryDomain": "example.com",
    "competitorDomains": ["competitor.com"],
    "languageCode": "en",
    "locationCode": 2840
  }'
Include your API key in the header for authenticated requests. Example with Bearer (or use X-API-KEY: YOUR_API_KEY): 
curl -X POST "https://www.suprkeywords.com/api/v1/jobs" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{ "primaryDomain": "example.com", "languageCode": "en", "locationCode": 2840 }'
From the dashboard, you can create jobs via the New Job form without an API key (session is used). Response (201): 
{
  "job": {
    "id": "uuid",
    "status": "queued",
    "createdAt": "2026-02-19T00:00:00.000Z"
  }
}

​
Step 2: Poll job status

GET /api/v1/jobs/{jobId} returns status, progress, and (when completed or failed) total keyword count. 
curl "https://www.suprkeywords.com/api/v1/jobs/YOUR_JOB_ID"
When status is completed, proceed to fetch results. When status is failed, check errorMessage.

​
Step 3: Fetch results

  • Personas: GET /api/v1/jobs/{jobId}/personas
  • Keywords: GET /api/v1/jobs/{jobId}/keywords (supports limit, offset, search, filters, sorting)
  • Clusters: GET /api/v1/jobs/{jobId}/clusters
  • Keywords in a cluster: GET /api/v1/jobs/{jobId}/clusters/{clusterId}/keywords
  • Export CSV: GET /api/v1/jobs/{jobId}/export-keywords (returns text/csv)
Example: 
curl "https://www.suprkeywords.com/api/v1/jobs/YOUR_JOB_ID/keywords?limit=10&sortBy=organicOpportunityScore&sortOrder=desc"

​
Listing languages and locations

  • GET /api/v1/languages – (e.g. for the New Job form).
  • GET /api/v1/locations – (e.g. United States = 2840).
No authentication required for these endpoints.

​
Next steps

  • See the API Reference for full endpoint details, parameters, and response schemas.
  • Use the dashboard at suprkeywords.com/app to create jobs and explore results in the UI.