Documentation — Zelvyn

Overview

The Zelvyn API is a stateless calculation and analytics platform for mathematics, statistics and business metrics.

Every JSON response shares one envelope: successes return { success, data, meta } and failures return { success, error, meta }, with a meta.requestId correlation id on both. Calculations are never persisted, and no database is on the calculation path.

## Authentication is optional

Endpoints are public. Send an API key via Authorization: Bearer <key> or the x-api-key header to receive plan rate limits and monthly quota accounting. Keyless (anonymous) traffic is limited per hashed client IP and has no account quota. See the *Authentication* section of the developer documentation for the full key lifecycle.

## Conventions

- All request bodies are JSON objects and are strictly validated: unknown fields are rejected (additionalProperties: false). - Percentage metrics return percent points (40 means 40%); roas is a plain ratio (4 means 4×). Percentages are never fractions and never carry a % sign. - Exact integer results beyond Number.MAX_SAFE_INTEGER are returned as decimal strings (never rounded). - Every error is a JSON envelope; no HTML error pages are returned for API paths.

Authentication

Authentication is optional on every public endpoint. Keyless requests are allowed and are rate limited per source; a valid API key receives the plan's limits and quota accounting.

Authorization: Bearer zlv_<env>_<keyId>_<secret> — the recommended header.
x-api-key: <key> — alternative header.Authorization takes precedence if both are present.
The account/session surface (/api/v1/account/*) is cookie-authenticated for the console at /dashboard and is intentionally not part of the public OpenAPI document.

Request correlation: send an optional x-request-id (8–64 chars of A–Za–z0–9._-) and a valid value is echoed in meta.requestId and the response header; otherwise a UUID v4 is generated.

API keys

API keys are opaque strings in the form zlv_<env>_<keyId>_<secret>, where <env> separates key environments (for example test and live). Keys select the plan whose rate limits and monthly quota apply to the request.

Key provisioning and revocation are currently handled by the API's private, token-guarded admin plane (server-to-server only). The public API does not yet expose key management to the browser console; the dashboard API-key page shows an honest not-yet-available state for that reason. Treat keys as secrets: never commit them, log them, or send them to analytics.

Math

Sixteen operations cover arithmetic, percentage change, powers and roots, logarithms, factorials, GCD/LCM, permutations and combinations.

Method	Endpoint	Summary	Try
POST	/api/v1/math/add	Add numbers values: number[]	Try it
POST	/api/v1/math/combinations	Combinations C(n, r) n: integer · r: integer	Try it
POST	/api/v1/math/divide	Divide numbers (left to right) values: number[]	Try it
POST	/api/v1/math/factorial	Factorial n: integer	Try it
POST	/api/v1/math/gcd	Greatest common divisor a: integer · b: integer	Try it
POST	/api/v1/math/lcm	Least common multiple a: integer · b: integer	Try it
POST	/api/v1/math/ln	Natural logarithm value: number	Try it
POST	/api/v1/math/log	Logarithm to a base (default 10) value: number · base?: number	Try it
POST	/api/v1/math/multiply	Multiply numbers values: number[]	Try it
POST	/api/v1/math/nth-root	N-th root value: number · degree: integer	Try it
POST	/api/v1/math/percent-of	Percent of a value percentage: number · value: number	Try it
POST	/api/v1/math/percentage-change	Percentage change between two values from: number · to: number	Try it
POST	/api/v1/math/permutations	Permutations P(n, r) n: integer · r: integer	Try it
POST	/api/v1/math/power	Raise a base to an exponent base: number · exponent: number	Try it
POST	/api/v1/math/sqrt	Square root value: number	Try it
POST	/api/v1/math/subtract	Subtract numbers (left to right) values: number[]	Try it

Statistics

The statistics surface currently exposes the arithmetic mean of a dataset of up to 10,000 values.

Method	Endpoint	Summary	Try
POST	/api/v1/statistics/mean	Arithmetic mean values: number[]	Try it

Business Analytics

Seventeen operations cover profitability, growth, marketing efficiency, pricing, retention and customer value.

Method	Endpoint	Summary	Try
POST	/api/v1/business/aov	Average order value AOV revenue: number · orders: number	Try it
POST	/api/v1/business/break-even	Break-even volume (units) fixedCosts: number · price: number · variableCost: number	Try it
POST	/api/v1/business/cac	Customer acquisition cost CAC cost: number · customers: number	Try it
POST	/api/v1/business/cagr	Compound annual growth rate CAGR (percent) beginValue: number · endValue: number · periods: number	Try it
POST	/api/v1/business/churn-rate	Churn rate (percent) churned: number · starting: number	Try it
POST	/api/v1/business/clv	Customer lifetime value CLV averageOrderValue: number · purchasesPerPeriod: number · lifespanPeriods: number	Try it
POST	/api/v1/business/conversion-rate	Conversion rate (percent) conversions: number · sessions: number	Try it
POST	/api/v1/business/cpa	Cost per acquisition CPA cost: number · conversions: number	Try it
POST	/api/v1/business/cpc	Cost per click CPC cost: number · clicks: number	Try it
POST	/api/v1/business/cpm	Cost per mille CPM cost: number · impressions: number	Try it
POST	/api/v1/business/ctr	Click-through rate CTR (percent) clicks: number · impressions: number	Try it
POST	/api/v1/business/markup	Markup (percent) price: number · cost: number	Try it
POST	/api/v1/business/profit	Profit revenue: number · costs: number	Try it
POST	/api/v1/business/profit-margin	Profit margin (percent) revenue: number · costs: number	Try it
POST	/api/v1/business/retention-rate	Retention rate (percent) retained: number · starting: number	Try it
POST	/api/v1/business/roas	Return on ad spend ROAS (ratio) revenue: number · adSpend: number	Try it
POST	/api/v1/business/roi	Return on investment ROI (percent) profit: number · investment: number	Try it

Errors

Every failure uses the envelope { success: false, error: { code, message, details? }, meta }. Branch on code; wording may change between releases. Stack traces and database detail are never returned.

HTTP	Code	Meaning
400	VALIDATION_ERROR	Malformed request: shape, types, ranges or JSON syntax.
401	UNAUTHORIZED	Missing or invalid credentials (including bad login).
403	FORBIDDEN	The caller is not allowed to perform the action.
404	NOT_FOUND	Unknown endpoint or operation.
404	INVALID_OPERATION	The operation requested does not exist.
405	METHOD_NOT_ALLOWED	This HTTP method is not supported for the endpoint.
410	ENDPOINT_SUNSET	The endpoint existed but has been retired.
413	PAYLOAD_TOO_LARGE	The request body exceeds documented limits.
422	INVALID_DATASET	The dataset is well-formed but invalid for this operation.
422	DIVISION_BY_ZERO	The request is mathematically undefined (division by zero).
422	UNDEFINED_RESULT	The result is mathematically undefined.
429	RATE_LIMITED	Rate limit exceeded; check retry-after.
429	QUOTA_EXCEEDED	The account monthly quota is exhausted.
500	INTERNAL_ERROR	Unexpected internal failure — details are never echoed.
503	SERVICE_UNAVAILABLE	A dependency or the gate is unavailable; fails closed.

Rate limits

Limits are enforced with persisted counters (never an in-memory budget), and a 429 RATE_LIMITED response includes a retry-after header in seconds.

Dimension	Scope	Limit
anonymous	Keyless callers, per source	60 / minute
key	one API key	per-key requests per minute
account	plan × environment	see `plans`
endpoint	one endpoint × one caller	see `plans`
ip	anonymised caller hash	anonymousRateLimitPerMinute
global	the whole API	off unless configured
admin	private admin control plane	ADMIN_RATE_LIMIT_GLOBAL_PER_MINUTE / ADMIN_RATE_LIMIT_IP_PER_MINUTE / ADMIN_RATE_LIMIT_FAILED_PER_MINUTE (default 120 / 60 / 10 per minute)

Quotas

Authenticated requests count toward a monthly quota for the key's account and plan. When exhausted, requests answer 429 QUOTA_EXCEEDED.

Plan	Requests / minute	Requests / month
FREE	60	10,000
PRO	600	1,000,000

The public API does not yet expose consumed quota back to the browser console; user-facing usage reporting is not available.

Versioning

The API is versioned in the URL (/api/v1/…, currently 0.1.0). The envelope — { success, data|error, meta } — is the v1 contract. These properties are stable:

The default response profile is byte-identical to v1: { operation, result }.
The optional x-zelvyn-profile header selects a field set (compact, default, detailed) where the endpoint offers one and the administrator has activated it; unsupported values are rejected with 400 VALIDATION_ERROR rather than silently ignored.
Additive changes (new endpoints, new fields) are preferred; breaking changes require a new major version.

Status codes

The statuses a managed endpoint can return: 200 success, then the failure set below.

Status	When
200	The calculation succeeded; data carries the result.
400	Validation failed (shape, types, ranges, JSON, profile value).
401	The API key is missing, malformed or revoked.
403	The caller is not authorized for this action.
404	No endpoint matches this path or operation.
405	Method not allowed for this endpoint.
410	The endpoint has been sunset (retired).
413	Request body exceeds the documented size limit.
422	The request is valid JSON but the operation is mathematically undefined or invalid.
429	Rate limited or monthly quota exhausted.
500	Unexpected internal error.
503	The API (or a required dependency) is temporarily unavailable.

Examples

Paste-ready calls that match the live contracts.

Arithmetic mean

curl -sS -X POST 'https://api-zelvyn.devs.surf/api/v1/statistics/mean' \
  -H 'Content-Type: application/json' \
  -d '{"values":[12,15,11,19,14,22,17,13,16,18,21,15]}'

Profit

curl -sS -X POST 'https://api-zelvyn.devs.surf/api/v1/business/profit' \
  -H 'Content-Type: application/json' \
  -d '{"revenue":184200,"costs":118400}'

Compound annual growth

curl -sS -X POST 'https://api-zelvyn.devs.surf/api/v1/business/cagr' \
  -H 'Content-Type: application/json' \
  -d '{"beginValue":10000,"endValue":212000,"periods":4}'