API Access

Programmatic access and direct feedback capture via API keys.

ProductSights provides API key authentication for programmatic access. Use API keys to integrate ProductSights into custom workflows, scripts, automation, and direct feedback capture.

API key types

ProductSights supports two types of API keys:

Type	Prefix	Use case	Capabilities
Secret	`ps_`	Server-side scripts, CI pipelines, data export	Full access — read insights, clusters, analytics, and capture feedback
Publishable	`ps_pub_`	Client-side code (widgets, browser extensions, custom capture forms)	Capture-only — can submit feedback but cannot read insights, clusters, or analytics

Use publishable keys whenever the key will be visible in client-side code (HTML, JavaScript bundles). They are safe to include in frontend code because they can only submit feedback, not read your data.

Domain restrictions

Publishable keys support optional domain restrictions. When configured, the key will only accept requests from specified domains and subdomains. The server validates the Origin and Referer headers on each request.

Configure domain restrictions when creating or editing a publishable key in Settings → API Keys.

Creating an API key

Go to Settings → API Keys
Make sure you've selected your role/department in onboarding
Click Create API key
Choose the key type — Secret or Publishable
Give the key a descriptive name (e.g., "CI Pipeline" or "Website Widget")
For publishable keys, optionally add domain restrictions
Copy the generated key — it won't be shown again

Using your API key

Include the API key in the Authorization header of your requests:

Authorization: Bearer ps_your_api_key_here

Available endpoints

API keys provide access to the same endpoints used by the ProductSights dashboard and public capture clients:

Endpoint	Method	Description
`/api/insights`	GET	List insights with filters
`/api/insights`	POST	Create a new insight
`/api/insights/[id]/refresh-analytics`	POST	Refresh analytics for one insight
`/api/insights/bulk-refresh-analytics`	POST	Queue bulk analytics refresh (body: `{ insightIds: string[] }`)
`/api/clusters`	GET	List insight clusters
`/api/analytics/ai-query`	POST	Run an AI-powered analytics query
`/api/analytics-integrations`	GET, POST	List or create analytics integrations
`/api/analytics-integrations/[id]`	GET, PATCH, DELETE	Manage analytics integration
`/api/analytics-integrations/[id]/test`	POST	Test analytics connection
`/api/analytics-integrations/[id]/sync-catalog`	POST	Sync event catalog
`/api/analytics-integrations/[id]/mappings`	GET, PUT	Event mappings
`/api/public/capture`	POST	Submit feedback from widgets, browser extensions, or custom clients

Direct feedback capture

Use /api/public/capture when you want to send feedback directly into the ProductSights triage pipeline from your own client or script.

curl -X POST https://productsights.io/api/public/capture \
  -H "Authorization: Bearer ps_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Customers keep missing the export button on the reports page",
    "context": "Captured from an internal QA run",
    "pageUrl": "https://app.example.com/reports",
    "pageTitle": "Reports",
    "customerName": "Taylor",
    "customerEmail": "[email protected]",
    "tags": ["qa", "reports"],
    "sourceType": "api"
  }'

Supported sourceType values for this endpoint are widget, browser-extension, and api. You can also attach a screenshotDataUrl field when sending feedback from a client that captures screenshots.

Rate limits

API requests are rate-limited to protect service quality:

Authenticated requests: 60 requests per minute
Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
If you exceed the limit, you'll receive a 429 Too Many Requests response with a Retry-After header

Managing keys

From the API Keys settings page:

View all active keys and their creation dates
Revoke keys that are no longer needed
Create new keys for different use cases

API key owners must select their role/department during onboarding before keys can be used for capture flows.

Security best practices

Never commit secret API keys to source control
Use environment variables to store secret keys on the server
Use publishable keys (not secret keys) in any client-side code — widgets, browser extensions, or frontend apps
Enable domain restrictions on publishable keys to limit which sites can use them
Create separate keys for different applications so you can revoke individually
Rotate keys periodically