API access
An API key lets a script or a tool read your ResponZ data without a browser. Keys are read-only, belong to your organization and can be revoked at any time.
Create a key
Keys are managed in Settings › Organization › API access. Only the organization owner can create or revoke a key; other members see the list.
- Click Create a key and give it a name that says where it will run, for example "Nightly export".
- Choose the permissions and how long the key stays valid.
- Click Create. The full key is shown once. Copy it before closing the window: it cannot be displayed again, and a lost key has to be replaced by a new one.
An organization can hold up to 10 active keys. The list shows each key's prefix (rz_live_1a4b…), its permissions, when it was created, when it was last used and when it expires. A key that has never been used carries a Never used badge: usually the key was never pasted into the tool.
Heads up
Use the key
Send the key in the Authorization header, after Bearer. No cookie and no organization header are needed: the key carries its organization, and it only ever reads that organization's data.
curl https://api.responz.io/v1/analytics/summary \
-H "Authorization: Bearer rz_live_..."Responses are the JSON the ResponZ dashboard itself reads. Date-based endpoints accept from and to query parameters and default to the last 90 days.
Permissions
- Statistics and analytics (
read:analytics): always granted. Figures, trends, topic clusters, goals, categories and documentation metrics. - Conversation content (
read:conversations): off by default. Includes the text of your customers' messages, and anything that names a customer or contact. Tick it only if your tool needs it.
What a key can read
A key is read-only. It only accepts GET requests, on a fixed list of endpoints. Anything else answers an error, even with a valid key.
With read:analytics:
/v1/dashboard/overview,/v1/dashboard/trends/v1/analytics/*indicators (summary, volume, SLA, CSAT, backlog, agents, forecasts…), except those listed underread:conversations/v1/trends/series,/v1/trends/annotations/v1/objectives,/v1/objectives/progress,/v1/objectives/suggestions/v1/clusters,/v1/categories,/v1/categories/stats/v1/docs/*documentation metrics, except a single article- CSV exports
/v1/export/clustersand/v1/export/gaps
With read:conversations as well:
/v1/conversations,/v1/conversations/:id,/v1/quality-scores/v1/clusters/:id/conversations,/v1/clusters/:id/answers,/v1/docs/articles/:id- In
/v1/analytics:fin/loops,open-risk,churn-risk,accounts/:companyId/journey,surveys,top-customers,unconverted-leads,free-tier-accounts - CSV exports
/v1/export/conversations,/v1/export/quality-scores,/v1/export/churn
A key never reaches Ask AI or search (they use AI credits), billing, organization and team settings, the audit log, or key management: a key cannot create another key. Your plan applies as it does in the dashboard: CSV exports start on the Starter plan.
Expiry
When you create a key, choose 30 days, 90 days (the default), 1 year, or no expiry. An expired key stops working and shows an Expired on badge. It cannot be extended: create a new one, then revoke the old one to clear it from the list.
Rate limit
Each key can make 60 calls per minute. The counter resets at the start of each minute and is kept per key, so two keys of the same organization do not share it. Beyond the limit, the API answers 429 with a Retry-After header giving the number of seconds to wait.
Error responses
401Invalid API key: unknown, malformed, expired or revoked key, or a key whose creator has left the organization.401Unauthorized: an endpoint that keys cannot reach.403API_KEY_SCOPE: the endpoint needsread:conversationsand the key does not have it.403API_KEY_READ_ONLY: any method other thanGET.402: the feature is not included in your plan.429: rate limit reached, seeRetry-After.
Revoke a key
In Settings › Organization › API access, the owner clicks Revoke and confirms. The key stops working on the very next call; revocation cannot be undone. The key leaves the list but stays in the audit log.
The audit log has an API access tab: it records when each key was created, first used and revoked. See Security & data.