Skip to main content

​
Base URL

All API endpoints are under the base URL:
EnvironmentBase URL
Productionhttps://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, 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.