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

# API Reference

> SuprKeywords REST API — base URL, authentication, and endpoint overview

## Base URL

All API endpoints are under the base URL:

| Environment | Base URL                       |
| ----------- | ------------------------------ |
| Production  | `https://www.suprkeywords.com` |

Full path for versioned API: `{baseUrl}/api/v1/...`. Example: `https://www.suprkeywords.com/api/v1/jobs`.

The API Reference **Try it** controls (on each endpoint) let you send live requests from your browser. Use the **server** dropdown to choose **Production** or **Local**. When you choose **Local**, the request goes to your machine — have the API running locally (e.g. `pnpm dev`) and use the same port as in the Local server URL in your OpenAPI spec. For protected endpoints, enter your **Bearer (API key)** or use session auth.

## Authentication

* **Programmatic access (API keys):** For scripts, server-to-server calls, and any non-browser client, authenticate with an API key. Create keys in **Settings → API Keys** in the dashboard (requires the Agency plan). Send the key in the request header as either `Authorization: Bearer <your-api-key>` or `X-API-KEY: <your-api-key>`. Endpoints that require authentication accept either header and return `401 Unauthorized` when the key is missing or invalid.
* **Dashboard (browser):** When using the SuprKeywords web app at [suprkeywords.com/app](https://www.suprkeywords.com/app), the app uses session cookies. No API key is needed in the browser.
* **Demo access:** Some GET endpoints allow unauthenticated access when the job belongs to the demo account (for public demo sharing).

Endpoints that require authentication return `401 Unauthorized` when neither a valid session (dashboard) nor a valid API key (Bearer or X-API-KEY) is provided.

## Rate limits and quotas

* Job creation consumes one **run** (credit) per job. Ensure your account has available runs before `POST /api/v1/jobs`.
* **Domain limit:** Each new primary domain counts against your account’s domain allowance. Existing primary domains do not.

## Response format

* Success: JSON body with the requested data. Paginated endpoints include `total`, `limit`, and `offset` where applicable.
* Errors: JSON with an `error` or `message` field and optional `details`. HTTP status codes: `400` (validation), `401` (unauthorized), `402` (insufficient runs), `403` (e.g. domain limit), `404` (not found), `500` (server error).

## Endpoints

The **Endpoints** section in the sidebar includes:

* **Jobs** – Create job, list jobs, get/delete job, get personas, keywords, clusters, references, export CSV.
* **Users** – Get current user and balances (`GET /api/v1/users/me`).
* **Locale** – List languages and locations (`GET /api/v1/languages`, `GET /api/v1/locations`).

Use the sidebar or the tabs above to open a specific endpoint for parameters, request bodies, and response schemas.