> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suprkeywords.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Create a keyword research job and fetch results using the SuprKeywords API

## Prerequisites

* A SuprKeywords account (sign up at [suprkeywords.com/app](https://www.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](https://www.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.

```bash theme={null}
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):

```bash theme={null}
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):

```json theme={null}
{
  "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.

```bash theme={null}
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:

```bash theme={null}
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](/api-reference/introduction) for full endpoint details, parameters, and response schemas.
* Use the dashboard at [suprkeywords.com/app](https://www.suprkeywords.com/app) to create jobs and explore results in the UI.