Zenovay's REST API is documented at docs.zenovay.com. Every request authenticates with a Bearer token (an "API key") that you generate in the dashboard.
Generating an API key
Open API keys settings
In
app.zenovay.com, go to Settings → API keys.Click 'Create API key'
Pick a name that describes the integration (e.g.
Slack alerts,Internal data export).Choose the scope
- Team scope — the key can read/write across every website in the team.
- Site scope — the key is locked to one specific website. Ideal for embedding in a per-customer integration.
Choose the role
- Read — analytics queries only. Cannot create goals, funnels, or modify settings.
- Write — can create/edit goals, funnels, alerts, and team-level resources (if team-scoped).
Copy the key once
The key starts with
zv_and is shown only once at creation time. Copy it into your secrets manager immediately. We only store a hash — we cannot recover a lost key.
Hello-world request
Every API call sends the key as a Bearer token in the Authorization header.
curl https://api.zenovay.com/v1/websites \
-H "Authorization: Bearer zv_your_actual_key_here"
A successful response returns the websites the key has access to as JSON. If the key is invalid or revoked, you'll get 401 Unauthorized.
Rate limits
Each API key respects per-plan rate limits:
| Plan | Per-minute | Per-day |
|---|---|---|
| Free | 60 | 1,000 |
| Pro | 300 | 50,000 |
| Scale | 1,000 | 500,000 |
| Enterprise | Custom | Custom |
The response includes X-RateLimit-Remaining and X-RateLimit-Reset headers — read them and back off when you're nearing the limit. See API rate limits for details.
Rotating and revoking keys
- Rotation — go to Settings → API keys, click Rotate next to the key. The old key works for 5 minutes after rotation to give you time to deploy the new one.
- Revocation — click Revoke. The key stops working immediately.
- Audit — every key shows last-used timestamp and last-used IP (hashed). If a key hasn't been used in 90 days and you don't recognize the integration, revoke it.
MCP server
Zenovay also speaks the Model Context Protocol — your API key can be used to connect Claude Desktop, Cursor, or any MCP client directly to your analytics. See the MCP documentation on the developer site for the connection URL and tool list.
Best practices
- Never commit a key to a public repo. GitHub auto-scans for
zv_prefixed strings and we will auto-revoke detected keys. - One key per integration. If a vendor is compromised, you only revoke their key.
- Use read-only keys unless the integration explicitly needs to write. Writes can create or modify goals, funnels, alerts, and (on team-scoped keys) settings.
- Site-scope keys for per-customer integrations — even if leaked, the blast radius is limited to one site.