Quickstart

​

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

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
  }'

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 }'

{
  "job": {
    "id": "uuid",
    "status": "queued",
    "createdAt": "2026-02-19T00:00:00.000Z"
  }
}

​

Step 2: Poll job status

curl "https://www.suprkeywords.com/api/v1/jobs/YOUR_JOB_ID"

​

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)

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).

​

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.