API Reference

​

Base URL

All API endpoints are relative to the web app base URL: Full path for versioned API: {baseUrl}/api/v1/.... Example: https://suprkeywords.com/app/api/v1/jobs.

​

Authentication

• Dashboard (browser): Requests from the SuprKeywords web app use Clerk session cookies. No API key is required when using the app at suprkeywords.com/app.
• Programmatic access: API keys for server-to-server or scripted calls are planned for a future release (Milestone 4). Until then, authenticated API use is via the dashboard or by sending the same session cookies as the browser.
• Demo access: Some GET endpoints allow unauthenticated access when the job is the demo account’s job (for public demo sharing).

Endpoints that require authentication return 401 Unauthorized when the session is missing or invalid.

​

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 is generated from our OpenAPI spec. It 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).

Internal endpoints (cache clear, webhooks, locale-suggest) are not documented in the public reference. Use the sidebar or the tabs above to open a specific endpoint for parameters, request bodies, and response schemas.