3分で読めます

OpenAPI Specification

The Zenovay External API is described by a live OpenAPI 3.1 spec served directly from the API. Fetch it any time to generate client SDKs, import into API testing tools, or build custom integrations.

Live spec

Fetch the live specBash

curl https://api.zenovay.com/api/external/v1/openapi.json | jq .info

The endpoint is public (no API key required to read the spec itself; you still need a key to call any documented endpoint). It's edge-cached for 5 minutes.

Specification Overview

Property	Value
OpenAPI Version	3.1.0
API Version	1.0.0
Base URL	`https://api.zenovay.com/api/external/v1`
Authentication	Bearer token (`Authorization: Bearer zv_...`) or `X-API-Key` header
Format	JSON
URL	`/api/external/v1/openapi.json`

Endpoints Covered

The specification documents all External API endpoints, including the Pro+ Stats API:

Tag	Endpoints
Stats API (Pro+)	`GET /stats/aggregate`, `GET /stats/timeseries`, `GET /stats/breakdown`
Account	`GET /usage`
Websites	`GET /websites`, `GET /websites/{websiteId}`
Analytics	`GET /analytics/{websiteId}`
AI & Advanced (Pro+)	`GET /insights/{websiteId}`, `GET /anomalies/{websiteId}`, `GET /retention/{websiteId}`, `GET /revenue/{websiteId}/ltv`
AI & Advanced (Scale+)	`POST /query/{websiteId}`

Using with Tools

Import into Postman

Open Postman and go to Import
Paste the URL https://api.zenovay.com/api/external/v1/openapi.json
Postman will create a collection with all endpoints pre-configured
Set the X-API-Key variable in your environment

Import into Insomnia

Open Insomnia and go to Import/Export > Import Data
Choose From URL and enter https://api.zenovay.com/api/external/v1/openapi.json
All endpoints will appear in a new workspace

Generate TypeScript Client

Using openapi-typescript-codegenBash

npx openapi-typescript-codegen \
--input https://api.zenovay.com/api/external/v1/openapi.json \
--output ./src/api-client

Generate Python Client

Using openapi-python-clientBash

pip install openapi-python-client
openapi-python-client generate \
--url https://api.zenovay.com/api/external/v1/openapi.json

Schema Highlights

Response Envelope

Every successful response uses the envelope:

Success EnvelopeJSON

{
"success": true,
"data": { ... },
"timestamp": "2026-02-07T12:00:00.000Z"
}

Every error response uses:

Error EnvelopeJSON

{
"success": false,
"error": {
  "message": "Human-readable error description",
  "code": "UNAUTHORIZED",
  "timestamp": "2026-02-07T12:00:00.000Z"
}
}

Error Codes

The spec defines these error codes:

Code	HTTP Status	Description
`VALIDATION_ERROR`	400	Invalid request parameters
`UNAUTHORIZED`	401	Missing or invalid API key
`FORBIDDEN`	403	Insufficient permissions
`NOT_FOUND`	404	Resource not found
`CONFLICT`	409	Resource conflict
`INTERNAL_ERROR`	500	Server error
`GENERIC_ERROR`	Various	General error

API Endpoints Overview - Full endpoint documentation
Authentication - API key management
API Playground - Test endpoints interactively